Quickstart¶

This guide walks you through your first interaction with Sera — from querying available tokens to placing your first swap.

Prerequisites¶

• An Ethereum wallet (e.g., MetaMask)
• Testnet ETH for deposits, withdrawals, and limit-order settlement (swap-only flows do not require ETH). Use a Sepolia faucet.
• Testnet stablecoins to trade with — claim any of the registered tokens (USDC, EURC, GBPA, XSGD, …) for free from the Sera testnet faucet (see below).

Step 1: Explore Available Tokens¶

Query the token registry to see what stablecoins are available:

curl https://api.testnet.sera.cx/api/v1/tokens

import requests

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

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

Step 2: Get a Swap Quote¶

Get a quote to swap between two tokens:

curl -X POST https://api.testnet.sera.cx/api/v1/swap/quote \
  -H "Content-Type: application/json" \
  -d '{
    "from_token": "0x965d4b4546716e416e950bc30467d128455d2d0e",
    "to_token": "0xef64d15ed6c371545eb6dcd6c026c17dfb6c440f",
    "from_amount": "1000000000",
    "owner_address": "0xYOUR_ADDRESS",
    "recipient": "0xYOUR_ADDRESS",
    "expiration": 1735689600,
    "gas_mode": "receive_less"
  }'

import time, requests

quote = requests.post(
    "https://api.testnet.sera.cx/api/v1/swap/quote",
    json={
        "from_token":     "0x965d4b4546716e416e950bc30467d128455d2d0e",  # USDC
        "to_token":       "0xef64d15ed6c371545eb6dcd6c026c17dfb6c440f",  # EURC
        "from_amount":    "1000000000",                                  # 1000 USDC (6 dec)
        "owner_address":  "0xYOUR_ADDRESS",
        "recipient":      "0xYOUR_ADDRESS",
        "expiration":     int(time.time()) + 3600,
        "gas_mode":       "receive_less",
    },
    timeout=10,
).json()
print(quote)

const response = await fetch("https://api.testnet.sera.cx/api/v1/swap/quote", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    from_token:    "0x965d4b4546716e416e950bc30467d128455d2d0e",   // USDC
    to_token:      "0xef64d15ed6c371545eb6dcd6c026c17dfb6c440f",   // EURC
    from_amount:   "1000000000",                                    // 1000 USDC (6 dec)
    owner_address: "0xYOUR_ADDRESS",
    recipient:     "0xYOUR_ADDRESS",
    expiration:    Math.floor(Date.now() / 1000) + 3600,
    gas_mode:      "receive_less",
  }),
});
const quote = await response.json();
console.log(quote);

The response includes a uuid and route_params — these are the parameters you'll sign with your wallet.

Step 3: Sign and Execute the Swap¶

Sign the route_params using EIP-712 typed data signing, then submit:

from eth_account import Account
from eth_account.messages import encode_typed_data

# `domain` and `INTENT_TYPES` are documented under Authentication
signable  = encode_typed_data(domain, INTENT_TYPES, quote["route_params"])
signature = Account.from_key(PRIVATE_KEY).sign_message(signable).signature.hex()

submit = requests.post(
    "https://api.testnet.sera.cx/api/v1/swap",
    json={"uuid": quote["uuid"], "signature": "0x" + signature.lstrip("0x")},
    timeout=10,
).json()

// `domain` and `INTENT_TYPES` are documented under Authentication
const signature = await signer.signTypedData(domain, INTENT_TYPES, quote.route_params);

const result = await fetch("https://api.testnet.sera.cx/api/v1/swap", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ uuid: quote.uuid, signature }),
});

Quotes are single-use. If submission fails after the quote is consumed, request a fresh quote instead of retrying the same uuid.

For detailed signing instructions, see Authentication.

Step 4: Check Your Balances¶

Create an API key to query your balances and order history. The /balances endpoint returns both your wallet balance (tokens in your Ethereum wallet) and your Vault balance (tokens deposited for limit order trading), along with any frozen amounts locked in open orders.

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

for bal in balances:
    print(f"{bal['symbol']}:")
    print(f"  Wallet:         {bal['wallet_balance']}")
    print(f"  Vault available: {bal['vault_available']}")
    print(f"  Vault frozen:    {bal['vault_frozen']}")

const response = await fetch(
  "https://api.testnet.sera.cx/api/v1/balances?owner_address=0xYOUR_ADDRESS",
  { headers: { "Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET" } },
);
const { balances } = await response.json();

for (const bal of balances) {
  console.log(`${bal.symbol}:`);
  console.log(`  Wallet:          ${bal.wallet_balance}`);
  console.log(`  Vault available: ${bal.vault_available}`);
  console.log(`  Vault frozen:    ${bal.vault_frozen}`);
}

Using the Web App¶

You can also trade directly through the Sera web interface:

1. Visit testnet.sera.cx
2. Connect your wallet
3. Select a currency pair
4. Place a limit order or execute an instant swap
5. Monitor your orders in the dashboard

Next Steps¶

• Market Maker Guide — End-to-end walkthrough for programmatic order placement and cancellation
• Core Concepts — Understand order types, lifecycle, and fees
• API Reference — Full API documentation
• Order Types — Learn about limit orders, swaps, and more