Sera for Agents

Templates, examples, docs, and x402 integrations built on top of sera-mcp.

Live site: agents.sera.cx · Core MCP: sera-cx/sera-mcp

Who this is for: developers integrating Sera into an existing agent product, picking up a template to ship fast, or self-hosting an x402 service for agent-to-agent FX delivery.

Multi-currency settlement infrastructure for AI agents. Quote, convert, and settle across 40 stablecoins and 22 fiat currencies — USD, SGD, MYR, JPY, EUR, GBP, BRL, MXN, IDR, and more — through an open Model Context Protocol server, six starter templates, a complete bundled agent, and a self-hosted x402 service.

For deeper reading, see ARCHITECTURE.md, SECURITY-MODEL.md, and CHANGELOG.md.

Four paths

Paths A–C are available through their listed artifacts. Path D provides a self-contained, localhost demo; agents.sera.cx does not offer a public x402 URL. Live mode is self-hosted and requires Base Sepolia E2E verification plus explicit operator approval. See x402-service/README.md and SECURITY-MODEL.md.

Repository contents

sera-agents/
├── README.md                     This file.
├── index.html                    Landing page (single file, host anywhere static).
│
├── agents-gateway/               Public HTTP + MCP gateway for agents.sera.cx (17 keyless tools).
│
├── sera-agent/                   PATH C — bundled CLI.
│   ├── agent.ts
│   ├── package.json
│   └── README.md
│
├── templates/                    PATH B — copy-and-customize starters.
│   ├── README.md
│   ├── chat-cli/                 Terminal REPL.
│   ├── web-chat/                 Express + browser chat UI.
│   ├── webhook-agent/            HTTP endpoint that triggers an agent task.
│   ├── slack-agent/              Slack bot worker (Bolt, Socket/HTTP).
│   ├── discord-agent/            Discord bot AI Agent.
│   ├── market-maker/             Deterministic two-sided spread bot.
│   └── withdraw-cli/             Dual-sig instant-withdrawal walkthrough.
│
├── x402-service/                 PATH D — protocol-level service.
│   ├── server.ts                 Hono server. Implements 402 → pay → 200.
│   ├── package.json
│   └── README.md
│
├── integrations/                 Per-host integration configs + READMEs.
│   ├── openclaw/                 Sera in OpenClaw (3 paths: MCP, clawhub, plugin).
│   ├── hermes/                   Sera in Hermes (native MCP + skill wrapper).
│   ├── nanoclaw/                 Sera in NanoClaw (.mcp.json).
│   └── standard-mcp-hosts/       Claude Code, Desktop, ChatGPT, Cursor, Cline, etc.
│
├── skills/                       Portable Agent Skills for coding agents.
│   └── sera-protocol/            Sera Protocol knowledge and safe-integration workflow.
│
├── examples/                     Reference flows (programmatic, single-task agents).
│   ├── invoice-payer/
│   └── treasury-rebalancer/
│
└── x402/sera-x402.md             Original design notes for the x402 endpoint.

Plus repo-root files: LICENSE (MIT), CONTRIBUTING.md, CODE_OF_CONDUCT.md, .github/ (issue + PR templates).

The MCP server itself lives in a separate repo: sera-cx/sera-mcp — distributed independently. v0.8.3, 55 tools.

Path A — install the MCP

Fastest — remote, keyless (17 tools: quote/settle-intent, rates, corridors, deal-scanning + analytics). No install:

claude mcp add --transport http sera https://agents.sera.cx/mcp

Full server — local stdio (~55 tools incl. treasury, orders, execution; your own signer/key):

git clone https://github.com/sera-cx/sera-mcp
cd sera-mcp
npm install && npm run build

claude mcp add sera --scope user \
  --env SERA_NETWORK=mainnet \
  --env POLICY_PRESET=standard \
  -- node $(pwd)/dist/index.js

Verify in any agent session: Call sera.doctor. For other hosts and agent frameworks see integrations/frameworks.md and DISTRIBUTION.md.

Sera Protocol Agent Skill

skills/sera-protocol/SKILL.md is the portable, official Sera Protocol skill for AI coding agents. It covers safe discovery, quoting, settlement-intent, MCP, and self-hosted x402 workflows without embedding credentials or treating a live payment action as implicit. Its references/ directory includes the detailed API, contracts, MCP, Sera Agents, SeraPay, and frontend material.

Copy the directory into the user-level skill location for your coding agent. The following commands assume you are at this repository’s root:

Claude Code

mkdir -p ~/.claude/skills
cp -R skills/sera-protocol ~/.claude/skills/

