API reference — Sera for Agents

sera.list_currencies

List supported stablecoins from Sera's live token registry — symbols, fiat tags, addresses, decimals. Use before any swap. Cached 5 min server-side.

Params

fiat — optional 3-letter fiat code filter (e.g. 'SGD')

Returns

{ count, policy_allowed_symbols, tokens: [{ symbol, fiat_currency, address, decimals, policy_allowed }] }

sera.get_markets

List the active trading-pair catalog from /markets. Pair existence ≠ tradeable now — pair with scan_markets for live quotability. Cached 10 min.

Params

None

Returns

{ count, markets: [{ pair, base, quote, ... }] }

sera.doctor

One-call self-check: API health, executor_id, network sanity, contract addresses, VL batch limits, signer mode, policy summary, persistence state.

Params

None

Returns

{ network_label, base_url, overall_ok, checks: [{ name, ok, detail }] }

sera.search_coins

Fuzzy-find stablecoins in Sera's live /tokens registry by case-insensitive substring match on symbol, name, or fiat tag (e.g. query='sgd'). Cached ~1 min server-side.

Params

query req — substring matched against token symbol, name, or fiat tag (e.g. 'sgd', 'usd', 'xsg')

Returns

{ query, count, matches: [{ symbol, name, fiat, address, decimals }] }

sera.get_coin_metadata

Full registry metadata (symbol, name, fiat, address, decimals) for a single stablecoin by symbol from Sera's /tokens registry. Case-insensitive; returns an honest not-found object if the symbol is unknown.

Params

symbol req — token symbol to look up (e.g. 'USDC', 'XSGD')

Returns

{ found, symbol, name, fiat, address, decimals }

sera.get_coin_history

Historical FX observations for a coin's implied fiat pair (e.g. XSGD → SGD/USD). Replays locally logged /fx/rate points and requires SERA_HISTORY_DB — returns an honest disabled/empty response otherwise.

Params

symbol req — token symbol whose implied fiat pair to pull history for (e.g. 'XSGD')
days — lookback window in days (default 7, max 365)

Returns

{ found, symbol, pair, enabled, note?, observations: [{ timestamp, rate, source }] }

sera.get_fx_rate

Sera's reference FX rate between two ISO currency codes. Has bid/ask asymmetry — for execution price use get_quote. Cached 60s.

Params

base req — base ISO fiat (e.g. 'GBP')
quote req — quote ISO fiat (e.g. 'USD')

Returns

{ pair, rate, as_of, rate_24h_ago, change_pct }

sera.compare_to_external_fx

Diff Sera's /fx/rate against Frankfurter (ECB published mid) to surface systematic pricing bias. Accepts ISO fiat or Sera token symbols.

Params

base req — ISO fiat or token symbol
quote req — ISO fiat or token symbol

Returns

{ pair, sera_rate, external: { source, rate, as_of }, deviation_bps, direction, ... }

sera.multi_source_mid

Median FX mid across 3 free external sources (Frankfurter / open.er-api / exchangerate.host). Resilient to a single source being down.

Params

base req — ISO fiat or token symbol
quote req — ISO fiat or token symbol

Returns

{ base, quote, sources: [{ source, rate, as_of }], median, range_bps }

sera.spread_radar

Liquidity-free FX consistency monitor across a currency basket. Flags forward/reverse pair asymmetry and triangular drift. Defaults: 150bps thresholds, USD/SGD/MYR/EUR/GBP/JPY basket.

Params

currencies — array of ISO fiat codes (default USD/SGD/MYR/EUR/GBP/JPY)
spread_alert_bps — flag forward×reverse deviation ≥ this (default 50)
triangular_alert_bps — flag triangle round-trip deviation ≥ this (default 50)
include_triangles — skip triangular checks when false (default true)

Returns

{ currencies, thresholds, summary, spreads, triangles, alerts, errors }

sera.scan_markets

