> ## 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 internal address
> Provision an additional custodial (internal) address for the specified account.
Use this endpoint to provision an **additional** custodial (internal) address on an account beyond the wallets Brale creates automatically at onboarding. This is useful when you want to segment funds within a single account (per end-user, per-purpose, or per-business-unit) and distinguish wallets by `name`.
Requires the `addresses:write` scope and a unique `Idempotency-Key` header on every request.
All values in `transfer_types` must resolve to the **same chain environment** (for example `["ethereum", "polygon"]` for EVM, or `["stellar"]` for Stellar).
### Request
```json Request (EVM) theme={null}
{
"name": "My EVM Wallet",
"transfer_types": ["ethereum", "polygon"]
}
```
```json Request (Stellar) theme={null}
{
"name": "Stellar Custodial Wallet",
"transfer_types": ["stellar"]
}
```
### Responses
Deterministic-address chains (Solana, Stellar, Ethereum, Base, Polygon) return synchronously with `status: "active"` and a non-null `address`.
```json 201 (synchronous) theme={null}
{
"id": "3EdBHmAtfm7tct7varYqgAz6iYW",
"status": "active",
"name": "My EVM Wallet",
"address": "0xc109f7016aF02fBF21E9f0d7d50a6A48f5F644Ad",
"transfer_types": ["ethereum", "polygon"]
}
```
Non-deterministic chains (Spark, Canton, Hedera) return `status: "pending"` and `address: null` until the chain confirms. The address transitions to `active` once provisioning completes — see [Address lifecycle](/key-concepts/addresses#address-lifecycle).
```json 201 (asynchronous) theme={null}
{
"id": "3EdBHmAtfm7tct7varYqgAz6iYW",
"status": "pending",
"name": "Hedera Custodial Wallet",
"address": null,
"transfer_types": ["hedera"]
}
```
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/internal
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—26-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.
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/internal:
post:
tags:
- Addresses
summary: Create a new internal address
description: >
Provisions an additional custodial (internal) address for the specified
account.
operationId: createInternalAddress
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/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
components:
schemas:
Ksuid:
title: Kusid
type: string
format: ksuid
pattern: ^[a-zA-Z0-9]{26}$
example: 2VcUIIsgARwVbEGlIYbhg6fGG57
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
nullable: true
description: A human-readable name for the new internal address.
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
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
" header.
````