Accounts, subaccounts & portfolios
An account nests subaccounts, and each subaccount nests portfolios. The portfolio is the unit that holds USDC collateral and positions; every order, balance, and transfer targets one portfolio.
Master vs session keys
A long-lived master key is the root of trust. It registers short-lived session keys that sign your day-to-day requests, so the master key rarely touches the wire.
Signing requests
Writes are signed over a compact binary payload, not JSON. You pack the body, sign the raw bytes, and POST the Base64SignedPayload envelope using standard base64.
request_id & freshness
Every signed write carries a
request_id: a UUIDv7 that doubles as the idempotency key. Its embedded timestamp must be current, so generate a fresh UUIDv7 at send time.Orders & time-in-force
LIMIT and MARKET only. Side is the sign of
quantity (positive long, negative short), and time-in-force packs into one integer covering IOC, FOK, GTC, and GTT.Precision & units
Prices and sizes are scaled integers: PriceOfAtom is 1e-16 USDC per atom, cash writes use CentiCents (1e-4 USDC), and quantities are atoms. Floor to the tick and step before signing.
Rate limits
Requests are metered per credential. Pace your calls and back off on the limit response rather than retrying in a tight loop.
Errors & the 200 rule
A
200 OK can still be a rejection: signed writes return a RequestAck, so branch on status. Non-2xx carries an RFC 9457 problem with a stable code — branch on code, not the prose detail.