Fan out parallel /swap/quote probes across many pairs — the deal-scanner pattern in one call. Default: 50 pairs, 8 concurrent, $100 notional.

Params

pairs — explicit [{ base, quote }]; else enumerated from /markets
notional_per_quote — probe size in from units (default 100)
max_pairs — cap when enumerating (default 50)
max_concurrency — bounded parallelism (default 8)
only_policy_allowed — restrict to POLICY_ALLOWED_SYMBOLS (default true)
gas_mode — receive_less | pay_more

Returns

{ summary: { pairs_tried, quotable_count, skipped_count, ... }, quotable, skipped }

sera.find_deals

End-to-end deal scanner: scan_markets + per-pair external mid comparison, filtered ≥ min_deviation_bps. Returns ranked good_sell / good_buy / fair lists.

Params

pairs — explicit pair list; else enumerated from /markets
notional_per_quote · max_pairs · max_concurrency
only_policy_allowed — restrict to allowed symbols
min_deviation_bps — minimum edge to count as a deal (default 25)
use_multi_source — benchmark = median of 3 sources (default true)
gas_mode — receive_less | pay_more

Returns

{ summary, good_sell: [...], good_buy: [...], fair: [...], skipped, note }

sera.maker_quote_ladder

Spread-ladder calculator for makers. Returns earnings at 5/10/15/25/50/100/200 bps for a pair + notional. Mid auto-fetched from multi-source median by default.

Params

base req · quote req
notional req — amount in the SELL leg
role — maker_sell_base | maker_buy_base (default sell)
mid — override the mid
mid_source — multi_source (default) | sera
spreads_bps — spreads to ladder (default [5,10,15,25,50,100,200])

Returns

{ pair, base_fiat, quote_fiat, role, notional, mid, mid_source, ladder: [{ spread_bps, quote_price, earned, ... }], reference, interpretation }

sera.probe_depth

Quote one corridor at a ladder of sizes to characterize price impact (bps relative to the smallest probe). Default sizes [100, 1000, 10000, 100000].

Params

from req · to req
sizes — human sizes to probe (default [100, 1k, 10k, 100k])
gas_mode · max_concurrency

Returns

{ pair, gas_mode, quotes: [{ size, output, rate }], price_impact: [{ size, impact_bps }], notes }

sera.round_trip_cost

Cost of A→B→A in bps — the spread floor a maker needs to cover their hedge. Returns absolute loss + bps interpretation.

Params

from req · to req
amount req — human amount in from units
gas_mode — receive_less | pay_more

Returns

{ pair, gas_mode, outbound, return, round_trip_loss_human, round_trip_loss_bps, interpretation }

sera.infer_book

Synthetic order book for a pair Sera doesn't publish a book for. Probes both directions at log-spaced sizes to construct bid/ask ladders. For visualizing depth, not execution.

Params

base req · quote req
sizes — probe sizes (default log-spaced 100→1M)
gas_mode — receive_less | pay_more

Returns

{ pair, best_bid, best_ask, spread_bps, bids: [...], asks: [...], notes }

sera.market_health

Quick yes/no on whether a corridor is quotable right now. Fires a single $1 simulate quote — cheaper than burning a full quote for pre-flight gating.

Params

from req · to req
gas_mode — receive_less | pay_more

Returns

{ pair, status: 'quotable' | 'no_liquidity' | 'unknown_pair' | 'error', detail }

sera.fx_quote_diff

Compare Sera's reference /fx/rate against the executable rate from a real quote at a chosen notional. Returns deviation in bps.

Params

from req · to req
notional — amount for the executable probe (default 100)
gas_mode — receive_less | pay_more

Returns

{ pair, fiat_pair, notional, reference_rate, executable_rate, executable_output, deviation_bps, gas_mode, interpretation }

sera.compare_corridors

Given a target output (currency + amount), rank candidate source currencies by USD-equivalent cost. "I need 5,000 SGD — which source does it cheapest?"

Params

