Create a new external address

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

POST /accounts/{account_id}/addresses/external

cURL

onchain_base

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

201

offchain_ach_credit

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

201

*/*

External address successfully created

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

id · 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"