Recipes

Copy. Paste. Ship.

Ten short snippets for things you'll do constantly. All assume sera-mcp is registered with the host (or imported as a Node module).

CLI5 lines

1. Quote a swap and execute it

The canonical pattern: get a quote, sign it, execute. The MCP never sees the key.

// In an MCP host (Claude Code / Cursor / your agent loop)
const q = await sera.get_quote({ from: 'USDC', to: 'XSGD', amount: 1000 });
const sig = await wallet.signTypedData(q.typed_data);
const r = await sera.execute_swap({ quote_id: q.uuid, signature: sig });
console.log('trade_id:', r.trade_id);

read-onlyno key

2. Find FX deals across all 60+ pairs

Probes Sera, diffs against multi-source external mid, ranks by edge. Use as a cron job.

const deals = await sera.find_deals({ min_bps: 25 });
deals.forEach(d =>
  console.log(`${d.pair}: ${d.edge_bps}bps @ ${d.notional}`)
);

CLIcron

3. Spread radar from a shell cron

Runs the triangular-arbitrage scanner across a fiat basket. Logs anything > 50 bps.

# crontab: every 15 min
*/15 * * * * sera spread-radar USD,SGD,MYR,EUR,GBP,JPY \
  --min-bps 50 --json >> /var/log/sera-arb.log

treasury

4. Compute multi-currency drift from target weights

Reads balances across all your wallets, values in USD, and emits the swaps that bring drift to zero.

const plan = await sera.rebalance_plan({
  wallets: ['0xAaa...', '0xBbb...'],
  targets: { USDC: 0.5, EURC: 0.3, XSGD: 0.2 },
  reporting_currency: 'USD'
});
plan.swaps.forEach(s => console.log(s.from, '→', s.to, s.amount));

x402curl

5. Hit the x402 endpoint from curl (demo mode)

No wallet, no MCP — just HTTP. The 402-then-pay-then-200 dance.

# 1. Get a 402 + payment_id
curl -i -X POST localhost:8402/x402/swap \
  -H 'Content-Type: application/json' \
  -d '{"from_currency":"USD","to_currency":"MYR","amount":100,"recipient":"0xVendor"}'

# 2. Retry with X-PAYMENT (demo mode accepts demo-auth)
curl -X POST localhost:8402/x402/swap \
  -H 'X-PAYMENT: <PAYMENT_ID>:demo-authorization' \
  -H 'Content-Type: application/json' \
  -d '{"from_currency":"USD","to_currency":"MYR","amount":100,"recipient":"0xVendor"}'

read-only

6. Mid-of-mids for any pair (no Sera liquidity required)

Median across three free FX providers. Useful as a reference for your own pricing.

const m = await sera.multi_source_mid({ base: 'USD', quote: 'JPY' });
console.log('median:', m.median, 'sources:', m.sources);

maker

7. Project market-making earnings at any spread

Returns the full ladder — what you earn at 5/10/25/50/100/200 bps for a given pair + size.

const ladder = await sera.maker_quote_ladder({
  pair: 'USDT/JPYC', notional_usd: 30000
});
ladder.forEach(r => console.log(`${r.bps}bps → $${r.expected_earnings}/day`));

conditional

8. Patient-quote pattern (limit watcher)

Sera's limit_watcher polls quotes within a budget; surfaces the executable swap when threshold hits.

const w = await sera.limit_watcher({
  from: 'USDC', to: 'EURC', amount: 10000,
  trigger_rate: 0.93, max_polls: 200, interval_s: 15
});
if (w.triggered) await sera.execute_swap({ quote_id: w.quote.uuid, signature: ... });

historySQLite

9. Build your own price feed by enabling history

Set SERA_HISTORY_DB and every fx_rate / quote call gets logged. Query series later.

# Enable persistence (set once)
export SERA_HISTORY_DB=$HOME/.sera/history.db

# After a few hours of normal use:
const series = await sera.fx_history({ pair: 'USD/SGD', hours: 24 });
const vol    = await sera.fx_volatility({ pair: 'USD/SGD', window_h: 24 });

opsfirst call

10. Health check + policy summary

Always run this first if anything looks off. Returns API health, network, signer mode, persistence state.

const d = await sera.doctor();
console.log('overall_ok:', d.overall_ok);
console.log('policy:', d.policy);
console.log('history_db:', d.persistence.history_db_present);

Need a recipe that's not here? Open an issue.