target req — output currency or token to deliver
target_amount req — exact amount of target
sources req — candidate source token symbols
max_concurrency · gas_mode

Returns

{ target, gas_mode, ranked, failed, cheapest, summary }

sera.get_quote

Single-use Sera swap quote. Returns route_params (EIP-712 Intent) to sign + uuid + fee breakdown. Pass simulate:true to probe with the burn address (no execution).

Params

from req — source symbol, address, or fiat
to req — target symbol, address, or fiat
amount req — human amount in from units
owner_address — funding wallet (required unless simulate=true)
recipient — where output lands (defaults to owner_address)
gas_mode — receive_less (default) | pay_more
expiration_seconds — quote validity window
simulate — read-only probe with burn address (default false)

Returns

{ uuid, route_params, fee_breakdown, expires_at, permit, from, to, human, estimated_usd_notional, ... }

sera.prepare_swap

Alias of get_quote intended for execution-track flows. Same params and policy gates — use this name when intent is clearly "about to execute."

Params

from req · to req · amount req
owner_address · recipient · gas_mode · expiration_seconds · simulate

Returns

{ uuid, route_params, fee_breakdown, expires_at, permit, from, to, human, estimated_usd_notional, ... }

sera.quote_recipient_amount

Inverse quote: "I want them to receive exactly X of currency B — what do I send of A?" Uses /fx/rate then two real quotes to tighten. Does NOT execute.

Params

from req — token you're paying with
to req — currency the recipient receives
recipient_amount req — amount recipient ends up with
owner_address req
recipient — destination address

Returns

{ estimated_input_human, quote, target_recipient_amount }

sera.find_cheapest_settlement_path

Compare gas-mode candidates (receive_less vs pay_more) for one A→B and rank by min_output. For planning; each candidate consumes its own UUID.

Params

from req · to req
amount req
owner_address req

Returns

{ ranked: [{ label, uuid, input, min_output, fee_breakdown }] }

sera.batch_quote

Submit 1–50 quote requests in one round-trip via Sera's POST /swap/quote/batch. Each gets its own uuid and signed Intent; per-item errors don't fail the batch.

Params

quotes req — array of 1–50 { from, to, amount, owner_address?, recipient?, gas_mode?, expiration_seconds?, simulate? }

Returns

{ items: [{ ok, quote, error }] }

sera.limit_watcher

Patient quote: poll /swap/quote on a fixed budget until target_rate hits (or budget exhausted). Default 5 attempts × 6s ≈ 30s blocking.

Params

from req · to req · amount req
target_rate req — output_per_input threshold to fire at
side req — sell_from (rate ≥ target) | buy_from (rate ≤ target)
max_attempts — default 5, capped 30
interval_seconds — default 6, capped 60
gas_mode — receive_less | pay_more

Returns

{ pair, side, target_rate, amount, attempts, hit, last_rate, hit_probe, probes, next_step }

sera.execute_swap

Submit a signed swap quote (uuid + EIP-712 signature) to Sera. Destructive — money moves. Quotes are single-use; re-quote on QUOTE_STALE/410. Gated by POLICY_DRY_RUN + daily cap.

Params

uuid req — quote UUID from get_quote / prepare_swap
signature — EIP-712 sig over route_params (required in external signer mode)
route_params — optional; must exactly match what was returned for the uuid
permit_signature — EIP-2612 permit sig (required if quote carried a permit envelope)
permit_deadline — permit deadline (required iff permit_signature given)

Returns

{ success, trade_id, server_estimated_usd_notional, ...upstream Sera /swap response }

sera.convert_and_send

High-level: quote A→B and deliver to recipient in one call. Destructive — requires SERA_SIGNER_MODE=local. For external signer, use get_quote → sign → execute_swap.

Params

from req · to req · amount req
owner_address req
recipient req — final destination for the output token
gas_mode — receive_less (default) | pay_more

Returns

{ quote, execution }

