1. CRX
  2. API reference
  3. Account
  4. Read your balance

Read your balance

GET/balance

Returns your collateral, margin, and last deposit and withdrawal. Granted viewers can call it.

Authentication

  • x-crx-address x-crx-ts x-crx-sig
  • x-crx-address x-crx-signer x-crx-ts x-crx-sig
  • x-crx-session

Parameters

NameInTypeDescription
chain requiredquerystring

A chains[].key from GET /health.

Responses

200

OK.

FieldTypeDescription
account requiredstring

Lowercase address.

state requiredstring live stale no_data not_on_chain not_seeded

live, stale (out of date), no_data, not_on_chain (removed or approval in progress) or not_seeded (onboarding not finished). Unless live, every figure except collateral is null; stale with seat_view.reason behind can keep the last live figures.

seat_viewobject
seat_view.reasonstring or null

Why state is not live: behind (figures lag the latest update). null when live.

as_of requiredinteger or null

Time of the figures.

as_of_block requiredinteger or null

Block number, or null.

collateral requiredstring or null

Live collateral in USD, else the last settled figure. null if none.

free requiredstring or null

Amount you can withdraw, in USD. null until every open position has a price.

equity requiredstring or null

Account equity, in USD.

im requiredstring or null

Initial margin, in USD.

mm requiredstring or null

Maintenance margin, in USD.

owed requiredstring or null

Loss the collateral did not cover; 0.000000 if none. Deposits repay it.

level_bps requiredinteger or null

Margin level: equity × 10000 / im.

margin_status requiredstring or null ok call liquidatable no_risk unconfirmed owes paused null

ok, no_risk (nothing open or owed), call (margin call), liquidatable (can be closed out), unconfirmed, owes (nothing open, owed above 0) or paused (all accounts paused).

clock_deadline requiredinteger or null

Deadline to cure a margin call, or null. Set by margin.called; cleared by margin.cured.

lift_band requiredstring or null

Expected margin_status when the pause ends. null unless margin_status is paused.

seed requiredobject

Onboarding status.

seed.statestring or null

seeded (onboarding finished) or null (not finished or unknown).

seed.codestring or null

Reserved. Always null.

open_legs requiredinteger or null

Number of open positions. null unless live.

account_statusstring active removed not_active

active, removed (no new trades; deposits and withdrawals allowed) or not_active (not approved, or setup not finished).

outcomestring

First that applies: platform_paused, margin_call (margin call or owes) or account_removed. Omitted if none.

messagestring

Text to show the user.

deposit requiredobject
deposit.last requiredobject or null

Latest deposit, or null.

deposit.last.tx requiredstring

Transaction hash; cite it to CRX.

deposit.last.index_in_tx requiredinteger or null

Index of your deposit in tx, from 0. null until known.

deposit.last.amount requiredstring or null

Amount in USD, as a decimal string.

deposit.last.status requiredstring pending credited failed

pending, credited (in this balance) or failed. The deposit.credited event on GET /trades can arrive a few seconds earlier. While final is false, a reorg can change failed to credited.

deposit.last.outcomestring

Why it is not credited or was returned; platform_paused if made during a pause. Omitted once credited.

deposit.last.messagestring

Text to show the user.

deposit.last.final requiredboolean

true once the status is final.

deposit.last.expected_byinteger or null

Expected credit time while pending. null during a CRX pause.

deposit.last.expected_by_atstring or null

expected_by as ISO 8601 UTC.

withdraw requiredobject
withdraw.live requiredboolean or null

true if on chain but not yet processed. null if unknown.

withdraw.nonce requiredstring

Nonce for your next POST /withdraw, as a decimal string. While withdraw.last is pending, it is that withdrawal's nonce and a new POST /withdraw returns 409 withdraw_in_progress.

withdraw.last requiredobject or null

Latest withdrawal, or null.

withdraw.last.item requiredstring or null

Withdrawal ID, as in POST /withdraw and withdraw.* events. If null, arm_tx identifies the withdrawal.

withdraw.last.tx requiredstring or null

Withdrawal transaction until executed, then the payout transaction. null until on chain or if unknown.

withdraw.last.arm_tx requiredstring or null

Withdrawal transaction. null until on chain.

withdraw.last.nonce requiredstring or null
withdraw.last.amount requiredstring or null

Amount in USD, as a decimal string. all for a withdrawal of all free collateral until it is accepted; then the USD it pays.

withdraw.last.paid requiredstring or null

USDC executed. On partial, the part executed.

withdraw.last.status requiredstring sending pending accepted paid partial returned refused

sending, pending (on chain), accepted (approved), paid (executed), partial (part executed), returned or refused. While final is false, a reorg can change returned or refused to accepted or paid.

withdraw.last.reason requiredstring or null

Refusal reason: expired, deadline_passed, bad_signature, paused, not_approved, in_progress or refused. null unless status is refused.

withdraw.last.outcomestring

withdrawal_pending (in progress), platform_paused (during a pause) or withdrawal_not_sent (refused, returned or part executed). Omitted once executed.

withdraw.last.messagestring

Text to show the user.

withdraw.last.final requiredboolean

true once the status is final. Always false on a refused with arm_tx null: no collateral moved; sign a new withdrawal.

withdraw.last.expected_byinteger or null

Latest expected execution time while in progress; execution can be earlier. null during a CRX pause or if unknown.

withdraw.last.expected_by_atstring or null

expected_by as ISO 8601 UTC.

400

bad_request, invalid_signature.

code bad_request invalid_signature

401

unauthorized: a header is missing or malformed, x-crx-ts is out of range, the call was already used, the signature does not match, or the caller lacks access.

code unauthorized

403

not_whitelisted: the account is not approved for this call.

code not_whitelisted

408

timeout: no answer within 30 seconds.

code timeout

429

rate_limited: retry after Retry-After seconds.

code rate_limited

HeaderTypeDescription
Retry-Afterinteger

Seconds until the next call is accepted.

ratelimit-limitinteger

Maximum calls in a burst.

ratelimit-remaininginteger

Calls remaining before the limit.

ratelimit-resetinteger

Seconds until the full limit is restored.

ratelimit-refillinteger

Calls restored per minute.

502

upstream: a chain read failed. Retry shortly.

code upstream