Order Lifecycle¶

This tutorial walks through the complete lifecycle of a limit order on Sera — from placing the order to claiming proceeds.

Overview¶

sequenceDiagram
    participant User
    participant API as Sera API
    participant Chain as Ethereum

    User->>API: POST /orders (signed order)
    API-->>User: order_id
    Note over API: Order is matched<br/>when counterparty found
    API->>Chain: Settlement on-chain
    User->>API: GET /orders/{id}
    API-->>User: Status: settled
    Note over User: Proceeds available<br/>in vault balance

Step 1: Check Server Time¶

Before creating signatures, sync with the server clock to avoid expiration issues:

import requests

time_res = requests.get("https://api.testnet.sera.cx/api/v1/system/time")
server_time = time_res.json()["timestamp"]
print(f"Server time: {server_time}")

const timeRes = await fetch("https://api.testnet.sera.cx/api/v1/system/time");
const { timestamp } = await timeRes.json();
console.log("Server time:", timestamp);

Every signed order requires expiration, and the API enforces now < expiration <= now + 365 days - 300 seconds. Use server time, not only the browser clock, when you derive that field.

Step 2: Query Available Tokens¶

Get the list of supported tokens to find the contract addresses you need:

tokens = requests.get("https://api.testnet.sera.cx/api/v1/tokens").json()["tokens"]

# Find USDC and EURC addresses
usdc = next(t for t in tokens if t["symbol"] == "USDC")
eurc = next(t for t in tokens if t["symbol"] == "EURC")

const tokensRes = await fetch("https://api.testnet.sera.cx/api/v1/tokens");
const { tokens } = await tokensRes.json();

// Find USDC and EURC addresses
const usdc = tokens.find((t: any) => t.symbol === "USDC");
const eurc = tokens.find((t: any) => t.symbol === "EURC");

Step 3: Place a Limit Order¶

Use the Market Maker Guide setup and single-order helper, including its market selection. BASE and QUOTE come from the returned market. The helper previews, signs the returned normalized fields, saves the exact request before sending and stops on errors. Here the price 1 is an example in quote per base; select a price appropriate to that market.

placed = place_order("bid", BASE, QUOTE, Decimal("1000"),
                     Decimal("1"), int(time.time()) + 3600)
order_id = placed["order_id"]

const placed = await placeOrder("bid", BASE, QUOTE, "1000", "1",
                                Math.floor(Date.now() / 1000) + 3600);
const orderId = placed.order_id;

Step 4: Monitor Order Status¶

Use your API key to poll the order status:

status = requests.get(
    f"https://api.testnet.sera.cx/api/v1/orders/{order_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET"},
    timeout=10,
).json()
print("Status:", status["status"])
# External statuses: "pending", "matched", "settled", "cancelled", "failed"
print("Filled:", status["filled_amount"])
print("Signed uuid_int:", status["uuid_int"])

const statusRes = await fetch(
  `https://api.testnet.sera.cx/api/v1/orders/${orderId}`,
  { headers: { "Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET" } },
);
const status = await statusRes.json();
console.log("Status:", status.status);
// External statuses: "pending", "matched", "settled", "cancelled", "failed"
console.log("Filled:", status.filled_amount);
console.log("Signed uuid_int:", status.uuid_int);

Step 5: Check Your Balances¶

Once the order settles, proceeds appear in your vault balance:

balances = requests.get(
    "https://api.testnet.sera.cx/api/v1/balances",
    params={"owner_address": wallet_address},
    headers={"Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET"},
    timeout=10,
).json()["balances"]

for bal in balances:
    print(f"{bal['symbol']}: vault_raw={bal['vault_available']}, "
          f"frozen_raw={bal['vault_frozen']}, decimals={bal['decimals']}")

const balanceRes = await fetch(
  `https://api.testnet.sera.cx/api/v1/balances?owner_address=${walletAddress}`,
  { headers: { "Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET" } },
);

const { balances } = await balanceRes.json();
for (const bal of balances) {
  console.log(`${bal.symbol}: vault_raw=${bal.vault_available}, ` +
              `frozen_raw=${bal.vault_frozen}, decimals=${bal.decimals}`);
}

GET /balances now returns raw uint256 decimal strings. Convert them with each row's decimals field before displaying human-readable balances.

Step 6: Cancel an Order (Optional)¶

If you want to cancel an unfilled or partially filled order:

# Reuse cancel_order from the Market Maker Guide.
cancel_order(order_id, int(status["uuid_int"]))
# Query this order again to confirm its current state.

// Reuse cancelOrder from the Market Maker Guide.
await cancelOrder(orderId, BigInt(status.uuid_int));
// Query this order again to confirm its current state.

Step 7: Withdraw (Optional)¶

To move funds from your vault back to your wallet, use the instant-withdraw flow:

1. POST /withdraw to obtain the executor co-signature.
2. POST /withdraw/build to get the unsigned executeInstantWithdrawDualSig transaction.
3. Sign that transaction locally and broadcast it with POST /withdraw/send.

If the API is unavailable, use the on-chain emergency withdrawal flow, subject to its request, delay, execution-window and balance rules.

Virtual Liquidity Orders¶

VL orders follow the same lifecycle as standard limit orders, but with shared budget management. When a VL sibling fills, the matching engine automatically amends or cancels the remaining siblings to stay within budget.

Key differences:

• Placement — Use POST /orders/vl/batch instead of POST /orders
• Cancellation — Use POST /orders/vl/cancel to cancel the entire batch, or POST /orders/cancel for individual siblings
• Budget tracking — The system tracks a shared frozen balance across all siblings; fills on one sibling reduce the budget available to others

See Virtual Liquidity for the full guide.

Order States Summary¶

pending can include a partially filled resting order. For progress displays, do not rely on status alone: read filled_base_amount, filled_quote_amount, remaining_amount, settlement_summary, and /fills. Use settlement_economics.gross_debits and gross_credits for owner balance-movement displays. The public API does not expose protocol spread capture or counterparty transfer splits.