sera.place_order

Submit a signed limit order. Destructive — agent-signed. Agent picks order_id (UUID4), signs the Order struct under the Sera EIP-712 domain. Idempotent on order_id.

Params

owner_address req
side req — bid | ask
amount req — quantity in base-token units
price req — quote per base
order_type req — 'limit'
from_address req — market BASE token address
to_address req — market QUOTE token address
order_id req — client-picked UUID4
uuid_int req · signature req · expiration req

Returns

{ order_id }

sera.cancel_order

Cancel an order by signing a CancelOrder struct (owner + uuid_int). Destructive. 5-min per-order cooldown (repeat → 429). In-flight fills may still settle.

Params

owner_address req
order_id req
uuid_int req
signature req

Returns

{ status }

sera.cancel_all_orders

Bulk-cancel every open order for the authenticated wallet. Destructive. Kill-switch / pause-trading workflow. Requires SERA_API_KEY.

Params

owner_address req — must match the authenticated API-key owner

Returns

{ cancelled: [...], failed: [...], skipped_cooldown: [...], total }

sera.place_vl_batch

Submit 2–50 signed limit orders sharing one collateral pool. Destructive. Engine freezes only the largest single-leg cost. Siblings share owner_address, fromToken, and a VL group_id.

Params

orders req — array of 2–50 signed orders (same owner_address + fromToken; shared VL group_id; sequential leg_id 0,1,2…)

Returns

{ order_ids, amendments, cancelled, fills, vl_group }

sera.cancel_vl_batch

Cancel an entire Virtual Liquidity batch by signing a CancelVLBatch struct against the batch's vl_batch_id. Destructive.

Params

owner_address req
vl_batch_id req — primary_id of the first leg
signature req

Returns

{ status }

sera.get_order

Full order record including settlement_summary (per-fill aggregation) and settlement_economics. Use to track fills or recover a lost uuid_int. Requires SERA_API_KEY.

Params

order_id req

Returns

{ ...upstream Sera GET /orders/{order_id} record }

sera.list_orders

Rich filtering over the wallet's order history: status, type, symbol, side, price/amount/notional ranges, time bounds, sort. Filters apply before pagination. Requires SERA_API_KEY.

Params

owner_address req
status · type · symbol · side — filters
from_token · to_token · base_token · quote_token · has_error
created_after · created_before · sort_by · order
limit (max 500) · offset

Returns

{ total, orders: [...] }

sera.get_fills

Per-fill list (maker/taker order ids, quantity, price, settlement_status, tx_hash, settlement_economics) filterable by order_status / settlement_status. Requires SERA_API_KEY.

Params

owner_address req
order_status · settlement_status — filters
limit (max 500) · offset

Returns

{ fills: [{ maker_order_id, taker_order_id, quantity, price, settlement_status, tx_hash, settlement_economics }] }

sera.get_fills_for_order

All fills against a specific order_id with per-fill settlement_economics. Requires SERA_API_KEY.

Params

order_id req
limit (max 500) · offset

Returns

{ fills: [{ quantity, price, settlement_status, settlement_economics }] }

sera.get_balances

Wallet + Vault balances for a wallet, normalized to human amounts. Requires SERA_API_KEY / SERA_API_SECRET.

Params

owner_address req — wallet to query

Returns

{ owner_address, balances: [{ symbol, wallet, vault_available, vault_frozen, raw }] }

sera.treasury_value

Aggregate balances across one or more wallets and value the portfolio in target_currency. Returns per-wallet rows + currency exposure breakdown.

Params

owner_addresses req — one or more 0x… wallets
target_currency — ISO fiat to value in (default USD)
include_zero — include zero-balance lines (default false)

Returns

{ target_currency, total_value, wallets: [...], exposure_breakdown: [...] }

sera.exposure_report

Slimmer cousin of treasury_value: just the currency mix and total. Use pre-trade ("am I over-exposed to MYR?").

Params

