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

# 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` ](/coverage/value-types)
* Transfer Types: [ `/coverage/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)

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```bash theme={null}
curl --request GET \
  --url "https://api.brale.xyz/accounts/${account_id}/transfers?page[size]=50" \
  --header "Authorization: Bearer ${token}"
```

Next page:

```bash theme={null}
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:

```bash theme={null}
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.