Transfers

Key rules

All IDs are KSUIDs (26-char, time-sortable); copy/paste carefully.
address_id is the universal source/destination primitive (covers wallets and fiat endpoints).
Always send Idempotency-Key on create POSTs; never on GETs. Do not reuse a key with a different payload/URI.

Each transfer requires both a source and a destination, which can be:

Fiat sources (e.g., a bank account for ACH or wire)
On-chain wallet addresses

Each source and destination includes:

value_type: The currency being transferred (USD, USDC, USDT, MXN, etc.)
transfer_type: The payment rail used (Wire, ACH, Polygon, Solana, SPEI, etc.)

Required Fields

Field	Where	Type	Description
`account_id`	Path	string	Account whose funds are being moved
`amount`	Body	object	`{ "value": "10", "currency": "USD" }`
`source`	Body	object	Origin of funds (fiat rail or on-chain address)
`value_type`	In `source` / `destination`	string	Currency/token (e.g., USD, USDC, SBC)
`transfer_type`	In `source` / `destination`	string	Payment rail / chain (wire, ach_credit, polygon, solana)
`address_id`	In `source` / `destination`	string	Wallet or fiat account sending or receiving value
`Idempotency-Key`	Header	string	UUID that guarantees exactly-once execution

Optional Fields

Field	Where	Type	Description
`brand`	Body	object	ACH only. `{ "account_id": "<ACCOUNT_ID>" }` to control which Account name appears on ACH bank statement line items (ACH debit + ACH credit). Not supported for `wire` or `rtp`.
`wire_memo`	In `destination`	string	Wire only. Memo or payment reference text sent with outbound wire transfers. Only applies when `destination.transfer_type` is `wire`.

Transfer Scenarios: understanding `value_type` and `transfer_type`

Flow	Source	Destination	Description
Onramp (Fiat → Stablecoin)	USD / wire	SBC / base	Mint SBC on Base funded by wire deposit
Offramp (Stablecoin → Fiat)	SBC / solana	USD / ACH	Redeem SBC on Solana to USD via ACH
Swap (Stablecoin ↔ Stablecoin)	USDC / solana	SBC / solana	1:1 swap from USDC to SBC with no slippage
On-chain Payout	USDC / polygon	USDC / polygon (external address)	Pay a recipient wallet
USDC off-ramp (wire)	USDC / polygon	USD / wire	Offramp USDC to wire
SBC branded ACH payout (ACH only)	SBC / base	USD / ach_credit + brand (ACH only)	ACH payout with brand on statement

Every request is scoped to an account, so the path always starts with: POST https://api.brale.xyz/accounts/{account_id}/transfers // The ID of your or your customer's account

USD to Stablecoin (Wire Transfer)

Accept a USD deposit to mint stablecoins. POST https://api.brale.xyz/accounts/account_id/transfers

curl --request POST \
  --url "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${AUTH_TOKEN}" \
  --header "Idempotency-Key: $(uuidgen)" \          # generate a fresh key per logical transfer; reuse on retries of the same transfer
  --data '{
    "amount":    { "value": "10", "currency": "USD" },
    "source":    { "value_type": "usd", "transfer_type": "wire" },
    "destination": {
      "address_id": "'"${ADDRESS_ID}"'",
      "value_type": "sbc",
      "transfer_type": "base"
    }
  }'

When initiating a fiat to stablecoin transfer via wire, we will return a set of wire_instructions so you can provide them to your customer.

Response

{
  "id": "2xNL6PAF0cbcQHyjMQJ2RKRfbD9",
  "status": "pending",
  "source": {
    "value_type": "USD",
    "transfer_type": "wire"
  },
  "destination": {
    "address_id": "2VcUIonJeVQzFoBuC7LdFT0dRe4",
    "value_type": "SBC",
    "transfer_type": "base"
  },
  "updated_at": "2025-05-20T20:36:48.147281Z",
  "created_at": "2025-05-20T20:36:48.147281Z",
  "amount": {
    "value": "10",
    "currency": "USD"
  },
  "note": null,
  "wire_instructions": {
    // Brale Bank instructions
  }
}

