Core Concepts¶

This page explains the fundamental concepts you need to understand when trading on Sera.

Order Types¶

Sera supports three primary order types:

Swaps¶

Instant swaps execute immediately at the best available price. You specify the tokens and amount you want to trade, and Sera finds the best route.

• Price Protection — Set a minimum output amount to protect against unfavorable prices
• Multi-Leg Routing — Swaps can route through intermediate currencies for better rates

For the full guide, see Swaps.

Limit Orders¶

Limit orders let you specify the exact price at which you want to trade. They sit on the order book until matched or cancelled. Requires a Vault deposit and ETH for gas.

• Bid (Buy) — Specify the maximum price you're willing to pay
• Ask (Sell) — Specify the minimum price you're willing to receive

For the full guide, see Limit Orders.

Virtual Liquidity Batches¶

Virtual Liquidity (VL) batches let you place limit orders across multiple trading pairs backed by a single shared budget, maximizing capital efficiency for multi-pair strategies.

• Shared Collateral — Freeze the max of any single order cost, not the sum
• Unique Markets — Each sibling must target a distinct market; inverse pairs such as XSGD/USDC and USDC/XSGD count as duplicates
• Automatic Amendment — When one order fills, siblings are resized to fit remaining budget

For a full guide, see Virtual Liquidity.

Order Lifecycle¶

Every order follows a defined lifecycle. The public API surfaces five statuses:

stateDiagram-v2
    [*] --> Pending: Place Order
    Pending --> Pending: Partial Fill (still active)
    Pending --> Matched: All Legs Crossed
    Matched --> Settled: Chain Confirmed
    Matched --> Failed: Settlement Reverted
    Pending --> Cancelled: Cancel
    Pending --> Failed: Rejected or Settlement Failed

For partially filled orders, pending means "still resting", not "unfilled". Use the filled/remaining amount fields, settlement_summary, /fills, and public settlement_economics to show execution progress and owner balance movement.

Proceeds from a settled order are credited to your Vault balance automatically — there is no separate "claim" step.

For a complete walkthrough, see Order Lifecycle.

Non-Custodial Architecture¶

Sera is fully non-custodial. Your funds are held in on-chain smart contracts — Sera's off-chain services handle only order matching and never have access to your tokens. Even if Sera's API goes down, you can always withdraw directly on-chain.

For the full explanation, see Non-Custodial Design.

Vault & Balances¶

• Wallet Balance — Tokens in your Ethereum wallet
• Vault Balance — Tokens deposited into the Vault, available for trading
• Frozen Balance — Tokens currently locked in open orders — still in the Vault contract under your address

To trade with limit orders, you first deposit tokens into the Vault. When you place an order, the required tokens are frozen. When an order fills, proceeds are credited to your Vault balance. All fund movements are enforced by the smart contracts.

Virtual Liquidity¶

Virtual Liquidity (VL) lets you place orders across multiple trading pairs backed by a single shared budget. Instead of locking capital for each order independently, a VL batch shares one pool of collateral — one fill automatically adjusts the remaining siblings to stay within budget.

• Capital Efficiency — Freeze the max of any single order cost, not the sum
• Multi-Pair Coverage — Place 2 to 50 sibling orders across distinct markets in one batch. Query GET /config → limits.vl_batch for the current cap.
• Unique Markets — Exact duplicates and inverse pairs are rejected inside the same batch
• Automatic Amendment — Siblings are resized or cancelled as the budget is consumed

For a full guide, see Virtual Liquidity.

Fees & Gas¶

• Swap users — Every cost the swap pays, including gas, is already incorporated into the quote you sign. Choose receive_less or pay_more gas mode when requesting the quote; you do not need to hold ETH separately.
• Limit order users — Gas is paid in real ETH at settlement time.

For more details, see Fees & Costs.

EIP-712 Signatures¶

All trading operations on Sera are authorized via EIP-712 typed data signatures. This means:

• You sign a structured message with your wallet (e.g., MetaMask)
• The signature authorizes a specific action (place order, cancel, withdraw)
• Your private key never leaves your device
• Each signature is bound to a specific chain and contract, preventing replay attacks

For API users, see Authentication to learn how to construct and sign these messages.

Next Steps¶