Reads are public. Writes are authorized by a signature from the account or an API wallet scoped to the account.
API wallets
An API wallet is a separate key that can sign trading actions without holding the master key. It cannot withdraw funds to an external chain.
| Capability | Master | API wallet |
|---|---|---|
| Read public data | Yes | Yes |
| Place / cancel orders | Yes | Yes |
| Modify leverage and margin | Yes | Yes |
| Transfer between sub-accounts | Yes | Yes |
| Withdraw to external chain | Yes | No |
| Create or revoke API wallets | Yes | No |
Create an API wallet from Settings → API wallets or with the approveAgent action. Revoke it at any time; revocation takes effect on the next block.
Request format
A signed exchange request contains the action, a nonce, a signature, and an optional vault address:
{
"action": {
"type": "order",
"orders": [{ "asset": 0, "isBuy": true, "limitPx": "104000", "sz": "0.01", "reduceOnly": false, "tif": "Gtc" }],
"grouping": "na"
},
"nonce": 1762732800123,
"signature": { "r": "0x...", "s": "0x...", "v": 27 },
"vaultAddress": null
}Never ship a master key
Use an API wallet in any client that is not a hardware wallet. If a key leaks, an attacker can trade and cancel, but cannot withdraw your funds. Revoke the wallet and rotate immediately.
Signing steps
- Serialize the action deterministically (sorted keys, no whitespace).
- Hash the serialized action with the domain separator.
- Sign the hash with the account or API wallet key.
- Send the action, nonce, and signature to
POST /exchange.
The exact typed-data structure is documented in signing. Use an SDK rather than implementing it by hand.
Nonces
Every signed action needs a nonce greater than the last accepted nonce for that signer. Use the current time in milliseconds. See nonces and API wallets.
Expiry
Some actions support expiresAfter, a millisecond timestamp after which the action is rejected. User-signed actions such as usdClassTransfer do not support it. An action canceled because it expired still consumes rate-limit weight (5x the normal weight).
Common errors
| Error | Meaning |
|---|---|
Invalid signature | Wrong domain, hash, or signer |
Nonce too low | Reused or out-of-order nonce |
Unauthorized | API wallet not approved for the account |
Action already expired | expiresAfter is in the past |