Integrate with OpenAI / ChatGPT

Give an OpenAI model — GPT via the API, an Assistant, or a Custom GPT — 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)

Option A — a function-calling tool definition

This is the Chat Completions tool shape (also used by Assistants). The Responses API takes the flattened form — lift name, description, and parameters up next to "type": "function" and drop the nested function wrapper. It mirrors the check_swap input schema; your code executes the HTTP call when the model requests it.

{
  "type": "function",
  "function": {
    "name": "check_swap",
    "description": "Pre-sign evidence check an agent runs BEFORE it signs 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 machine-readable 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 Routescore's 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"]
    }
  }
}

When the model calls the tool, make the request server-side and feed the JSON result back as the tool output:

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."
  ],
  "record_id": "…",
  "evidence_bundle_id": "preflight:…"
}

Option B — a Custom GPT Action from the OpenAPI spec

For a no-code Custom GPT, add an Action and point it at Routescore's public OpenAPI 3.1 spec — the whole schema is discoverable with no auth:

1. In the GPT editor, open Configure → Actions → Create new action.
2. Under Schema, import from URL: https://www.routescore.io/api/public/v1/openapi.json.
3. Set Authentication → API Key → Bearer, and paste your rs_live_… key.
4. Keep only the POST /check/swap operation (and GET /me) enabled if you want a focused pre-sign GPT.

What the response means

• verdict — clear | caution | unsupported. An advisory pre-sign read, never an instruction to execute. clear reports the absence of caution-level findings within the stated coverage and score_state, nothing more.
• token_safety.state — recognized means 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 (e.g. an unsupported chain) returns an evaluated unsupported verdict as HTTP 422 with a full body. It means not evaluated; the model must not guess, substitute another chain's model, or infer a score. 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 the caveats[] verbatim to your user.

Every keyed call also attempts to persist an owner-scoped, hash-verifiable evidence record and returns its record_id — re-verifiable offline.

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.