Sera FX Agent

A complete AI agent workspace for settling foreign exchange transactions across stablecoin rails using Sera Protocol.

7 knowledge domains. 6 reasoning skills. 9 MCP tools wired to live Sera endpoints — every query goes through GraphQL parameterized variables (no string interpolation, no injection vectors).

Clone it, configure it, run it. Works in OpenClaw, Hermes, NanoClaw, Claude Code, Claude Desktop, Cursor, OpenAI Agents SDK — and any other MCP-capable host.

Quick Start (OpenClaw — default)

git clone https://github.com/Josh-sera/sera-fx-agent.git
cd sera-fx-agent

# Copy env, add your LLM API key
cp .env.example .env

# Install MCP server dependencies
cd mcp/sera-fx-server && npm install && cd ../..

# Run with OpenClaw
openclaw start

Other hosts

See hosts/README.md for per-host setup snippets:

• Hermes — native MCP support since v0.13.0; symlink the skills folder for native skill discovery
• NanoClaw — drop the .mcp.json file from hosts/nanoclaw.mcp.json
• Claude Code — claude mcp add sera-fx -- npx tsx <path>/mcp/sera-fx-server/index.ts
• Claude Desktop / Cursor / Cline / Continue / Windsurf / Zed / Goose — standard MCP stdio config

Architecture

Two-layer knowledge system (context-engineering style):

• Layer 1: MEMORY.md (~150 lines, always loaded). Compressed essentials: corridor economics, cost formulas, decision trees, tool reference. Keeps every conversation grounded with low token cost.

• Layer 2: 7 knowledge/*.md files (each 379–733 lines, lazy-loaded). Loaded only when keyword triggers in AGENTS.md match. Query about "SWIFT" → loads cross-border.md. Query about "Uniswap" → loads defi-infra.md. Deterministic, no guessing, low cost.

• Schema is the highest-leverage artifact: AGENTS.md defines the keyword routing + tool routing + behavior rules. Inspired by Karpathy's "LLM Wiki" pattern — see knowledge/freshness.md for the verification log that keeps grounding from rotting.

Why this matters for cost:

Loading every knowledge file into every prompt: $50+/day. Keyword-triggered loading: $3–$12/day.

Sera MCP Tools (9)

Schema verified live against the Sera subgraph (sera-pro/1.0.9) on 2026-05-13.

The MCP never holds a private key. Order params come back; your wallet sets the maker field and signs.

Sera Protocol

Sera is a fully on-chain central limit order book (CLOB) for FX settlement between stablecoins on Ethereum.

• Zero slippage — trade at exactly the price you see (CLOB, not AMM)
• 60+ FX pairs — verify the live count via sera_list_markets
• Order NFTs — every position is a composable on-chain asset
• Sepolia testnet live, mainnet rolling out 2026

Endpoints (override via env):

• GraphQL: https://api.goldsky.com/api/public/.../sera-pro/1.0.9/gn
• Router (Sepolia): 0x82bfe1b31b6c1c3d201a0256416a18d93331d99e
• Docs: docs.sera.cx

Repository layout

sera-fx-agent/
├── README.md
├── MEMORY.md                          Always-loaded compressed memory
├── AGENTS.md                          Keyword triggers + tool routing
├── openclaw.json                      OpenClaw config
├── .env.example
│
├── knowledge/                         Lazy-loaded deep references (7 files)
│   ├── fx-markets.md
│   ├── stablecoins.md
│   ├── defi-infra.md
│   ├── cross-border.md
│   ├── quant-trading.md
│   ├── agent-protocols.md
│   ├── programmable.md
│   └── freshness.md                   Verification log (Karpathy pattern)
│
├── skills/                            6 SKILL.md files (structured outputs)
│   ├── fx-market-analysis/
│   ├── stablecoin-routing/
│   ├── settlement-risk/
│   ├── defi-protocol-selector/
│   ├── agent-protocol-advisor/
│   └── cross-border-analyzer/
│
├── mcp/sera-fx-server/                9 Sera MCP tools (live-verified)
│   ├── index.ts
│   ├── package.json
│   └── tsconfig.json
│
└── hosts/                             Per-host integration snippets
    ├── README.md
    ├── nanoclaw.mcp.json
    ├── hermes.mcp.json
    └── claude-desktop.json

What changed in v2.0 (2026-05-13)

The previous build had 4 of 7 MCP tools broken against the live Sera schema (queried orders and ficammPositions which don't exist; used string interpolation in GraphQL — injection vector). v2.0 is a full audit + rewrite:

• Schema mapped against the live sera-pro/1.0.9 subgraph; all queries use parameterized variables
• Killed sera_ficamm_settle_advisor (no FCIC AMM entity in subgraph) and sera_run_market_maker (was a config-only placeholder, no actual MM logic)
• Renamed sera_rebalance_vault → sera_rebalance_plan with honest "PLANNER ONLY" disclosure
• Added sera_subgraph_status, sera_list_tokens, sera_list_markets, sera_chart_log
• Added knowledge/freshness.md verification log (Karpathy "LLM Wiki" pattern)
• Added hosts/ directory with Hermes, NanoClaw, Claude Desktop, Cursor configs
• All 9 tools smoke-tested live against real Sera markets

License

MIT