Limit Orders¶

Limit orders let you specify the exact price at which you want to buy or sell. The order sits on the order book until it is filled, cancelled, or expires.

Prerequisites¶

Before placing a limit order, you need:

1. Deposit into the Vault — limits and VL orders require collateral. Pre-funding reduces funding failures but does not guarantee settlement.
2. Gas for your own transactions — approve, deposit or withdrawal transactions sent by your wallet require network gas; settlement is sent by a relayer executor.

Bid (Buy Order)¶

A bid order specifies:

• Price — The maximum price you're willing to pay per unit
• Amount — The quantity you want to buy
• Pair identity — from_address is the market base token (what you want to buy) and to_address is the market quote token (what prices the market)

Example: "Buy 1000 XSGD at 0.7450 USDC per XSGD"

Ask (Sell Order)¶

An ask order specifies:

• Price — The minimum price you're willing to accept per unit
• Amount — The quantity you want to sell
• Pair identity — from_address is still the market base token and to_address is still the market quote token

Example: "Sell 500 XSGD at 0.7460 USDC per XSGD"

For every limit order:

• bid spends to_address to buy from_address
• ask spends from_address to sell into to_address
• Use the token contract addresses from GET /tokens; human-readable pair labels come from GET /markets

How Collateral Works¶

Assets remain in the on-chain Vault. Placing an order reserves collateral by moving amounts from available to frozen in off-chain accounting. Settlement updates the chain ledger; cancellation/recovery updates the reservation after the result is confirmed. Use vault_spendable and recovery/sync fields when determining whether another order can be placed. See balances.

Gas Costs¶

Settlement transactions consume EVM gas and are signed and broadcast by a relayer executor, whose wallet pays the chain fee. This does not require the limit-order owner to hold ETH merely for that settlement. User-visible fees are described by the quote and settlement_economics.fees_paid; this is not a promise that every deployment offers free trading. Transactions you send yourself, such as approve, deposit and withdrawal, require network gas.

Order Expiration¶

Orders must include an expiration timestamp — a future Unix timestamp after which the order can no longer be matched.

• expiration is required on every signed order
• the API rejects expiration <= now
• the API also rejects values beyond 365 days minus a 300-second clock-skew guard from current server time

Use GET /system/time when you build the order and leave a small client-side buffer instead of signing right at the limit.

Cancelling Orders¶

Orders can be cancelled at any time if they have not been fully filled. Cancelling a partially filled order returns the unfilled portion to your Vault balance.

• Single cancel — POST /orders/cancel with an EIP-712 CancelOrder signature
• Cancel all — POST /orders/cancel-all (requires API key)

API Reference¶

See Order Endpoints for full request/response details.

Before signing, use order preview to obtain canonical amount/price strings and raw signing fields. Bulk cancellation also requires a nonce and deadline; see order endpoints.