USD to Stablecoin (ACH Debit)

Onramp to your stablecoin by debiting a Plaid connected address. POST https://api.brale.xyz/accounts/account_id/transfers

Request

{
  "amount": {
    "value": "1",
    "currency": "USD"
  },
  "source": {
    "address_id": "2VcUIonJeVQzFoBuC7LdFT0dRe4", // address_id is the primitive, even for onchain sources
    "value_type": "USD",
    "transfer_type": "ach_debit"
  },
  "destination": {
    "address_id": "34yGFQf7tP1HJCPAWNGaN4rh4nX",
    "value_type": "SBC",
    "transfer_type": "polygon"
  },
  "brand": { "account_id": "34lCJZ2bxbPAzB3ou67Md01veUo" }
}

Optional brand object You can specify which Account’s name appears on the receiver’s bank statement line items for ACH only. It is not supported for wire or RTP.

Stablecoin to USD (Wire Offramp or Payout)

Offramp your stablecoin to USD via wire transfer. POST https://api.brale.xyz/accounts/account_id/transfers

Request

{
  "amount": {
    "value": "1",
    "currency": "USD"
  },
  "source": {
    "address_id": "2VcUIonJeVQzFoBuC7LdFT0dRe4",
    "value_type": "SBC",
    "transfer_type": "Polygon"
  },
  "destination": {
    "address_id": "34yGFQf7tP1HJCPAWNGaN4rh4nX",
    "value_type": "USD",
    "transfer_type": "wire",
    "wire_memo": "Invoice 1048"
  }
}

For outbound wire transfers, you can optionally pass destination.wire_memo to include a memo or payment reference for the receiving bank or recipient.

Stablecoin to USD (ACH)

Offramp your stablecoin to USD via ACH Credit. POST https://api.brale.xyz/accounts/account_id/transfers

Request

{
  "amount": {
    "value": "1",
    "currency": "USD"
  },
  "source": {
    "address_id": "2VcUIonJeVQzFoBuC7LdFT0dRe4",
    "value_type": "SBC",
    "transfer_type": "canton"
  },
  "destination": {
    "address_id": "34yGFQf7tP1HJCPAWNGaN4rh4nX",
    "value_type": "USD",
    "transfer_type": "same_day_ach_credit"
  }
}

Stablecoin Swaps

Swap USDC to your own stablecoin (YSBC). All stablecoin swaps are 1:1 with no slippage. POST https://api.brale.xyz/accounts/account_id/transfers

Request

{
  "amount": {
    "value": "100",
    "currency": "USD"
  },
  "source": {
    "address_id": "2VcUIonJeVQzFoBuC7LdFT0dRe4",
    "value_type": "USDC",
    "transfer_type": "Solana"
  },
  "destination": {
    "address_id": "2VcUIonJeVQzFoBuC7LdFT0dRe4",
    "value_type": "YSBC",
    "transfer_type": "Solana"
  }
}

Stablecoin Payout

Process stablecoin payouts to one or many external addresses (EOAs). POST https://api.brale.xyz/accounts/account_id/transfers

Request

{
  "amount": {
    "value": "500",
    "currency": "USD"
  },
  "source": {
    "address_id": "2VcUIonJeVQzFoBuC7LdFT0dRe4",
    "value_type": "SBC",
    "transfer_type": "Solana"
  },
  "destination": {
    "address_id": "2xNL6PAF0cbcQHyjMQJ2RKRfbD9",
    "value_type": "SBC",
    "transfer_type": "Solana"
  }
}

Retrieving a single transfer

GET https://api.brale.xyz/accounts/{account_id}/transfers/{transfer_id}

Response

{
  "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
}

transaction_id is a response-only field on source and destination. It contains the on-chain transaction hash or off-chain payment reference once the leg has been submitted to the network. It is not present in create requests.

Listing transfers

GET https://api.brale.xyz/accounts/{account_id}/transfers Returns a paginated list of transfers for the account. You can narrow results with query-parameter filters.

Filters

All filters are exact match and case-sensitive. When you combine multiple filters they apply with AND semantics.

