Skip to content

API Overview

The Sera API is a versioned REST API for trading, balance queries, and transaction-building flows.

Base URL

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

Content Type

All request and response bodies use JSON.

Authentication

Method Used For How It Is Sent
API Key Read endpoints and transaction-building helpers Authorization: Bearer {api_key}:{api_secret}
EIP-712 Signature Trading mutations, cancellations, withdrawals, API-key management Signature fields in the request body or query string

See Authentication for the EIP-712 domain, typed-data payloads, and uuid_int rules.

Rate Limits

Public per-client throttling is enforced at the edge proxy/CDN.

Requests authenticated with an API key are additionally rate limited per wallet inside the application:

Group Typical Endpoints Limit
read GET /orders, GET /balances, GET /fills 10 req/s
trade POST /orders, POST /swap 5 req/s
cancel POST /orders/cancel, DELETE /orders/cancel-all 2 req/s
transfer Deposit, approve, withdraw, transfer, and tx-broadcast helpers 2 req/s

Endpoints

System

Method Path Auth Description
GET /health None Service health, executor_id, and signature readiness
GET /system/time None Server timestamp for signature deadlines
GET /tokens None Whitelisted token registry
GET /markets None Active markets with token metadata
GET /fx/rate None Aggregated FX rate for an ISO currency pair plus 24h delta
GET /permit/metadata API Key EIP-2612 permit domain, nonce, and allowance probe
GET /config None Public chain and contract bootstrap config
POST /verify-signature None Verify an EIP-712 order signature

Trading

Method Path Auth Description
POST /swap/quote None Get a swap quote and signed route_params payload
POST /swap EIP-712 Execute a signed swap quote
POST /orders EIP-712 Place a limit order
POST /orders/cancel EIP-712 Cancel a single order
DELETE /orders/cancel-all API Key Cancel all open orders
POST /orders/vl/batch EIP-712 Place a Virtual Liquidity batch
POST /orders/vl/cancel EIP-712 Cancel a full Virtual Liquidity batch

Orders And Fills

Method Path Auth Description
GET /orders/{order_id} API Key Get one order by ID
GET /orders API Key List orders for one account
GET /fills/{order_id} API Key List fills for one order
GET /fills API Key List fills across all orders

Account And Funds

Method Path Auth Description
GET /balances API Key Wallet + vault balances
POST /approve API Key Build unsigned ERC-20 approve(spender, amount) tx
POST /deposit API Key Build unsigned depositFund or depositFundWithPermit tx
POST /tx/send API Key Broadcast a signed approve/deposit tx
POST /withdraw EIP-712 Request executor co-signature for instant withdraw
POST /withdraw/build Optional API Key Build unsigned executeInstantWithdrawDualSig tx
POST /withdraw/send Optional API Key Broadcast a signed withdrawal tx
POST /transfer API Key Build unsigned ERC-20 transfer tx
POST /transfer/send API Key Broadcast a signed transfer tx

API Key Management

Method Path Auth Description
POST /api-keys EIP-712 Create a read-only API key
GET /api-keys EIP-712 List API keys for one wallet (signed query parameters)
POST /api-keys/list EIP-712 List API keys for one wallet (signed JSON body)
DELETE /api-keys EIP-712 Revoke an API key (signed query parameters)
POST /api-keys/revoke EIP-712 Revoke an API key (signed JSON body)
POST /api-keys/revoke-all EIP-712 Bulk-revoke every active API key for one wallet in a single signature
POST /api-keys/self-revoke API Key Revoke the API key currently being used
POST /api-keys/verify None Verify an API key/secret pair without consuming rate-limit budget

Error Responses

Most errors return a JSON body with a detail field:

{
  "detail": "Human-readable error message"
}

Server-side failures (originally 5xx) are mapped to 503 with a generic body — clients see {"detail": "Service temporarily unavailable; please retry"} plus a Retry-After: 1 header. The specific cause is recorded server-side and is not echoed back to integrators.

Common Status Codes

Code Meaning
200 Success
201 Resource created
400 Bad request or signature mismatch
401 Missing or invalid API key
403 Authenticated wallet does not match requested owner
404 Resource not found
409 Conflict, such as replayed signature or self-match rejection
410 Quote expired, already consumed, or not found
422 Validation failure
429 Rate limit or cancel cooldown hit
503 Service temporarily unavailable; retry after the Retry-After header

Code Examples

// Public endpoint (no auth)
const tokens = await fetch('https://api.sera.cx/api/v1/tokens')
  .then(r => r.json());

// Authenticated endpoint (API key)
const orders = await fetch('https://api.sera.cx/api/v1/orders?owner_address=0x...', {
  headers: { 'Authorization': 'Bearer sera_abc123:secret456' }
}).then(r => r.json());

import requests

# Public endpoint
tokens = requests.get("https://api.sera.cx/api/v1/tokens").json()

# Authenticated endpoint
headers = {"Authorization": "Bearer sera_abc123:secret456"}
orders = requests.get(
    "https://api.sera.cx/api/v1/orders",
    params={"owner_address": "0x..."},
    headers=headers
).json()

# Public endpoint
curl https://api.sera.cx/api/v1/tokens

# Authenticated endpoint
curl -H "Authorization: Bearer sera_abc123:secret456" \
  "https://api.sera.cx/api/v1/orders?owner_address=0x..."