Brale Addresses API

openapi: 3.2.0
info:
  title: Brale Issuance and Orchestration Addresses 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: Addresses
  description: On-chain and off-chain endpoints (custodial or external) represented by a single Addresses resource
paths:
  /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
                  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_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
                    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
        '422':
          description: "The request is valid but cannot be processed. FedNow-related cases:\n\n- `fednow_routing_number_not_supported`: the `routing_number` does not\n  participate in FedNow. Do not retry with the same body. Remove\n  `fednow_credit` or use a FedNow-participating account.\n\n- `fednow_provider_registration_failed`: Brale could not register the\n  recipient for FedNow with its banking provider. This can be temporary.\n  Retry the same request with the same `Idempotency-Key` after a backoff.\n"
          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'
  /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:\n- `invalid_address` — a bank balance request did not use\n  `transfer_type=ach_debit`.\n\n- `invalid_value_type` — a bank balance request did not use\n  `value_type=USD`.\n\n- `balance_not_supported_for_address` — the address is not\n  Plaid-linked, or the currency is not supported.\n\n- `plaid_error` with `code: plaid_item_login_required` — the\n  Plaid connection needs to be re-authenticated. Have the user\n  relink the bank account through Plaid.\n"
          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
components:
  schemas:
    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'
    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
          - 'null'
          example: Suite 500
        city:
          type: string
          example: Springfield
        state:
          type: string
          example: CA
        zip:
          type: string
          example: '90001'
        country:
          type: string
          example: US
    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
    CreateExternalBlockchainAddressRequest:
      type: object
      additionalProperties: false
      title: CreateExternalBlockchainAddressRequest
      required:
      - name
      - address
      - transfer_types
      properties:
        name:
          type:
          - string
          - 'null'
          example: Company External EVM Address
        address:
          type: string
          example: '0xb518d4d6221d9a41d23d71cbce8e106e7aab8f9b'
        transfer_types:
          type: array
          items:
            type: string
            example: solana
    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
    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
          - 'null'
          description: A human-readable name for the new internal address.
    CreateExternalAddressRequest:
      type: object
      oneOf:
      - $ref: '#/components/schemas/CreateExternalBlockchainAddressRequest'
      - $ref: '#/components/schemas/CreateExternalFinancialInstitutionRequest'
      title: CreateExternalAddressRequest
    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
        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
    GetAddressesResponse:
      type: object
      properties:
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
    AddressReference:
      title: AddressReference
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/Ksuid'
        address:
          type:
          - string
          - 'null'
          description: On-chain address for wallets. `null` for bank addresses.
          example: '0xb518d4d6221d9a41d23d71cbce8e106e7aab8f9b'
        account_number:
          type:
          - string
          - 'null'
          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
    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
          - 'null'
          example: checking 7890
        owner:
          type: string
          example: Jane Doe
        status:
          type: string
          example: active
        ownership:
          type: string
          example: customer-owned
        bank_address:
          allOf:
          - $ref: '#/components/schemas/ExternalAddressResponseStreetAddress'
        beneficiary_address:
          allOf:
          - $ref: '#/components/schemas/ExternalAddressResponseStreetAddress'
        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
    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
    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.
    Ksuid:
      title: Kusid
      type: string
      format: ksuid
      pattern: ^[a-zA-Z0-9]{27}$
      example: 2VcUIIsgARwVbEGlIYbhg6fGG57
  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)