API Overview¶

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

Base URL¶

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

Content Type¶

All request and response bodies use JSON.

Authentication¶

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

Rate Limits¶

Public per-client limits can also be configured at the edge proxy/CDN; check the limits published for your environment.

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

Access Scope¶

Customer endpoints support external integrations and retain the API-key, wallet-signature or signed-transaction requirements documented for each operation. “None” in the table means no trading API key is required; it does not mean unrestricted access. Credential verification still requires the credentials being verified. Use the features and ingress provided for your environment.

Operational probes are for deployment, load balancing and monitoring and should be accessed through restricted operational ingress. They are outside the customer trading flow. Documenting their paths does not require exposing them to the public internet.

Endpoints¶

System¶

Trading¶

Orders And Fills¶

Account And Funds¶

API Key Management¶

Additional API Versions and Services¶

v1 and v2 coexist; v2 changes amounts, status interpretation and pagination. Use the complete versioned paths above. The Address Screening API is a separate service with its own host and response contracts. System endpoints also document GET /api/v1/livez, /api/v1/warmz, /api/v1/readyz, /api/v1/policy-readyz, /api/v1/traffic-readyz and /api/v1/screening/status.

Operational Probes¶

These endpoints are for operators. Their handlers do not require a trading API key; deployment ingress should restrict access separately. Absence of an API-key requirement does not establish public-ingress protection.

Error Responses¶

Most errors return a JSON body with a detail field:

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

Most handler-side 5xx failures return 503 with {"detail":"Service temporarily unavailable; please retry"} and Retry-After: 1. Startup gates may return a different detail. See the client handling notes below for structured errors and safe retries.

Common Status Codes¶

Code Examples¶

import requests

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

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

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

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

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

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

Client Handling Notes¶

Quote and order-entry endpoints use an application-level public throttle; production-like environments require its 429 enforcement. Do not assume every anonymous endpoint uses the same limits. Batch quotes consume one slot per quote, not per HTTP request. API-key wallet limits still apply. Use X-RateLimit-Limit, X-RateLimit-Remaining and Retry-After when returned.

Most handler 5xx errors are replaced by a generic 503 with Retry-After: 1. Startup gates can return a different 503 detail while caches are warming. X-Sera-Retry-Safe: true explicitly marks selected failures before admission; without that marker, do not infer that a write had no effect. Query its order/quote identity before replacing an uncertain execution.

Do not assume detail is always a string or that every 422 contains Pydantic field details. Request-model errors use { "detail": "Invalid request" }. New flows also use 202 (execution pending), 304 (unchanged market response, no body), and 406 (unacceptable encoding). Unknown error codes should remain failures and retain the request ID for support.

Examples illustrate request/response shapes. Replace placeholder addresses and historic timestamps before sending requests; obtain current chain/contract values from /config and current seconds from /system/time. A path being documented does not establish that a particular deployment has enabled it.

Request body size¶

The trading API defaults to a 64 KiB (65,536 byte) limit on the complete request body; the target deployment may set another limit. The limit also applies to streamed bodies. Batch item counts and per-signature limits do not override the aggregate limit. HTTP 413 returns {"detail":"Request body too large"}; reduce the request size instead of retrying it unchanged. Screening has its own body and error rules. Its protocol/429 errors need not contain schema_version or error.retryable; do not require those fields for every error.