API & MCP access

Routescore's modeled DeFi decision-support is available to agents and code two ways: as an MCP server you drop into Claude, Codex, Cursor, or any MCP-capable client, and as a keyed REST API you call from your own backend. Both speak the same trust-envelope contract. Each available MCP tool delegates to a corresponding keyed REST endpoint; tool availability differs by package version, transport, and environment as disclosed below.

Step 1 — Get an API key

Step 2, option A — Use it as an MCP server

The published @routescore/mcp package is a thin, stateless wrapper around the API — nothing is stored locally. Add it to your client config and set your key in the env block.

Claude Desktop (claude_desktop_config.json) or Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "routescore": {
      "command": "npx",
      "args": ["-y", "@routescore/mcp@latest"],
      "env": {
        "ROUTESCORE_API_KEY": "rs_live_your_key_here"
      }
    }
  }
}

Claude Code (CLI):

claude mcp add routescore --env ROUTESCORE_API_KEY=rs_live_... -- npx -y @routescore/mcp@latest

Restart the client. You should see the Routescore tools appear. Ask the agent to run whoami first — it confirms the key works and reports your plan tier. (The server also checks the key shape at startup and exits with an actionable error when ROUTESCORE_API_KEY is missing or obviously malformed.)

Building an agent that should use these tools with discipline? Install the agent skills for Routescore preflight — two SKILL.md files that teach the preflight-before-signing and verdict-relay workflow.

The published @routescore/mcp@latest package and live hosted /api/mcp transport are currently 0.3.5 with eight tools. The source tree and repository manifest prepare 0.4.0 with eleven tools for DEV previews: owner-scoped record_execution and review_execution require an authenticated Pro key, while review_public_transaction is declared for contract discovery but disabled against production. Promoting the hosted candidate or publishing the 0.4.0 stdio npm package remains founder-gated.

The tools

All quote_* results are modeled, point-in-time premium estimates — decision support only, not a live cover, insurance, refund, or premium-acceptance offer. Routescore does not underwrite risk.

Step 2, option B — Call the REST API directly

Prefer to call from a script or backend? Every tool maps to one endpoint under https://www.routescore.io/api/public/v1. Authenticate with a bearer token.

Verify your key with GET /me:

curl https://www.routescore.io/api/public/v1/me \
  -H "Authorization: Bearer rs_live_your_key_here"

{
  "authenticated": true,
  "tier": "power",
  "plan_includes_api": true,
  "score_state": "valid"
}

Request a modeled MEV estimate with POST /quote/mev — this returns a modeled, point-in-time premium estimate for MEV-sandwich exposure, not a live cover offer:

curl -X POST https://www.routescore.io/api/public/v1/quote/mev \
  -H "Authorization: Bearer rs_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "notional_usd": 25000, "asset_pair": "USDC/ETH", "route": "uniswap-v3" }'

The eleven-tool source-tree/repository DEV candidate maps to these REST endpoints. The published npm package and live hosted production endpoint expose the eight rows that are not marked source-tree/DEV-preview 0.4.0:

Run a pre-sign check with POST /check/swap before an agent asks a user to sign. This example scopes the check to Robinhood Chain (4663) and a tokenized asset; the result remains decision support only and the token registry read does not verify sellability, redemption, shareholder rights, custody, dividends, or jurisdiction eligibility. For RHC tokenized stocks/ETFs, pass the Routescore registry contract address; symbol-only checks are treated as unverified because they are not contract verification:

curl -X POST https://www.routescore.io/api/public/v1/check/swap \
  -H "Authorization: Bearer rs_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "notional_usd": 10000,
    "chain_id": 4663,
    "route": "uniswap-v3-rho",
    "token_in": "USDG",
    "token_out": "0xaF3D76f1834A1d425780943C99Ea8A608f8a93f9",
    "slippage_allowance_bps": 75
  }'

Every evaluated check/swap response also carries two basis-regime gap-state fields for tokenized assets: reference_price (reference-price freshness state) and market_regime (market-open/closed regime flag). Tokenized assets can trade on-chain around the clock while their reference instruments trade in defined market sessions; until a basis observation source is live, these fields report explicit unobserved states (unavailable with freshness: unknown / regime: unknown for recognized tokenized assets, unsupported otherwise) with caveats in-band — values are never guessed.

Agent policies may also declare three reserved basis-regime hooks — max_basis_bps, max_reference_staleness_seconds, block_when_market_closed — on POST /policy/evaluate. Reserved hooks are accepted but not evaluated (there is no basis observation source yet): each one is surfaced in the response's not_evaluated_fields with a basis_regime reason at your policy's safe default, and is never treated as satisfied.

The complete, machine-readable schema for every endpoint — inputs, outputs, and defaults — lives at /api/public/v1/openapi.json. Point your OpenAPI tooling or codegen at it.

What the responses tell you

Every check_swap, quote, and scenario response carries a trust envelope so agents and dashboards never have to guess how much to trust a number. Render these fields by default. Abbreviated example:

{
  "score_state": "partial",
  "source_freshness": {
    "state": "partial",
    "checked_at": "2026-06-21T00:00:00.000Z",
    "sources": [
      { "name": "routescore_backend", "freshness_state": "fresh" },
      { "name": "bridge_risk_labels", "freshness_state": "unknown" }
    ]
  },
  "methodology_version": "routescore.public_api.v1",
  "confidence_band": { "low": null, "high": null, "unit": "bps" },
  "caveats": [
    "Modeled, point-in-time decision support. Not an execution guarantee.",
    "Unsupported or stale inputs widen uncertainty instead of hiding risk."
  ],
  "commercial_disclosure": {
    "paid_placement": false,
    "score_influenced_by_partner": false
  }
}

• score_state — valid, partial, or degraded. partial means some inputs were stale or unsupported; the estimate widens its uncertainty rather than hiding the gap.
• source_freshness — per-source freshness so you can see exactly which inputs were fresh, stale, or unknown at request time.
• confidence_band — the modeled uncertainty around the estimate, in bps.
• caveats and commercial_disclosure — plain-language limits, plus an explicit statement that estimates are not paid placements or partner-influenced.

Rate limits

The daily check_swap quota applies per account, shared across that account's keys. Per-minute burst limits apply per key and scale with the plan. Read the X-RateLimit-* and X-RateLimit-Daily-* headers and back off before a limit.