Ctrlk

POST /info

All public reads use one endpoint with a top-level type discriminator.

Unsupported or malformed query bodies return:

{
  "error": {
    "code": "UnsupportedInfoType",
    "message": "unsupported public info type `...`"
  }
}

assets

curl -sS -X POST "$API_URL/info" \
  -H 'content-type: application/json' \
  -d '{"type":"assets"}'

Response:

See Decimal Units for raw/display conversion and validation rules.

{
  "query_height": 180000,
  "app_hash": "0x...",
  "assets": [
    {
      "asset_id": 0,
      "symbol": "USDC",
      "balance_decimals": 8,
      "issuer": "0x0000000000000000000000000000000000000000"
    },
    {
      "asset_id": 6,
      "symbol": "SOL",
      "balance_decimals": 8,
      "issuer": "0xabcdef0123456789abcdef0123456789abcdef01"
    }
  ]
}

issuer is the owner account bound to an asset by the operator addAssetWithIssuer action. Genesis assets and assets created by the legacy operator addAsset action surface as the zero address. The issuer is a per-asset binding only — it is not an admin signer and confers no privileges beyond the recorded mapping. The assets response does not include cloid; client operation ids are only observable via txStatusByCloid while a transaction is in the recent query window.

quoteAssets

Returns the current canonical quote-asset allowlist sorted by asset_id. min_quantity is the human-readable minimum order notional in the quote token; min_quantity_atoms is the raw integer atom quantity encoded as a decimal string for JavaScript safety.

markets

Response field markets is sorted by market_id. price_decimals and max_price_sig_figs are market metadata, as is base_quantity_decimals. quote_balance_decimals is derived from the quote asset and included as a convenience field for raw notional conversion. See Decimal Units.

l2Book

depth is optional, defaults to 20, and is capped by the server.

userBalances

spotCreditAccount

status is "active" or "frozen". credit_usd_atoms and the available fields are in usd_atoms (USD_SCALE = 10^8). available_usd_atoms is null when any nonzero position asset lacks a mark at the latest query height; accounts with no exposure can report their credit without marks. last_known_available_usd_atoms always uses the most recently committed marks regardless of staleness and is null only when a position asset has never had a mark. Negative fractional USD-atom position values are rounded down conservatively, matching the execution credit gate.

spotCreditPositions

Stage 6 single-leg semantics: a resting ask only debits the base asset; a resting bid only debits the quote asset. The other leg appears as actual_qty only when a fill produces a real settlement delta.

oracleStatus

When the oracle is unavailable, oracle_status is { "status": "unavailable", "reason_code": "ProviderError" } (or MissingRoute, StalePrice, InvalidPrice).

markPrices

asset_ids is optional; omitting it returns all known marks. The response is sorted by asset_id:

usd_atoms is the positive mark price scaled by USD_SCALE = 10^8. source_ts_ms is the upstream provider's per-feed timestamp (Binance spot: worker wall clock at response-fully-read; OKX: per-ticker ts; Binance futures: per-symbol time from /fapi/v2/ticker/price; Llama: per-coin timestamp (seconds) × 1000; cross routes use min(base, quote) of the inputs).

openOrders

original_qty is the submitted order quantity. For an order that partially fills and then rests on the book, filled_qty is nonzero and remaining_qty is the currently open quantity.

userAgents

Response field agents contains the active agent slots for the owner.

userFills

limit must be positive and is capped by the server. Height ranges wider than the configured recent window are rejected.

Each fill reports only the querying owner's side fee (chosen by role). fee_asset_id is the asset the fee was charged in (the asset that side received: base for a bid, quote for an ask), fee is the decimal amount formatted with that asset's balance_decimals, and fee_mode is "balance" or "credit". (Internally — in canonical events and the query model — the fee amount is a raw atom; only this public JSON fee is the formatted decimal string.) Trading fees activate at a network-specific height defined by the code protocol-rules schedule. There are two distinct null cases:

  • Pre-activation / no-fee fill (below the network's fee activation height): "fee_asset_id": null, "fee": "0", "fee_mode": null.

  • Fee-active fill whose fee floored to zero: non-null fee_asset_id and fee_mode with "fee": "0" — so clients can tell the fee regime is live.

orderStatus

Query by server order id:

Query by client order id:

orderStatus first checks the live pending overlay (cloid lookup only), then the current open-order view. If neither covers the order, it falls back to the latest retained status record for that oid or (user, market_id, cloid). Status records are action-result records, not a complete lifecycle stream: a successful incoming order writes one record even when it rests on the book, but later passive maker fills are exposed through userFills and open-order state changes rather than a new status record for the maker order. Explicit cancel and modify actions do write status records for the affected resting order. Outcome-stage failed order attempts also write retained status records when execution has enough order context: IocCancel, FokCancel, BadAloPx, MarketOrderNoLiquidity, and InsufficientSpotCredit can be queried by oid or (user, market_id, cloid) inside the recent query window.

The cloid lookup additionally surfaces:

  • Pending response (live overlay): when /trade returned accepted for a cloid-bearing tx but the queryView has not yet published the result, orderStatus by cloid returns a synthetic pending response (see below). The pending entry retires automatically when queryView publishes a result for the same accepted tx_hash; a queryView result whose tx_hash matches replaces the pending response with the real result on the next query.

  • Null-OID early-failure rows: when an accepted cloid-bearing tx fails before execution can assign an OrderId (BadNonce, ExpiredTx, agent/owner authorization failure, missing modify target, batch-item-level pre-OID failures, etc.), the published row carries "oid": null and a lower-case canonical status string. The row remains visible only while the live process is up — it is not regenerated by WAL replay on restart.

Admin/operator transaction status by cloid uses the admin signer address as the user namespace and does not require a market id:

Open order response:

Pending response (live overlay, accepted but not yet published):

Null-OID early-failure response (live-only):

Terminal order response:

Not found:

PreviousPOST /tradeNextTransaction Signing

Last updated