Wallets & accounts

Create an MPC wallet, attach assets to get deposit addresses, receive funds, and read balances.

Create a wallet

Wallet creation is asynchronous. The API records the request and returns at once; the signing cluster then runs distributed key generation, and the wallet becomes active when its public key has been stored. Locally this takes seconds; allow up to a minute.

curl -X POST https://<api-host>/api/v1/wallets \
  -H "ACCESS-API-KEY: $KEY" -H "ACCESS-TIMESTAMP: $TS" -H "ACCESS-SIGN: $SIG" \
  -H "X-Idempotency-Key: 5f9a…" \
  -H "Content-Type: application/json" \
  -d '{"workspace_id": "<workspace_id>", "name": "Treasury", "wallet_type": "mpc"}'

The response is 202 Accepted with a wallet operation: the new wallet_id and status: "pending". Poll the operation until it completes:

GET /api/v1/wallets/creation-status/{wallet_id}

Status	Meaning
pending	Recorded; key generation not yet published.
submitted	Key generation is running on the cluster.
success	The wallet is active and can hold assets.
failed	Key generation failed or timed out; the reason is in status_reason. Create a new wallet with a new idempotency key.

Or subscribe to the wallet.creation_requested and wallet.created events; see Webhooks & events.

Repeating the POST with the same X-Idempotency-Key returns the same operation; it never starts a second key generation.

In the console: Wallet → Create Wallet → choose MPC Wallet, name it, confirm. The console polls creation status and opens the wallet when it is ready.

Read wallets

GET /api/v1/workspaces/{workspace_id}/wallets      # list
GET /api/v1/wallets/{wallet_id}                    # detail

Attach an asset and get a deposit address

A wallet holds funds per asset (a network plus, for tokens, a contract). Attaching an asset derives the wallet’s deposit address on that network from its public key. Asset IDs come from the catalog:

GET /api/v1/networks          # supported networks
GET /api/v1/assets            # catalog assets, with network, decimals, native/token flag
PUT /api/v1/wallets/{wallet_id}/asset/{asset_id}   # attach; returns the wallet asset and its address

Attaching the same asset twice is idempotent. The derivation path is fixed on the server; the API does not accept client-supplied paths. Read addresses and attached assets with:

GET /api/v1/wallets/{wallet_id}/assets
GET /api/v1/wallets/{wallet_id}/deposit-address?asset_id={asset_id}

In the console: open the wallet → Receive → choose the asset. The console attaches it if needed and shows the address and a QR code.

Receive funds

Anything sent to a deposit address is picked up by the chain scanner. A deposit is recorded as an inbound transaction when it is observed and credited to the balance once it reaches the configured confirmation depth for that asset. If the chain reorganises below that depth, the deposit is marked failed and the affected blocks are rescanned; balances are only ever credited from canonical blocks.

Events: deposit.detected, deposit.failed, balance.updated.

Read balances

GET /api/v1/wallets/{wallet_id}/balance/{asset_id}   # one asset
GET /api/v1/wallets/{wallet_id}/overview             # all attached assets

Balances are chain-observed snapshots written by the scanner, not running totals kept by the API. Each balance shows what is available and what is held by in-flight withdrawals. If the scanner falls behind, the last known balance is returned; a stale scanner never reports zero.

Supported networks

Wallets can hold native assets and tokens on the EVM networks listed for MPC Wallet Infrastructure on Supported networks & assets. Ethereum Sepolia is available in the sandbox.