Skip to content

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. Tokens deposited in the Vault — Both you and your counterparty pre-deposit into the Vault, guaranteeing that every matched order settles. See The Vault to understand why this is needed and how it works.
  2. ETH in your wallet — Limit order settlement happens on-chain, and gas is paid in real ETH (unlike swaps, where gas is included in the quote).

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

Collateral is managed entirely by the on-chain Vault smart contract — Sera's off-chain services never hold or control your funds.

When you place a limit order:

  1. The required collateral is frozen in the Vault smart contract on-chain — it remains in the contract under your address, not transferred to Sera
  2. When the order is filled, proceeds are credited to your Vault balance on-chain via the settlement contract
  3. If you cancel, the frozen collateral is released back to your available Vault balance

Even while frozen, your tokens stay in the Vault contract and can be recovered via emergency withdrawal if Sera's off-chain services become unavailable.

You can check your available and frozen balances via GET /balances.

Gas Costs

Limit orders are settled on-chain when matched. You are responsible for paying gas in real ETH — unlike swaps, gas is not abstracted away. Make sure you have ETH in your wallet to cover settlement transaction fees.

Note

On Sepolia testnet, you can get free test ETH from a faucet.

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 — DELETE /orders/cancel-all (requires API key)

Note

All users are subject to a 5-minute cooldown — orders must be at least 5 minutes old before they can be cancelled.

API Reference

Action Endpoint Auth
Place order POST /orders EIP-712 signature
Cancel order POST /orders/cancel EIP-712 signature
Cancel all DELETE /orders/cancel-all API Key
Get order GET /orders/{id} API Key
List orders GET /orders API Key

See Order Endpoints for full request/response details.