Architecture

How the layers compose.

Sera for Agents is a stack of independent layers. Pick the highest one that solves your problem; everything below it is implementation detail.

The stack, top-down

┌─────────────────────────────────────────────────────────┐
│  Your app / agent / dashboard / widget / cron job       │
└─────────────────┬───────────────────────────┬───────────┘
                  │                           │
       ┌──────────▼──────────┐    ┌───────────▼──────────┐
       │  MCP host           │    │  HTTP (x402)          │
       │  Claude / Cursor /  │    │  Plain fetch / curl   │
       │  ChatGPT / Hermes   │    │                       │
       │  / OpenClaw / your  │    │                       │
       │  own.               │    │                       │
       └──────────┬──────────┘    └───────────┬──────────┘
                  │                           │
       ┌──────────▼──────────┐    ┌───────────▼──────────┐
       │  sera-mcp           │    │  x402-service         │
       │  32 tools, stdio    │    │  Express, /x402/swap  │
       │  JSON-RPC.          │    │  402 → pay → 200      │
       │  Policy + caps +    │    │  Wraps sera-mcp.      │
       │  signer + dry-run.  │    │                       │
       └──────────┬──────────┘    └───────────┬──────────┘
                  │                           │
                  └─────────────┬─────────────┘
                                │
                  ┌─────────────▼─────────────┐
                  │  Sera REST API             │
                  │  api.sera.cx/api/v1        │
                  │  /tokens · /markets · /fx  │
                  │  /quote · /execute · /...  │
                  └─────────────┬─────────────┘
                                │
                  ┌─────────────▼─────────────┐
                  │  Sera Protocol             │
                  │  CLOB on Ethereum mainnet  │
                  │  Maker / taker / settle    │
                  └────────────────────────────┘

Layers explained

1. Sera Protocol (on-chain)

An on-chain central limit order book for stablecoin FX, deployed on Ethereum mainnet. Makers post quotes, takers cross them, settlement is atomic. Not a DEX. Not an AMM. Think Visa, not Uniswap.

2. Sera REST API (`api.sera.cx/api/v1`)

The canonical interface to Sera Protocol state. Token registry, market catalog, FX rates, quote generation, execute. Every higher layer routes through this.

3. `sera-mcp` (the MCP)

32 tools exposed over the Model Context Protocol — stdio JSON-RPC. Wraps the REST API with policy gates, daily volume caps, dry-run kill switch, EIP-712 quote→sign→execute flow, server-derived USD notional, uuid-route_params binding. Self-contained: no SDK, no signer, no key handling.

Why an MCP? Because every modern agent host (Claude, Cursor, ChatGPT, OpenClaw, Hermes, NanoClaw) speaks MCP natively. Three lines of config and your agent has 32 FX tools.

4. `x402-service` (HTTP wrapper)

A thin Express server that wraps sera-mcp behind the x402 payment protocol. The calling agent pays USDC over plain HTTP, the service performs the FX swap on Sera, the recipient gets the target currency. No MCP host required, no SDK to import.

5. Templates & bundled agent

Pre-wired starter projects (terminal chat, web chat, webhook responder) and a complete bundled Sera Agent — useful when you want one-command-to-run rather than configure-from-scratch.

Two execution paths

Every interaction with Sera goes through one of two paths, depending on whether the caller speaks MCP or HTTP:

Path 1 — MCP (the default)

Agent host (Claude, Cursor, etc.) loads sera-mcp at startup.
Agent calls sera.get_quote — gets back a quote object with EIP-712 typed-data.
Agent's wallet client signs the typed-data (the MCP never sees the key).
Agent calls sera.execute_swap with the signature; sera-mcp submits to Sera REST.
On-chain settlement; agent polls sera.settlement_status for confirmation.

Path 2 — x402 (skip MCP)

Caller hits POST /x402/swap on the x402-service.
Server returns 402 Payment Required + a payment_id.
Caller pays USDC (EIP-3009 transferWithAuthorization) and retries with X-PAYMENT header.
Server verifies the payment, then performs the FX swap on Sera using a vault wallet, then transfers the target currency to the recipient.
Returns 200 OK with delivered amount + trade_id.

Trust boundaries

What the MCP can do

Read everything from Sera REST (rates, markets, history, deals).
Generate signed-typed-data quote objects for the agent's wallet to sign.
Submit pre-signed quotes for execution.
Apply policy gates: notional caps, recipient whitelists, dry-run-only mode.

What the MCP cannot do

Hold or read a private key (signer is always the agent's wallet client).
Move funds without an externally-signed quote.
Bypass its own policy gates from inside a tool call.

x402 trust model

The x402-service runs a vault wallet that holds USDC inflows and executes the FX swap. That's a centralized custodian for the duration of the swap. Use the MCP path if you want the user's own wallet to sign every leg.

Where to put your code

An MCP plugin / agent skill — call sera.* tools, no extra infra needed. Cheapest, most flexible. See AI agent tutorial.
A web app — call sera-mcp from your backend (spawn it as a subprocess, talk JSON-RPC over stdio) OR call sera-agents/x402-service over plain HTTP. See payment widget + trading dashboard tutorials.
A smart contract — read Sera's reference rate from your contract via an oracle wrapper or call get_fx_rate off-chain and post it on-chain. See prediction market tutorial.
A cron job — call the bundled sera CLI from your scheduler. See treasury rebalancer tutorial.
An x402-paid API — wrap your own service in the same x402 pattern we use. See x402-paid API tutorial.

Repository layout

sera-mcp/            — the MCP server itself (32 tools, CLI)
sera-agents/
├── integrations/     — per-host install snippets (11 hosts)
├── templates/        — chat-cli · web-chat · webhook starters
├── sera-agent/       — the bundled interactive agent
├── x402-service/     — x402 HTTP wrapper around sera-mcp
├── x402/             — EIP-3009 payment helpers
├── examples/         — minimal one-file references
└── docs/             — this site

Next up: Concepts (CLOB, MCP, x402, EIP-712) · Pick a tutorial · Full API reference.