owner_addresses req
target_currency — ISO fiat to value in (default USD)

Returns

{ target_currency, total_value, exposure: [{ fiat, value_in_target, pct }] }

sera.rebalance_plan

Given target weights (by fiat code) and current balances, emit suggested swaps to rebalance. Pure planner — does not execute. Feed each trade into get_quote.

Params

owner_addresses req
target_weights req — { USD: 50, SGD: 30, MYR: 20 } (normalized)
target_currency — default USD
min_trade_value — skip trades below this (default 10)

Returns

{ target_currency, total_value, target_weights_normalized, drift, trades: [{ from_fiat, to_fiat, value_in_target, note }], next_step }

sera.pay_invoice

"I owe X of currency Y to address Z — given my source assets, what's the cheapest path?" Fans out across each candidate source and ranks by USD-equivalent cost.

Params

owner_address req · recipient req
amount req — recipient receives this in target_currency units
target_currency req — ISO fiat the recipient wants
source_symbols req — stablecoins available to spend
target_symbol — specific output token

Returns

{ invoice, ranked, failed, cheapest }

sera.settlement_status

Query Sera /orders for trade history or a specific trade. Filter by trade_id, uuid, owner_address, status, limit. Requires SERA_API_KEY / SERA_API_SECRET.

Params

trade_id · uuid · owner_address · status · limit — all optional filters

Returns

{ filters_used, result, note }

sera.build_approve

Build an unsigned EIP-1559 ERC-20 approve() tx. Sign locally with the owner wallet, then broadcast via send_tx. Spender must be the live vault_address or sor_address.

Params

token req — ERC-20 token address
owner req — owner wallet (matches API-key owner)
spender req — vault or SOR address
amount req — raw uint256 allowance

Returns

{ tx }

sera.build_deposit

Build an unsigned deposit tx. Omit permit_* for the standard depositFund flow (needs prior approve); include them to combine approval + deposit via depositFundWithPermit.

Params

token req · owner req
amount req — raw uint256 deposit amount
permit_signature · permit_deadline · permit_amount — optional EIP-2612 permit

Returns

{ tx }

sera.build_transfer

Build an unsigned ERC-20 transfer() tx. Sign locally, broadcast via send_transfer.

Params

token req
to req — recipient address
amount req — raw uint256 amount
from_address req — sender wallet

Returns

{ tx }

sera.send_tx

Broadcast a locally-signed raw_tx from build_approve or build_deposit. Destructive. Sera validates the selector-to-target pairing.

Params

raw_tx req — locally-signed raw transaction hex

Returns

{ tx_hash }

sera.send_transfer

Broadcast a locally-signed raw_tx from build_transfer. Destructive.

Params

raw_tx req — locally-signed raw transaction hex

Returns

{ tx_hash }

sera.withdraw_request

Step 1 of the dual-signature instant-withdrawal flow. User pre-signs a WithdrawIntent under the Sera EIP-712 domain; returns the executor co-signature.

Params

intent req — WithdrawIntent { user, tokens[], amounts[], recipient, deadline, uuid }
user_signature req — EIP-712 sig over the intent

Returns

{ success, executor_address, executor_signature, error }

sera.withdraw_build

Step 2 of dual-sig withdraw. Given the WithdrawIntent + user signature + executor co-signature, returns the unsigned executeInstantWithdrawDualSig transaction.

Params

intent req · user_signature req
executor req — co-signing executor address
executor_signature req

Returns

{ tx }

sera.withdraw_send

Step 4 of dual-sig withdraw. Broadcast the locally-signed executeInstantWithdrawDualSig raw_tx. Destructive. Only accepts calls targeting the live Sera contract.

Params

raw_tx req — locally-signed raw transaction hex

Returns

{ tx_hash }

sera.fx_history

Sera /fx/rate observations logged by THIS MCP since since_hours_ago. Sera doesn't publish OHLC — over time the MCP becomes its own price feed.

