Skip to main content
A member’s own API key can start an organisation wallet (with treasury_write) or the member’s own personal wallet (with orders_write, where Advanced is enabled). Each owner chooses their own sign-in methods and approves it on their own signing page, so no wallet exists at the provider until they have.

At a glance

Paths are under /api/v1/workspaces/{workspaceId}. The key’s member also needs View wallets for a personal wallet, or Manage wallets for an organisation wallet.
1

Start it

POST /api/v1/workspaces/{workspaceId}/wallets with scope (organisation, or personal for the key’s own member), a connectionId (a workspace wallet connection, or platform-turnkey), family, networks, displayName and an ownerGroup: the people who approve, each with an empty factors list and no walletId, and the threshold. A personal wallet’s group is the key’s member alone, threshold 1. Send an Idempotency-Key. The answer is 202 with the pending wallet and signingRequest.approvalUrl.
Request body
2

Send the owners to approve

Each owner, the key’s member included, opens approvalUrl, signs in, chooses their sign-in methods and proves them. For an organisation wallet the key’s member first confirms it was them with an authenticator app or security key. With returnUrl, on one of the workspace’s registered wallet callback origins, the page sends them back with signingRequestId and outcome.
3

Follow it

GET …/wallets/{walletId} until status is active, or failed, expired, cancelled or declined; after any of the last four, start again. missing names who has not approved yet. GET …/wallets?status=pending lists the pending ones.
A key never names how a person approves: an owner sent with factors or a walletId is 403 API_KEY_WALLET_FACTORS_REFUSED, and nothing is recorded. Each person picks their own sign-in methods or wallet on the approval page. A key needs the scope its body needs: orders_write for a personal wallet, treasury_write for an organisation wallet (403 INSUFFICIENT_SCOPE otherwise, with details.requiredScope). A key holding neither is refused before its body is read, and that refusal’s details.requiredScope names orders_write. A personal wallet where Advanced is not enabled is 403 ADVANCED_MODE_DISABLED, and a service account’s key is 403 API_KEY_WALLET_CREATOR_NOT_A_PERSON. A key sends no stepUpProof, tradeFromThisWallet or initialAccess (403 API_KEY_WALLET_GRANT_REFUSED): set access and grants in the app. An API key never approves.
POST …/wallets/{walletId}/cancel with an Idempotency-Key, and the scope the creation needed. A pending creation is withdrawn at once and reads cancelled. An uncertain one is checked at the provider first and refused by name when the wallet may exist there. Any other status is 409 WALLET_CREATION_NOT_CANCELLABLE.
pending, creating, uncertain, created, active, readbackMismatch, failed, expired, cancelled, declined. The list can grow: read a value you do not know as not usable yet.

Next

Give a key organisation wallets

Let a key trade from the new wallet.

Choose wallets and accounts

Name the wallet a quote trades from.