{
  "openapi": "3.1.0",
  "info": {
    "title": "XRPL Toll Booth \u2014 Cybersecurity API",
    "summary": "Pay-per-call cybersecurity endpoints for Web3 agents and auditors, settled on the XRP Ledger via x402.",
    "description": "Five POST routes use x402 on XRPL mainnet: /wallet-risk, /contract-risk, /tx-simulate-risk, /scope-check and /verify-poc. /auth-ping retains Bearer API-key access; administration retains master-key access. Offers observed September 29, 2026 were 5000 drops XRP or 0.002 RLUSD, excluding applicable network fees; a fresh endpoint challenge is authoritative. Payment occurs before request-body validation, so invalid input can be charged. No automatic refund, free retry, cached replay, latency SLA or universal safety guarantee is promised. Successful wallet, contract, simulation and PoC responses support opt-in v0.8 when signing is enabled; scope and errors remain legacy JSON. This is a documentation revision, not a new envelope protocol or proof of all paid capabilities.",
    "version": "2026.09.29",
    "contact": {
      "name": "transactionguardian2025",
      "url": "https://github.com/Bubakooz22/xrpl-tollbooth/issues"
    },
    "license": {
      "name": "ISC",
      "identifier": "ISC"
    }
  },
  "servers": [
    {
      "url": "https://api.txnguardian.com",
      "description": "Production HTTPS API; payments on XRPL mainnet"
    }
  ],
  "tags": [
    { "name": "discovery",   "description": "Unauthenticated metadata endpoints." },
    { "name": "risk",        "description": "x402-paid: wallet, contract, and transaction risk scoring." },
    { "name": "scope",       "description": "x402-paid: bug bounty scope lookup." },
    { "name": "verify",      "description": "x402-paid: Foundry PoC verification; workload admission requires separate review." },
    { "name": "admin",       "description": "Master-key: API key CRUD." }
  ],
  "components": {
    "securitySchemes": {
      "X402XRPL": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "Base64-encoded x402 payment payload settled on XRPL. On first request the server responds 402 with a `PAYMENT-REQUIRED` header describing accepts (XRP drops or RLUSD). Sign the returned requirements with your XRPL key and retry with `PAYMENT-SIGNATURE`. See `docs/x402-spec-notes.md`."
      },
      "BearerApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "tb_live_<32hex>",
        "description": "API key issued by the tollbooth admin. Format: `tb_live_` followed by 32 lowercase hex chars. In closed beta \u2014 contact maintainer."
      },
      "MasterKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "hex-64",
        "description": "Server master key. Used only by the operator to CRUD API keys via `/admin/keys`."
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "facilitator": {
            "type": "object",
            "properties": {
              "scheme":      { "type": "string", "example": "exact" },
              "network":     { "type": "string", "example": "xrpl:0" },
              "x402Version": { "type": "integer", "example": 2 }
            }
          }
        },
        "required": ["ok"]
      },
      "PaymentRequired402": {
        "description": "Body returned with HTTP 402 when a payment header is missing.",
        "type": "object",
        "properties": {
          "x402Version": { "type": "integer", "const": 2 },
          "resource": {
            "type": "object",
            "properties": { "url": { "type": "string", "format": "uri" } }
          },
          "accepts": {
            "type": "array",
            "description": "One entry per accepted asset. Currently: XRP drops and RLUSD IOU.",
            "items": {
              "type": "object",
              "properties": {
                "scheme":      { "type": "string", "example": "exact" },
                "network":     { "type": "string", "example": "xrpl:0" },
                "asset":       { "type": "string", "description": "'XRP' for native XRP, or 40-hex currency code for IOU." },
                "amount":      { "type": "string", "description": "Amount in drops for XRP, or decimal string for IOU." },
                "payTo":       { "type": "string", "example": "rK1C1DPzJo9gSjK2LSdhV5J5veFB84zHer" },
                "resource":    { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } },
                "facilitatorUrl": { "type": "string", "format": "uri" },
                "extra": {
                  "type": "object",
                  "properties": {
                    "invoiceId": { "type": "string", "format": "uuid" },
                    "issuer": { "type": "string", "description": "RLUSD issuer for IOU offers." },
                    "sourceTag": { "type": "integer" },
                    "areFeesSponsored": { "type": "boolean" }
                  }
                },
                "maxTimeoutSeconds": { "type": "integer", "example": 300 },
                "x402Version": { "type": "integer", "example": 2 }
              }
            }
          }
        }
      },
      "ReasonCode": {
        "type": "string",
        "description": "Stable machine-readable code. See per-endpoint docs for the full list."
      },
      "RiskReason": {
        "type": "object",
        "required": ["code", "severity"],
        "properties": {
          "code": { "type": "string" },
          "severity": { "type": "string" },
          "source": { "type": "string" },
          "evidence": {},
          "override_permitted": { "type": "boolean" }
        }
      },
      "SignedResponseV08": {
        "type": "object",
        "required": ["envelope", "signature"],
        "description": "Risk report and request binding, not raw handler output or a signed payment receipt. HTTP 200 only; scope is not wrapped. No replay-cache guarantee.",
        "properties": {
          "envelope": {
            "type": "object",
            "required": ["version", "endpoint", "request_hash", "risk_level", "reason_codes", "human", "fulfillment_status", "retry_permitted", "retry_after_seconds", "issued_at", "expires_at", "signing_key_id", "envelope_hash"],
            "properties": {
              "version": { "const": "0.8" },
              "endpoint": { "type": "string", "enum": ["/wallet-risk", "/contract-risk", "/tx-simulate-risk", "/verify-poc"] },
              "request_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of canonical parsed request JSON." },
              "risk_level": { "type": "string" },
              "reason_codes": { "type": "array", "items": { "allOf": [{ "$ref": "#/components/schemas/RiskReason" }, { "required": ["override_permitted"] }] } },
              "human": { "type": "string" },
              "fulfillment_status": { "const": "complete" },
              "retry_permitted": { "const": false },
              "retry_after_seconds": { "type": "null" },
              "issued_at": { "type": "string", "format": "date-time" },
              "expires_at": { "type": "string", "format": "date-time" },
              "signing_key_id": { "type": "string" },
              "envelope_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of canonical envelope excluding envelope_hash and signature." }
            }
          },
          "signature": {
            "type": "object",
            "required": ["alg", "key_id", "value"],
            "properties": {
              "alg": { "const": "Ed25519" },
              "key_id": { "type": "string" },
              "value": { "type": "string", "contentEncoding": "base64", "description": "Ed25519 signature over canonical envelope including envelope_hash." }
            }
          }
        }
      },
      "WalletRiskRequest": {
        "type": "object",
        "required": ["address"],
        "properties": {
          "chain":   { "type": "string", "enum": ["eth", "base", "xrpl", "sol"] },
          "address": { "type": "string", "description": "Chain-native address." }
        }
      },
      "WalletRiskResponse": {
        "type": "object",
        "properties": {
          "chain":         { "type": "string" },
          "address":       { "type": "string" },
          "score":         { "type": "integer", "minimum": 0, "maximum": 100 },
          "risk_level":    { "type": "string", "enum": ["low", "medium", "high", "critical"] },
          "reason_codes":  { "type": "array", "items": { "$ref": "#/components/schemas/RiskReason" } },
          "sources_checked": { "type": "array", "items": { "type": "string" } },
          "cache_ttl_seconds": { "type": "integer" }
        }
      },
      "ContractRiskRequest": {
        "type": "object",
        "required": ["address"],
        "properties": {
          "chain":   { "type": "string", "enum": ["eth", "base"], "default": "eth" },
          "address": { "type": "string", "description": "20-byte hex address." }
        }
      },
      "ContractRiskResponse": {
        "type": "object",
        "properties": {
          "chain":        { "type": "string" },
          "address":      { "type": "string" },
          "score":        { "type": "integer" },
          "risk_level":   { "type": "string" },
          "reason_codes": { "type": "array", "items": { "$ref": "#/components/schemas/RiskReason" } },
          "metadata": { "type": "object" }
        }
      },
      "TxSimulateRiskRequest": {
        "type": "object",
        "required": ["from"],
        "description": "Use a 0x-prefixed sender. chain defaults to eth. Omitted/null/empty to denotes contract creation and requires nonempty data; this source-supported category was not covered by the September 29 paid proof. The public handler does not forward a block override. Send value as an exact non-negative decimal or hexadecimal string, not a floating-point number.",
        "properties": {
          "chain": { "type": "string", "enum": ["eth", "ethereum", "mainnet"], "default": "eth" },
          "from":  { "type": "string", "description": "Sender address. Impersonated in the anvil fork." },
          "to":    { "type": ["string", "null"], "description": "0x-prefixed target; omitted/null/empty for creation with nonempty data." },
          "data":  { "type": ["string", "null"], "description": "Nonempty calldata must be 0x-prefixed hex. Omitted/null/empty defaults to 0x." },
          "value": { "type": ["string", "number", "null"], "description": "Prefer exact non-negative integer wei as decimal or 0x-prefixed hex string. Omitted/null/empty defaults to 0. Numeric input is accepted and truncated by the implementation; avoid precision loss." }
        }
      },
      "TxSimulateRiskResponse": {
        "type": "object",
        "properties": {
          "chain":       { "type": "string" },
          "from":        { "type": "string" },
          "to":          { "type": ["string", "null"] },
          "normalized_from": { "type": "string" },
          "normalized_to": { "type": ["string", "null"] },
          "value_wei": { "type": "string" },
          "success": { "type": "boolean" },
          "reverted":    { "type": "boolean" },
          "gas_used":    { "type": ["integer", "null"] },
          "score":       { "type": "integer" },
          "risk_level":  { "type": "string" },
          "reason_codes":{ "type": "array", "items": { "$ref": "#/components/schemas/RiskReason" } },
          "state_changes": {
            "type": "object",
            "properties": {
              "eth_balance_deltas": { "type": "object", "additionalProperties": { "type": "string" } },
              "token_transfers": { "type": "array", "items": { "type": "object" } },
              "approvals_granted": { "type": "array", "items": { "type": "object" } },
              "ownership_changes": { "type": "array", "items": { "type": "object" } },
              "upgrades": { "type": "array", "items": { "type": "object" } }
            }
          },
          "traces_summary": {
            "type": "object",
            "properties": {
              "traces_text_head": { "type": "string", "description": "Up to 1500 characters. Empty for reverted execution." },
              "internal_calls_count": { "type": "integer" },
              "delegatecalls_count": { "type": "integer" },
              "staticcalls_count": { "type": "integer" },
              "has_selfdestruct": { "type": "boolean" },
              "has_create": { "type": "boolean" }
            }
          },
          "fork_block": { "type": "integer" },
          "metadata": {
            "type": "object",
            "properties": {
              "tx_hash_on_fork": { "type": "string" },
              "upstream_rpc": { "type": "string" },
              "simulation_duration_ms": { "type": "integer" }
            }
          },
          "checked_at": { "type": "string", "format": "date-time" },
          "sources_checked": { "type": "array", "items": { "type": "string" } },
          "cache_ttl_seconds": { "type": "integer", "const": 0 },
          "notes": { "type": "array", "items": { "type": "string" } }
        }
      },
      "ScopeCheckRequest": {
        "type": "object",
        "anyOf": [{ "required": ["address"] }, { "required": ["addresses"] }],
        "properties": {
          "address": { "type": "string" },
          "addresses": { "type": "array", "items": { "type": "string" }, "description": "Batch lookup; takes precedence when supplied as an array." },
          "chain":   { "type": "string" }
        }
      },
      "ScopeCheckResponse": {
        "type": "object",
        "properties": {
          "address":     { "type": "string" },
          "in_scope":    { "type": "boolean" },
          "programs":    {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "platform":  { "type": "string", "example": "immunefi" },
                "project":   { "type": "string" },
                "url":       { "type": "string" },
                "max_payout_usd":{ "type": "number" }
              }
            }
          },
          "data_freshness": { "type": "object" },
          "count": { "type": "integer", "description": "Batch response only." },
          "any_in_scope": { "type": "boolean", "description": "Batch response only." },
          "total_top_payout_usd": { "type": "number", "description": "Batch response only; not an earnings prediction." },
          "results": { "type": "array", "items": { "type": "object" }, "description": "Batch per-address results, including individual errors." }
        }
      },
      "VerifyPocRequest": {
        "type": "object",
        "required": ["test_file"],
        "properties": {
          "test_file":       { "type": "string", "description": "Base64-encoded Foundry .t.sol source. Max 128 KB decoded." },
          "chain":           { "type": "string", "enum": ["eth"], "default": "eth" },
          "fork_block":      { "type": "integer", "description": "Block number to fork at. Latest if omitted." },
          "expected_result": { "type": "string", "enum": ["pass", "revert"], "default": "pass" },
          "solidity_version":{ "type": "string", "description": "Ignored today \u2014 forge picks from pragma." },
          "rpc_url":         { "type": "string", "format": "uri", "description": "Override upstream RPC. Not recommended in production." }
        }
      },
      "VerifyPocResponse": {
        "type": "object",
        "properties": {
          "verified":     { "type": "boolean" },
          "expected":     { "type": "string" },
          "actual":       { "type": ["string", "null"] },
          "test_name":    { "type": ["string", "null"] },
          "gas_used":     { "type": ["integer", "null"] },
          "logs":         { "type": "array", "items": { "type": "string" } },
          "traces_head":  { "type": ["string", "null"] },
          "fork_block":   { "type": ["integer", "null"] },
          "duration_ms":  { "type": "integer" },
          "reason_codes": { "type": "array", "items": { "$ref": "#/components/schemas/ReasonCode" } },
          "notes":        { "type": "array", "items": { "type": "string" } }
        }
      },
      "AuthPingResponse": {
        "type": "object",
        "properties": {
          "ok":         { "type": "boolean" },
          "key_prefix": { "type": "string", "example": "tb_live_d169" },
          "key_id":     { "type": "integer" }
        }
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id":         { "type": "integer" },
          "name":       { "type": "string" },
          "prefix":     { "type": "string" },
          "key":        { "type": "string", "description": "Full raw key. Only returned once on create." },
          "created_at": { "type": "integer", "description": "Unix seconds." },
          "revoked_at": { "type": ["integer", "null"] }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "code":  { "type": "integer" }
        }
      }
    },
    "headers": {
      "PaymentReceipt": {
        "schema": { "type": "string" },
        "description": "Base64-encoded settlement receipt when available. Separate from, and not authenticated by, the v0.8 report signature. Not guaranteed on every infrastructure failure."
      },
      "EnvelopeWarning": {
        "schema": { "type": "string", "enum": ["envelope_wrap_failed"] },
        "description": "Signing failed and legacy JSON was returned; reject if a signed report is required."
      }
    },
    "parameters": {
      "EnvelopeAccept": {
        "name": "Accept", "in": "header", "required": false,
        "schema": { "type": "string", "example": "application/vnd.tollbooth.v0.8+json" },
        "description": "Opt in to v0.8 on eligible HTTP 200 responses with signing enabled. Default is legacy JSON; inspect actual Content-Type and verify the signature. Scope and errors are not wrapped."
      }
    },
    "responses": {
      "PaidInputError": {
        "description": "Invalid input after payment gating. Receipt included if available; no refund or free retry implied.",
        "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentReceipt" } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
      },
      "PaidInternalError": {
        "description": "Internal failure. Receipt may be present if the handler retained one; no signed envelope or universal receipt guarantee.",
        "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentReceipt" } },
        "content": { "application/json": { "schema": { "type": "object" } } }
      },
      "PaymentRequired": {
        "description": "402 \u2014 payment required. Body describes accepted assets.",
        "headers": {
          "PAYMENT-REQUIRED": {
            "schema": { "type": "string" },
            "description": "Base64 of the same body. x402 v2 compliance."
          }
        },
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired402" } }
        }
      },
      "Unauthorized": {
        "description": "401 \u2014 missing or invalid Bearer key.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
      },
      "RateLimited": {
        "description": "429 \u2014 per-key rate limit hit.",
        "headers": {
          "Retry-After":         { "schema": { "type": "integer" } },
          "X-RateLimit-Limit":   { "schema": { "type": "integer" } },
          "X-RateLimit-Remaining": { "schema": { "type": "integer" } },
          "X-RateLimit-Reset":   { "schema": { "type": "integer" } }
        },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
      }
    }
  },
  "paths": {
    "/.well-known/tollbooth-keys.json": {
      "get": {
        "tags": ["discovery"],
        "summary": "Public verification keys for signed v0.8 reports.",
        "description": "Read-only manifest when signing is enabled. Public Ed25519 keys are raw 32-byte base64 values. Resolve the report's signing_key_id, enforce key status and validity policy, then verify hash, signature, request binding and freshness.",
        "responses": {
          "200": {
            "description": "Public signing-key manifest.",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": { "keys": { "type": "array", "items": {
                "type": "object",
                "properties": {
                  "key_id": { "type": "string" },
                  "alg": { "const": "Ed25519" },
                  "public_key": { "type": "string", "contentEncoding": "base64" },
                  "status": { "type": "string" }
                }
              } } }
            } } }
          },
          "304": { "description": "Unchanged according to If-None-Match." },
          "503": { "description": "Signing-key discovery unavailable when disabled (v08_not_enabled)." }
        }
      }
    },
    "/health": {
      "get": {
        "tags": ["discovery"],
        "summary": "Liveness probe",
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } }
          }
        }
      }
    },
    "/.well-known/openapi.json": {
      "get": {
        "tags": ["discovery"],
        "summary": "This OpenAPI 3.1 spec.",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": {} } }
        }
      }
    },
    "/.well-known/agent.json": {
      "get": {
        "tags": ["discovery"],
        "summary": "Agent manifest \u2014 x402-compatible discovery.",
        "description": "Machine-readable manifest for agent frameworks. Lists each endpoint, its auth model, pricing, and reason-code vocabulary.",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": {} } }
        }
      }
    },
    "/.well-known/x402": {
      "get": {
        "tags": ["discovery"],
        "summary": "Sample current x402 offers.",
        "description": "Read-only discovery, not a reusable payment authorization. Obtain a fresh 402 challenge from the actual endpoint before signing.",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": {} } }
        }
      }
    },
    "/wallet-risk": {
      "post": {
        "tags": ["risk"],
        "summary": "Score a wallet address for known risk signals.",
        "parameters": [{ "$ref": "#/components/parameters/EnvelopeAccept" }],
        "description": "Wallet risk signals from configured datasets and chain checks. Coverage depends on available sources; no exact coverage or refresh guarantee. Current challenge controls payment terms.",
        "security": [{ "X402XRPL": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletRiskRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Risk assessment.",
            "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentReceipt" }, "X-Tollbooth-V08-Warning": { "$ref": "#/components/headers/EnvelopeWarning" } },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletRiskResponse" } }, "application/vnd.tollbooth.v0.8+json": { "schema": { "$ref": "#/components/schemas/SignedResponseV08" } } }
          },
          "400": { "$ref": "#/components/responses/PaidInputError" },
          "500": { "$ref": "#/components/responses/PaidInternalError" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/contract-risk": {
      "post": {
        "tags": ["risk"],
        "summary": "Score a smart-contract address for known-exploit and heuristic risk.",
        "parameters": [{ "$ref": "#/components/parameters/EnvelopeAccept" }],
        "description": "Matches a curated exploit dataset plus available contract heuristics. Source checks depend on provider configuration. No exact dataset-count or completeness guarantee; current challenge controls payment terms.",
        "security": [{ "X402XRPL": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractRiskRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Risk assessment.",
            "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentReceipt" }, "X-Tollbooth-V08-Warning": { "$ref": "#/components/headers/EnvelopeWarning" } },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractRiskResponse" } }, "application/vnd.tollbooth.v0.8+json": { "schema": { "$ref": "#/components/schemas/SignedResponseV08" } } }
          },
          "400": { "$ref": "#/components/responses/PaidInputError" },
          "500": { "$ref": "#/components/responses/PaidInternalError" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/tx-simulate-risk": {
      "post": {
        "tags": ["risk"],
        "summary": "Simulate an Ethereum transaction on a mainnet fork and grade the outcome.",
        "parameters": [{ "$ref": "#/components/parameters/EnvelopeAccept" }],
        "description": "Costs 5000 drops XRP or 0.002 RLUSD per call. Spins up an ephemeral anvil fork, impersonates `from`, sets balance, executes, mines a block, parses receipt logs and traces. Detects unlimited approvals, ownership transfer, proxy upgrade, selfdestruct, reverts, and multi-token outbound flows.",
        "security": [{ "X402XRPL": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TxSimulateRiskRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Simulation completed, including reverted transactions. A low risk label is not proof of success. Legacy JSON contains execution details; signed v0.8 contains the risk report only.",
            "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentReceipt" }, "X-Tollbooth-V08-Warning": { "$ref": "#/components/headers/EnvelopeWarning" } },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TxSimulateRiskResponse" } }, "application/vnd.tollbooth.v0.8+json": { "schema": { "$ref": "#/components/schemas/SignedResponseV08" } } }
          },
          "400": { "$ref": "#/components/responses/PaidInputError" },
          "502": {
            "description": "Simulation infrastructure failure: upstream, fork startup, receipt or trace unavailable. Not a completed low-risk result.",
            "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentReceipt" } },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          },
          "500": { "$ref": "#/components/responses/PaidInternalError" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/scope-check": {
      "post": {
        "tags": ["scope"],
        "summary": "Look up whether an address is in scope of any known bug bounty program.",
        "description": "Local dataset lookup, not authoritative permission to test. No exact coverage or daily-refresh guarantee. Single-address or batch JSON responses; not signed v0.8. Current challenge controls payment terms.",
        "security": [{ "X402XRPL": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeCheckRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Scope match result.",
            "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentReceipt" } },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeCheckResponse" } } }
          },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "400": { "$ref": "#/components/responses/PaidInputError" },
          "500": { "$ref": "#/components/responses/PaidInternalError" }
        }
      }
    },
    "/verify-poc": {
      "post": {
        "tags": ["verify"],
        "summary": "Grade a Foundry PoC against an Ethereum mainnet fork.",
        "parameters": [{ "$ref": "#/components/parameters/EnvelopeAccept" }],
        "description": "x402-paid Foundry PoC grading. No API-key per-route limiter is applied by this handler; workload admission requires separate review before broad promotion. No latency SLA or multi-file roadmap promise. Payment precedes input validation.",
        "security": [{ "X402XRPL": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyPocRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Grading complete (`verified` true or false).",
            "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentReceipt" }, "X-Tollbooth-V08-Warning": { "$ref": "#/components/headers/EnvelopeWarning" } },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyPocResponse" } }, "application/vnd.tollbooth.v0.8+json": { "schema": { "$ref": "#/components/schemas/SignedResponseV08" } } }
          },
          "400": { "description": "Malformed JSON or invalid PoC input.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentReceipt" } }, "content": { "application/json": { "schema": { "anyOf": [{ "$ref": "#/components/schemas/ErrorResponse" }, { "$ref": "#/components/schemas/VerifyPocResponse" }] } } } },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "422": { "description": "Compile / parse / no-tests failure.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentReceipt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyPocResponse" } } } },
          "502": { "description": "Upstream RPC unreachable.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentReceipt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyPocResponse" } } } },
          "504": { "description": "PoC execution timed out.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentReceipt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyPocResponse" } } } },
          "500": { "$ref": "#/components/responses/PaidInternalError" }
        }
      }
    },
    "/auth-ping": {
      "get": {
        "tags": ["verify"],
        "summary": "Verify a Bearer API key works.",
        "security": [{ "BearerApiKey": [] }],
        "responses": {
          "200": {
            "description": "Key valid.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthPingResponse" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/admin/keys": {
      "post": {
        "tags": ["admin"],
        "summary": "Create a new API key.",
        "security": [{ "MasterKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": { "name": { "type": "string" } }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Created. `key` returned once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "get": {
        "tags": ["admin"],
        "summary": "List all API keys (hashed, no raw values).",
        "security": [{ "MasterKey": [] }],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/admin/keys/{id}": {
      "delete": {
        "tags": ["admin"],
        "summary": "Revoke an API key by ID.",
        "security": [{ "MasterKey": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" }, "id": { "type": "integer" } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    }
  }
}
