Transfers

Transfers enable the movement of funds between fiat and stablecoins, stablecoin-to-stablecoin conversions, and stablecoin-to-fiat transactions.

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`.

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

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 Transfers

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

Response

{
  "id": "transfer_123",
  "status": "pending",
  "amount": {
    "value": "1",
    "currency": "USD"
  },
  "created_at": "2025-02-05T19:39:14.316Z",
  "updated_at": "2025-02-05T19:39:14.316Z",
  "source": {
    "transfer_type": "wire",
    "value_type": "USD"
  },
  "destination": {
    "transfer_type": "polygon",
    "value_type": "YSBC",
    "address_id": "d7bd28e4-93e6-4313-880c-ab9178eacd3b"
  },
  "wire_instructions": {
    // ...Brale bank details
  }
}

Retrieving Transfers & Pagination

List Call

GET https://api.brale.xyz/accounts/account_id/transfers/transfer_id?page[size]=50 Returns the 50 most recent transfers.

Paging Forward

GET https://api.brale.xyz/accounts/account_id/transfers/transfer_id?page[next]=g3QAAAABdw... Use the pagination.next token from the previous response.

Paging Backward

GET https://api.brale.xyz/accounts/account_id/transfers/transfer_id?page[prev]=g3QAAAABdw... Only one of page[next] or page[prev] may be present.

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 Transfers

List Call

Paging Forward

Paging Backward

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 Transfers

​Retrieving Transfers & Pagination

​List Call

​Paging Forward

​Paging Backward

​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 Transfers

Retrieving Transfers & Pagination

List Call

Paging Forward

Paging Backward

Reconciliation best practices

Transfer Statuses

Transfer Flow

Transfer Limits