Give Grok the ability to run a pre-sign evidence check before it proposes or executes an onchain swap. It calls POST /api/public/v1/check/swap and gets back a modeled route-quality read, modeled MEV/execution exposure where observable, a token registry recognition read, and a clear | caution | unsupported verdict with caveats to relay verbatim.

Routescore is one composable element of an agentic stack — the evidence/attestation element alongside your planner, executor, and wallet. It is read-only: it never signs, executes, routes funds, custodies assets, or gives advice.

plan → preflight (Routescore) → execute (venue/agent) → record (Routescore)

Read-only, non-custodial, free agent tier

Everything returned is modeled, point-in-time decision support. Nothing holds a key, moves funds, or promises an outcome. The pre-sign check_swap endpoint is on the free agent tier — any signed-in tier can mint an rs_live_… key and call it (free 100/day, Pro 1,000, Power 10,000, per account); the modeled-quote and scenario endpoints require Power. Send the key as a bearer token — generate one at Account → Developer → API & MCP access.

1. Define the tool

xAI's API is OpenAI tool-call compatible. This is the Chat Completions tool shape; xAI's Responses API takes the flattened form (lift name, description, parameters up beside "type": "function" and drop the nested function wrapper). Register it with a Grok request and execute the HTTP call yourself when Grok requests it.

{
  "type": "function",
  "function": {
    "name": "check_swap",
    "description": "Pre-sign evidence check to run BEFORE signing an onchain swap. Returns a read-only, modeled route-quality grade, modeled slippage estimate, modeled MEV/execution exposure where observable, a token registry recognition read (recognized vs unverified), and a clear | caution | unsupported verdict with reasons and caveats. Decision support only: it does not execute, route funds, sign, or promise an outcome.",
    "parameters": {
      "type": "object",
      "properties": {
        "notional_usd": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000000, "description": "Trade size in USD (> 0, <= 1e12)." },
        "chain_id": { "type": "integer", "minimum": 1, "description": "Chain ID (positive integer). 1 = Ethereum (default), 4663 = Robinhood Chain." },
        "route": { "type": "string", "description": "Route id to score, e.g. 'uniswap-v3-rho'. Omit to score the chain's default public route." },
        "token_out": { "type": "string", "description": "Token being received (address or symbol), checked against the recognized-token registry. For tokenized stocks/ETFs pass the registry contract address; a bare symbol is downgraded to unverified." },
        "token_in": { "type": "string", "description": "Token being sold (address or symbol)." },
        "slippage_allowance_bps": { "type": "number", "minimum": 0, "maximum": 10000, "description": "Slippage allowance in bps (0–10000). Default 50." }
      },
      "required": ["notional_usd"]
    }
  }
}

2. Execute the call

When Grok emits a check_swap tool call, run the request server-side with your key and feed the JSON back as the tool result:

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
  }'

Abbreviated response (HTTP 200; timestamps illustrative):

{
  "verdict": "caution",
  "chain": { "chainId": 4663, "name": "Robinhood Chain", "supportLevel": "modeled" },
  "route": { "grade": "A", "qualityScore": 97, "modeledSlippageBps": 25.5, "orderFlow": "sequencer_ordered" },
  "token_safety": { "state": "recognized", "recognized": true, "flags": ["tokenized_asset_registry_only"] },
  "reasons": ["sequencer_ordering_uncalibrated"],
  "score_state": "partial",
  "methodology_version": "routescore.public_api.v1",
  "caveats": [
    "Pre-trade decision support only. Routescore does not execute trades, route funds, or promise an outcome.",
    "Route and execution-risk values are modeled, point-in-time. Token-safety is registry recognition vs unverified status, not a live honeypot, can-sell, rights, redemption, or liquidity audit."
  ]
}

What the response means

verdict — clear | caution | unsupported. Advisory, never an instruction to execute. clear reports the absence of caution-level findings within the stated coverage and score_state.
token_safety.state — recognized is a registry match only; it is not a safety, sellability, liquidity, rights, redemption, or investment-quality verification. unverified means Routescore has not confirmed the token and downgrades the verdict to caution.
unsupported — a valid-but-unsupported request returns an evaluated unsupported verdict as HTTP 422 with a full body, meaning not evaluated; Grok must not guess or substitute another chain's model. Malformed input (non-positive notional_usd, non-integer chain_id, out-of-range slippage) is rejected earlier with HTTP 400.
trust envelope — score_state, source_freshness, methodology_version, caveats, and commercial_disclosure (paid_placement: false) ride on every response. Pin the methodology_version and relay caveats[] verbatim.

Every keyed call also attempts to persist an owner-scoped, hash-verifiable evidence record and returns its record_id — re-verifiable offline. The full machine-readable schema is at /api/public/v1/openapi.json (public, no auth).

Where the proof lives

/calibration — how modeled figures reconcile against realized outcomes, per source (honest-but-empty where a cohort is too small).
/methodology — how the scores are computed.
/limitations — what Routescore does not know or do.

Decision support, not execution or advice

Routescore returns modeled, point-in-time decision support with a methodology_version — not investment, legal, or tax advice, and not an execution service. Robinhood Chain figures are additionally uncalibrated today. Grok, its policy, and your user decide what to do with the evidence.