Example Standard

Brale API conventions used across docs and examples — IDs, enum casing, SBC placeholder, canonical Create Transfer shape, automations exception, pagination, and testnet terminology.

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:

• Value Types: /coverage/value-types
• Transfer Types: /coverage/transfer-types

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:

Resource	Use this name
Account	account_id
Address	address_id
Transfer	transfer_id
Automation	automation_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.