Create a new external address

curl --request POST \
  --url https://api.brale.xyz/accounts/{account_id}/addresses/external \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "name": "Base External Wallet",
  "transfer_types": [
    "base"
  ],
  "address": "0xE57e438aE0b1557bFC1ad70BD7751635E473D888"
}
'

{
  "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"
}

POST

accounts

{account_id}

addresses

external

curl --request POST \
  --url https://api.brale.xyz/accounts/{account_id}/addresses/external \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "name": "Base External Wallet",
  "transfer_types": [
    "base"
  ],
  "address": "0xE57e438aE0b1557bFC1ad70BD7751635E473D888"
}
'

{
  "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"
}

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

This endpoint does not support ach_debit. If you need ACH debit, use the Plaid-linked bank account flow instead.

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.

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.

Request

{
  "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.

Request

{
  "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"
}

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 for details.

FedNow Credit (`fednow_credit`)

Omit bank_address and beneficiary_address for FedNow-only addresses.

Request

{
  "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 and confirm status is active and transfer_types includes fednow_credit before you send a payout. See Send FedNow payouts.

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.

Response (422)

{
  "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.

Request

{
  "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"
  }
}

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.

Authorizations

Authorization

string

header

required

Use the Bearer token returned from the Auth endpoint via OAuth2 client_credentials flow. Include the token in the "Authorization: Bearer " header.

Headers

Idempotency-Key

string

required

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

Path Parameters

account_id

string<ksuid>

required

The ID of the account

Pattern: ^[a-zA-Z0-9]{27}$

Example:

"2VcUIIsgARwVbEGlIYbhg6fGG57"

Body

application/json

CreateExternalBlockchainAddressRequest
CreateExternalFinancialInstitutionRequest

name

string | null

required

Example:

"Company External EVM Address"

address

string

required

Example:

"0xb518d4d6221d9a41d23d71cbce8e106e7aab8f9b"

transfer_types

string[]

required

Response

External address successfully created

The full external address object returned by POST /accounts/{account_id}/addresses/external.

string<ksuid>

Pattern: ^[a-zA-Z0-9]{27}$

Example:

"2VcUIIsgARwVbEGlIYbhg6fGG57"

name

string | null

Example:

"checking 7890"

owner

string

Example:

"Jane Doe"

status

string

Example:

"active"

ownership

string

Example:

"customer-owned"

account_holder_type

enum<string> | null

Whether the bank account is held by an individual or a business. null if it was not set.

Available options:

individual,

business

Example:

"business"

bank_address

ExternalAddressResponseStreetAddress · object | null

US street address as returned in external address responses. Includes country, unlike the request USStreetAddress schema.

Show child attributes

beneficiary_address

ExternalAddressResponseStreetAddress · object | null

US street address as returned in external address responses. Includes country, unlike the request USStreetAddress schema.

Show child attributes

created

string<date-time>

Example:

"2026-06-02T20:01:02.226850Z"

transfer_types

string[]

Example:

["ach_credit"]

account_number

string

Returned masked (e.g. ****7890).

Example:

"****7890"

account_type

enum<string>

Available options:

checking,

savings

Example:

"checking"

needs_update

boolean

Example:

false

last_updated

string<date-time>

Example:

"2026-06-02T20:01:03.321461Z"

routingNumber

string

Note: this single field is currently returned in camelCase (routingNumber) while all other fields use snake_case.

Example:

"063108680"

API overview

Accounts

Addresses

Automations

Transfers

Financial institutions

Webhooks

Tokenization

Create a new external address

Direct bank entry field requirements

Direct bank entry examples

ACH Credit (`ach_credit`, `same_day_ach_credit`)

RTP Credit (`rtp_credit`)

FedNow Credit (`fednow_credit`)

FedNow errors

Wire (`wire`)

Authorizations

Headers

Path Parameters

Body

Response

​Direct bank entry field requirements

​Direct bank entry examples

​ACH Credit (ach_credit, same_day_ach_credit)

​RTP Credit (rtp_credit)

​FedNow Credit (fednow_credit)

​FedNow errors

​Wire (wire)

Authorizations

Headers

Path Parameters

Body

Response

Direct bank entry field requirements

Direct bank entry examples

ACH Credit (`ach_credit`, `same_day_ach_credit`)

RTP Credit (`rtp_credit`)

FedNow Credit (`fednow_credit`)

FedNow errors

Wire (`wire`)