Skip to main content
POST /api/v1/trading/withdraw is signed by an Ed25519 session key, the same as order entry and other cash writes. But the exchange holds withdrawals to a higher bar: the signing session must be admin-rooted, and a valid signature alone does not authorize one.

​
What “admin-rooted” means

A session is admin-rooted when both of these hold:
  • It was minted under an admin master key — not a scoped one.
  • It is unpinned — its scope is the unpinned sentinel (the maximum 32-bit value), not a single subaccount index.
Pinning a session under an admin key does not keep it admin-rooted. Pinning narrows the session to one subaccount and strips account-level authority, even when the parent is an admin key. So a pinned session, or a session rooted on a scoped master key, is rejected even when its signature verifies. Admin-rooting is independent of the FullAccess / TradingOnly role a master key carries. They are separate checks; a withdrawal needs the admin-rooted chain regardless of role.

​
How to withdraw

1

Mint an unpinned session under an admin master key

Call POST /api/v1/auth/sessions signed by an admin master key, with scope set to the unpinned sentinel (the maximum 32-bit value). See Session keys.
2

Sign the withdrawal with that session

Build the WithdrawCash payload and sign it with the Ed25519 session key (signature_type = 0). See Signed payloads.
3

Submit

POST the signed envelope to POST /api/v1/trading/withdraw. A rejection still returns HTTP 200 with success: false (or a rejected_* status) — read the body.

​
Why the chain matters, not just the signature

The withdrawal authority lives in the master key, not the session. The exchange treats the session as a delegate: it checks the signature, then walks the chain to confirm the session descends from an admin master key and was never pinned. Both checks must pass. The same rule governs subaccount creation and admin-scope key management. The chain to an admin master key — not just a valid signature — authorizes account-level operations.

​
The secrets-once implication

Keep the admin master key offline and mint short-lived sessions from it on demand. Every minted session secret is held only by you: the exchange never returns the session private key, and master-key material never leaves your control.
If you lose every admin master key with no replacement, you can no longer mint an admin-rooted session, and the account can no longer withdraw or manage its keys. The exchange refuses to remove the last admin key, but it cannot recover one you lose. Register a second admin master key as a recovery path.
  • Keep the admin master key offline. It is the root of withdrawal authority. Generate and store its material off-exchange.
  • Mint sessions on demand. Sessions are cheap and revocable. Mint an unpinned admin-rooted session when you need to withdraw, set a tight valid_until, and revoke it when done.
Pinned sessions, scoped master keys, API keys, and device keys are still useful for everything that is not admin-rooted — order entry, reads, transfers within scope. Reserve admin-rooted sessions for the operations that require them.