Restart Claude Code if ~/.claude/skills did not exist when the session began, then invoke /sera-protocol or ask a Sera-related question.

Codex

mkdir -p ~/.codex/skills
cp -R skills/sera-protocol ~/.codex/skills/

Start a new Codex session after installing. Codex also provides a Skill installer for installing directly from this repository once this directory is on main.

GitHub Copilot

mkdir -p ~/.copilot/skills
cp -R skills/sera-protocol ~/.copilot/skills/

For a repository-only installation, use .github/skills/sera-protocol/ instead. Copilot can then auto-load the skill or invoke /sera-protocol.

Kiro

mkdir -p ~/.kiro/skills
cp -R skills/sera-protocol ~/.kiro/skills/

Kiro also supports importing this folder from its Agent Steering & Skills panel. For a workspace-only installation, copy it to .kiro/skills/sera-protocol/.

The layout follows the open Agent Skills convention, so the same directory can be shared across compatible tools. See the original implementation walkthrough: Sera Protocol Agent SKILL on Zenn.

Path B — build from a template

# Pick chat-cli, web-chat, webhook-agent, slack-agent, market-maker, or withdraw-cli
cp -r templates/web-chat ~/my-sera-agent
cd ~/my-sera-agent
npm install
export OPENAI_API_KEY=sk-...
export SERA_MCP_DIST=/path/to/sera-mcp/dist/index.js
npm start

Then customize SYSTEM_PROMPT in agent.ts/server.ts to make the agent yours. See templates/README.md for what each template is shaped for.

Path C — run the bundled agent

cd sera-agent
npm install
export OPENAI_API_KEY=sk-...
npm start

Interactive terminal chat. Try:

• “What stablecoins do you support for SGD?”
• “How much USDC to deliver exactly 5,000 MYR?”
• “Run sera.find_deals at 25 bps and rank the results.”

Path D — self-host the x402 service

cd x402-service
npm install
npm run demo                   # X402_MODE=demo, listens on :8402

In another terminal:

# Initial request → 402 with payment_required
curl -X POST http://localhost:8402/x402/swap \
  -H 'Content-Type: application/json' \
  -d '{"from_currency":"USD","to_currency":"MYR","amount":100,"recipient":"0xVendor"}'

# Retry with X-PAYMENT header → 200 with delivered
curl -X POST http://localhost:8402/x402/swap \
  -H 'Content-Type: application/json' \
  -H 'X-PAYMENT: :demo-authorization' \
  -d '{"from_currency":"USD","to_currency":"MYR","amount":100,"recipient":"0xVendor"}'

This demo is local-only; it is not hosted at agents.sera.cx. Live mode (X402_MODE=live) needs your own deployment, a funded vault wallet, RPC URL, facilitator integration, completed Base Sepolia E2E, and explicit operator approval. See x402-service/README.md and SECURITY-MODEL.md.

Reference flows (programmatic, not interactive)

# Cross-currency invoice payer
cd examples/invoice-payer
npm install
OPENAI_API_KEY=sk-... npm run start -- \
  --owner 0xYou --recipient 0xVendor --amount 5000 --currency MYR

# Treasury rebalancer
cd examples/treasury-rebalancer
npm install
OPENAI_API_KEY=sk-... \
SERA_API_KEY=... SERA_API_SECRET=... \
npm run start -- \
  --wallets 0xA,0xB,0xC \
  --target USD:40,SGD:30,MYR:20,EUR:10

Position

Sera complements single-currency agent rails rather than replacing them. Use any stablecoin as inflow. Use Sera for the FX leg whenever the counterparty needs settlement in a different currency.

Status

Honest read of what’s solid vs what’s still moving:

Roadmap

• x402-service live mode — Base Sepolia E2E verification. v0.6.0 wired the Coinbase CDP facilitator integration end-to-end (verify + settle + atomic CAS idempotency + cache-control + k≥3 confirmation gate + manual-refund queue). Operator needs to run one full payment cycle on Base Sepolia, refine authHeader() if CDP requires HMAC-SHA256 JWT instead of the current Bearer ${id}:${secret} form, then switch X402_NETWORK=base for mainnet.
• npx create-sera-agent — proper scaffolder once enough people use the templates.
• Push subscriptions — deal alerts and rate-threshold notifications instead of polling.

Development

# install all workspace packages
npm install

# run typecheck across every package
npm run typecheck

# run audit across every package (high+)
npm run audit

# both
npm run check

CI runs the same checks on every PR — see .github/workflows/ci.yml.

License

MIT.