> ## 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 (27-char string) | `2MhCCIHuK4TGVgT9a4loQzJx1rj` | | `value_type` | Currency / token on source **or** destination | Canonical API id (case-sensitive) | `USDC`, `SBC`, `usd` | | `transfer_type` | Blockchain on source **or** destination. Fiat rails such as `wire` and `fednow_credit` are not supported as filter values. | Canonical API id (case-sensitive) | `polygon`, `base`, `solana` | | `transaction_id` | On-chain transaction hash or off-chain payment reference | String (exact match, case-sensitive) | `0xdd5646ea…` | > [!NOTE] > > `value_type` and `transfer_type` use canonical API identifiers. See [Value types](https://docs.brale.xyz/coverage/value-types.md) and [Transfer types](https://docs.brale.xyz/coverage/transfer-types.md) 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}" ``` ### FedNow Transfers for an Automation Inbound FedNow deposits create Transfers with `source.transfer_type: "fednow_credit"` and the Automation's `automation_id`. Outbound FedNow payouts have `destination.transfer_type: "fednow_credit"`. The `transfer_type` query parameter filters by blockchain only. Fiat rails such as `fednow_credit`, `same_day_ach_credit`, and `wire` are not supported as filter values. Filter by `automation_id` (inbound) or `address_id` (outbound), then check `source.transfer_type` or `destination.transfer_type` on each Transfer. ```bash theme={null} curl "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers?automation_id=35kVg1llbsOBYvx9XKr9eOtsD9z" \ -H "Authorization: Bearer ${AUTH_TOKEN}" ``` The payment ID in a `payment.completed` webhook is not a Transfer ID. See [Receive FedNow deposits](https://docs.brale.xyz/guides/fednow-inbound.md#find-the-transfer) to correlate the two. ### 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": "2O6asmNK4TGVgT9a4loQzJx1rjH", "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. For inbound wires, Brale may also populate this field from "Instruction for Creditor Agent," which some banks label "Message to receiving bank." This fallback is used only when no existing memo, Originator-to-Beneficiary Information (OBI), or remittance reference is available. Existing reference precedence is preserved. | | `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`](https://docs.brale.xyz/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 and ACH transfers. The object is optional and may be absent immediately after a transfer is created. Brale populates it later once the wire IMAD or the ACH trace number is available. | Field | Type | Description | | :- | :- | :- | | `imad` | string \| null | Wire IMAD / tracking identifier for the outbound wire, when available | | `trace_number` | string \| null | ACH trace number for the outbound ACH payout (`ach_credit` or `same_day_ach_credit`), when available | | `sent_at` | string (date-time) \| null | When the outbound wire or ACH payout was sent, when available | See [Transfers — `destination.payment_details`](https://docs.brale.xyz/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—27-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. **FedNow** - Added the `fednow_credit` rail. Outbound: create a Transfer with `destination.transfer_type: fednow_credit` to a bank Address that lists `fednow_credit` in `transfer_types`. Inbound: payers send FedNow credits to an active Automation's `source.funding_instructions`; Brale creates the Transfer automatically with `source.transfer_type: fednow_credit`. - Simulate a testnet FedNow deposit with `transfer_type: fednow` on `POST /accounts/{account_id}/automations/{automation_id}/simulations/deposits`. - `bank_address` and `beneficiary_address` are required only when an external bank Address requests `wire`. - FedNow availability depends on account enablement. 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 blockchain chain (for example, `solana`, `base`, `ethereum`). Fiat payment types (for example, `same_day_ach_credit`, `wire`, `fednow_credit`) are not supported as filter values. To find FedNow Transfers, filter by `automation_id` or `address_id` and check `source.transfer_type` or `destination.transfer_type`. 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[after] 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]{27}$ 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 - refunding - refunded 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, outbound wire 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: >- Optional. When returned with a value of `true`, the source funding for this transfer was simulated in testnet rather than coming from a real payment. Not every simulated transfer is guaranteed to include this field. Not present for production-funded 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 returns and `wire_return` is only present for outbound wire returns. Do not require rail-specific fields for other failure types. properties: type: type: string description: >- Error classification for the failure, for example `ach_return` or `wire_return`. example: ach_return occurred_at: type: string format: date-time description: >- When Brale recorded the failure. This is not necessarily the exact time the bank returned the payment. 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; `null` or not set for wire returns, on-chain failures, and 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 wire_return: type: object nullable: true description: >- Wire-only return details. Present when `type` is `wire_return` for a returned outbound wire; `null` or not set for other failures. Has no `category` field; the ACH return taxonomy does not apply. properties: code: type: string description: >- The provider's wire return reason code when available (for example, `AC04`). When the provider supplies no code, Brale sets `WIRE_RETURN`, a Brale fallback marker that is not an ISO 20022 bank reason code. example: AC04 reason: type: string nullable: true description: Human-readable return reason, when available. example: Account closed 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 FedNow) and on `destination.payment_details` for outbound wire and ACH transfers. Optional and may be absent depending on the rail and on whether the underlying bank metadata is available yet. Fields are rail-specific. For example, `imad` applies only to wires and `trace_number` only to ACH. Do not expect wire or ACH identifiers on `fednow_credit` legs. 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. For inbound wires, Brale may also populate this field from "Instruction for Creditor Agent," which some banks label "Message to receiving bank." This fallback is used only when no existing memo, Originator-to-Beneficiary Information (OBI), or remittance reference is available. Existing reference precedence is preserved. 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. Appears on `source.payment_details` for inbound ACH-funded transfers and on `destination.payment_details` for outbound ACH transfers (`ach_credit` and `same_day_ach_credit`) once the trace number is assigned. example: '021000029876543' sent_at: type: string format: date-time nullable: true description: >- When the outbound payment was sent, when available. Appears on `destination.payment_details` for outbound wire and ACH transfers. example: '2026-04-07T00:04:58.000000Z' 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. ````