Skip to Content
API ReferenceREST APIGET /account/[id]

GET /account/{account_id}

Returns comprehensive account information including balances, positions, open orders, and margin status.

Request

Path Parameters:

NameTypeRequiredDescription
account_idnumberYesNord account ID
curl https://zo-mainnet.n1.xyz/account/12345

Response

{ "updateId": 1, "orders": [ { "orderId": 1, "marketId": 1, "side": "ask", "size": 1, "price": 1, "originalOrderSize": 1, "clientOrderId": null } ], "positions": [ { "marketId": 1, "openOrders": 1, "perp": null, "actionId": 1 } ], "balances": [ { "tokenId": 1, "token": "…", "amount": 1 } ], "margins": { "omf": 1, "mf": 1, "imf": 1, "cmf": 1, "mmf": 1, "pon": 1, "pn": 1, "bankruptcy": true } }

Response Fields

Account Object

FieldTypeDescription
updateIdnumberSequence number for state tracking
balancesBalance[]Token balances
positionsPosition[]Market positions
ordersOrder[]Open orders
marginsMarginsAccount margin/health status

Balance Object

FieldTypeDescription
tokenIdnumberToken identifier
tokenstringToken symbol (e.g., “USDC”)
amountnumberTotal balance

Position Object

FieldTypeDescription
marketIdnumberMarket identifier
openOrdersnumberNumber of open orders in this market
perpPerpPosition | nullPerpetual position details
actionIdnumberLast action that modified this position

PerpPosition Object

FieldTypeDescription
baseSizenumberPosition size in base asset
pricenumberEntry/average price
isLongbooleanTrue if long, false if short
sizePricePnlnumberPnL from size/price changes (USDC)
fundingPaymentPnlnumberPnL from funding payments (USDC)
updatedFundingRateIndexnumberFunding rate index at last update

Order Object

FieldTypeDescription
orderIdnumberUnique order identifier
marketIdnumberMarket identifier
sidestringbid (buy) or ask (sell)
pricenumberOrder price
sizenumberRemaining order size
originalOrderSizenumberOriginal order size
clientOrderIdnumber | nullOptional client-provided order ID

Margins Object

FieldTypeDescription
omfnumberOpen Margin Fraction numerator (USD)
mfnumberMargin Fraction numerator (USD)
imfnumberInitial Margin requirement numerator
cmfnumberCancel Margin requirement numerator
mmfnumberMaintenance Margin requirement numerator
ponnumberPosition + Orders Notional (USD)
pnnumberPosition Notional (USD)
bankruptcybooleanTrue if account is bankrupt

[!NOTE] Margin fractions are expressed as numerators. Divide by pon or pn to get the actual ratio. For example, if omf = 15000 and pon = 50000, the open margin fraction is 0.3 (30%).

Example: Python

import requests API_URL = "https://zo-mainnet.n1.xyz" def get_account(account_id: int): resp = requests.get(f"{API_URL}/account/{account_id}") return resp.json() account = get_account(12345) # Print balances print("Balances:") for balance in account["balances"]: print(f" {balance['token']}: {balance['amount']:.2f}") # Print positions print("\nPositions:") for pos in account["positions"]: if pos.get("perp"): perp = pos["perp"] direction = "LONG" if perp["isLong"] else "SHORT" pnl = perp["sizePricePnl"] + perp["fundingPaymentPnl"] print(f" Market {pos['marketId']}: {direction} {perp['baseSize']:.4f} @ ${perp['price']:,.2f} (PnL: ${pnl:,.2f})") # Print open orders print("\nOpen Orders:") for order in account["orders"]: side = "BUY" if order["side"] == "bid" else "SELL" print(f" {side} {order['size']:.4f} @ ${order['price']:,.2f}") # Check account health margins = account["margins"] if margins["pon"] > 0: margin_ratio = margins["omf"] / margins["pon"] print(f"\nMargin Ratio: {margin_ratio:.2%}") if margins["bankruptcy"]: print("⚠️ ACCOUNT IS BANKRUPT")

Error Responses

StatusDescription
404Account not found
Last updated on