Integer API (v2)¶

The v2 endpoints accept and return integer amounts as decimal strings. The existing v1 endpoints remain available. All paths on this page include /api/v2; do not append them to the /api/v1 base URL.

Amounts and Prices¶

amount_raw is the base-token amount in its smallest units; divide by 10 ** base_decimals for display.
price_tick is the quote/base price multiplied by 10 ** tick_precision. Use integer or exact decimal arithmetic, never JavaScript Number for economic values.
Current markets use quantity_precision = base_decimals and tick_precision = quote_decimals; read these values from GET /api/v1/markets.
Requests require positive uint256 strings. Response quantities such as left_amount_raw may be "0". raw_encoding is "int".

Place an Order¶

POST /api/v2/orders

Authentication: EIP-712 Order signature. An optional API key must belong to the same owner.

Request Body¶

{
  "owner_address": "0x...",
  "side": "bid",
  "amount_raw": "1000000000",
  "price_tick": "1085000",
  "order_type": "limit",
  "from_address": "0x...",
  "to_address": "0x...",
  "order_id": "00000000-0000-4000-8000-000000000001",
  "uuid_int": "6427948336465191935941739505432058208337171677044006212075520",
  "signature": "0x...",
  "expiration": 1800000000,
  "fee_bps": 0
}

This example assumes both tokens and the price have six decimals. Replace addresses, identifiers and deadlines with live values before signing.

Field	Required	Description
`owner_address`	Yes	Signing wallet
`side`	Yes	`bid` or `ask`
`amount_raw` / `price_tick`	Yes	Positive uint256 decimal strings; `amount` / `price` are not accepted
`from_address` / `to_address`	Yes	Market base/quote addresses, independent of side
`order_type`	Yes	`limit` or `market`; this route does not accept `fok`, `IOC` or `post_only`
`order_id` / `uuid_int`	Yes	Bound identifiers; use the UUID rules
`signature`	Yes	EIP-712 Order signature
`expiration`	Yes	Future Unix seconds, at most 365 days minus 300 seconds ahead
`fee_bps`	No	Nonnegative uint48 integer; default 0, included as `feeBps` in the signed Order
`client_id`	No	Accepted by the request schema but not forwarded as an order identifier or idempotency key

The signed Order uses raw fromAmount / toAmount. Compute base raw = amount_raw, quote raw = floor(amount_raw * price_tick / 10 ** base_decimals) for current market precision. A bid spends quote raw and receives base raw; an ask spends base raw and receives quote raw. Alternatively, preview the corresponding natural-unit values using order preview and sign its eip712_order. Use the domain from GET /api/v1/config.

Response¶

HTTP 201:

{
  "order_id": "00000000-0000-4000-8000-000000000001"
}

Query Orders¶

GET /api/v2/orders/{order_id}
GET /api/v2/orders

Authentication: API Key required. The owner comes from the key; neither route requires an owner_address query parameter.

List Parameters¶

Parameter	Default	Description
`status`	All	Stored order status, not the v1 display status
`symbol`	All	Market symbol
`limit`	100	1–1000
`before_timestamp`	None	Timestamp cursor
`before_order_id`	None	Order ID paired with the timestamp cursor

The list returns a JSON array, not {trades, total}. There is no offset, total, next_cursor or created_at in the v2 response. Do not derive a timestamp cursor from a field that is not returned; use a timestamp boundary already known to your application. For a display-oriented paginated history with creation times and totals, use v1 GET /orders.

Order Fields¶

Fields	Description
`order_id`, `owner_address`, `symbol`, `side`, `order_type`	Order identity and market
`status`	`submitted`, `open`, `filled`, `partially_filled`, `cancelled`, `rejected`, `failed`; `filled` does not itself prove chain settlement
`amount_raw`, `left_amount_raw`, `filled_base_amount_raw`	Original, remaining and filled base-token quantities
`filled_quote_amount_raw`, `price_tick`	Filled quote-token quantity and integer price
`quantity_precision`, `tick_precision`, `base_decimals`, `quote_decimals`	Integer metadata for interpretation
`raw_encoding`	`"int"`
`expiration`, `uuid_int`, `vl_batch_id`, `error`, `error_code`	Nullable metadata; `expiration` is an integer here, unlike the v1 string

Query Fills¶

GET /api/v2/fills/{order_id}
GET /api/v2/fills

Authentication: API Key required. Only the key owner's records are returned.

Both accept limit (default 100, maximum 500) and offset (default 0, maximum 10000). The account-wide route additionally accepts settlement_status; it does not implement v1's order_status filter.

Both return { "items": [...] }. Each item contains quantity_raw, price_tick, settlement_base_amount_raw, settlement_quote_amount_raw, maker_order_id, taker_order_id, is_taker_buyer, settlement_status, raw_encoding, and nullable trade_id, timestamp, tx_hash, failure_reason. Use settlement evidence to distinguish a match from a confirmed transfer.

Balances and Cancellations¶

GET /api/v2/balances

This is an alias of v1 balances: API Key required, owner_address must match the authenticated owner, include_zero defaults to false, and amounts remain raw strings.

Cancellation continues through the signed v1 cancel endpoints. There is no separate v2 cancellation route. See error handling for 4xx/503 handling.

Balance synchronization¶

POST /api/v2/balances/sync uses the same required fields, API Key owner check, HTTP 202 response and version-conflict handling as v1 balance sync. Read capabilities.balances.sync_enabled first. v2 balances also return the spendability and recovery fields; vault_available alone is not spendable balance. Zero rows carrying recovery/sync state can remain when include_zero=false.