Brale Transfers API

openapi: 3.2.0
info:
  title: Brale Issuance and Orchestration Transfers 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.'
servers:
- url: https://api.brale.xyz
  description: Production server
security:
- BearerAuth: []
tags:
- name: Transfers
  description: Endpoints for creating and retrieving transfers (fiat to stablecoins, etc.)
paths:
  /accounts/{account_id}/transfers:
    get:
      tags:
      - Transfers
      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
      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 → 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 → 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'
        '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.

            '
          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'
components:
  schemas:
    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
    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—use 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.
      required:
      - transfer_type
      - value_type
    Pagination:
      title: Pagination
      description: Cursor-based pagination metadata
      type: object
      additionalProperties: false
      properties:
        page_size:
          type: integer
          example: 25
        next:
          type:
          - string
          - 'null'
          example: g3QAAAABdw...
        prev:
          type:
          - string
          - 'null'
          example: g3QAAAABdw...
      required:
      - page_size
    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
    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
          example: pending
        failure:
          allOf:
          - $ref: '#/components/schemas/TransferFailure'
          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
          - 'null'
          description: Optional free-form note attached to the transfer.
          example: null
        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.
        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'
    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…
            address_id: 2MhCCIHu…
            value_type: USDC
            transfer_type: polygon
          destination:
            transaction_id: 0xdd5646ea…
            address_id: 2O6asmN…
            value_type: USDC
            transfer_type: polygon
          amount:
            value: '100.00'
            currency: USD
          note: null
          created_at: '2026-01-01T00:00:00Z'
          updated_at: '2026-01-01T00:00:00Z'
    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
          - 'null'
          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
          - 'null'
          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
              - 'null'
              description: Human-readable return reason, when available.
              example: Account closed
    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 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
          - 'null'
          format: date-time
          description: When the underlying payment was received or posted.
          example: '2026-04-07T00:01:24.514000Z'
        sender_name:
          type:
          - string
          - 'null'
          description: Name of the originating sender, when available.
          example: Originator Name
        sender_bank_name:
          type:
          - string
          - 'null'
          description: Originating bank name, when available.
          example: JPMorgan Chase Bank
        sender_bank_routing_number:
          type:
          - string
          - 'null'
          description: Originating bank routing number, when available.
          example: '000000123'
        payment_reference:
          type:
          - string
          - 'null'
          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
          - 'null'
          description: Wire IMAD / tracking identifier, when available.
          example: 20260406XOIZJDPP953495
        trace_number:
          type:
          - string
          - 'null'
          description: ACH trace identifier for the underlying payment, when available. Primarily relevant for inbound ACH-funded transfers.
          example: 021000029876543
    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
    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
    Ksuid:
      title: Kusid
      type: string
      format: ksuid
      pattern: ^[a-zA-Z0-9]{27}$
      example: 2VcUIIsgARwVbEGlIYbhg6fGG57
    BrandData:
      type:
      - object
      - 'null'
      additionalProperties: false
      required:
      - account_id
      properties:
        account_id:
          type: string
  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 <token>" 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
x-tagGroups:
- name: Core
  tags:
  - Accounts
  - Addresses
  - Transfers
  - Automations
  - Plaid
- name: Legacy
  tags:
  - Financial Institutions
  - Orders
x-provenance:
  method: harvested
  publisher: Brale
  source: https://docs.brale.xyz/api-reference/brale-openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)