Skip to content

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.

Step 1: Explore Available Tokens

Query the token registry to see what stablecoins are available:

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

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

import requests

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

Step 2: Get a Swap Quote

Get a quote to swap between two tokens:

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

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

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:

// Sign the route_params with your wallet (EIP-712)
const signature = await signer.signTypedData(domain, types, route_params);

// Submit the signed swap
const result = await fetch('https://api.sera.cx/api/v1/swap', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    uuid: data.uuid,
    signature: 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.

const response = await fetch('https://api.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