Sub-Account Wallets

Create Wallets for a Sub-Account

Use this flow when your platform needs to provision a currency-specific wallet for a downstream customer so that customer can receive funds, hold balances, convert currencies, or send payouts in their own ledger context.

✅ Before you start

Complete these steps before you create the wallet:

Create the sub-account and make sure it is ready for wallet provisioning.
Authenticate with your master credentials or a scoped sub-account session.
Decide which currency the customer needs for receive, exchange, transfer, or payout flows.
Make sure you have the correct X-Sub-Account-Id for the customer that should own the wallet.

📚 Use this page with the recipe

This guide explains when to create a sub-account wallet and the minimum sequence. For the step-by-step implementation, use the recipe:

Create Wallets for a Sub-Account Recipe →

The sub-account wallet workflow

This use case follows a short setup sequence:

Set the sub-account context with either X-Sub-Account-Id or a scoped token.
Create the wallet in the correct customer context.
Store the returned wallet ID for later account issuance, receive, FX, statement, transfer, and payout flows.

What makes this use case different?

Unlike a standard wallet guide, this use case is specifically for platforms that need to:

provision wallets on behalf of downstream customers
keep balances isolated per customer
connect later receive or payout activity to the correct sub-account ledger
choose wallet currencies based on the customer’s next operational action

Where to go deeper

Use the product guides when you need implementation detail for a specific step:

Success indicators

Signal	What it means
Wallet created in the correct context	The customer now has a dedicated balance container in the intended currency.
Wallet ID stored successfully	Later receive, FX, statement, transfer, and payout requests can target the same ledger.
No cross-customer leakage	The wallet belongs only to the intended downstream customer and not to the master account or another sub-account.

Troubleshooting

Issue	What to check
Wallet creation fails	Confirm the sub-account is active and the currency is supported for your account.
Wallet is created for the wrong customer	Check whether the `X-Sub-Account-Id` header or scoped token belongs to a different sub-account.
Later requests cannot find the wallet	Verify your system stored the returned wallet ID immediately after creation.

Next steps


Login as a Sub-Account and Run a Scoped Action → Use customer-specific sessions when one token should only operate on one downstream account.	Global Collection to Payout → See the advanced pattern for collecting funds into a sub-account context and sending them onward.