Skip to main content
Collateral on the ZLL Trading API is USDC only. Every perpetual market is quoted in USDC, and every cash balance, deposit, withdrawal, transfer, fee, and notional value is denominated in USDC. Each portfolio carries one cash balance — the collateral bucket your orders draw against. Cash in one portfolio does not back another; each portfolio has its own balance and its own margin. To move collateral between portfolios, transfer it.

​
Cash units on the wire

Cash uses one internal unit but reads differently depending on direction.
  • Internally, cash is measured in CentiCents, where 1 CentiCent = 0.0001 USDC (one ten-thousandth of a USDC) — the same integer family used for prices and sizes, covered in markets, assets, and precision.
  • In responses (reads), a cash balance comes back as a USDC decimal string, not an integer. For example, cash_balance is a string such as "1000.00".
  • In request bodies (writes), the size field of a deposit, withdrawal, or transfer is a signed 64-bit integer in CentiCents. To deposit 1,000 USDC, send size = 10000000 (1000 × 10000).
Do not mix the two representations. Balances you read back are USDC strings; the size you submit is an integer count of CentiCents. Multiply your USDC amount by 10000 to get the wire value.

​
Read your balance

Two read endpoints return cash, both authenticated with a read credential:
  • GET /api/v1/portfolio/balance returns the free cash balance for a single portfolio, as a USDC string.
  • GET /api/v1/portfolio/cash_balances returns one balance per portfolio. A pinned credential sees its own subaccount; an unpinned credential sees the whole account.
The Trading API reference has the full response schemas.

​
Deposit

Add USDC collateral to a portfolio.
  • Endpoint: POST /api/v1/trading/deposit
  • Auth: session-key signed payload.
  • Body: portfolio_id (the account_id / subaccount_index / portfolio_index triple) and size (CentiCents).
The response is a request acknowledgement carrying a status and processed_at_ns. A failed deposit returns a rejecting status rather than a transport error — read the body. Spot deposit is not yet available: the spot deposit request type is rejected with 400. Only USDC cash deposit is live.

​
Withdraw

Remove USDC collateral from a portfolio. A withdrawal is signed by a session key on the wire, the same as a deposit, but the exchange holds it to a higher bar.
A valid session signature alone does not authorize a withdrawal. The signing session must be admin-rooted — unpinned and chained to an admin master key. See withdrawals are admin-rooted.
  • Endpoint: POST /api/v1/trading/withdraw
  • Auth: admin-rooted session-key signed body.
  • Body: portfolio_id and size (CentiCents).
Spot withdrawal is not yet available: the spot withdrawal request type is rejected with 400. Only USDC cash withdrawal is live.

​
Transfer

Move USDC cash between portfolios without an external deposit or withdrawal. Both variants hit the same endpoint; the embedded request body selects the variant.
  • Endpoint: POST /api/v1/trading/transfer
  • Auth: session-key signed body.
Move cash between two portfolios you own under one account_id. The body carries the account_id once, plus from_subaccount_index / to_subaccount_index, from_portfolio_index / to_portfolio_index, and size (CentiCents).
Intra-account transfers rebalance collateral across your own subaccounts and portfolios — for example, funding an isolated-margin portfolio from your main one without leaving the exchange.

​
Closing a portfolio requires zero cash

A portfolio with a non-zero cash balance cannot be closed. Withdraw or transfer the balance out first. Next, deposit collateral and place your first order end to end in the quickstart.