> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brale.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# List transfers
> Returns a paginated list of transfers for a given account, with optional filters.
## Filters
You can narrow results by appending query parameters. All filters use **exact match** and are **case-sensitive**. When you combine multiple filters they apply with **AND** semantics — only transfers matching every supplied filter are returned.
If no transfers match the filters, the API returns `200` with an empty `transfers` array and a `pagination` object.
| Parameter | Filters by | Format | Example |
| :--------------- | :------------------------------------------------------- | :----------------------------------- | :---------------------------- |
| `automation_id` | Automation that created the transfer | KSUID (26-char string) | `2MhCCIHuK4TGVgT9a4loQzJx1rj` |
| `value_type` | Currency / token on source **or** destination | Canonical API id (case-sensitive) | `USDC`, `SBC`, `usd` |
| `transfer_type` | Payment rail / chain on source **or** destination | Canonical API id (case-sensitive) | `polygon`, `wire`, `solana` |
| `transaction_id` | On-chain transaction hash or off-chain payment reference | String (exact match, case-sensitive) | `0xdd5646ea…` |
`value_type` and `transfer_type` use canonical API identifiers. See [Value types](/coverage/value-types) and [Transfer types](/coverage/transfer-types) for the full list of valid values.
### Filtering by `transaction_id`
Pass the full on-chain transaction hash or off-chain payment reference to find transfers that match on either the `source` or `destination` leg. The filter is exact match and case-sensitive. If no transfer matches, the API returns `200` with an empty `transfers` array.
You can combine `transaction_id` with other filters — multiple filters use **AND** semantics.
## Pagination
| Parameter | Description | Default |
| :------------ | :--------------------------------------------------- | :------ |
| `page[size]` | Number of transfers per page (1–100) | 25 |
| `page[after]` | Cursor for forward pagination | — |
| `page[prev]` | Cursor from `pagination.prev` in a previous response | — |
Only one of `page[after]` or `page[prev]` may be present per request. Filters persist across pages — you do not need to resend them when paging. Use the `pagination.next` value from the previous response as the `page[after]` query parameter in the next request.
## Examples
### Filter by `transaction_id`
```bash theme={null}
curl "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers?transaction_id=0xdd5646ea..." \
-H "Authorization: Bearer ${AUTH_TOKEN}"
```
### Filter by `automation_id`
```bash theme={null}
curl "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers?automation_id=2MhCCIHuK4TGVgT9a4loQzJx1rj" \
-H "Authorization: Bearer ${AUTH_TOKEN}"
```
### Filter by `value_type`
```bash theme={null}
curl "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers?value_type=USDC" \
-H "Authorization: Bearer ${AUTH_TOKEN}"
```
### Filter by `transfer_type`
```bash theme={null}
curl "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers?transfer_type=polygon" \
-H "Authorization: Bearer ${AUTH_TOKEN}"
```
### Combined filters
Return only Polygon USDC transfers created by a specific Automation, 10 per page:
```bash theme={null}
curl "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers?automation_id=2MhCCIHuK4TGVgT9a4loQzJx1rj&value_type=USDC&transfer_type=polygon&page[size]=10" \
-H "Authorization: Bearer ${AUTH_TOKEN}"
```
## Response schema
A successful response returns `200` with the following structure:
```json title="Response" theme={null}
{
"pagination": {
"next": "g3QAAAABdw...",
"page_size": 25
},
"transfers": [
{
"id": "30NoY6R1Ns2tRBcx1Kb16SnuXOW",
"status": "complete",
"amount": {
"value": "100.00",
"currency": "USD"
},
"created_at": "2025-07-25T21:03:55.364134Z",
"updated_at": "2025-07-25T21:05:07.779018Z",
"source": {
"address_id": "2MhCCIHuK4TGVgT9a4loQzJx1rj",
"value_type": "USDC",
"transfer_type": "polygon",
"transaction_id": "0xdd5646ea…"
},
"destination": {
"address_id": "2O6asmNK4TGVgT9a4loQzJx1rj",
"value_type": "USDC",
"transfer_type": "polygon",
"transaction_id": "0xdd5646ea…"
},
"note": null
},
{
"id": "3C0QcbwVywOGyU2HBSenljm5dhU",
"status": "complete",
"failure": null,
"amount": {
"value": "102.0",
"currency": "USD"
},
"created_at": "2026-04-07T00:01:27.756775Z",
"updated_at": "2026-04-07T00:01:44.824834Z",
"source": {
"transfer_type": "wire",
"financial_institution_id": "3AjRnbvj9Mq6crkviJv08d0KLB2",
"value_type": "USD",
"payment_details": {
"received_at": "2026-04-07T00:01:24.514000Z",
"sender_name": "Originator Name",
"sender_bank_name": "JPMorgan Chase Bank",
"sender_bank_routing_number": "000000123",
"payment_reference": "Simulated Wire",
"imad": "20260406XOIZJDPP953495"
}
},
"destination": {
"transaction_id": "0x41c66f1d059dad7a55a854e157a1b5b938780c77ba5296e434a02dfb1727fe5e",
"transfer_type": "base",
"address_id": "3ARaM0I93ObWOIFDIztsTx4TAsp",
"value_type": "ARB"
},
"note": null,
"automation_id": "3AjRnDClEzwuCKlRioG3OXMS4pH"
},
{
"id": "3D1RcbwVywOGyU2HBSenljm5dhV",
"status": "complete",
"amount": {
"value": "100.00",
"currency": "USD"
},
"created_at": "2026-04-07T00:01:27.756775Z",
"updated_at": "2026-04-07T00:05:12.102000Z",
"source": {
"address_id": "2VcUIonJeVQzFoBuC7LdFT0dRe4",
"value_type": "SBC",
"transfer_type": "solana",
"transaction_id": "5K8…"
},
"destination": {
"address_id": "34yGFQf7tP1HJCPAWNGaN4rh4nX",
"value_type": "USD",
"transfer_type": "wire",
"wire_memo": "Invoice 1048",
"payment_details": {
"imad": "20260406XOIZJDPP953495"
}
},
"note": null
}
]
}
```
### `source.payment_details`
`source.payment_details` appears when Brale has underlying payment metadata to expose for the source leg of a transfer. This is primarily relevant for inbound fiat-funded transfers. The object is optional and is not present on all transfers.
Wire transfers typically include the full set of fields. ACH transfers may include only a subset — fields may be `null` or omitted depending on available rail metadata.
| Field | Type | Description |
| :--------------------------- | :---------------- | :-------------------------------------------------------------------------------------------------------------------- |
| `received_at` | string (ISO 8601) | When the underlying payment was received or posted |
| `sender_name` | string \| null | Name of the originating sender, when available |
| `sender_bank_name` | string \| null | Originating bank name, when available |
| `sender_bank_routing_number` | string \| null | Originating bank routing number, when available |
| `payment_reference` | string \| null | Sender-provided payment reference or memo, when available |
| `imad` | string \| null | Wire IMAD / tracking identifier, when available |
| `trace_number` | string \| null | ACH trace identifier for the underlying payment, when available. Primarily relevant for inbound ACH-funded transfers. |
See [Transfers — `source.payment_details`](/key-concepts/transfers#sourcepayment_details) for full details.
### `destination.payment_details`
`destination.payment_details` appears when Brale has underlying payment metadata to expose for the destination leg of a transfer. This is primarily relevant for outbound wire transfers. The object is optional and may be absent immediately after a transfer is created; for outbound wires, Brale populates it later once the IMAD is available from the sending bank.
| Field | Type | Description |
| :----- | :------------- | :-------------------------------------------------------------------- |
| `imad` | string \| null | Wire IMAD / tracking identifier for the outbound wire, when available |
See [Transfers — `destination.payment_details`](/key-concepts/transfers#destinationpayment_details) for full details.
## OpenAPI
````yaml GET /accounts/{account_id}/transfers
openapi: 3.0.3
info:
title: Brale Issuance and Orchestration API
version: 2.3.1
description: >
Brale supports stablecoin issuance and orchestration, enabling businesses
and
ecosystems to create their own stablecoins and convert between fiat and
stablecoins
seamlessly. From stablecoin onramps, offramps, and swaps to custody and
payouts, the
Brale API makes it easy to build stablecoin-enabled products.
NOTE: All resource IDs (including account_id, address_id,
financial_institution_id,
and automation_id) are KSUIDs—26-character alphanumeric strings that are
sortable
by time. Examples showing UUIDs are incorrect.
**What's new in 2.3.1**
- Unified **Addresses** model for on-chain and off-chain endpoints
- `Transfers` now accepts **address_id only** (no financial_institution_id)
- Optional `brand` object to control bank statement presentation (`branding` still accepted as legacy alias)
- Added off-chain rails: `ach_credit`, `same_day_ach_credit`, `ach_debit`,
`same_day_ach_debit`, `rtp-credit`
- Plaid endpoints moved to `/accounts/{account_id}/plaid/*`
- `Financial Institutions` marked **deprecated** (migration path to
**Addresses**)
- Create Account now uses `CreateManagedAccountRequest` with
`beneficial_owners`, `business_controller`, and `EndUserTosAttestation`.
- Transfers now accept `brand` (replaces `branding`, still aliased in docs).
- Plaid endpoints updated to return `address_id` and accept
`transfer_types`.
- Off-chain Address creation uses `CreateExternalAddressRequest` oneOf with
bank + blockchain variants.
- FI endpoints kept but marked deprecated; use Addresses instead.
- `rtp_credit` is the canonical RTP rail name.
servers:
- url: https://api.brale.xyz
description: Production server
security:
- BearerAuth: []
tags:
- name: Accounts
description: Endpoints related to managing customer accounts (KYB, details, etc.)
- name: Transfers
description: >-
Endpoints for creating and retrieving transfers (fiat to stablecoins,
etc.)
- name: Addresses
description: >-
On-chain and off-chain endpoints (custodial or external) represented by a
single Addresses resource
- name: Financial Institutions
description: Legacy (deprecated) bank endpoints. Use Addresses instead.
- name: Automations
description: Automated deposit addresses or onramps
- name: Plaid
description: Bank linking and ACH debit via Plaid.
- name: Orders
description: Legacy tag used for transfers in older specs.
paths:
/accounts/{account_id}/transfers:
get:
tags:
- Transfers
- Orders
summary: Get all transfers for a given account
description: Returns a list of transfers associated with the specified account.
operationId: listTransfers
parameters:
- name: account_id
in: path
required: true
description: The ID of the account
schema:
$ref: '#/components/schemas/Ksuid'
- name: automation_id
in: query
required: false
schema:
$ref: '#/components/schemas/Ksuid'
description: >-
Filter transfers to only those created by the specified Automation.
Must be a valid KSUID. Exact match.
example: 2MhCCIHuK4TGVgT9a4loQzJx1rj
- name: value_type
in: query
required: false
schema:
type: string
description: >-
Filter transfers by currency or token identifier. Matches transfers
where the source **or** destination `value_type` equals this value.
Case-sensitive. Use canonical API ids from the Coverage page.
example: USDC
- name: transfer_type
in: query
required: false
schema:
type: string
description: >-
Filter transfers by payment rail or chain identifier. Matches
transfers where the source **or** destination `transfer_type` equals
this value. Case-sensitive. Use canonical API ids from the Coverage
page.
example: polygon
- name: transaction_id
in: query
required: false
schema:
type: string
description: >-
Filter transfers by on-chain transaction hash or off-chain payment
reference. Exact match against the `transaction_id` field on either
the source or destination leg.
example: 0xdd5646ea…
- name: page[size]
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
example: 50
description: The number of transfers to return per page (1–100, default 25).
- name: page[next]
in: query
required: false
schema:
type: string
example: g3QAAAABdw...
description: Cursor for the next page (value returned in `pagination.next`)
- name: page[prev]
in: query
required: false
schema:
type: string
example: g3QAAAABdw...
description: Cursor for the previous page (value returned in `pagination.prev`)
responses:
'200':
description: A list of transfers with pagination cursors
content:
'*/*':
schema:
$ref: '#/components/schemas/TransfersList'
components:
schemas:
Ksuid:
title: Kusid
type: string
format: ksuid
pattern: ^[a-zA-Z0-9]{26}$
example: 2VcUIIsgARwVbEGlIYbhg6fGG57
TransfersList:
title: TransfersList
description: List of transfers plus pagination cursors
type: object
additionalProperties: false
properties:
pagination:
$ref: '#/components/schemas/Pagination'
transfers:
type: array
items:
$ref: '#/components/schemas/Transfer'
required:
- pagination
- transfers
example:
pagination:
next: g3QAAAABdw...
prev: null
page_size: 25
transfers:
- id: 30NoY6R1Ns2tRBcx1Kb16SnuXOW
status: complete
failure: null
source:
transaction_id: 0xdd5646ea…
address_id: 2MhCCIHu…
value_type: USDC
transfer_type: polygon
destination:
transaction_id: 0xdd5646ea…
address_id: 2O6asmN…
value_type: USDC
transfer_type: polygon
amount:
value: '100.00'
currency: USD
note: null
created_at: '2026-01-01T00:00:00Z'
updated_at: '2026-01-01T00:00:00Z'
Pagination:
title: Pagination
description: Cursor-based pagination metadata
type: object
additionalProperties: false
properties:
page_size:
type: integer
example: 25
next:
type: string
nullable: true
example: g3QAAAABdw...
prev:
type: string
nullable: true
example: g3QAAAABdw...
required:
- page_size
Transfer:
title: Transfer
type: object
description: >-
A money movement between a source and a destination. Returned by the
create, get, and list transfer endpoints. The same shape is used
everywhere a Transfer is exposed to API consumers.
properties:
id:
$ref: '#/components/schemas/Ksuid'
status:
type: string
description: Lifecycle stage of the transfer
enum:
- pending
- processing
- complete
- canceled
- failed
example: pending
failure:
allOf:
- $ref: '#/components/schemas/TransferFailure'
nullable: true
description: >-
Structured failure details for a failed transfer. Usually `null`.
Populated when `status` is `failed` and Brale has structured failure
details for the transfer — most commonly for ACH returns and other
rail/provider failures. Clients should not assume `failure` is
always present for every failed transfer; check for `null` before
reading nested fields.
example: null
source:
$ref: '#/components/schemas/TransferEndpoint'
destination:
$ref: '#/components/schemas/TransferEndpoint'
amount:
$ref: '#/components/schemas/Amount'
note:
type: string
nullable: true
description: Optional free-form note attached to the transfer.
example: null
automation_id:
allOf:
- $ref: '#/components/schemas/Ksuid'
description: >-
ID of the Automation that created this transfer, when applicable.
Omitted for transfers created directly via the API.
nullable: true
funding_simulated:
type: boolean
description: >-
Set to `true` when the source funding for this transfer was
simulated in a test environment rather than coming from a real
payment. Not present for production transfers.
created_at:
type: string
format: date-time
example: '2026-01-01T00:00:00Z'
updated_at:
type: string
format: date-time
example: '2026-01-01T00:00:00Z'
TransferFailure:
title: TransferFailure
type: object
description: >-
Structured failure details for a failed transfer. Populated by Brale
when `status` is `failed` and the underlying rail/provider has supplied
structured failure details. Field availability varies by rail — for
example, `ach_return` is only present for ACH transfers.
properties:
type:
type: string
description: Error classification for the failure.
example: ach_return
occurred_at:
type: string
format: date-time
description: When the failure occurred.
example: '2026-04-07T00:05:12.102000Z'
retriable:
type: boolean
description: >-
Whether the failure is considered retriable. When `true`, Brale may
automatically retry the underlying operation; when `false`, the
failure is permanent.
example: false
ach_return:
type: object
nullable: true
description: >-
ACH-only return details. Present for ACH return failures; not set
for on-chain or other rail failures.
properties:
code:
type: string
description: ACH return code (e.g. `R01` — Insufficient Funds).
example: R01
reason:
type: string
description: Human-readable description of the ACH return reason.
example: Insufficient Funds
category:
type: string
description: >-
Simplified taxonomy of the ACH return. `administrative` covers
bank issues that may be retriable. `unauthorized` covers
customer disputes. `general` covers everything else.
enum:
- administrative
- unauthorized
- general
example: administrative
TransferEndpoint:
title: TransferEndpoint
description: >-
One side (source or destination) of a Transfer. The same shape is used
in create requests and in responses. Response-only fields like
`transaction_id` and `payment_details` are populated by Brale as the
underlying leg settles.
type: object
properties:
value_type:
type: string
example: USD
transfer_type:
type: string
example: wire
address_id:
$ref: '#/components/schemas/Ksuid'
financial_institution_id:
type: string
deprecated: true
description: Legacy — use `address_id`.
wire_memo:
type: string
description: >-
Optional memo or payment reference text sent with outbound wire
transfers. Only applies when `transfer_type` is `wire` on the
destination leg.
transaction_id:
type: string
description: >-
On-chain transaction hash or off-chain payment reference. Present in
responses once the leg has been submitted to the network. Not
included in create requests.
example: 0xdd5646ea…
payment_details:
$ref: '#/components/schemas/PaymentDetails'
required:
- value_type
- transfer_type
Amount:
title: Amount
type: object
description: Monetary value with explicit currency
additionalProperties: false
properties:
value:
type: string
example: '11234.88'
currency:
type: string
example: USD
required:
- value
- currency
PaymentDetails:
title: PaymentDetails
type: object
description: >-
Underlying payment metadata for a transfer leg. Response-only. Appears
on `source.payment_details` for inbound fiat-funded transfers (wire,
ACH) and on `destination.payment_details` for outbound wire transfers.
Optional and may be absent depending on the rail and on whether the
underlying bank metadata is available yet.
properties:
received_at:
type: string
format: date-time
nullable: true
description: When the underlying payment was received or posted.
example: '2026-04-07T00:01:24.514000Z'
sender_name:
type: string
nullable: true
description: Name of the originating sender, when available.
example: Originator Name
sender_bank_name:
type: string
nullable: true
description: Originating bank name, when available.
example: JPMorgan Chase Bank
sender_bank_routing_number:
type: string
nullable: true
description: Originating bank routing number, when available.
example: '000000123'
payment_reference:
type: string
nullable: true
description: Sender-provided payment reference or memo, when available.
example: Simulated Wire
imad:
type: string
nullable: true
description: Wire IMAD / tracking identifier, when available.
example: 20260406XOIZJDPP953495
trace_number:
type: string
nullable: true
description: >-
ACH trace identifier for the underlying payment, when available.
Primarily relevant for inbound ACH-funded transfers.
example: '021000029876543'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >
Use the Bearer token returned from the Auth endpoint via OAuth2
client_credentials flow. Include the token in the "Authorization: Bearer
" header.
````