> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brale.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a new external address

> Creates a non-custodial address (EOA) for the specified account using the Direct bank entry path.

This endpoint is the **Direct bank entry** path for creating external off-chain bank addresses. Use it when you already have the bank account details (account number, routing number) and need `wire`, `ach_credit`, `same_day_ach_credit`, `rtp_credit`, or `fednow_credit` (on accounts with FedNow enabled).

> [!NOTE]
>
> This endpoint does **not** support `ach_debit`. If you need ACH debit, use the [Plaid-linked bank account flow](https://docs.brale.xyz/api-reference/brale/create-plaid-link-token.md) instead.

> [!WARNING]
>
> 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.

For a full comparison of both external bank address creation paths, see [External bank addresses](https://docs.brale.xyz/key-concepts/external-bank-addresses.md).

### Direct bank entry field requirements

For Direct bank entry, required fields depend on the transfer types you request.

| Field | ACH Credit | Same Day ACH Credit | RTP Credit | FedNow Credit | Wire |
| - | - | - | - | - | - |
| `owner` | Required | Required | Required | Required | Required |
| `account_number` | Required | Required | Required | Required | Required |
| `routing_number` | Required | Required | Required | Required | Required |
| `account_type` | Required | Required | Required | Required | Required |
| `transfer_types` | Required | Required | Required | Required | Required |
| `bank_address` | Optional | Optional | Optional | Optional | Required |
| `beneficiary_address` | Optional | Optional | Optional | Optional | Required |

If `transfer_types` includes `wire`, wire requirements apply. For addresses without `wire`, omit `bank_address` and `beneficiary_address` unless you have accurate values. Send `account_number` and `routing_number` as strings so leading zeros are preserved.

### Direct bank entry examples

#### ACH Credit (`ach_credit`, `same_day_ach_credit`)

Omit `bank_address` and `beneficiary_address` for ACH-only addresses.

```json Request theme={null}
{
  "owner": "Jane Doe",
  "transfer_types": ["ach_credit", "same_day_ach_credit"],
  "account_number": "1234567890",
  "routing_number": "063108680",
  "account_type": "checking",
  "name": "Example Bank"
}
```

#### RTP Credit (`rtp_credit`)

Omit `bank_address` and `beneficiary_address` for RTP-only addresses.

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

> [!NOTE]
>
> RTP eligibility is determined asynchronously by the banking partner after the address is created. The `rtp_credit` transfer type may not appear immediately. See [Key Concepts → Addresses](https://docs.brale.xyz/key-concepts/addresses.md#create-external-address-for-rtp) for details.

#### FedNow Credit (`fednow_credit`)

Omit `bank_address` and `beneficiary_address` for FedNow-only addresses.

```json Request theme={null}
{
  "owner": "Jane Doe",
  "transfer_types": ["fednow_credit"],
  "account_number": "0012345678",
  "routing_number": "063108680",
  "account_type": "checking",
  "name": "Example Bank"
}
```

Do not assume `fednow_credit` is added asynchronously like `rtp_credit`. [Retrieve the address](https://docs.brale.xyz/api-reference/brale/get-address.md) and confirm `status` is `active` and `transfer_types` includes `fednow_credit` before you send a payout. See [Send FedNow payouts](https://docs.brale.xyz/guides/fednow-outbound.md).

#### FedNow errors

Brale returns these errors with the standard error envelope:

| Status | `type` | Meaning | Retry |
| - | - | - | - |
| `422` | `fednow_routing_number_not_supported` | The routing number does not participate in FedNow. | No. Use another rail. |
| `422` | `fednow_provider_registration_failed` | FedNow registration failed. This can be temporary. | Yes. Retry with the same `Idempotency-Key` and body after a backoff. |

```json Response (422) theme={null}
{
  "type": "fednow_routing_number_not_supported",
  "detail": "The routing number does not support FedNow.",
  "status": 422
}
```

#### Wire (`wire`)

Wire-capable addresses require both `bank_address` and `beneficiary_address`.

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

> [!NOTE]
>
> If you include `wire` in `transfer_types`, both `bank_address` and `beneficiary_address` are required, even if the same address also includes ACH, RTP, or FedNow rails.

Use the playground below to try this endpoint directly, or review the OpenAPI details in the right panel.


## OpenAPI

````yaml POST /accounts/{account_id}/addresses/external
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.
servers:
  - url: https://api.brale.xyz
    description: Production server
security:
  - BearerAuth: []
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.
paths:
  /accounts/{account_id}/addresses/external:
    post:
      tags:
        - Addresses
      summary: Create a new external address
      description: |
        Creates a non-custodial address (EOA) for the specified account.
      operationId: createAddress
      parameters:
        - name: account_id
          in: path
          required: true
          description: The ID of the account
          schema:
            $ref: '#/components/schemas/Ksuid'
        - 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_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
                    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:


            - `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
components:
  schemas:
    Ksuid:
      title: Kusid
      type: string
      format: ksuid
      pattern: ^[a-zA-Z0-9]{27}$
      example: 2VcUIIsgARwVbEGlIYbhg6fGG57
    CreateExternalAddressRequest:
      type: object
      oneOf:
        - $ref: '#/components/schemas/CreateExternalBlockchainAddressRequest'
        - $ref: '#/components/schemas/CreateExternalFinancialInstitutionRequest'
      title: CreateExternalAddressRequest
    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
        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'
    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
    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
          enum:
            - checking
            - savings
          example: checking
        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
        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
    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
    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'
  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.

````