Skip to content

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.

No prior Vault deposit required

Swaps can use wallet funding and available Vault funds. This does not mean the route bypasses Vault: settlement can pull, credit or withdraw tokens through it. Separate approval transactions may require ETH.

  • 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 rest on the book until filled, cancelled or expired. They need Vault collateral; the relayer sends settlement transactions.

  • 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

Eligible failed limit takers may have their depth restored during recovery and return to pending; explicit user cancellation, expiration and non-limit order types prevent this recovery. Read the current order together with settlement_summary, /fills and balance movements rather than assuming every status transition is permanent.

Status Description
pending Submitted, resting on the book, or partially filled
matched All legs crossed in the matching engine; on-chain settlement is in flight
settled Fully filled and on-chain settlement confirmed
cancelled Cancelled by the owner before full fill
failed Rejected at intake or settlement reverted

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.

Settlement proceeds follow the signed recipient: the zero recipient credits the owner’s Vault ledger, while an external recipient receives tokens in that wallet. There is no separate claim step.

For a complete walkthrough, see Order Lifecycle.

Non-Custodial Architecture

Assets are held and settled on chain. The API, matching and accounting services coordinate instructions and reservations. Signing checks and contract roles define the authorization boundary; see Non-Custodial Design.

Vault & Balances

Wallet balances are external tokens. vault_available and vault_frozen are off-chain accounting amounts against on-chain custody; availability is not a guarantee of current spendability. Use vault_spendable, spendability_status and recovery/sync fields in balances.

Virtual Liquidity

VL shares one collateral budget across distinct markets. The engine deducts consumption and shrinks or cancels siblings when required; it does not increase their remaining signed quantity. Read the active minimum and maximum from GET /config → limits.vl_batch (default 2–50). See Virtual Liquidity.

Fees & Gas

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.

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