Parameter	Filters by	Format	Example
`automation_id`	Automation that created the transfer	KSUID	`2MhCCIHuK4TGVgT9a4loQzJx1rj`
`value_type`	Currency / token on source or destination	Canonical API id	`USDC`, `SBC`, `usd`
`transfer_type`	Payment rail / chain on source or destination	Canonical API id	`polygon`, `wire`, `solana`

value_type and transfer_type use canonical identifiers listed on the Value types and Transfer types coverage pages.

If no transfers match, the API returns 200 with an empty transfers array. transaction_id is not a list filter. It appears only in transfer responses. To locate a transfer by its on-chain hash, filter by transfer_type and match transaction_id client-side.

Example: filter by automation

curl "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers?automation_id=2MhCCIHuK4TGVgT9a4loQzJx1rj" \
  -H "Authorization: Bearer ${AUTH_TOKEN}"

Example: combined filters

curl "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers?value_type=USDC&transfer_type=polygon&page[size]=10" \
  -H "Authorization: Bearer ${AUTH_TOKEN}"

Pagination

Parameter	Description	Default
`page[size]`	Results per page (1–100)	25
`page[after]`	Cursor for forward pagination	—
`page[prev]`	Cursor from `pagination.prev`	—

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.

# First page
curl "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers?page[size]=50" \
  -H "Authorization: Bearer ${AUTH_TOKEN}"

# Next page
curl "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers?page[size]=50&page[after]=${cursor}" \
  -H "Authorization: Bearer ${AUTH_TOKEN}"

Reconciliation best practices

Store transfer id, Idempotency-Key, timestamps, status, and any provider references.
Poll with backoff; avoid tight loops. Reuse the same Idempotency-Key when retrying the same logical transfer.
On 401, refresh the token and retry idempotently.

Transfer Statuses

Value	Description
`pending`	The transfer has been submitted but is not yet in progress. This may be due to Brale waiting for funds (e.g., fiat-to-stablecoin wire transfer) or an ongoing review.
`processing`	The transfer is in progress.
`complete`	The transfer is finalized and funds have arrived at the destination.
`canceled`	The transfer has been canceled.
`failed`	An issue prevented Brale from completing the transfer. Manual intervention may be required.

Transfer Flow

A transfer will progress from pending → processing → complete. Transfers include an updated_at field denoting the last time the status updated.

Transfer Limits

Inbound ACH transactions are limited to $50,000 per transaction.
There are no limits for wire or stablecoin transactions.

Overview

Key concepts

Required Fields

Optional Fields

Transfer Scenarios: understanding `value_type` and `transfer_type`

USD to Stablecoin (Wire Transfer)

USD to Stablecoin (ACH Debit)

Stablecoin to USD (Wire Offramp or Payout)

Stablecoin to USD (ACH)

Stablecoin Swaps

Stablecoin Payout

Retrieving a single transfer

Listing transfers

Filters

Example: filter by automation

Example: combined filters

Reconciliation best practices

Transfer Statuses

Transfer Flow

Transfer Limits

Overview

Key concepts

​Required Fields

​Optional Fields

​Transfer Scenarios: understanding value_type and transfer_type

​USD to Stablecoin (Wire Transfer)

​USD to Stablecoin (ACH Debit)

​Stablecoin to USD (Wire Offramp or Payout)

​Stablecoin to USD (ACH)

​Stablecoin Swaps

​Stablecoin Payout

​Retrieving a single transfer

​Listing transfers

​Filters

​Example: filter by automation

​Example: combined filters

​Pagination

​Reconciliation best practices

​Transfer Statuses

​Transfer Flow

​Transfer Limits

Required Fields

Optional Fields

Transfer Scenarios: understanding `value_type` and `transfer_type`

USD to Stablecoin (Wire Transfer)

USD to Stablecoin (ACH Debit)

Stablecoin to USD (Wire Offramp or Payout)

Stablecoin to USD (ACH)

Stablecoin Swaps

Stablecoin Payout

Retrieving a single transfer

Listing transfers

Filters

Example: filter by automation

Example: combined filters

Pagination

Reconciliation best practices

Transfer Statuses

Transfer Flow

Transfer Limits