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         │
       │  55 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)

55 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 55 FX tools.

4. `x402-service` (HTTP wrapper)

A thin Express server that you run locally or deploy yourself, wrapping sera-mcp behind the x402 payment protocol. The calling agent pays USDC over plain HTTP, the service performs the FX swap on Sera, and the recipient gets the target currency. No MCP host or SDK is required, but agents.sera.cx does not host this service.

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. The three starters use a local stdio MCP by default; set SERA_MCP_URL to connect them to a Streamable HTTP MCP instead.

Two execution paths

Use the MCP path directly, or self-host the HTTP path when the caller speaks x402:

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 — self-hosted x402

You run x402-service locally or deploy it; the caller hits POST /x402/swap on your 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

Your x402-service deployment 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 self-host sera-agents/x402-service and call your deployment 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 (55 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

For local demo and live-readiness requirements, see x402-service/README.md and SECURITY-MODEL.md. Next up: Concepts (CLOB, MCP, x402, EIP-712) · Pick a tutorial · Full API reference.