Wallets and networks.
A wallet belongs to a workspace and a supported network. Customer keys are managed by the platform.
01Network identity
Initial support covers TRON, Ethereum, and Base. Asset identity includes its network and verified contract.
02Custody provisioning
Owners and administrators select the network and primary crypto separately. GET /v1/workspaces/{workspaceId}/wallet-options lists the supported test networks and their compatible assets. POST /v1/workspaces/{workspaceId}/wallets accepts name, network and optional assetId with a stable Idempotency-Key. The saved primaryAssetId is a display and receiving preference; every supported asset on that network remains included. A separate custody service prepares the address.
03Setup states
Requests move through queued, preparing, retry, custody ready, or operator review. Receiving has a separate protected readiness endpoint and explicit operator activation. Address presentation requires current custody/network checks and published deposit pricing; mainnet stays disabled.
04Receiving details
Use wallets:receive to read GET /v1/merchant/wallets/{walletId}/receive from your server. The response includes current readiness, supported contracts and published deposit fees. It returns an address only after explicit testnet approval and current custody/network checks. All other states return address=null. Pausing cannot prevent transfers to an address already shared; supported funds may remain held for review.
05Access and retries
Dashboard requests use an authenticated session and workspace role. Server applications use wallets:create to POST /v1/merchant/wallets, and wallets:read to list or recover current wallet status. Creation always queues a testnet wallet and returns no receiving address. Repeat the same Idempotency-Key and body to recover the original creation response, including with a replacement authorized key in the same workspace. A different body with the same request key is rejected. Current key, role and website authority are checked inside the write transaction and again after its records are saved; expiry while waiting rolls back the request.
POST /v1/merchant/wallets
Authorization: Bearer <server-only-key-with-wallets:create>
Idempotency-Key: <persisted-wallet-request-id>
Content-Type: application/json
{ "name": "Store payments", "network": "tron" }
// 201: saved testnet setup request; 200: original receipt replayed
// Grant wallets:read to retrieve its current state.
GET /v1/merchant/wallets/{walletId}
// Grant wallets:receive for approved receiving details.
GET /v1/merchant/wallets/{walletId}/receive
// Use address only when state is available; otherwise address is null.
GET /v1/networks
GET /v1/assets
GET /v1/workspaces/{workspaceId}/wallets
GET /v1/workspaces/{workspaceId}/wallets/{walletId}/receive
POST /v1/workspaces/{workspaceId}/wallets
Idempotency-Key: <unique-request-id>
Content-Type: application/json
{ "name": "Store payments", "network": "tron" }
// 201: saved request; 200: original response replayed
// List responses withhold the address. Use /receive for current readiness.
// /receive.address is null while setup, monitoring or approval is pending.Open your workspace