Params

base req · quote req
since_hours_ago — lookback window (default 24)

Returns

{ enabled, pair, since_hours_ago, observation_count, observations }

sera.fx_volatility

Stats over the fx_history window: mean, stdev, range_bps, annualized vol estimate.

Params

base req · quote req
since_hours_ago — lookback window (default 24)

Returns

{ enabled, pair, window_hours, observation_count, stats: { mean, stdev, min, max, range_bps, annualized_volatility_estimate }, note }

sera.corridor_pnl

What would holding the long side of this pair have realized over the window? Mark-to-market on logged /fx/rate; excludes swap costs.

Params

base req · quote req
since_hours_ago — lookback window (default 24)

Returns

{ enabled, pair, window_hours, first_rate, last_rate, drift_absolute, drift_bps, quote_observation_count, ... }

sera.verify_signature

Round-trip a signed payload through Sera's /verify-signature endpoint — diagnose wallet-side signing issues (wrong domain, malformed typed-data, mismatched uuid_int) before burning a quote.

Params

owner_address req · side req (bid|ask)
amount req · price req
from_address req — base token · to_address req — quote token
order_id req · uuid_int req
signature req · expiration req

Returns

{ valid, recovered_address, expected_address, error }

sera.permit_metadata

Whether a token supports EIP-2612 (permit_supported), the current owner→spender allowance, and — if supported — the EIP-2612 domain + next nonce.

Params

token req — ERC-20 to check
owner req — wallet that may sign permit
spender req — allowance target (vault/sor)
amount — raw amount to compare against allowance (adds required)

Returns

{ permit_supported, token, owner, spender, current_allowance_raw, nonce?, domain? }

Resources (5)

Browseable static catalogs the host can show.

sera://help/tools — full tool reference (this page, machine-readable)
sera://catalog/currencies — all supported stablecoins
sera://catalog/markets — all trading pairs
sera://policy/current — active policy preset + caps
sera://network/status — chain + indexer status

Slash prompts (4)

Pre-templated prompts that hosts surface as commands. Type /deal_scan in Claude Code, etc.

/deal_scan — find FX deals across all pairs above an edge threshold
/treasury_brief — multi-currency exposure report + drift
/invoice_optimizer — cheapest source for a given target payout
/fx_integrity_check — triangular-arb scan across a fiat basket

API reference.

Discovery (6)

sera.list_currencies

sera.get_markets

sera.doctor

sera.search_coins

sera.get_coin_metadata

sera.get_coin_history

Pricing & analytics

sera.get_fx_rate

sera.compare_to_external_fx

sera.multi_source_mid

sera.spread_radar

Liquidity probing

sera.scan_markets

sera.find_deals

sera.maker_quote_ladder

sera.probe_depth

sera.round_trip_cost

sera.infer_book

sera.market_health

sera.fx_quote_diff

sera.compare_corridors

Quote & plan

sera.get_quote

sera.prepare_swap

sera.quote_recipient_amount

sera.find_cheapest_settlement_path

sera.batch_quote

sera.limit_watcher

Execution

sera.execute_swap

sera.convert_and_send

Maker & orders

sera.place_order

sera.cancel_order

sera.cancel_all_orders

sera.place_vl_batch

sera.cancel_vl_batch

sera.get_order

sera.list_orders

sera.get_fills

sera.get_fills_for_order

Treasury

sera.get_balances

sera.treasury_value

sera.exposure_report

sera.rebalance_plan

sera.pay_invoice

sera.settlement_status

Account & funds

sera.build_approve

sera.build_deposit

sera.build_transfer

sera.send_tx

sera.send_transfer

Withdraw

sera.withdraw_request

sera.withdraw_build

sera.withdraw_send

History

sera.fx_history

sera.fx_volatility

sera.corridor_pnl

Signing & debug

sera.verify_signature

sera.permit_metadata

MCP resources & prompts

Resources (5)

Slash prompts (4)