Wallets

Compose uses three wallets to move funds between fiat and stablecoins: deposit wallets (customer-registered, fiat → USDC), withdrawal wallets (Compose-provisioned, USDC → fiat), and your embedded wallet (your organization's non-custodial embedded Safe wallet on Base).

Deposit Wallets

A deposit wallet is a USDC-on-Base address that your customer controls. You register it via POST /customers/{customerId}/deposit/wallets.

When a customer deposits fiat to their assigned shared/virtual account details, Compose automatically converts it to USDC and sends it to the registered address. No manual intervention is required.

Licensing:

• Licensed organizations: A deposit wallet is optional. If none is configured, funds are sent to your organization's embedded wallet.
• Unlicensed organizations: Each customer must have a deposit wallet configured before deposits can be processed.

See Quick Start Step 5 for setup instructions, or the Deposit Wallets endpoints for the full API reference.

Withdrawal Wallets

A withdrawal wallet is a Compose-provisioned USDC-on-Base address linked to a withdrawal bank. It is auto-created when you call POST /customers/{customerId}/withdrawal/banks. You do not choose or register this address — Compose generates it.

Where to find it: The wallet is returned in the wallets array on GET and POST /customers/{customerId}/withdrawal/banks. Each wallet includes:

• id — unique wallet identifier
• address — the blockchain address to send USDC to
• currency — usdc
• chain — base
• enabled — whether the wallet is active
• instructions — human-readable funding instructions (includes the 5 USDC minimum)

Two ways to off-ramp through a withdrawal wallet:

Both paths result in an automatic fiat payout to the linked bank account.

1. Direct send — Send USDC from any external wallet to the withdrawal wallet's address. No API call is needed to initiate the withdrawal. Minimum: 5 USDC (see the instructions field).
2. Via API — Call POST /customers/{customerId}/withdrawal to trigger an off-ramp from your embedded wallet. Compose routes USDC through the per-bank withdrawal wallet as part of the settlement flow. For automatic API withdrawals, you must also configure the Allowance module.

See the Withdrawals endpoints for full API reference.

Embedded Wallet

Your embedded wallet is your organization's non-custodial embedded Safe wallet on Base. It is provisioned during Compose onboarding — not a wallet you import or register via API. You control funds via passkey; Compose does not hold your withdrawal keys. Each organization has one embedded wallet.

How it is created (onboarding)

This is a dashboard flow, not an API endpoint. When you sign up:

1. Create a passkey — use your device's biometric or PIN (WebAuthn)
2. Create your wallet — Compose deploys your organization's embedded Safe wallet on Base, secured by your passkey

How it fits in fund flows

• Deposits — when no customer deposit wallet is configured (licensed organizations), converted USDC is sent to your embedded wallet
• API withdrawals — POST /customers/{customerId}/withdrawal debits USDC from your embedded wallet (see Allowance for automatic execution)
• Developer fees — claimed to your embedded wallet via POST /developer-fees

Signing and approvals

Manual operations (dashboard sends, manual withdrawals, wallet configuration) require passkey signatures. Organizations can add multiple approvers; transactions execute on-chain once the configured approval threshold is met. API withdrawals within your configured allowance can execute without passkey signing — see Allowance.

Check on-chain USDC in your embedded wallet via Get balances.

Comparing Wallets

---