openapi: 3.0.3 info: title: Brale Issuance and Orchestration API version: 2.3.1 description: | Brale supports stablecoin issuance and orchestration, enabling businesses and ecosystems to create their own stablecoins and convert between fiat and stablecoins seamlessly. From stablecoin onramps, offramps, and swaps to custody and payouts, the Brale API makes it easy to build stablecoin-enabled products. NOTE: All resource IDs (including account_id, address_id, financial_institution_id, and automation_id) are KSUIDs—27-character alphanumeric strings that are sortable by time. Examples showing UUIDs are incorrect. **What's new in 2.3.1** - Unified **Addresses** model for on-chain and off-chain endpoints - `Transfers` now accepts **address_id only** (no financial_institution_id) - Optional `brand` object to control bank statement presentation (`branding` still accepted as legacy alias) - Added off-chain rails: `ach_credit`, `same_day_ach_credit`, `ach_debit`, `same_day_ach_debit`, `rtp-credit` - Plaid endpoints moved to `/accounts/{account_id}/plaid/*` - `Financial Institutions` marked **deprecated** (migration path to **Addresses**) - Create Account now uses `CreateManagedAccountRequest` with `beneficial_owners`, `business_controller`, and `EndUserTosAttestation`. - Transfers now accept `brand` (replaces `branding`, still aliased in docs). - Plaid endpoints updated to return `address_id` and accept `transfer_types`. - Off-chain Address creation uses `CreateExternalAddressRequest` oneOf with bank + blockchain variants. - FI endpoints kept but marked deprecated; use Addresses instead. - `rtp_credit` is the canonical RTP rail name. **FedNow** - Added the `fednow_credit` rail. Outbound: create a Transfer with `destination.transfer_type: fednow_credit` to a bank Address that lists `fednow_credit` in `transfer_types`. Inbound: payers send FedNow credits to an active Automation's `source.funding_instructions`; Brale creates the Transfer automatically with `source.transfer_type: fednow_credit`. - Simulate a testnet FedNow deposit with `transfer_type: fednow` on `POST /accounts/{account_id}/automations/{automation_id}/simulations/deposits`. - `bank_address` and `beneficiary_address` are required only when an external bank Address requests `wire`. - FedNow availability depends on account enablement. tags: - name: Accounts description: Endpoints related to managing customer accounts (KYB, details, etc.) - name: Transfers description: Endpoints for creating and retrieving transfers (fiat to stablecoins, etc.) - name: Addresses description: On-chain and off-chain endpoints (custodial or external) represented by a single Addresses resource - name: Financial Institutions description: Legacy (deprecated) bank endpoints. Use Addresses instead. - name: Automations description: Automated deposit addresses or onramps - name: Plaid description: Bank linking and ACH debit via Plaid. - name: Orders description: Legacy tag used for transfers in older specs. servers: - url: https://api.brale.xyz description: Production server # ==================== Security (Global) ==================== # This ensures every endpoint requires a Bearer token. security: - BearerAuth: [] components: securitySchemes: BearerAuth: type: http scheme: bearer description: > Use the Bearer token returned from the Auth endpoint via OAuth2 client_credentials flow. Include the token in the "Authorization: Bearer " header. oauth: type: oauth2 flows: clientCredentials: tokenUrl: https://auth.brale.xyz/oauth2/token scopes: accounts:read: Read account details accounts:write: Create or update accounts addresses:read: Read address details addresses:write: Create addresses automations:read: Read automations automations:write: Create automations network:testnet: Access testnet-only operations, such as Automation deposit simulation financial-institutions:read: Read FI details (legacy) financial-institutions:write: Create FI (legacy) transfers:read: Read transfers transfers:write: Create transfers schemas: ## --------------------- KSUID SCHEMA --------------------- ## Ksuid: title: Kusid type: string format: ksuid pattern: ^[a-zA-Z0-9]{27}$ example: 2VcUIIsgARwVbEGlIYbhg6fGG57 ExternalAddressResponseStreetAddress: title: ExternalAddressResponseStreetAddress type: object description: US street address as returned in external address responses. Includes `country`, unlike the request `USStreetAddress` schema. properties: street_line_1: type: string example: 100 Example St street_line_2: type: string nullable: true example: Suite 500 city: type: string example: Springfield state: type: string example: CA zip: type: string example: '90001' country: type: string example: US ExternalAddressResponse: title: ExternalAddressResponse type: object description: The full external address object returned by `POST /accounts/{account_id}/addresses/external`. properties: id: $ref: '#/components/schemas/Ksuid' name: type: string nullable: true example: checking 7890 owner: type: string example: Jane Doe status: type: string example: active ownership: type: string example: customer-owned account_holder_type: type: string nullable: true enum: - individual - business description: Whether the bank account is held by an individual or a business. `null` if it was not set. example: business date_of_birth: type: string nullable: true description: Recipient's date of birth, masked to the year (`YYYY-**-**`). Brale never returns the full date. `null` if no date of birth is on file. example: '1990-**-**' bank_address: allOf: - $ref: '#/components/schemas/ExternalAddressResponseStreetAddress' nullable: true beneficiary_address: allOf: - $ref: '#/components/schemas/ExternalAddressResponseStreetAddress' nullable: true created: type: string format: date-time example: '2026-06-02T20:01:02.226850Z' transfer_types: type: array items: type: string example: - ach_credit account_number: type: string description: Returned masked (e.g. `****7890`). example: '****7890' account_type: type: string enum: - checking - savings example: checking needs_update: type: boolean example: false last_updated: type: string format: date-time example: '2026-06-02T20:01:03.321461Z' routingNumber: type: string description: 'Note: this single field is currently returned in camelCase (`routingNumber`) while all other fields use snake_case.' example: '063108680' Pagination: title: Pagination description: Cursor-based pagination metadata type: object additionalProperties: false properties: page_size: type: integer example: 25 next: type: string nullable: true example: g3QAAAABdw... prev: type: string nullable: true example: g3QAAAABdw... required: - page_size ## --------------------- ACCOUNTS --------------------- ## AccountCreateRequest: type: object properties: business_name: type: string example: ABC Company Inc ein: type: string example: 111-11-1111 address: $ref: '#/components/schemas/AccountAddress' phone_number: type: string example: '2134678902' email: type: string format: email example: mark@example.com website: type: string example: abccompany.com ultimate_beneficial_owners: type: array items: $ref: '#/components/schemas/UltimateBeneficialOwner' required: - business_name - ein - address - phone_number - email - ultimate_beneficial_owners Account: title: Account type: object description: >- Summary representation of a customer account returned by GET /accounts and GET /accounts/{account_id}. Account creation requires KYB / business details (see `AccountCreateRequest` / `CreateManagedAccountRequest`), but account read and list responses return only this account summary and do not return sensitive KYB details. properties: id: $ref: '#/components/schemas/Ksuid' name: type: string description: Account / business display name returned by the API. example: ABC Company status: type: string description: KYB / onboarding status of the account. enum: - complete - pending - rejected example: complete created: type: string format: date-time description: When the account was created. example: '2026-01-01T00:00:00Z' updated: type: string format: date-time description: When the account was last updated. example: '2026-01-01T00:00:00Z' required: - id - name - status example: id: 2VcUIIsgARwVbEGlIYbhg6fGG57 name: ABC Company status: complete created: '2026-01-01T00:00:00Z' updated: '2026-01-01T00:00:00Z' AccountAddress: title: AccountAddress type: object properties: street_line_1: type: string example: 123 Main St street_line_2: type: string example: Apt C city: type: string example: Des Moines state: type: string example: Iowa zip: type: string example: '12345' required: - street_line_1 - city - state - zip UltimateBeneficialOwner: title: UltimateBeneficialOwner type: object properties: name: type: string example: John Doe ssn: type: string example: 222-22-2222 address: $ref: '#/components/schemas/AccountAddress' required: - name - ssn - address ## --------------------- TRANSFERS --------------------- ## Transfer: title: Transfer type: object description: >- A money movement between a source and a destination. Returned by the create, get, and list transfer endpoints. The same shape is used everywhere a Transfer is exposed to API consumers. properties: id: $ref: '#/components/schemas/Ksuid' status: type: string description: Lifecycle stage of the transfer enum: - pending - processing - complete - canceled - failed - refunding - refunded example: pending failure: allOf: - $ref: '#/components/schemas/TransferFailure' nullable: true description: >- Structured failure details for a failed transfer. Usually `null`. Populated when `status` is `failed` and Brale has structured failure details for the transfer — most commonly for ACH returns, outbound wire returns, and other rail/provider failures. Clients should not assume `failure` is always present for every failed transfer; check for `null` before reading nested fields. example: null source: $ref: '#/components/schemas/TransferEndpoint' destination: $ref: '#/components/schemas/TransferEndpoint' amount: $ref: '#/components/schemas/Amount' note: type: string nullable: true description: Optional free-form note attached to the transfer. example: null brand: type: object nullable: true additionalProperties: false description: >- The Account the transfer was branded as, or `null` when the transfer was not branded. Returned on the create, get, and list transfer endpoints. Use it to confirm that the `brand` you requested was applied. A transfer created with `brand` can still return `null` if Brale sent it unbranded. required: - account_id properties: account_id: type: string description: ID of the Account whose identity was used as the brand. example: null created_by: allOf: - $ref: '#/components/schemas/TransferCreatedBy' nullable: true description: >- Who created the transfer, or `null` when the creator is not one of the exposed types. Returned on the create, get, and list transfer endpoints, on the simulate Automation deposit response, and in the `data` object of `transfer.completed` and `transfer.canceled` webhooks. example: type: automation id: 3AjRnDClEzwuCKlRioG3OXMS4pH automation_id: allOf: - $ref: '#/components/schemas/Ksuid' description: >- ID of the Automation that created this transfer, when applicable. Omitted for transfers created directly via the API. nullable: true funding_simulated: type: boolean description: >- Optional. When returned with a value of `true`, the source funding for this transfer was simulated in testnet rather than coming from a real payment. Not every simulated transfer is guaranteed to include this field. Not present for production-funded transfers. created_at: type: string format: date-time example: '2026-01-01T00:00:00Z' updated_at: type: string format: date-time example: '2026-01-01T00:00:00Z' TransferCreatedBy: title: TransferCreatedBy type: object additionalProperties: false description: Who created a transfer. required: - type - id properties: type: type: string description: >- The kind of creator. `user`, `application`, and `automation` identify the Brale user, application, or Automation that created the transfer. `transfer` means the transfer is an on-chain deposit. `brale` means Brale created the transfer. enum: - brale - user - application - automation - transfer example: automation id: type: string nullable: true description: >- ID of the creator. `null` when `type` is `brale`. When `type` is `transfer`, this is the chain and the deposit's on-chain transaction hash in the form `-`, not a Brale ID. example: 3AjRnDClEzwuCKlRioG3OXMS4pH TransferEndpoint: title: TransferEndpoint description: >- One side (source or destination) of a Transfer. The same shape is used in create requests and in responses. Response-only fields like `transaction_id` and `payment_details` are populated by Brale as the underlying leg settles. type: object properties: value_type: type: string example: USD transfer_type: type: string example: wire address_id: $ref: '#/components/schemas/Ksuid' financial_institution_id: type: string deprecated: true description: Legacy — use `address_id`. wire_memo: type: string description: >- Optional memo or payment reference text sent with outbound wire transfers. Only applies when `transfer_type` is `wire` on the destination leg. transaction_id: type: string description: >- On-chain transaction hash or off-chain payment reference. Present in responses once the leg has been submitted to the network. Not included in create requests. example: '0xdd5646ea…' payment_details: $ref: '#/components/schemas/PaymentDetails' required: - value_type - transfer_type PaymentDetails: title: PaymentDetails type: object description: >- Underlying payment metadata for a transfer leg. Response-only. Appears on `source.payment_details` for inbound fiat-funded transfers (wire, ACH, and FedNow) and on `destination.payment_details` for outbound wire and ACH transfers. Optional and may be absent depending on the rail and on whether the underlying bank metadata is available yet. Fields are rail-specific. For example, `imad` applies only to wires and `trace_number` only to ACH. Do not expect wire or ACH identifiers on `fednow_credit` legs. properties: received_at: type: string format: date-time nullable: true description: When the underlying payment was received or posted. example: '2026-04-07T00:01:24.514000Z' sender_name: type: string nullable: true description: Name of the originating sender, when available. example: Originator Name sender_bank_name: type: string nullable: true description: Originating bank name, when available. example: JPMorgan Chase Bank sender_bank_routing_number: type: string nullable: true description: Originating bank routing number, when available. example: '000000123' payment_reference: type: string nullable: true description: >- Sender-provided payment reference or memo, when available. For inbound wires, Brale may also populate this field from "Instruction for Creditor Agent," which some banks label "Message to receiving bank." This fallback is used only when no existing memo, Originator-to-Beneficiary Information (OBI), or remittance reference is available. Existing reference precedence is preserved. example: Simulated Wire imad: type: string nullable: true description: Wire IMAD / tracking identifier, when available. example: 20260406XOIZJDPP953495 trace_number: type: string nullable: true description: >- ACH trace identifier for the underlying payment, when available. Appears on `source.payment_details` for inbound ACH-funded transfers and on `destination.payment_details` for outbound ACH transfers (`ach_credit` and `same_day_ach_credit`) once the trace number is assigned. example: '021000029876543' sent_at: type: string format: date-time nullable: true description: >- When the outbound payment was sent, when available. Appears on `destination.payment_details` for outbound wire and ACH transfers. example: '2026-04-07T00:04:58.000000Z' TransferFailure: title: TransferFailure type: object description: >- Structured failure details for a failed transfer. Populated by Brale when `status` is `failed` and the underlying rail/provider has supplied structured failure details. Field availability varies by rail — for example, `ach_return` is only present for ACH returns and `wire_return` is only present for outbound wire returns. Do not require rail-specific fields for other failure types. properties: type: type: string description: >- Error classification for the failure, for example `ach_return` or `wire_return`. example: ach_return occurred_at: type: string format: date-time description: >- When Brale recorded the failure. This is not necessarily the exact time the bank returned the payment. example: '2026-04-07T00:05:12.102000Z' retriable: type: boolean description: >- Whether the failure is considered retriable. When `true`, Brale may automatically retry the underlying operation; when `false`, the failure is permanent. example: false ach_return: type: object nullable: true description: >- ACH-only return details. Present for ACH return failures; `null` or not set for wire returns, on-chain failures, and other rail failures. properties: code: type: string description: ACH return code (e.g. `R01` — Insufficient Funds). example: R01 reason: type: string description: Human-readable description of the ACH return reason. example: Insufficient Funds category: type: string description: >- Simplified taxonomy of the ACH return. `administrative` covers bank issues that may be retriable. `unauthorized` covers customer disputes. `general` covers everything else. enum: - administrative - unauthorized - general example: administrative wire_return: type: object nullable: true description: >- Wire-only return details. Present when `type` is `wire_return` for a returned outbound wire; `null` or not set for other failures. Has no `category` field; the ACH return taxonomy does not apply. properties: code: type: string description: >- The provider's wire return reason code when available (for example, `AC04`). When the provider supplies no code, Brale sets `WIRE_RETURN`, a Brale fallback marker that is not an ISO 20022 bank reason code. example: AC04 reason: type: string nullable: true description: Human-readable return reason, when available. example: Account closed TransfersList: title: TransfersList description: List of transfers plus pagination cursors type: object additionalProperties: false properties: pagination: $ref: '#/components/schemas/Pagination' transfers: type: array items: $ref: '#/components/schemas/Transfer' required: - pagination - transfers example: pagination: next: g3QAAAABdw... prev: null page_size: 25 transfers: - id: 30NoY6R1Ns2tRBcx1Kb16SnuXOW status: complete failure: null source: transaction_id: "0xdd5646ea\u2026" address_id: "2MhCCIHu\u2026" value_type: USDC transfer_type: polygon destination: transaction_id: "0xdd5646ea\u2026" address_id: "2O6asmN\u2026" value_type: USDC transfer_type: polygon amount: value: '100.00' currency: USD note: null brand: null created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' TransferCreateRequest: title: TransferCreateRequest type: object properties: amount: type: object properties: value: type: string example: '100' currency: type: string example: USD required: - value - currency source: $ref: '#/components/schemas/TransferEndpoint' destination: $ref: '#/components/schemas/TransferEndpoint' brand: $ref: '#/components/schemas/BrandData' description: >- Selects whose verified Account identity the counterparty sees. On ACH transfers it controls the name on bank statement line items. On outbound wires it selects the wire sender (originator). Legacy alias `branding` is still accepted but deprecated. required: - amount - source - destination GetAddressesResponse: type: object properties: addresses: type: array items: $ref: '#/components/schemas/Address' Address: title: Address type: object properties: id: $ref: '#/components/schemas/Ksuid' status: type: string enum: - pending - active - archived example: active name: type: string example: Solana Custodial Wallet address: type: string description: The on-chain wallet address example: 73uyt9HkEqx9bThYXWaUBP67sWsiJEsyJ5rSCieDx5me transfer_types: type: array items: type: string example: - solana - base - wire AddressReference: title: AddressReference type: object additionalProperties: false properties: id: $ref: '#/components/schemas/Ksuid' address: type: string nullable: true description: On-chain address for wallets. `null` for bank addresses. example: '0xb518d4d6221d9a41d23d71cbce8e106e7aab8f9b' account_number: type: string nullable: true description: Masked bank account number for bank addresses, for example `****1234`. Brale never returns the full account number. `null` or omitted for wallets. example: '****1234' required: - id Amount: title: Amount type: object description: Monetary value with explicit currency additionalProperties: false properties: value: type: string example: '11234.88' currency: type: string example: USD required: - value - currency AddressBalanceResponse: title: AddressBalance type: object additionalProperties: false description: Balance of **one** token on **one** chain for a custodial wallet, or the USD balance of a Plaid-linked bank address. properties: address: $ref: '#/components/schemas/AddressReference' balance: $ref: '#/components/schemas/Amount' transfer_type: type: string description: Blockchain network for wallets (for example, `solana` or `base`), or `ach_debit` for a Plaid-linked bank. example: solana value_type: type: string description: Token ticker for wallets (for example, `SBC`), or `USD` for a Plaid-linked bank. example: SBC required: - address - balance - value_type - transfer_type example: address: id: 2VcUIIsgARwVbEGlIYbhg6fGG57 address: 73uyt9HkEqx9bThYXWaUBP67sWsiJEsyJ5rSCieDx5me balance: value: '100.00' currency: SBC transfer_type: solana value_type: SBC Balance: title: Balance type: object properties: balance: type: string example: '100' value_type: type: string example: SBC AddressCreateRequest: oneOf: - $ref: '#/components/schemas/ExternalAddressOnchainCreate' - $ref: '#/components/schemas/ExternalAddressOffchainCreate' GetFinancialInstitutionsResponse: type: object properties: financial_institutions: type: array items: $ref: '#/components/schemas/FinancialInstitution' FinancialInstitutionCreateRequest: title: FinancialInstitutionCreateRequest type: object properties: name: type: string example: Business Checking Account transfer_type: type: array items: type: string example: - ach - wire bank_details: $ref: '#/components/schemas/BankDetails' required: - name - transfer_type - bank_details FinancialInstitution: title: FinancialInstitution type: object properties: id: $ref: '#/components/schemas/Ksuid' name: type: string example: Business Checking Account status: type: string enum: - processing - active - archived example: active bank_details: $ref: '#/components/schemas/BankDetails' BankDetails: title: Bank type: object properties: owner: type: string example: Jane Doe account_number: type: string example: '1234567890' routing_number: type: string example: 063108680 name: type: string description: The name of the bank example: Example Bank address: $ref: '#/components/schemas/AccountAddress' account_type: type: string example: checking required: - owner - account_number - routing_number - name - account_type AutomationCreateRequest: title: AutomationCreateRequest type: object properties: name: type: string example: XYZ Onramp source: $ref: '#/components/schemas/AutomationCreateSource' destination: $ref: '#/components/schemas/AutomationDestination' brand: $ref: '#/components/schemas/AutomationBrand' required: - name - source - destination AutomationCreateSource: title: AutomationCreateSource type: object description: >- The funding source to configure when creating an automation. Set `value_type: USD` to accept fiat deposits. Do not send funding instructions. Brale populates `source.funding_instructions` in the Automation response once the automation becomes active. properties: value_type: type: string description: The fiat value type accepted by the automation (e.g. `USD`). example: USD transfer_type: type: string nullable: true description: >- Optional. Omit this field to accept every inbound rail enabled for the virtual account. required: - value_type AutomationBrand: title: AutomationBrand type: object description: >- Optional. Selects the verified identity shown as the beneficiary on the automation's funding instructions. Pass the account_id of your own account or a managed account (business or individual). Both custodial and transactional accounts can be used, subject to applicable verification and program eligibility. The automation is still created under the account in the request path; `brand.account_id` only controls the identity rendered on the funding instructions. If omitted, Brale is the default beneficiary. properties: account_id: $ref: '#/components/schemas/Ksuid' description: >- The account whose verified identity appears as the beneficiary on wire and ACH funding instructions. For a business account, this is the business name and address. For an individual account, this is the individual's legal name and address. required: - account_id AutomationSource: title: AutomationSource type: object description: >- The funding source for the automation. Set `value_type: USD` to accept fiat deposits. You do not need to select a deposit rail: a USD Automation's virtual account accepts the inbound rails enabled for your account (wire, ACH, and FedNow where enabled). When the automation becomes active, `funding_instructions` is populated with the virtual account details to share with the payer. This is Automation configuration. The rail of each deposit is reported on the resulting Transfer's `source.transfer_type` (for example, `fednow_credit`), not here. properties: value_type: type: string description: The fiat value type accepted by the automation (e.g. `USD`). example: USD transfer_type: type: string nullable: true description: >- Optional. Omit this field to accept every inbound rail enabled for the virtual account. Responses may return `null`. Do not set it to restrict deposits to FedNow. A null value does not mean FedNow is unavailable. example: null funding_instructions: $ref: '#/components/schemas/FundingInstructions' required: - value_type AutomationDestination: title: AutomationDestination type: object description: >- The destination wallet that receives minted stablecoins when the automation is funded. properties: address_id: $ref: '#/components/schemas/Ksuid' value_type: type: string description: The stablecoin value type minted to the destination (e.g. `SBC`). example: SBC transfer_type: type: string description: The destination chain or rail (e.g. `solana`). example: solana required: - address_id - value_type - transfer_type Automation: title: Automation type: object properties: id: $ref: '#/components/schemas/Ksuid' name: type: string example: XYZ Onramp status: type: string description: The current lifecycle state of the automation. enum: - pending - active - disabled - archived example: active source: $ref: '#/components/schemas/AutomationSource' destination: $ref: '#/components/schemas/AutomationDestination' created_at: type: string format: date-time example: '2024-01-15T12:34:56Z' updated_at: type: string format: date-time example: '2024-01-15T12:34:56Z' brand: $ref: '#/components/schemas/AutomationBrand' FundingInstructions: title: FundingInstructions type: object description: >- Bank details for the virtual account that funds the automation. Populated by Brale once the automation becomes active. Share these coordinates with the payer to fund the automation. properties: beneficiary_name: type: string example: Jane Business bank_name: type: string example: Example Bank bank_address: type: string example: 456 Commerce St., Des Moines, IA 50309 beneficiary_address: type: string example: 612 Commerce St., Des Moines, IA 50309 account_number: type: string description: >- Bank account number to fund the automation. On testnet, this field contains the automation's alphanumeric ID as a placeholder, not a numeric bank account number. This applies to both branded and unbranded automations. example: '123456789' routing_number: type: string example: '063108680' GetAutomationsResponse: title: AutomationListResponse type: object properties: automations: type: array items: $ref: '#/components/schemas/Automation' TransferType: type: string description: | Rail or chain identifier. See [Transfer types](/coverage/transfer-types) for the full list of supported values. On input, `tx`, `tx_testnet`, `verona`, and `verona_testnet` are accepted as aliases for `coreum`, `coreum_testnet`, `xion`, and `xion_testnet`. Responses always return the canonical identifier (for example, `coreum`). enum: - wire - ach_credit - same_day_ach_credit - ach_debit - same_day_ach_debit - rtp_credit - fednow_credit - solana - ethereum - polygon - base - arbitrum - canton - avalanche - base_sepolia - sepolia - solana_devnet - tempo_testnet - stellar - spark - spark_testnet - xrp_ledger ExternalAddressOnchainCreate: type: object required: - name - transfer_types - address properties: name: type: string transfer_types: type: array items: $ref: '#/components/schemas/TransferType' description: Must include a supported chain (e.g., ethereum, base, solana, xrp_ledger) address: type: string description: On-chain wallet address ExternalAddressOffchainCreate: type: object required: - transfer_types properties: name: type: string owner: type: string description: Account owner/beneficiary name transfer_types: type: array items: $ref: '#/components/schemas/TransferType' description: One or more rails (wire, ach_credit, same_day_ach_credit, ach_debit, same_day_ach_debit, rtp_credit, fednow_credit) plaid_token: type: string description: Required when using ach_debit or same_day_ach_debit account_number: type: string routing_number: type: string account_type: type: string enum: - checking - savings bank_address: $ref: '#/components/schemas/AccountAddress' beneficiary_address: $ref: '#/components/schemas/AccountAddress' email: type: string format: email TransferBranding: type: object properties: account_id: type: string description: Account whose name should appear on bank statement line items DateTime: type: string format: date-time title: DateTime description: ISO-8601 timestamp that includes date and time example: '2020-01-01T12:00:00Z' USStreetAddress: type: object additionalProperties: false title: USStreetAddress required: - street_line_1 - city - state - zip properties: street_line_1: type: string example: 100 Example St. street_line_2: type: string example: Suite 500 city: type: string example: Springfield state: type: string example: CA zip: type: string example: '90001' BusinessAddress: type: object additionalProperties: false title: BusinessAddress description: > Business address. `state` is absent from `required` because whether it is required depends on `country`: a US business must supply a recognized US state or territory, and elsewhere it is optional and free-form. required: - street_line_1 - city - zip properties: street_line_1: type: string example: 100 Example St. street_line_2: type: string example: Suite 500 city: type: string example: Springfield state: type: string description: > State, province, or region. When the business's country is US or omitted this is required and must be a US state or territory, by abbreviation or full name (`CA`, `California`, `PR`). Optional and free-form otherwise. example: CA zip: type: string description: Postal code (any format). example: '90001' country: type: string description: > ISO 3166-1 alpha-2 country code of the business. Defaults to `US` when omitted. Determines jurisdiction coverage for the account. A non-US business in an approved country can be created as a transactional account, or as a custodial account if it sends `regulatory_profile`. example: US ControllingPartyAddress: type: object additionalProperties: false title: ControllingPartyAddress description: > Postal address for a business controller or beneficial owner. `state` is free-form and the postal code accepts any format, so controlling parties outside the US are supported. `state` is absent from `required` because whether it is required depends on `country`, which this schema cannot express: a US party must supply a recognized US state, and elsewhere it is optional because many countries have no state or province. required: - street_line_1 - city - zip properties: street_line_1: type: string example: Calle 93 #11-27 street_line_2: type: string example: Oficina 402 city: type: string example: Bogota state: type: string description: > State, province, or region. Required when `country` is the US, optional otherwise. A blank value is treated as absent. example: Cundinamarca zip: type: string description: Postal code. Any format is accepted, so non-US postal codes are supported. example: '110221' country: type: string description: > ISO 3166-1 country code or country name. Defaults to `US` when omitted, so requests written before non-US parties were supported are unchanged. example: CO ControllingParty: type: object additionalProperties: false title: ControllingParty description: > A business controller or beneficial owner. Identity is supplied one of two ways, and exactly one of them is required: `ssn` for a US party, which is what every request written before non-US parties were supported already sends, or `identity` (number and type) otherwise. `ssn` is only accepted when the party's country is the US, since an SSN has no meaning elsewhere. A US party may also use `identity` when the document is something other than an SSN. required: - first_name - last_name - dob - address - email - phone_number properties: first_name: type: string example: John last_name: type: string example: Doe dob: type: string example: YYYY-MM-DD ssn: type: string example: 123-45-6789 description: > US Social Security Number. Required for a US party unless `identity` is supplied, and not accepted for a party outside the US. identity: allOf: - $ref: '#/components/schemas/IndividualIdentity' nullable: true description: > Typed identity document, a number and the kind of document it came from. Required for a party outside the US, where the number could be a passport, a national ID or a tax number and the type is what keeps it from being submitted as an SSN. Mutually exclusive with `ssn`. address: $ref: '#/components/schemas/ControllingPartyAddress' email: type: string example: a@b.com phone_number: type: string example: 515-555-1212 description: > Parsed against the party's own country, so a number written in national form outside the US is accepted and stored in E.164. ownership_percentage: type: number nullable: true example: 40 RegulatoryProfile: type: object additionalProperties: false title: RegulatoryProfile description: > Optional. Send only for a regulated business, for example a money services business (MSB) or a virtual asset service provider (VASP). Sending it declares the business regulated; omitting it means the business is not regulated. Required for a non-US business custodial account. Declaring the business regulated is not approval: Brale requests supporting regulatory documents and verifies the license during verification. Business path only; sending it on the individual path returns `400 unexpected_business_fields`. properties: regulator: type: string description: > The authority the business is licensed or registered with. Required and must be non-blank when `regulatory_profile` is sent; otherwise the request returns `400 regulator_required`. example: FINTRAC license_number: type: string description: > The license or registration number that `regulator` issued. Required and must be non-blank when `regulatory_profile` is sent; otherwise the request returns `400 license_number_required`. example: M12345678 EndUserTosAttestation: type: object additionalProperties: false title: EndUserTosAttestation required: - accepted_at properties: accepted_at: $ref: '#/components/schemas/DateTime' ip: type: string example: 203.0.113.42 user_agent: type: string example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:138.0) Gecko/20100101 Firefox/138.0 version: type: string example: '2025-04-01' CreateManagedAccountRequest: type: object additionalProperties: false title: CreateManagedAccountRequest description: > Business (KYB) account creation payload. This is the default path when `entity_type` is omitted, or when it is explicitly set to `business`. `account_type` selects between a custodial account (the default) and a non-custodial transactional account. A business outside the US sends its country in `address.country`; see `BusinessAddress`. It can be created as a transactional account, or as a custodial account if it is a regulated business in an approved country and sends `regulatory_profile`. required: - business_name - ein - address - phone_number - email - website - business_controller - tos_attestation properties: entity_type: type: string enum: - business description: > Optional discriminator. When omitted, defaults to `business`. example: business account_type: type: string enum: - custodial - transactional description: > Optional. When omitted, defaults to `custodial` for business accounts. `custodial` accounts receive Brale-managed internal wallets and can hold balances. Business custodial accounts are available in supported US states, and outside the US only to regulated businesses in approved countries that send `regulatory_profile`; any other non-US business custodial request returns `422 unsupported_jurisdiction`. `transactional` accounts are non-custodial: they receive no internal wallets, hold no balances at Brale, and register external destination-only addresses. example: custodial verification_mode: type: string enum: - standard - reliance description: > Optional. When omitted, defaults to `standard`. `reliance` is enabled per managing account by Brale and is not self-serve; a caller without it enabled receives `422 unsupported_account_combination`. example: standard business_name: type: string example: My Customer ein: type: string example: '123456789' address: $ref: '#/components/schemas/BusinessAddress' regulatory_profile: $ref: '#/components/schemas/RegulatoryProfile' beneficial_owners: type: array nullable: true items: $ref: '#/components/schemas/ControllingParty' ultimate_beneficial_owners: deprecated: true description: Deprecated alias of beneficial_owners. type: array items: $ref: '#/components/schemas/ControllingParty' business_controller: $ref: '#/components/schemas/ControllingParty' email: type: string example: a@b.com phone_number: type: string example: 515-555-1212 tos_attestation: $ref: '#/components/schemas/EndUserTosAttestation' website: type: string example: https://example.com name: type: string example: My Account doc_submission_ids: type: array description: Optional pre-staged verification document submission IDs to link on creation. items: $ref: '#/components/schemas/Ksuid' IndividualAddress: type: object additionalProperties: false title: IndividualAddress description: > Residential address for an individual account. When `individual.country` is `US` or `USA`, `state` is required and must be a US state or territory, as an abbreviation or full name (`CA`, `California`, and `PR` all work); otherwise the request returns `422 invalid_us_state`. A US territory is a US jurisdiction, not a separate country: send `country: US` with the territory in `state` (`PR`, `GU`, `AS`, `VI`, `MP`). For non-US individuals `state` is optional and free-form, since many countries have no state or province. `state` is absent from `required` because whether it is required depends on `individual.country`, which this schema cannot express. required: - street_line_1 - city - zip properties: street_line_1: type: string example: 123 Main St street_line_2: type: string example: Apt 4 city: type: string example: Des Moines state: type: string description: > State, province, or region. Required when `individual.country` is `US` or `USA`, and accepted as an abbreviation or full name (`CA`, `California`, `PR`); optional and free-form otherwise. A blank value is treated as absent. example: IA zip: type: string description: Postal code. Any format is accepted, so non-US postal codes are supported. example: '50309' country: type: string description: > Optional. The individual's jurisdiction is taken from the top-level `individual.country`, not from this field. example: US IndividualIdentity: type: object additionalProperties: false title: IndividualIdentity description: > A government-issued identifier for a natural person. One identity is submitted per person: `SSN9` for a US taxpayer, or a document type such as `PASSPORT` or `NATIONAL_ID` for someone outside the US. Used by an individual account and, as `identity`, by a controlling party. required: - number - type properties: number: type: string example: 222-22-2222 description: The identifier value (for `SSN9`, the 9-digit Social Security number). type: type: string enum: - SSN9 - SSN4 - DRIVER_LICENSE - PASSPORT - NATIONAL_ID - VOTER_ID - BVN - NIN - NIN_SLIP - SSNIT - TAX_ID - KENYA_KRA_PIN - ALIEN_CARD - RESIDENT_ID - COLOMBIA_PPT - GHANA_CARD_NUMBER example: SSN9 description: The kind of identifier submitted. Individual: type: object additionalProperties: false title: Individual required: - first_name - last_name - date_of_birth - email - phone_number - country - address - identity properties: first_name: type: string example: Jane last_name: type: string example: Doe date_of_birth: type: string description: ISO date, `YYYY-MM-DD`. example: '1990-01-01' email: type: string example: jane@example.com phone_number: type: string example: '2125550182' country: type: string description: > Top-level jurisdiction used for verification. Separate from `address`. When `US` or `USA`, `address.state` must be a valid US state or territory. example: US address: $ref: '#/components/schemas/IndividualAddress' identity: $ref: '#/components/schemas/IndividualIdentity' CreateIndividualAccountRequest: type: object additionalProperties: false title: CreateIndividualAccountRequest description: > Individual (KYC) account creation payload, custodial or transactional. The request shape is identical for both account types. Business-only fields (`business_name`, `ein`, `website`, `business_controller`, `beneficial_owners`, `regulatory_profile`) must not be sent on this path; they are rejected with `400 unexpected_business_fields`. required: - entity_type - account_type - individual - tos_attestation properties: entity_type: type: string enum: - individual example: individual account_type: type: string enum: - custodial - transactional description: > `custodial` accounts receive Brale-custodied internal wallets and can hold balances at Brale; they are US-only. `transactional` accounts are non-custodial: they receive no custodial wallets and cannot create custodial addresses. example: transactional verification_mode: type: string enum: - standard - reliance description: > `standard` (default) or `reliance`. Use `reliance` when your integration operates under an agreement with Brale that specifies a reliance model. Reliance is enabled per managing account by Brale and is not self-serve; a caller without it enabled receives `422 unsupported_account_combination`. example: standard individual: $ref: '#/components/schemas/Individual' tos_attestation: $ref: '#/components/schemas/EndUserTosAttestation' name: type: string description: Optional display name. When omitted, the account's `name` is derived from the individual's first and last name. example: Jane Doe doc_submission_ids: type: array description: Optional pre-staged verification document submission IDs to link on creation. items: $ref: '#/components/schemas/Ksuid' CreateAccountRequest: title: CreateAccountRequest description: > Request body for `POST /accounts`. The three optional dimension fields `entity_type`, `account_type`, and `verification_mode` select which shape is validated. All eight combinations of `entity_type` (`business`, `individual`), `account_type` (`custodial`, `transactional`), and `verification_mode` (`standard`, `reliance`) are supported. Omitting all three fields creates a business custodial account with `standard` verification. `verification_mode: bypass` is not supported for any combination and returns `422 unsupported_account_combination`. `reliance` is enabled per managing account by Brale and is not self-serve; a caller without it enabled receives `422 unsupported_account_combination`. No `discriminator` is declared, because `entity_type` is optional: a request that omits it is a business account, and a discriminator would require the property to be present. The two branches resolve unambiguously without one, since both set `additionalProperties: false` and their required fields are disjoint. oneOf: - $ref: '#/components/schemas/CreateManagedAccountRequest' - $ref: '#/components/schemas/CreateIndividualAccountRequest' ErrorResponse: type: object title: ErrorResponse description: Standard Brale error envelope. required: - type properties: type: type: string description: Machine-readable error type identifier. example: unsupported_account_combination message: type: string description: Human-readable explanation of the error. example: The combination of entity_type, account_type, and verification_mode is not supported. SimulateAutomationDepositRequest: title: SimulateAutomationDepositRequest type: object description: >- Request body for simulating an inbound fiat deposit into a testnet Automation. additionalProperties: false properties: amount: allOf: - $ref: '#/components/schemas/Amount' description: >- Deposit amount. `value` must be a positive decimal string greater than zero. `currency` must be a reserve currency accepted by the API. example: value: '10.00' currency: USD transfer_type: type: string description: >- Inbound rail to simulate. This is a simulator input, not a Transfer rail identifier. `fednow` produces a Transfer with `source.transfer_type: fednow_credit`. enum: - ach - wire - fednow example: fednow required: - amount - transfer_type ApiErrorV2: title: ApiErrorV2 type: object description: Error envelope returned by newer Brale endpoints. required: - type properties: type: type: string description: Machine-readable error type identifier. example: automation_not_active detail: type: string description: Human-readable explanation of the error. example: Automation must be active to simulate a deposit code: type: string example: ValidationError status: type: integer example: 422 values: type: array items: type: string BrandData: type: object nullable: true additionalProperties: false description: >- Optional branding for a transfer. Supported for ACH transfers (`ach_debit`, `ach_credit`, `same_day_ach_credit`), outbound wire payouts (`destination.transfer_type: wire`), and FedNow payouts (`destination.transfer_type: fednow_credit`). Not supported for `rtp_credit`. Branding does not change which Account funds the transfer (the Account in the request path), the source or destination, or `destination.wire_memo`. Omit `brand` to send the transfer unbranded. See [Branded Transfers](/guides/2nd-and-3rd-party-transfers). required: - account_id properties: account_id: type: string description: >- ID of the verified Account whose identity is presented to the counterparty. For ACH, this is the name on bank statement line items. For outbound wires, this Account's verified identity is used as the wire sender (originator). This is an Account ID, not free-form display text. PaymentData: type: object additionalProperties: false title: PaymentData properties: address_id: type: string description: Preferred Address identifier financial_institution_id: type: string deprecated: true description: "Legacy\u2014use address_id" transfer_type: type: string value_type: type: string wire_memo: type: string description: >- Optional memo or payment reference text sent with outbound wire transfers. Only applies when transfer_type is wire. ach_description: type: string description: >- Optional short description shown after the sender name on the recipient's ACH bank statement. Set it on the ACH leg: `destination.ach_description` for payouts (`ach_credit`, `same_day_ach_credit`) and `source.ach_description` for `ach_debit`. Does not apply to `wire`, `rtp_credit`, or `fednow_credit`. Only the first 10 characters are used. Use letters, numbers, and spaces. Unsupported characters are removed and longer values are cut to 10 characters. If omitted, the description defaults to `PAYOUT` for payouts and `PAYMENT` for ACH debits. Independent of `brand`, which sets the sender name. Not currently returned on GET transfer responses. Exact display varies by receiving bank. required: - transfer_type - value_type CreateTransfer: type: object additionalProperties: false required: - amount - source - destination properties: amount: $ref: '#/components/schemas/Amount' source: $ref: '#/components/schemas/PaymentData' destination: $ref: '#/components/schemas/PaymentData' brand: $ref: '#/components/schemas/BrandData' note: type: string title: CreateTransfer CreateLinkTokenRequest: type: object title: CreateLinkTokenRequest properties: legal_name: type: string description: User's legal name example: John Doe email_address: type: string description: User's email address example: user@example.com phone_number: type: string description: User's phone number example: '+1234567890' date_of_birth: type: string description: User's date of birth example: '1990-01-01' client_name: type: string maxLength: 30 default: Brale description: Application name displayed to users in Plaid Link. Defaults to `Brale` when omitted. Values longer than 30 characters return a validation error. This value changes the displayed application name only. It does not change logos, colors, or ACH bank statement descriptors. example: Rhythmic LinkTokenResponse: type: object title: LinkTokenResponse required: - link_token - expiration - callback_url properties: link_token: type: string description: Plaid Link token example: link-sandbox-123456789 expiration: type: string description: ISO 8601 expiration example: '2024-01-01T12:00:00Z' callback_url: type: string description: URL to POST the public token to after Plaid Link example: https://customer.com/webhooks/plaid-updates RegisterAccountWithTransferTypesRequest: type: object title: RegisterAccountWithTransferTypesRequest required: - public_token - customer_webhook_url - transfer_types properties: public_token: type: string description: Plaid public token example: public-sandbox-123456789 customer_webhook_url: type: string format: uri description: Webhook for Plaid item updates example: https://customer.com/webhooks/plaid-updates transfer_types: type: array minItems: 1 items: type: string example: ach_credit description: Rails to enable (e.g., ach_credit, rtp_credit) account_holder_type: type: string enum: - individual - business description: > Optional. Whether the linked bank account is held by an individual or a business. Used when Plaid does not report the account holder category. If Plaid reports it, Plaid's value is used. RegisterAccountAddressResponse: type: object title: RegisterAccountAddressResponse required: - address_id properties: address_id: type: string description: ID of the created address example: addr_123456789 CreateExternalBlockchainAddressRequest: type: object additionalProperties: false title: CreateExternalBlockchainAddressRequest required: - name - address - transfer_types properties: name: type: string example: Company External EVM Address nullable: true address: type: string example: '0xb518d4d6221d9a41d23d71cbce8e106e7aab8f9b' transfer_types: type: array items: type: string example: solana CreateExternalFinancialInstitutionRequest: type: object additionalProperties: false title: CreateExternalFinancialInstitutionRequest description: > Address fields are conditional. `bank_address` and `beneficiary_address` are required when `transfer_types` includes `wire`. They are optional for `ach_credit`, `same_day_ach_credit`, `rtp_credit`, and `fednow_credit`. For addresses without `wire`, do not provide placeholder or generic bank addresses. Omit these fields unless you have accurate values. Requesting `fednow_credit` requires a routing number that participates in FedNow; otherwise Brale returns `422` `fednow_routing_number_not_supported`. required: - owner - account_number - routing_number - account_type - transfer_types properties: owner: type: string example: Jane Doe name: type: string example: First Last Bank account_number: type: string example: '123456789' routing_number: type: string example: '123456789' account_type: type: string example: checking enum: - checking - savings account_holder_type: type: string enum: - individual - business description: > Whether the bank account is held by an individual or a business. Optional. Determines the ACH SEC code for payouts to this address (`individual` → PPD, `business` → CCD). If omitted, Brale uses the entity type of the account that owns the address. Once set, it cannot be changed. example: business date_of_birth: type: string format: date description: > Optional. Date of birth of an individual recipient, in `YYYY-MM-DD` format. Accepted when `account_holder_type` is `individual` or not set. Sending it with `account_holder_type: business` returns `400` `date_of_birth_not_supported`. A malformed or future date returns `400` `validation_errors`. Responses return the date masked to the year (`1990-**-**`). example: '1990-01-31' bank_address: description: > Bank physical address. Required when `transfer_types` includes `wire`. Optional for `ach_credit`, `same_day_ach_credit`, `rtp_credit`, and `fednow_credit`. allOf: - $ref: '#/components/schemas/USStreetAddress' beneficiary_address: description: > Beneficiary physical address. Required when `transfer_types` includes `wire`. Optional for `ach_credit`, `same_day_ach_credit`, `rtp_credit`, and `fednow_credit`. allOf: - $ref: '#/components/schemas/USStreetAddress' transfer_types: type: array minItems: 1 description: > Rails to enable for this bank endpoint. If this array includes `wire`, the request must include `bank_address` and `beneficiary_address`. For addresses without `wire` (for example, ACH, RTP, or FedNow only), those address fields are optional. items: type: string example: ach_credit example: - ach_credit - rtp_credit - fednow_credit CreateExternalAddressRequest: type: object oneOf: - $ref: '#/components/schemas/CreateExternalBlockchainAddressRequest' - $ref: '#/components/schemas/CreateExternalFinancialInstitutionRequest' title: CreateExternalAddressRequest CreateInternalAddressRequest: type: object title: CreateInternalAddressRequest required: - transfer_types - name properties: transfer_types: type: array minItems: 1 items: type: string description: 'One or more transfer types that must all resolve to the same chain environment (e.g. `["ethereum","polygon"]` for EVM, `["stellar"]` for Stellar).' name: type: string nullable: true description: A human-readable name for the new internal address. paths: /accounts: get: tags: - Accounts operationId: listAccounts summary: Retrieve all accounts description: Returns an array of accounts. responses: '200': description: An array of accounts content: '*/*': schema: type: array items: $ref: '#/components/schemas/Account' post: tags: - Accounts operationId: createAccount summary: Create a customer account description: 'Creates a new customer (account) with the required KYC/KYB details. ' parameters: - in: header name: Idempotency-Key required: true schema: type: string example: idemp-123e4567-e89b-12d3-a456-426614174000 description: 'A unique string used to prevent duplicate operations. Each POST request must use a new idempotency key. Use a UUIDv4 string. Example: `idemp-123e4567-e89b-12d3-a456-426614174000` ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAccountRequest' examples: create_business_account: summary: Business account with controller + TOS attestation value: business_name: ABC Company Inc ein: 11-1111111 address: street_line_1: 100 Example St city: Des Moines state: IA zip: '50309' country: US phone_number: '5155550182' email: ops@abc.example website: https://abc.example beneficial_owners: - first_name: Jane last_name: Doe dob: '1980-05-12' ssn: 222-22-2222 email: jane@example.com phone_number: 212-555-0182 address: street_line_1: 100 Example St city: Des Moines state: IA zip: '50309' country: US business_controller: first_name: Alicia last_name: Ng dob: '1986-07-14' ssn: 123-45-6789 email: alicia.ng@example.com phone_number: '+12125550182' address: street_line_1: 200 Market St city: Des Moines state: IA zip: '50310' country: US tos_attestation: accepted_at: '2025-05-13T20:45:15Z' version: '2025-04-01' ip: 203.0.113.42 user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ... name: My Account create_business_transactional_account_non_us: summary: Business (KYB) transactional account, non-US value: entity_type: business account_type: transactional business_name: Example Trading Ltd ein: '12345678' address: street_line_1: 10 Example Street city: London zip: EC1A 1BB country: GB phone_number: '+442071234567' email: ops@example.co.uk website: https://example.co.uk beneficial_owners: [] business_controller: first_name: Oliver last_name: Smith dob: '1985-03-14' email: oliver@example.co.uk phone_number: '+447700900123' address: street_line_1: 10 Example Street city: London zip: EC1A 1BB country: GB identity: number: '123456789' type: PASSPORT tos_attestation: accepted_at: '2026-05-13T20:45:15Z' version: '2025-04-01' create_business_custodial_account_regulated_non_us: summary: Business (KYB) custodial account, regulated non-US value: entity_type: business account_type: custodial verification_mode: standard business_name: Example Payments Inc ein: '123456789' address: street_line_1: 100 King Street West city: Toronto state: 'ON' zip: M5X 1A9 country: CA phone_number: '+14165550123' email: ops@example.ca website: https://example.ca regulatory_profile: regulator: FINTRAC license_number: M12345678 beneficial_owners: [] business_controller: first_name: Emma last_name: Tremblay dob: '1984-06-21' email: emma@example.ca phone_number: '+14165550188' address: street_line_1: 100 King Street West city: Toronto state: 'ON' zip: M5X 1A9 country: CA identity: number: AB123456 type: PASSPORT tos_attestation: accepted_at: '2026-05-13T20:45:15Z' version: '2025-04-01' create_individual_account: summary: Individual (KYC) transactional account value: entity_type: individual account_type: transactional verification_mode: standard individual: first_name: Jane last_name: Doe date_of_birth: '1990-01-01' email: jane@example.com phone_number: '2125550182' country: US address: street_line_1: 123 Main St street_line_2: Apt 4 city: Des Moines state: IA zip: '50309' identity: number: 222-22-2222 type: SSN9 tos_attestation: accepted_at: '2026-05-13T20:45:15Z' version: '2025-04-01' ip: 203.0.113.42 user_agent: Mozilla/5.0 ... create_individual_custodial_account: summary: Individual (KYC) custodial account value: entity_type: individual account_type: custodial verification_mode: standard individual: first_name: Jane last_name: Doe date_of_birth: '1990-01-01' email: jane@example.com phone_number: '2125550182' country: US address: street_line_1: 123 Main St street_line_2: Apt 4 city: Des Moines state: IA zip: '50309' identity: number: 222-22-2222 type: SSN9 tos_attestation: accepted_at: '2026-05-13T20:45:15Z' version: '2025-04-01' create_individual_account_non_us: summary: Individual (KYC) transactional account, non-US value: entity_type: individual account_type: transactional individual: first_name: Amara last_name: Okafor date_of_birth: '1988-07-22' email: amara@example.com phone_number: '+2348012345678' country: NG address: street_line_1: 12 Awolowo Road city: Lagos state: Lagos zip: '101233' identity: number: '22222222222' type: BVN tos_attestation: accepted_at: '2026-05-13T20:45:15Z' version: '2025-04-01' responses: '201': description: Account successfully created content: '*/*': schema: type: object properties: id: $ref: '#/components/schemas/Ksuid' '400': description: > Bad request. Possible `type` values on the business path: - `regulator_required` — `regulatory_profile` was sent with `regulator` missing or blank. Permanent; safe to cache against an idempotency key. - `license_number_required` — `regulatory_profile` was sent with `license_number` missing or blank. Permanent; safe to cache against an idempotency key. Possible `type` values on the individual path: - `individual_details_required` — `entity_type: individual` was sent with no `individual` object. - `tos_attestation_required` — the individual path was used with no `tos_attestation`. - `unexpected_business_fields` — a business-only field (`business_name`, `ein`, `website`, `business_controller`, `beneficial_owners`, `regulatory_profile`) was sent on the individual path. - `invalid_attestation_timestamp` — `tos_attestation.accepted_at` is not an ISO-8601 timestamp. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: > Unprocessable entity. Possible `type` values on account creation: - `unsupported_account_combination` — the combination of `entity_type`, `account_type`, and `verification_mode` is not supported: any `verification_mode: bypass`, or `verification_mode: reliance` from a caller without reliance enabled. Permanent; safe to cache against an idempotency key. - `unsupported_jurisdiction` — Brale does not serve the applicant's jurisdiction for the requested account type (for example, a non-US individual custodial account, a non-US business custodial account without `regulatory_profile` or outside the approved countries, or a US state where the combination is unavailable). Permanent; safe to cache against an idempotency key. - `invalid_us_state` — `individual.country` is `US` or `USA` and `individual.address.state` is missing, blank, or not a recognized US state or territory (abbreviation or full name). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /accounts/{account_id}: get: tags: - Accounts operationId: getAccount summary: Retrieve a customer account description: Returns the details of a specific customer account, including KYB status. parameters: - name: account_id in: path required: true description: The ID of the account schema: $ref: '#/components/schemas/Ksuid' responses: '200': description: Details of the requested account content: '*/*': schema: $ref: '#/components/schemas/Account' /accounts/{account_id}/transfers: get: tags: - Transfers - Orders operationId: listTransfers summary: Get all transfers for a given account description: Returns a list of transfers associated with the specified account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the account - name: automation_id in: query required: false schema: $ref: '#/components/schemas/Ksuid' description: >- Filter transfers to only those created by the specified Automation. Must be a valid KSUID. Exact match. example: 2MhCCIHuK4TGVgT9a4loQzJx1rj - name: value_type in: query required: false schema: type: string description: >- Filter transfers by currency or token identifier. Matches transfers where the source **or** destination `value_type` equals this value. Case-sensitive. Use canonical API ids from the Coverage page. example: USDC - name: transfer_type in: query required: false schema: type: string description: >- Filter transfers by blockchain chain (for example, `solana`, `base`, `ethereum`). Fiat payment types (for example, `same_day_ach_credit`, `wire`, `fednow_credit`) are not supported as filter values. To find FedNow Transfers, filter by `automation_id` or `address_id` and check `source.transfer_type` or `destination.transfer_type`. example: polygon - name: transaction_id in: query required: false schema: type: string description: >- Filter transfers by on-chain transaction hash or off-chain payment reference. Exact match against the `transaction_id` field on either the source or destination leg. example: '0xdd5646ea…' - name: page[size] in: query required: false schema: type: integer minimum: 1 maximum: 100 example: 50 description: The number of transfers to return per page (1–100, default 25). - name: page[after] in: query required: false schema: type: string example: g3QAAAABdw... description: Cursor for the next page (value returned in `pagination.next`) - name: page[prev] in: query required: false schema: type: string example: g3QAAAABdw... description: Cursor for the previous page (value returned in `pagination.prev`) responses: '200': description: A list of transfers with pagination cursors content: '*/*': schema: $ref: '#/components/schemas/TransfersList' post: tags: - Transfers - Orders operationId: createTransfer summary: Create a new transfer description: Creates a new transfer using the specified source and destination details. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the account - in: header name: Idempotency-Key required: true schema: type: string example: idemp-123e4567-e89b-12d3-a456-426614174000 description: 'A unique string used to prevent duplicate operations. Each POST request must use a new idempotency key. Use a UUIDv4 string. Example: `idemp-123e4567-e89b-12d3-a456-426614174000` ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTransfer' examples: ach_debit_to_solana: summary: "Onramp via ACH debit \u2192 Mint on Solana" value: amount: value: '2500.00' currency: USD source: address_id: 2VcUIonJeVQzFoBuC7LdFT0dRe4 value_type: USD transfer_type: ach_debit destination: address_id: 35LWXNTO2jem13nXCLyciFdi162 value_type: SBC transfer_type: solana wire_offramp_with_brand: summary: "Burn on Polygon \u2192 Wire out (brand override)" value: amount: value: '10000.00' currency: USD source: address_id: 35LWXNTO2jem13nXCLyciFdi162 value_type: SBC transfer_type: polygon destination: address_id: 2MhCCIHulVdXrHiEuQDJvnKbSkl value_type: USD transfer_type: wire wire_memo: Invoice 1048 brand: account_id: 2VcUIIsgARwVbEGlIYbhg6fGG57 rtp_payout: summary: Stablecoin payout via RTP value: amount: value: '150.00' currency: USD source: address_id: 35LWXNTO2jem13nXCLyciFdi162 value_type: SBC transfer_type: ethereum destination: address_id: 2MhCCIHulVdXrHiEuQDJvnKbSkl value_type: USD transfer_type: rtp_credit fednow_payout: summary: Stablecoin payout via FedNow description: >- Pays out USD over FedNow from a funded Brale internal Address. The source `value_type` and `transfer_type` must match the token and network held by the source Address. The destination bank Address must be `active` and list `fednow_credit` in `transfer_types`. value: amount: value: '1.00' currency: USD source: address_id: 2VcUIonJeVQzFoBuC7LdFT0dRe4 value_type: USDB transfer_type: spark destination: address_id: 2MhCCIHulVdXrHiEuQDJvnKbSkl value_type: USD transfer_type: fednow_credit responses: '201': description: >- Transfer successfully created. Creation is not settlement. Track `status` until it reaches `complete`, `canceled`, or `failed`. content: '*/*': schema: $ref: '#/components/schemas/Transfer' '400': description: > The transfer amount is invalid. Known cases include: - `invalid_amount` with `detail` `Invalid transfer amount`: `amount.value` is not a number (for example, `"abc"`). - `invalid_amount` with `detail` `Amount must be greater than zero`: `amount.value` is zero or negative. - `invalid_amount_currency`: `amount.currency` is not supported for the account (for example, `BTC`). content: application/json: schema: $ref: '#/components/schemas/ApiErrorV2' '422': description: > The request is valid but cannot be processed. Known cases include `insufficient_balance` (the source Address does not hold enough of the source `value_type`) and reuse of an `Idempotency-Key` with a different body or URI. After funding the source Address, retry `insufficient_balance` with the same `Idempotency-Key` and body. For an `ach_debit` transfer, Brale can also reject the request when the source bank Address cannot be debited: - `bank_account_not_linked`: the bank account is not linked through Plaid. Link the bank account before using it for an ACH debit. - `bank_account_relink_required`: the bank account's Plaid link has expired. Have the user relink the bank account, then retry. - `bank_balance_unavailable`: Brale could not verify the bank account's balance. Retry, or relink the bank account if the error continues. - `insufficient_balance`: the transfer amount exceeds the bank account's available balance. For a branded transfer, Brale can also reject the request when the Account in `brand.account_id` can't be used as a brand: - `brand_account_not_verified`: the brand Account is not ready to be used as a brand. Contact support to resolve this, then retry. - `brand_account_update_required`: the brand Account can't be used for branded transfers yet. Contact support to resolve this, then retry with the same `Idempotency-Key` and body. Brale does not store this response for the key, so the same request succeeds once support has fixed the brand Account. content: application/json: schema: $ref: '#/components/schemas/ApiErrorV2' '503': description: > `brand_identity_unavailable`: Brale can't process branded transfers right now. Retry the same request with the same `Idempotency-Key` after a few minutes, and contact support if the error continues. Brale does not store this response for the key. content: application/json: schema: $ref: '#/components/schemas/ApiErrorV2' /accounts/{account_id}/transfers/{id}: get: tags: - Transfers operationId: getTransfer summary: Retrieve a single transfer description: Returns details for a specific transfer. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the account - name: id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the transfer (KSUID) responses: '200': description: A single transfer object content: '*/*': schema: $ref: '#/components/schemas/Transfer' /accounts/{account_id}/addresses: get: tags: - Addresses operationId: listAddresses summary: Fetch all addresses description: 'Retrieves all addresses (internal and external) associated with the given account. ' parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the account responses: '200': description: A list of addresses content: '*/*': schema: $ref: '#/components/schemas/GetAddressesResponse' /accounts/{account_id}/addresses/external: post: tags: - Addresses operationId: createAddress summary: Create a new external address description: 'Creates a non-custodial address (EOA) for the specified account. ' parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the account - in: header name: Idempotency-Key required: true schema: type: string example: idemp-123e4567-e89b-12d3-a456-426614174000 description: 'A unique string used to prevent duplicate operations. Each POST request must use a new idempotency key. Use a UUIDv4 string. Example: `idemp-123e4567-e89b-12d3-a456-426614174000` ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateExternalAddressRequest' examples: onchain_base: summary: On-chain (Base) value: name: Base External Wallet transfer_types: - base address: '0xE57e438aE0b1557bFC1ad70BD7751635E473D888' offchain_ach_credit: summary: Off-chain (ACH Credit / Same Day ACH Credit) value: owner: Jane Doe transfer_types: - ach_credit - same_day_ach_credit account_number: '1234567890' routing_number: '063108680' account_type: checking account_holder_type: business name: Example Bank offchain_rtp_credit: summary: Off-chain (ACH + RTP Credit) value: owner: Jane Doe transfer_types: - ach_credit - same_day_ach_credit - rtp_credit account_number: '1234567890' routing_number: '063108680' account_type: checking name: Example Bank offchain_individual_with_date_of_birth: summary: Off-chain (ACH Credit, individual recipient with date of birth) value: owner: Jane Doe transfer_types: - ach_credit account_number: '1234567890' routing_number: '063108680' account_type: checking account_holder_type: individual date_of_birth: '1990-01-31' name: Example Bank offchain_fednow_credit: summary: Off-chain (FedNow Credit, no postal addresses required) value: owner: Jane Doe transfer_types: - fednow_credit account_number: '0012345678' routing_number: '063108680' account_type: checking name: Example Bank offchain_wire: summary: Off-chain (Wire — requires bank_address and beneficiary_address) value: owner: Jane Doe transfer_types: - wire account_number: '1234567890' routing_number: '063108680' account_type: checking name: Example Bank bank_address: street_line_1: 100 Example St street_line_2: Suite 500 city: Springfield state: CA zip: '90001' beneficiary_address: street_line_1: 100 Example St street_line_2: Suite 500 city: Springfield state: CA zip: '90001' offchain_ach_debit: summary: Off-chain (ACH Debit via Plaid) value: name: Operating Account (ACH Debit) transfer_types: - ach_debit - same_day_ach_debit plaid_token: PUBLIC_TOKEN_EXCHANGED_WITH_BRALE responses: '201': description: External address successfully created content: '*/*': schema: $ref: '#/components/schemas/ExternalAddressResponse' examples: offchain_ach_credit: summary: Off-chain bank address (ACH Credit) value: id: 3EaxQ8mDX3RLdK9wvn1BAptMs6H name: checking 7890 owner: Jane Doe status: active ownership: customer-owned account_holder_type: business date_of_birth: null bank_address: null beneficiary_address: street_line_1: 100 Example St street_line_2: Suite 500 city: Springfield state: CA zip: '90001' country: US created: '2026-06-02T20:01:02.226850Z' transfer_types: - ach_credit account_number: '****7890' account_type: checking needs_update: false last_updated: '2026-06-02T20:01:03.321461Z' routingNumber: '063108680' '400': description: > Bad request. Date of birth cases: - `date_of_birth_not_supported`: `date_of_birth` was sent with `account_holder_type: business`. Brale does not create the address. - `validation_errors`: `date_of_birth` is malformed or in the future. The error response does not include the submitted value. content: application/json: schema: $ref: '#/components/schemas/ApiErrorV2' examples: date_of_birth_not_supported: summary: Date of birth sent for a business recipient value: type: date_of_birth_not_supported detail: date_of_birth can only be set when account_holder_type is individual or not set. code: ValidationError status: 400 '422': description: > The request is valid but cannot be processed. FedNow-related cases: - `fednow_routing_number_not_supported`: the `routing_number` does not participate in FedNow. Do not retry with the same body. Remove `fednow_credit` or use a FedNow-participating account. - `fednow_provider_registration_failed`: Brale could not register the recipient for FedNow with its banking provider. This can be temporary. Retry the same request with the same `Idempotency-Key` after a backoff. content: application/json: schema: $ref: '#/components/schemas/ApiErrorV2' examples: fednow_routing_number_not_supported: summary: Routing number does not support FedNow value: type: fednow_routing_number_not_supported detail: The routing number does not support FedNow. status: 422 fednow_provider_registration_failed: summary: FedNow recipient registration failed value: type: fednow_provider_registration_failed detail: The recipient could not be registered for FedNow. Try again later. status: 422 /accounts/{account_id}/addresses/internal: post: tags: - Addresses operationId: createInternalAddress summary: Create a new internal address description: 'Provisions an additional custodial (internal) address for the specified account. ' parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the account - in: header name: Idempotency-Key required: true schema: type: string example: idemp-123e4567-e89b-12d3-a456-426614174000 description: 'A unique string used to prevent duplicate operations. Each POST request must use a new idempotency key. Use a UUIDv4 string. Example: `idemp-123e4567-e89b-12d3-a456-426614174000` ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateInternalAddressRequest' examples: evm: summary: EVM (Ethereum + Polygon) value: name: My EVM Wallet transfer_types: - ethereum - polygon stellar: summary: Stellar value: name: Stellar Custodial Wallet transfer_types: - stellar responses: '201': description: Internal address successfully created content: '*/*': schema: $ref: '#/components/schemas/Address' examples: sync_active: summary: Synchronous (deterministic-address chain) value: id: 3EdBHmAtfm7tct7varYqgAz6iYW status: active name: My EVM Wallet address: '0xc109f7016aF02fBF21E9f0d7d50a6A48f5F644Ad' transfer_types: - ethereum - polygon async_pending: summary: Asynchronous (non-deterministic chain) value: id: 3EdBHmAtfm7tct7varYqgAz6iYW status: pending name: Hedera Custodial Wallet address: null transfer_types: - hedera /accounts/{account_id}/addresses/{address_id}: get: tags: - Addresses operationId: getAddress summary: Retrieve an address description: 'Retrieves a single address by address_id. Use this endpoint to fetch the latest status, address value, and enabled transfer_types for an internal or external address. For RTP-enabled bank addresses, inspect transfer_types to confirm whether rtp_credit has been added after asynchronous eligibility checks complete. Before sending a FedNow payout, confirm the address is active and transfer_types includes fednow_credit.' parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the account - name: address_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the address responses: '200': description: A single address content: '*/*': schema: $ref: '#/components/schemas/Address' patch: tags: - Addresses operationId: update_account_address summary: Update an address description: > Makes targeted updates to an existing address. All fields are optional. Include only the fields you want to change. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the account - name: address_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the address requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: name: type: string nullable: true example: Company External EVM Address status: type: string nullable: true enum: - active - archived additional_transfer_types: type: array description: Transfer types to add to the address. Merged into the existing `transfer_types`. items: type: string example: solana bank_address: description: For bank addresses only. Supply before adding `wire` to `additional_transfer_types`. nullable: true allOf: - $ref: '#/components/schemas/USStreetAddress' beneficiary_address: description: For bank addresses only. Supply before adding `wire` to `additional_transfer_types`. nullable: true allOf: - $ref: '#/components/schemas/USStreetAddress' account_holder_type: type: string enum: - individual - business description: > For bank addresses only. Whether the bank account belongs to an individual or a business. Can be set only while it is not set yet. Sending the stored value succeeds with no change. A different value returns `400` `account_holder_type_already_set`. date_of_birth: type: string format: date description: > For bank addresses only. Date of birth of an individual recipient, in `YYYY-MM-DD` format. Can be set only while no date of birth is stored. Sending the stored value returns `200` with no change. A different value returns `400` `date_of_birth_already_set`. Sending it for a business recipient, or with `account_holder_type: business`, returns `400` `date_of_birth_not_supported`. A malformed or future date returns `400` `validation_errors`. Responses return the date masked to the year (`1990-**-**`). example: '1990-01-31' examples: set_date_of_birth: summary: Set a recipient's date of birth value: date_of_birth: '1990-01-31' responses: '200': description: The updated address content: application/json: schema: $ref: '#/components/schemas/Address' '400': description: > Bad request. Date of birth cases: - `date_of_birth_already_set`: the address already has a different date of birth. - `date_of_birth_not_supported`: `date_of_birth` was sent for a business recipient, or `account_holder_type: business` was sent for an address with a stored date of birth. - `validation_errors`: `date_of_birth` is malformed or in the future. The error response does not include the submitted value. content: application/json: schema: $ref: '#/components/schemas/ApiErrorV2' examples: date_of_birth_already_set: summary: A different date of birth is already stored value: type: date_of_birth_already_set detail: Date of birth is already set and cannot be changed code: ValidationError status: 400 '404': description: Address not found or not owned by the account. '422': description: > The request is valid but cannot be processed: - `recipient_update_failed`: Brale could not update the recipient with the new date of birth. Brale does not save the change. - `fednow_routing_number_not_supported`: the address's routing number does not participate in FedNow. Do not retry. - `fednow_provider_registration_failed`: FedNow registration failed. This can be temporary. Retry after a backoff. content: application/json: schema: $ref: '#/components/schemas/ApiErrorV2' examples: recipient_update_failed: summary: Recipient update rejected value: type: recipient_update_failed detail: The recipient could not be updated code: ValidationError status: 422 '503': description: > `service_unavailable`: Brale could not update the recipient at this time. Brale does not save the change. Retry after a backoff. /accounts/{account_id}/addresses/{address_id}/balance: get: tags: - Addresses operationId: get_address_balance summary: Get an address balance description: 'Returns the balance of one address for the requested `transfer_type` and `value_type`. Both query parameters are required. - **Custodial wallets** (`type=internal`): pass the blockchain network and token ticker, for example `transfer_type=base&value_type=SBC`. - **Plaid-linked bank addresses**: pass `transfer_type=ach_debit&value_type=USD`. Brale returns Plaid''s available balance when Plaid supplies it, otherwise the current balance. Successful reads may be cached for up to 30 seconds. The balance is a point-in-time snapshot and does not guarantee that an ACH debit will settle. Brale never returns the full bank account number. Only Plaid-linked USD bank addresses support balance lookup. Bank addresses created through Direct bank entry do not. ' parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the account - name: address_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the address - name: transfer_type in: query required: true schema: type: string example: base description: Blockchain network for wallets (for example, `solana`, `base`, `ethereum`), or `ach_debit` for a Plaid-linked bank. - name: value_type in: query required: true schema: type: string example: SBC description: Token ticker for wallets (for example, `SBC`, `USDC`), or `USD` for a Plaid-linked bank. responses: '200': description: The address details and balance info content: '*/*': schema: $ref: '#/components/schemas/AddressBalanceResponse' examples: wallet: summary: Custodial wallet (transfer_type=solana, value_type=SBC) value: address: id: 2VcUIIsgARwVbEGlIYbhg6fGG57 address: 73uyt9HkEqx9bThYXWaUBP67sWsiJEsyJ5rSCieDx5me balance: value: '100.00' currency: SBC transfer_type: solana value_type: SBC plaid_bank: summary: Plaid-linked bank (transfer_type=ach_debit, value_type=USD) value: address: id: 34yknnMShvDbSW6tQg4HLlN41QO address: null account_number: '****1234' balance: value: '1250.42' currency: USD value_type: USD transfer_type: ach_debit '400': description: > Bad request. Possible `type` values: - `invalid_address` — a bank balance request did not use `transfer_type=ach_debit`. - `invalid_value_type` — a bank balance request did not use `value_type=USD`. - `balance_not_supported_for_address` — the address is not Plaid-linked, or the currency is not supported. - `plaid_error` with `code: plaid_item_login_required` — the Plaid connection needs to be re-authenticated. Have the user relink the bank account through Plaid. content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorResponse' - type: object properties: code: type: string description: Provider-specific error code. Present on `plaid_error`. example: plaid_item_login_required examples: plaid_item_login_required: summary: Plaid relink required value: type: plaid_error code: plaid_item_login_required balance_not_supported_for_address: summary: Address does not support balance lookup value: type: balance_not_supported_for_address '503': description: > `service_unavailable` — Plaid returned an error or balance data is unavailable. This does not mean the balance is zero or insufficient. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: type: service_unavailable /accounts/{account_id}/financial-institutions: get: tags: - Financial Institutions operationId: ListFinancialInstitutions summary: Fetch all financial institutions description: 'Returns all financial institutions associated with the given account. Deprecated. Use Addresses. Create an off-chain Address (ACH/Wire/RTP) and pass its `address_id` to Transfers. Plaid endpoints have moved to `/accounts/{account_id}/plaid/*`.' parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the account responses: '200': description: A list of financial institutions content: '*/*': schema: $ref: '#/components/schemas/GetFinancialInstitutionsResponse' deprecated: true /accounts/{account_id}/financial-institutions/external: post: tags: - Financial Institutions operationId: createFinancialInstitution summary: Create a new external financial institution description: 'Links an external bank account to the specified account (ACH, wire, etc.). Deprecated. Use Addresses. Create an off-chain Address (ACH/Wire/RTP) and pass its `address_id` to Transfers. Plaid endpoints have moved to `/accounts/{account_id}/plaid/*`. This endpoint does not accept `date_of_birth`. Sending one returns `400` `date_of_birth_not_accepted`. To store a recipient''s date of birth, create the bank address with `POST /accounts/{account_id}/addresses/external`.' parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the account - in: header name: Idempotency-Key required: true schema: type: string example: idemp-123e4567-e89b-12d3-a456-426614174000 description: 'A unique string used to prevent duplicate operations. Each POST request must use a new idempotency key. Use a UUIDv4 string. Example: `idemp-123e4567-e89b-12d3-a456-426614174000` ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FinancialInstitutionCreateRequest' responses: '201': description: Financial institution successfully created content: '*/*': schema: type: object properties: id: $ref: '#/components/schemas/Ksuid' deprecated: true /accounts/{account_id}/financial-institutions/{id}: get: tags: - Financial Institutions operationId: getFinancialInstitution summary: Fetch a specific financial institution description: 'Retrieves details for the specified financial institution (bank account). Deprecated. Use Addresses. Create an off-chain Address (ACH/Wire/RTP) and pass its `address_id` to Transfers. Plaid endpoints have moved to `/accounts/{account_id}/plaid/*`.' parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the account - name: id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the financial institution responses: '200': description: A financial institution object content: '*/*': schema: $ref: '#/components/schemas/FinancialInstitution' deprecated: true /accounts/{account_id}/automations: post: tags: - Automations operationId: createAutomations summary: Create an Automation description: 'Creates a new automation. ' parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the account - in: header name: Idempotency-Key required: true schema: type: string example: idemp-123e4567-e89b-12d3-a456-426614174000 description: 'A unique string used to prevent duplicate operations. Each POST request must use a new idempotency key. Use a UUIDv4 string. Example: `idemp-123e4567-e89b-12d3-a456-426614174000` ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AutomationCreateRequest' examples: branded: summary: Branded automation (individual account) value: name: Jane Doe Onramp source: value_type: USD destination: address_id: 2MhCCIHulVdXrHiEuQDJvnKbSkl value_type: SBC transfer_type: solana brand: account_id: 3Ar9BnQCKIrB3SYjKGBzCtFs6XL responses: '201': description: Automation successfully created content: '*/*': schema: $ref: '#/components/schemas/Automation' get: tags: - Automations operationId: listAutomations summary: Fetch all automations for an account description: 'Retrieves all automations associated with the specified customer account. ' parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the account responses: '200': description: A list of automations content: '*/*': schema: $ref: '#/components/schemas/GetAutomationsResponse' /accounts/{account_id}/automations/{id}: get: tags: - Automations operationId: getAutomations summary: Retrieve a single automation description: Returns details for a specific automation. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the account - name: id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the automation responses: '200': description: A single automation object content: '*/*': schema: $ref: '#/components/schemas/Automation' /accounts/{account_id}/automations/{automation_id}/simulations/deposits: post: tags: - Automations operationId: simulate_automation_deposit summary: Simulate Automation Deposit description: > Simulates an inbound ACH, wire, or FedNow deposit into a testnet Automation and runs the normal Automation mint path. Returns the resulting Transfer. The request `transfer_type` is a simulator input (`ach`, `wire`, or `fednow`). A `fednow` simulation produces a Transfer with `source.transfer_type: fednow_credit`. Available only with testnet credentials. Required scopes: `automations:write` and `network:testnet`. The Automation must belong to the account in the path, be `active`, and have a testnet destination chain. Brale does not contact a bank and no real fiat moves. Retrying with the same `Idempotency-Key` and body returns the original `202` response without creating another payment, Transfer, or mint. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the account that owns the Automation - name: automation_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the testnet Automation to fund - in: header name: Idempotency-Key required: true schema: type: string example: idemp-123e4567-e89b-12d3-a456-426614174000 description: > A unique string used to prevent duplicate operations. Use a new key for each new simulated deposit. Reuse the same key only to retry the same request. Reusing a key with a different body or URI returns `422`. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SimulateAutomationDepositRequest' examples: fednow: summary: Simulate a FedNow deposit value: amount: value: '1.00' currency: USD transfer_type: fednow wire: summary: Simulate a wire deposit value: amount: value: '10.00' currency: USD transfer_type: wire ach: summary: Simulate an ACH deposit value: amount: value: '10.00' currency: USD transfer_type: ach responses: '202': description: >- Accepted. Returns the Transfer created by the Automation. The Transfer includes `automation_id`, and `source.transfer_type` identifies the simulated rail. For `fednow`, `source.transfer_type` is `fednow_credit`. `202` means the simulated deposit was accepted. It does not mean the mint is complete. content: application/json: schema: $ref: '#/components/schemas/Transfer' '400': description: > Invalid request or schema. Known cases: - `transfer_type` is not `ach`, `wire`, or `fednow` (for example, `rtp` or `fednow_credit`) — schema validation error. - `invalid_currency` — the currency is not a supported reserve currency (for example, `EUR`). - `invalid_amount` — the amount is malformed, zero, or negative. For zero, `detail` is `Amount must be greater than zero`. content: application/json: schema: $ref: '#/components/schemas/ApiErrorV2' '401': description: Unauthorized. Missing or invalid bearer token. '403': description: >- Forbidden. The credentials do not include `network:testnet` or another required scope. Mainnet API keys receive this response. '404': description: >- The account or Automation was not found, or the Automation does not belong to the account in the path. content: application/json: schema: $ref: '#/components/schemas/ApiErrorV2' '422': description: > The request is valid but cannot be processed. Known cases: - `mainnet_destination` — `Deposit simulation is only available for testnet automations`. - `automation_not_active` — `Automation must be active to simulate a deposit`. Returned for pending, disabled, archived, or otherwise inactive Automations. - The `Idempotency-Key` was already used with a different request body or URI. content: application/json: schema: $ref: '#/components/schemas/ApiErrorV2' /accounts/{account_id}/plaid/link_token: post: tags: - Plaid summary: Create Plaid link token parameters: - in: path name: account_id required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateLinkTokenRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/LinkTokenResponse' /accounts/{account_id}/plaid/register-account: post: tags: - Plaid summary: Register financial institution account via Plaid and return address ID parameters: - in: path name: account_id required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RegisterAccountWithTransferTypesRequest' responses: '201': description: Created headers: Location: schema: type: string description: URL of the created address resource content: application/json: schema: $ref: '#/components/schemas/RegisterAccountAddressResponse' description: Registers a bank using a Plaid public_token and returns the new Address ID. x-tagGroups: - name: Core tags: - Accounts - Addresses - Transfers - Automations - Plaid - name: Legacy tags: - Financial Institutions - Orders