Skip to main content
POST
Create Wallet
Creates a deposit wallet for an account and asks the custody provider for an on-chain address. The wallet is returned with HTTP 200. Wallets are for crypto deposits only. For fiat, use Deposit Instructions. See the Deposit Flows guide for the full picture. Requires an API key with write access on the accounts scope.

Path Parameters

string
required
The account’s external ID (starts with acct_)

Headers

This endpoint ignores Idempotency-Key. A retry is a fresh create, not a replay of the first one. If an active wallet already exists for the pair on the current provider, the retry returns LIMIT_EXCEEDED. The client API has no delete endpoint. Read the wallet back with List Wallets before retrying.

Request Body

string
required
Crypto currency code, for example USDC or USDT. The chain is not part of this value. Pass it in network.
string
required
Blockchain network. Mainnets: ethereum, solana, tron, plasma, bsc, polygon, xlm, avax, base. Testnets, non-production only: ethereum_sepolia, solana_devnet, tron_shasta.A recognized network name does not guarantee that a wallet can be provisioned. Availability depends on the enabled currency/network pairs for your organization and its custody provider.
string
required
Label for the wallet, max 255 characters

Which currency and network combinations work

The combination must be one your organization is set up for. An unsupported pair returns 422 WALLET_UNSUPPORTED_COMBINATION, with details.currency and details.network echoing what you sent. The pairs available in each environment; your organization may be enabled for a different set.
Sandbox networks are testnets and carry no mainnet value. To credit a balance without an on-chain transfer at all, use Simulate Payin.

One wallet per pair

An account may hold one active wallet per currency and network on its current custody service. A second create for the same pair returns 422 LIMIT_EXCEEDED, with details carrying resource, currency, network, current_count and max_allowed.

Response

string
Wallet identifier (starts with wal_)
string
Always returns "wallet"
string
The account that owns the wallet (starts with acct_)
string
Crypto currency code
string
Blockchain network, or null
string
On-chain deposit address, or null when the custody provider has not returned one yet. Poll Get Wallet until it is populated, and never publish a wallet as a deposit target while it is null.
string
The label you supplied, or null
string
Wallet status: active, suspended or deactivated. A newly created wallet is always active.
string
ISO 8601 timestamp when created
string
ISO 8601 timestamp when last updated, or null
string
Actor that created the wallet, or null when no actor was recorded. API-key actors use an ak_ ID; Hop administrators are shown as hop_admin.
string
Actor that last updated the wallet, or null when no actor was recorded.

Errors

Request Example

Response Example