Skip to main content
This page defines the canonical conventions used across Brale’s API docs and examples. Examples are designed to be copy/paste safe. When in doubt, treat the Coverage pages as canonical:

​
ID conventions

Brale resource identifiers are KSUIDs. Treat IDs as opaque strings: store them and pass them back, but don’t parse them.

​
Exact ID names used in docs

When examples refer to an ID, we use these exact names:
ResourceUse this name
Accountaccount_id
Addressaddress_id
Transfertransfer_id
Automationautomation_id
Note: API responses often contain a generic id. In docs, we use account_id / transfer_id / etc. as variable names so it’s obvious which id to reuse in follow-up calls.

​
Enum casing + SBC (use API ids)

Enum values in requests are case-sensitive. Always use the API id (not a display name).

​
value_type

Use the API ids listed in Coverage → Value Types.
  • Offchain fiat value types are lowercase (e.g., usd, mxn).
  • Onchain tokens use their canonical tickers/codes (e.g., SBC, USDC, MXNe).

​
transfer_type

Use the API ids listed in Coverage → Transfer Types.
  • Transfer types are lowercase identifiers (e.g., wire, ach_debit, solana, canton).
  • Testnet uses testnet chain values (e.g., solana_devnet, base_sepolia, sepolia).

​
SBC

Examples frequently use SBC as a placeholder stablecoin. Replace it with the stablecoin your integration uses when appropriate.
Note: amount.currency is an ISO-4217 code (e.g., USD). It is separate from value_type.

​
Canonical Create Transfer request shape

All Create Transfer examples use the same top-level shape:
  • amount
  • source
  • destination
No wrappers. No alternate key names. No camelCase.

​
Canonical JSON (minimum shape)

{
  "amount": { "value": "100", "currency": "USD" },
  "source": {
    "value_type": "usd",
    "transfer_type": "wire"
  },
  "destination": {
    "address_id": "2VcUIonJeVQzFoBuC7LdFT0dRe4",
    "value_type": "SBC",
    "transfer_type": "solana"
  }
}

​
Notes

  • amount.value is a decimal string (avoid floats).
  • source and destination include value_type and transfer_type.
  • address_id is required when a leg targets a specific address (wallet, Plaid-linked bank account, external bank destination, etc.).
  • address_id is omitted for rails where Brale returns deposit instructions for funding (e.g., wire onramp-style sources).
Reminder: Include an Idempotency-Key header on create POSTs, and reuse the same key on retries of the same logical request.

​
Automations exception (where it differs)

Automations are rules that generate transfers later when funds arrive. They differ from Create Transfer:
  • No amount (amount is determined by the inbound deposit)
  • source does not include transfer_type or address_id
  • Additional required field: name

​
Canonical Create Automation request shape

{
  "name": "Customer Onramp",
  "source": {
    "value_type": "usd"
  },
  "destination": {
    "address_id": "35LWXNTO2jem13nXCLyciFdi162",
    "value_type": "SBC",
    "transfer_type": "solana"
  }
}
Note: When an automation becomes active, Brale populates source.funding_instructions with bank details (routing/account number, beneficiary, memo rules, etc.). Those are the coordinates you share to fund the automation.

​
Pagination standard

List endpoints that paginate use:
  • page[size]
  • page[next]
  • page[prev]

​
Rules

  • page[size] is an integer in the range 1..100.
  • page[next] is the cursor token from pagination.next.
  • page[prev] is the cursor token from pagination.prev.
  • Include at most one of page[next] or page[prev] in a request.

​
Examples

First page: 
curl --request GET \
  --url "https://api.brale.xyz/accounts/${account_id}/transfers?page[size]=50" \
  --header "Authorization: Bearer ${token}"
Next page: 
curl --request GET \
  --url "https://api.brale.xyz/accounts/${account_id}/transfers?page[size]=50&page[next]=${pagination_next}" \
  --header "Authorization: Bearer ${token}"
Previous page: 
curl --request GET \
  --url "https://api.brale.xyz/accounts/${account_id}/transfers?page[size]=50&page[prev]=${pagination_prev}" \
  --header "Authorization: Bearer ${token}"

​
Testnet terminology

Use testnet as the only term for the non-production environment.
  • Say testnet and mainnet (when contrast is needed).
  • Do not call the environment “sandbox.”
  • Only testnet networks are supported in testnet (e.g., sepolia, solana_devnet, base_sepolia).
Warning: In docs prose, examples, and headings: use testnet. Never name an environment “sandbox.”

​
9-point author checklist (prevents copy/paste failures)

  1. IDs are KSUIDs: treat IDs as opaque; don’t parse or validate by length.
  2. Correct ID names: use account_id, address_id, transfer_id, automation_id in examples (never camelCase).
  3. Snake_case everywhere: no valueType, transferType, etc.
  4. value_type is exact: copy API ids from Coverage → Value Types (case-sensitive).
  5. transfer_type is exact: copy API ids from Coverage → Transfer Types (lowercase; use testnet variants on testnet).
  6. Create Transfer is canonical: top-level keys are exactly amount, source, destination.
  7. address_id usage is correct: include it when a leg targets a specific address; omit it only when Brale returns deposit instructions for funding.
  8. Automations follow the exception: include name; omit amount; source is only { "value_type": "usd" }.
  9. Idempotency is correct: include Idempotency-Key on create POSTs, reuse on retries of the same request, and do not send it on GETs.