{
  "openapi": "3.1.0",
  "info": {
    "title": "M2M Sentinel — Base Capability Intelligence API",
    "version": "2.2.0",
    "summary": "Proxy-aware static bytecode capability observations and sourced Base market data for bots and autonomous agents.",
    "description": "Every protected response carries provenance. Contract analysis reports selected opcode and selector observations, common proxy resolution, evidence quality, and explicit limitations. It does not classify contracts as safe, malicious, or exploitable. When the engine cannot obtain evidence-grade data it returns `capabilityRating: \"UNVERIFIED\"`, or HTTP 503 `DATA_SOURCE_UNAVAILABLE`. No live value is estimated or defaulted.",
    "contact": { "name": "M2M Sentinel API", "email": "contact@m2msentinel.com" },
    "license": { "name": "Proprietary", "url": "https://m2msentinel.com/terms" },
    "termsOfService": "https://m2msentinel.com/terms"
  },
  "servers": [
    { "url": "https://api.m2msentinel.com", "description": "Production High-Performance Gateway (Direct Edge)" },
    { "url": "https://m2msentinel.com", "description": "Production Web & Fallback Gateway" }
  ],
  "tags": [
    { "name": "Status", "description": "Health and capability discovery. No credential required." },
    { "name": "Onboarding", "description": "Free-tier and paid key provisioning. No credential required." },
    { "name": "Demo", "description": "Live no-wallet analysis of a fixed sample allowlist." },
    { "name": "Capabilities", "description": "Static contract capability observations. Requires an API key or a settled x402 payment." },
    { "name": "Market", "description": "Sourced Base market data. Requires an API key or a settled x402 payment." },
    { "name": "Keys", "description": "Key self-service. Requires the key itself." }
  ],
  "security": [{ "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "X402Payment": [] }],
  "paths": {
    "/v1/status": {
      "get": {
        "tags": ["Status"],
        "operationId": "getStatus",
        "summary": "Instantaneous dependency health",
        "description": "Reports the live state of persistence, Base RPC trust, verdict quality and payment settlement. Returns 503 when both persistence and RPC are unreachable. Historical availability is published only for windows with sufficient recorded health samples.",
        "security": [],
        "responses": {
          "200": {
            "description": "Health snapshot",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } }
          },
          "503": {
            "description": "All core dependencies are unreachable",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } }
          }
        }
      }
    },
    "/v1/stats": {
      "get": {
        "tags": ["Status"],
        "operationId": "getAggregateStats",
        "summary": "Public telemetry metadata or operator-authorized aggregate detail",
        "description": "Without operator authorization this returns no exact adoption, funnel, utilization, attribution, or revenue counters. A Bearer OPERATOR_STATS_TOKEN returns identifier-free global daily counters. No IP address, wallet, API key, contract address, path parameter, user agent, referrer, or per-user identifier is collected.",
        "security": [],
        "parameters": [{ "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 400, "default": 30 } }],
        "responses": {
          "200": { "description": "Redacted public metadata, or detailed counters when operator-authorized", "content": { "application/json": { "schema": { "oneOf": [{ "$ref": "#/components/schemas/PublicStats" }, { "$ref": "#/components/schemas/AggregateStats" }] } } } },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/events": {
      "post": {
        "tags": ["Status"],
        "operationId": "recordAggregateProductEvent",
        "summary": "Record an allowlisted first-party aggregate event",
        "description": "Accepts only pageViewed and ctaClicked plus fixed enum dimensions. Commercial outcomes are recorded authoritatively by server routes. Unknown fields, free text and identifiers are refused.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicProductEvent" } } }
        },
        "responses": {
          "202": { "description": "Valid aggregate event accepted" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/demo/audit/{address}": {
      "get": {
        "tags": ["Demo"],
        "operationId": "demoAuditContract",
        "summary": "Run live capability analysis for an allowlisted sample",
        "description": "Uses the same live Base RPC, proxy resolution, and bytecode analysis pipeline as the paid audit route. Only the published samples are accepted; results are not stored or precomputed.",
        "security": [],
        "parameters": [{ "$ref": "#/components/parameters/Address" }],
        "responses": {
          "200": { "description": "Live sample analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    },
    "/v1/plans": {
      "get": {
        "tags": ["Status"],
        "operationId": "getPlans",
        "summary": "Authoritative plan and pricing catalogue",
        "description": "The single source of truth for pricing. The website renders this endpoint; if any page disagrees with it, this endpoint governs.",
        "security": [],
        "responses": {
          "200": {
            "description": "Plan catalogue",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plans" } } }
          }
        }
      }
    },
    "/v1/subscribe/free/challenge": {
      "post": {
        "tags": ["Onboarding"],
        "operationId": "createFreeChallenge",
        "summary": "Request a wallet challenge for a free key",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["userWallet"],
                "properties": {
                  "userWallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "examples": ["0x6d6C398390cfb88f1CD42715B84906a0Bd6652aa"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Challenge issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntentEnvelope" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    },
    "/v1/subscribe/free/claim": {
      "post": {
        "tags": ["Onboarding"],
        "operationId": "claimFreeKey",
        "summary": "Exchange a signed challenge for a free key",
        "description": "Allocated once per wallet. The raw key is returned exactly once and is never recoverable afterwards.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["intentId", "signature"],
                "properties": {
                  "intentId": { "type": "string" },
                  "signature": { "type": "string", "description": "personal_sign signature over intent.messageToSign" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Key issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedKey" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "409": { "description": "A free key already exists for this wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    },
    "/v1/subscribe/intents": {
      "post": {
        "tags": ["Onboarding"],
        "operationId": "createPurchaseIntent",
        "summary": "Create a signable purchase intent with a frozen quote",
        "description": "The exact USDC amount (and, when a live ETH quote exists, the exact wei amount), duration and optional same-key renewal target are frozen into the message you sign. The intent is valid for 15 minutes. Renewals require the active same-tier paid key in x-api-key; changing tiers requires a new key.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["tier", "userWallet"],
                "properties": {
                  "tier": { "type": "string", "enum": ["STARTER", "GROWTH", "PRO"] },
                  "userWallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Must be the wallet that will send the payment." },
                  "durationDays": { "type": "integer", "enum": [31, 90, 365], "default": 31 },
                  "renewExistingKey": { "type": "boolean", "default": false, "description": "When true, present the active same-tier paid key in x-api-key. The key expiry is extended atomically and its raw secret does not change." }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Intent created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseIntent" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    },
    "/v1/subscribe/crypto": {
      "post": {
        "tags": ["Onboarding"],
        "operationId": "claimSubscription",
        "summary": "Claim a subscription key after on-chain payment",
        "description": "Requires 3 block confirmations and a credentialed RPC. The signer of the intent, the transaction sender and the payment sender must be the same wallet. A transaction hash can be redeemed exactly once.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["intentId", "signature", "txHash"],
                "properties": {
                  "intentId": { "type": "string" },
                  "signature": { "type": "string" },
                  "txHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Payment verified and key provisioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedKey" } } } },
          "400": { "description": "Intent, amount, sender or finality check failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    },
    "/v1/audit/{address}": {
      "get": {
        "tags": ["Capabilities"],
        "operationId": "auditContract",
        "summary": "Static bytecode capability and proxy observations",
        "description": "Reports selected bytecode patterns and common proxy structures. `notASafetyGuarantee` is always true; absence of a pattern is not evidence of safety.",
        "parameters": [{ "$ref": "#/components/parameters/Address" }],
        "responses": {
          "200": {
            "description": "Capability report. `capabilityRating` is `UNVERIFIED` and `capabilityScore` is null when RPC trust is below evidence grade.",
            "headers": {
              "X-Sentinel-RPC-Provider": { "$ref": "#/components/headers/RpcProvider" },
              "X-Sentinel-Trust-Level": { "$ref": "#/components/headers/TrustLevel" },
              "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "X-Credits-Remaining": { "$ref": "#/components/headers/CreditsRemaining" }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditResponse" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "405": { "$ref": "#/components/responses/MethodNotAllowed" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    },
    "/v1/security/score/{address}": {
      "get": {
        "tags": ["Capabilities"],
        "operationId": "getCapabilityScoreLegacyPath",
        "summary": "Legacy URL for the static capability coverage index",
        "description": "Higher values mean fewer selected static patterns were observed. This is not a security score or safety probability. `capabilityScore` is null whenever evidence-grade analysis is unavailable.",
        "parameters": [{ "$ref": "#/components/parameters/Address" }],
        "responses": {
          "200": { "description": "Score and deduction breakdown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    },
    "/v1/gas/fees": {
      "get": {
        "tags": ["Market"],
        "operationId": "getGasFees",
        "summary": "Observed Base gas price",
        "responses": {
          "200": { "description": "Gas observation with provenance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GasResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/DataSourceUnavailable" }
        }
      }
    },
    "/v1/dex/metrics": {
      "get": {
        "tags": ["Market"],
        "operationId": "getDexMetrics",
        "summary": "Aggregate DEX liquidity and volume for tracked Base tokens",
        "description": "The `coverage` object states exactly which tokens were aggregated. This is not a whole-chain total.",
        "responses": {
          "200": { "description": "Aggregate with coverage and provenance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DexMetricsResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/DataSourceUnavailable" }
        }
      }
    },
    "/v1/token/price/{symbol}": {
      "get": {
        "tags": ["Market"],
        "operationId": "getTokenPrice",
        "summary": "Liquidity-weighted Base token price",
        "description": "Median of the five deepest indexed pools, so a single manipulated pool cannot move the published price. Unknown symbols return 404 with the supported list; a price is never guessed.",
        "parameters": [
          { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string", "examples": ["USDC", "WETH", "AERO"] } }
        ],
        "responses": {
          "200": { "description": "Priced token with provenance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenPriceResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "404": { "description": "Symbol is not tracked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/DataSourceUnavailable" }
        }
      }
    },
    "/v1/whales/signals": {
      "get": {
        "tags": ["Market"],
        "operationId": "getWhaleSignals",
        "summary": "Large ERC-20 transfers observed on Base",
        "description": "Sourced from eth_getLogs over a bounded recent block range and valued using live pool prices. ERC-20 Transfer events only.",
        "responses": {
          "200": { "description": "Observed signals with the exact query window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhaleResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/DataSourceUnavailable" }
        }
      }
    },
    "/v1/keys/self": {
      "get": {
        "tags": ["Keys"],
        "operationId": "getOwnKey",
        "summary": "Metadata for the presented key",
        "description": "Requires an API key; an x402 payment cannot access this route. The raw key is never echoed.",
        "security": [{ "ApiKeyHeader": [] }, { "BearerAuth": [] }],
        "responses": {
          "200": { "description": "Key metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeySelf" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    },
    "/v1/keys/revoke": {
      "post": {
        "tags": ["Keys"],
        "operationId": "revokeOwnKey",
        "summary": "Permanently revoke the presented key",
        "security": [{ "ApiKeyHeader": [] }, { "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "type": "object", "required": ["confirm"], "properties": { "confirm": { "type": "boolean", "const": true } } }
            }
          }
        },
        "responses": {
          "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "revokedAt": { "type": "string", "format": "date-time" } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    },
    "/v1/keys/recovery/challenge": {
      "post": {
        "tags": ["Keys"],
        "operationId": "createPaidKeyRecoveryChallenge",
        "summary": "Create a non-enumerating paid-key recovery challenge",
        "description": "Returns the same 202 envelope for known and unknown wallets. An optional original subscription txHash bootstraps legacy paid keys. Free and revoked keys cannot be recovered.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["userWallet"], "properties": {
              "userWallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" },
              "txHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Original subscription payment; needed only for a legacy key without a wallet index." }
            }
          } } }
        },
        "responses": {
          "202": { "description": "Structurally identical real or decoy challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryIntent" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    },
    "/v1/keys/recovery/claim": {
      "post": {
        "tags": ["Keys"],
        "operationId": "claimPaidKeyRecovery",
        "summary": "Rotate a paid API key with its subscriber-wallet signature",
        "description": "Atomically revokes the previous secret and returns a replacement exactly once. The tier and expiration are preserved.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["intentId", "signature"], "properties": {
              "intentId": { "type": "string" },
              "signature": { "type": "string" }
            }
          } } }
        },
        "responses": {
          "200": { "description": "Replacement key issued and previous key revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedKey" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "409": { "description": "Challenge already consumed or target changed" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Header only. Credentials supplied in a query string are rejected with HTTP 401 and must be rotated."
      },
      "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Alternative to x-api-key." },
      "X402Payment": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 v2 micro-payment. Call without a credential to receive HTTP 402 and a PAYMENT-REQUIRED challenge, settle it, then retry with this header."
      }
    },
    "parameters": {
      "Address": {
        "name": "address",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" },
        "examples": { "usdc": { "value": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } }
      }
    },
    "headers": {
      "RpcProvider": { "schema": { "type": "string" }, "description": "Provider (or joined providers) that answered." },
      "TrustLevel": { "schema": { "type": "string", "enum": ["HIGH_TRUST_PRIMARY", "QUORUM_PUBLIC", "DEGRADED_LOW_TRUST"] } },
      "RateLimitRemaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current minute." },
      "CreditsRemaining": { "schema": { "type": "integer" }, "description": "Decision credits remaining in the current issuance-anchored 31-day cycle." },
      "PaymentRequired": { "schema": { "type": "string", "format": "byte" }, "description": "Base64-encoded JSON x402 v2 challenge." },
      "PaymentResponse": { "schema": { "type": "string", "format": "byte" }, "description": "Base64-encoded JSON x402 v2 settlement receipt." },
      "RetryAfter": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }
    },
    "responses": {
      "BadRequest": { "description": "Malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": {
        "description": "Missing or invalid credential, or a credential was supplied in the query string",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "PaymentRequired": {
        "description": "No credential supplied for a payable route, or the issuance-anchored 31-day credit allowance is exhausted",
        "headers": { "PAYMENT-REQUIRED": { "$ref": "#/components/headers/PaymentRequired" } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequired" } } }
      },
      "MethodNotAllowed": {
        "description": "Verb not supported. HEAD is refused on protected routes because it would execute a metered handler while suppressing the body.",
        "headers": { "Allow": { "schema": { "type": "string" } } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "RateLimited": {
        "description": "A plan burst limit or bounded public/intent retry limit was exceeded",
        "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "ServiceUnavailable": { "description": "A required dependency is unavailable; the request failed closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "DataSourceUnavailable": {
        "description": "The upstream data source is unavailable. No value is returned rather than an estimated one.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error", "message"],
        "properties": {
          "error": { "type": "string", "examples": ["UNAUTHORIZED", "PAYMENT_REQUIRED", "DATA_SOURCE_UNAVAILABLE", "RATE_LIMITED", "CREDITS_EXHAUSTED", "METHOD_NOT_ALLOWED"] },
          "message": { "type": "string" },
          "reason": { "type": "string" },
          "source": { "type": "string" },
          "reference": { "type": "string", "description": "Correlation id for a server-side error." }
        }
      },
      "X402PaymentRequired": {
        "type": "object",
        "required": ["x402Version", "resource", "accepts"],
        "properties": {
          "x402Version": { "type": "integer", "const": 2 },
          "error": { "type": "string" },
          "resource": {
            "type": "object",
            "required": ["url"],
            "properties": {
              "url": { "type": "string", "format": "uri" },
              "description": { "type": "string" },
              "mimeType": { "type": "string" }
            }
          },
          "accepts": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": ["scheme", "network", "amount", "asset", "payTo", "maxTimeoutSeconds"],
              "properties": {
                "scheme": { "type": "string", "const": "exact" },
                "network": { "type": "string", "const": "eip155:8453" },
                "amount": { "type": "string" },
                "asset": { "type": "string" },
                "payTo": { "type": "string" },
                "maxTimeoutSeconds": { "type": "integer" },
                "extra": { "type": "object" }
              }
            }
          },
          "extensions": { "type": "object" }
        }
      },
      "Provenance": {
        "type": "object",
        "description": "Where a value came from and how old it is. Present on every data response.",
        "properties": {
          "source": { "type": "string" },
          "endpoint": { "type": "string" },
          "trustLevel": { "type": "string", "enum": ["HIGH_TRUST_PRIMARY", "QUORUM_PUBLIC", "DEGRADED_LOW_TRUST"] },
          "agreement": { "type": "integer", "description": "Providers that returned the selected result." },
          "sampled": { "type": "integer", "description": "Providers that answered at all." },
          "retrievedAt": { "type": "string", "format": "date-time" },
          "ageSeconds": { "type": "integer" },
          "network": { "type": "string" },
          "note": { "type": ["string", "null"] }
        }
      },
      "Verdict": {
        "type": "object",
        "properties": {
          "capabilityRating": { "type": "string", "enum": ["NO_SELECTED_CAPABILITIES_DETECTED", "REVIEW_RECOMMENDED", "MULTIPLE_FLAGS", "NOT_A_CONTRACT", "UNVERIFIED"] },
          "evidenceGrade": { "type": "boolean", "description": "False when RPC trust or proxy resolution was insufficient to publish a capability label." },
          "reason": { "type": "string" },
          "explanation": { "type": "string" },
          "executableCapabilities": { "type": "array", "items": { "type": "string" } }
        }
      },
      "AnalysisSemantics": {
        "type": "object",
        "required": ["analysisKind", "notASafetyGuarantee", "limitations"],
        "properties": {
          "analysisKind": { "type": "string", "const": "STATIC_BYTECODE_CAPABILITY_HEURISTIC" },
          "notASafetyGuarantee": { "type": "boolean", "const": true },
          "limitations": { "type": "array", "minItems": 3, "items": { "type": "string" } }
        }
      },
      "Capability": {
        "type": "object",
        "properties": {
          "type": { "type": "string", "enum": ["DELEGATECALL", "SELFDESTRUCT", "MINT_SELECTOR", "PAUSE_SELECTOR", "FREEZE_SELECTOR"] },
          "confidence": { "type": "string", "enum": ["HIGH", "MEDIUM", "LOW"] },
          "byteOffsetHex": { "type": "string" },
          "selectorHex": { "type": "string" },
          "snippetHex": { "type": "string" },
          "evidence": { "type": "string" }
        }
      },
      "Dissection": {
        "type": "object",
        "properties": {
          "isValidContract": { "type": "boolean" },
          "bytecodeSizeBytes": { "type": "integer" },
          "targetBytecodeHash": { "type": ["string", "null"], "description": "Cryptographic SHA-256 hash of the analyzed bytecode" },
          "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" } },
          "detectedCapabilities": { "type": "array", "items": { "type": "string" } },
          "metadata": { "type": "object", "properties": { "disclaimer": { "type": "string" } } }
        }
      },
      "ProxyResolution": {
        "type": "object",
        "properties": {
          "isProxy": { "type": "boolean" },
          "proxyType": { "type": "string", "enum": ["NONE", "EIP1967_DIRECT", "EIP1822_UUPS", "ZEPPELINOS_LEGACY", "EIP1967_BEACON", "EIP1967_BEACON_UNRESOLVED", "EIP1167_MINIMAL_PROXY", "DELEGATECALL_PROXY_SUSPECTED", "CYCLE_DETECTED", "MAX_DEPTH_EXCEEDED"] },
          "targetAddress": { "type": "string" },
          "beaconAddress": { "type": "string" },
          "confidence": { "type": "string", "enum": ["HIGH", "MEDIUM", "LOW"] },
          "resolutionPath": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "via": { "type": "string" } } } },
          "warning": { "type": "string" },
          "note": { "type": "string" }
        }
      },
      "Reproducibility": {
        "type": "object",
        "description": "Deterministic reproducibility metadata and cryptographic bytecode hashes for independent verification.",
        "properties": {
          "chainId": { "type": "integer", "example": 8453 },
          "network": { "type": "string", "example": "eip155:8453" },
          "contractAddress": { "type": "string" },
          "runtimeBytecodeHash": { "type": ["string", "null"], "description": "SHA-256 hash of the target contract deployed runtime bytecode." },
          "isProxy": { "type": "boolean" },
          "implementationAddress": { "type": ["string", "null"] },
          "implementationBytecodeHash": { "type": ["string", "null"], "description": "SHA-256 hash of the implementation bytecode if target is a proxy." },
          "rulesetVersion": { "type": "string", "example": "2.2.0" },
          "engineVersion": { "type": "string", "example": "2.2.0" },
          "evidenceGrade": { "type": "boolean" },
          "trustLevel": { "type": "string" },
          "retrievedAt": { "type": "string", "format": "date-time" }
        }
      },
      "AuditResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "payoutWallet": { "type": "string" },
          "audit": {
            "type": "object",
            "properties": {
              "address": { "type": "string" },
              "analysisKind": { "type": "string", "const": "STATIC_BYTECODE_CAPABILITY_HEURISTIC" },
              "notASafetyGuarantee": { "type": "boolean", "const": true },
              "limitations": { "type": "array", "items": { "type": "string" } },
              "proxyResolution": { "$ref": "#/components/schemas/ProxyResolution" },
              "dissection": { "$ref": "#/components/schemas/Dissection" },
              "capabilityRating": { "type": "string" },
              "verdict": { "$ref": "#/components/schemas/Verdict" },
              "capabilityScore": { "type": ["integer", "null"], "minimum": 1, "maximum": 100 },
              "scoreBreakdown": { "type": "array", "items": { "type": "object" } },
              "scoreMeaning": { "type": ["string", "null"] },
              "evidenceGrade": { "type": "boolean" },
              "reproducibility": { "$ref": "#/components/schemas/Reproducibility" },
              "network": { "type": "string" },
              "provenance": { "$ref": "#/components/schemas/Provenance" }
            }
          }
        }
      },
      "ScoreResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "address": { "type": "string" },
          "analysisKind": { "type": "string", "const": "STATIC_BYTECODE_CAPABILITY_HEURISTIC" },
          "notASafetyGuarantee": { "type": "boolean", "const": true },
          "limitations": { "type": "array", "items": { "type": "string" } },
          "capabilityScore": { "type": ["integer", "null"] },
          "scoreBreakdown": { "type": "array", "items": { "type": "object", "properties": { "capability": { "type": "string" }, "confidence": { "type": "string" }, "points": { "type": "integer" } } } },
          "scoreMeaning": { "type": ["string", "null"] },
          "capabilityRating": { "type": "string" },
          "evidenceGrade": { "type": "boolean" },
          "verdict": { "$ref": "#/components/schemas/Verdict" },
          "capabilitiesDetected": { "type": "array", "items": { "type": "string" } },
          "provenance": { "$ref": "#/components/schemas/Provenance" }
        }
      },
      "GasResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "network": { "type": "string" },
          "gasPrice": { "type": "object", "properties": { "wei": { "type": "integer" }, "gwei": { "type": "number" } } },
          "provenance": { "$ref": "#/components/schemas/Provenance" }
        }
      },
      "DexMetricsResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "metrics": {
            "type": "object",
            "properties": {
              "indexedPools": { "type": "integer" },
              "totalVolume24hUsd": { "type": "integer" },
              "totalLiquidityDepthUsd": { "type": "integer" },
              "topPairs": { "type": "array", "items": { "type": "object", "properties": { "pair": { "type": "string" }, "dex": { "type": "string" }, "pairAddress": { "type": "string" }, "liquidityUsd": { "type": "integer" }, "volume24hUsd": { "type": "integer" }, "priceUsd": { "type": "number" } } } }
            }
          },
          "coverage": {
            "type": "object",
            "properties": {
              "description": { "type": "string" },
              "trackedTokens": { "type": "array", "items": { "type": "string" } },
              "sourcesQueried": { "type": "integer" },
              "sourcesSucceeded": { "type": "integer" },
              "degraded": { "type": "boolean" }
            }
          },
          "provenance": { "$ref": "#/components/schemas/Provenance" }
        }
      },
      "TokenPriceResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "token": {
            "type": "object",
            "properties": {
              "symbol": { "type": "string" },
              "name": { "type": "string" },
              "address": { "type": "string" },
              "decimals": { "type": "integer" },
              "priceUsd": { "type": "number" },
              "change24hPercent": { "type": ["number", "null"] },
              "volume24hUsd": { "type": "integer" },
              "liquidityUsd": { "type": "integer" },
              "fdvUsd": { "type": ["number", "null"] },
              "marketCapUsd": { "type": ["number", "null"] },
              "pricedFrom": {
                "type": "object",
                "properties": {
                  "method": { "type": "string" },
                  "deepestPool": { "type": "object" },
                  "priceSpreadPercent": { "type": "number", "description": "Spread across the pools used. A large spread indicates thin or manipulated liquidity." }
                }
              },
              "poolsConsidered": { "type": "integer" }
            }
          },
          "provenance": { "$ref": "#/components/schemas/Provenance" }
        }
      },
      "WhaleResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "signals": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "txHash": { "type": "string" },
                "blockNumber": { "type": "integer" },
                "logIndex": { "type": "integer" },
                "tokenAddress": { "type": "string" },
                "tokenSymbol": { "type": "string" },
                "sender": { "type": "string" },
                "receiver": { "type": "string" },
                "amount": { "type": "number" },
                "amountUsd": { "type": "integer" },
                "priceUsdUsedForValuation": { "type": "number" }
              }
            }
          },
          "query": {
            "type": "object",
            "properties": {
              "fromBlock": { "type": "integer" },
              "toBlock": { "type": "integer" },
              "blocksScanned": { "type": "integer" },
              "minimumUsd": { "type": "number" },
              "tokensQueried": { "type": "array", "items": { "type": "string" } },
              "tokensReadable": { "type": "array", "items": { "type": "string" } },
              "degraded": { "type": "boolean" }
            }
          },
          "provenance": { "$ref": "#/components/schemas/Provenance" }
        }
      },
      "PublicStats": {
        "type": "object",
        "required": ["status", "windowDays", "generatedAt", "privacy", "detailAccess"],
        "properties": {
          "status": { "type": "string", "const": "SUCCESS" },
          "windowDays": { "type": "integer" },
          "generatedAt": { "type": "string", "format": "date-time" },
          "privacy": { "type": "string" },
          "detailAccess": { "type": "string" }
        },
        "additionalProperties": false
      },
      "PublicProductEvent": {
        "oneOf": [
          {
            "type": "object", "required": ["event", "page", "campaign"], "additionalProperties": false,
            "properties": {
              "event": { "const": "pageViewed" },
              "page": { "type": "string", "enum": ["home", "pricing", "docs", "checkout", "demo", "status"] },
              "campaign": { "type": "string", "enum": ["direct", "organic", "github", "npm", "pypi", "mcp", "x402", "partner"] }
            }
          },
          {
            "type": "object", "required": ["event", "cta", "campaign"], "additionalProperties": false,
            "properties": {
              "event": { "const": "ctaClicked" },
              "cta": { "const": "subscribe" },
              "page": { "type": "string", "enum": ["home", "pricing", "docs", "checkout", "demo", "status"] },
              "tier": { "type": "string", "enum": ["FREE", "STARTER", "GROWTH", "PRO", "ENTERPRISE"] },
              "campaign": { "type": "string", "enum": ["direct", "organic", "github", "npm", "pypi", "mcp", "x402", "partner"] }
            }
          },
          {
            "type": "object", "required": ["event", "cta", "campaign"], "additionalProperties": false,
            "properties": {
              "event": { "const": "ctaClicked" },
              "cta": { "type": "string", "enum": ["demo", "freeKey", "docs", "sdk", "renew", "recover"] },
              "page": { "type": "string", "enum": ["home", "pricing", "docs", "checkout", "demo", "status"] },
              "campaign": { "type": "string", "enum": ["direct", "organic", "github", "npm", "pypi", "mcp", "x402", "partner"] }
            }
          }
        ]
      },
      "AggregateStats": {
        "type": "object",
        "required": ["status", "windowDays", "generatedAt", "totals", "revenue", "privacy"],
        "properties": {
          "status": { "type": "string", "const": "SUCCESS" },
          "windowDays": { "type": "integer", "minimum": 1, "maximum": 400 },
          "generatedAt": { "type": "string", "format": "date-time" },
          "totals": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "demoRequested": { "type": "integer" },
              "demoSucceeded": { "type": "integer" },
              "demoUnsupported": { "type": "integer" },
              "paymentChallengeIssued": { "type": "integer" },
              "x402Settled": { "type": "integer" },
              "authenticatedDecisionServed": { "type": "integer" },
              "freeChallengeCreated": { "type": "integer" },
              "freeKeyIssued": { "type": "integer" },
              "subscriptionIntentCreated": { "type": "integer" },
              "subscriptionKeyIssued": { "type": "integer" },
              "subscriptionRenewed": { "type": "integer" },
              "keyRecovered": { "type": "integer" },
              "quotaExhausted": { "type": "integer" },
              "x402RevenueMicrousd": { "type": "integer" },
              "subscriptionRevenueMicrousd": { "type": "integer" }
            }
          },
          "productEvents": { "type": "array", "items": { "type": "object", "description": "Allowlisted event dimensions plus an aggregate count." } },
          "revenue": { "type": "object", "properties": { "x402Usd": { "type": "number" }, "subscriptionsUsd": { "type": "number" } } },
          "privacy": { "type": "string" }
        }
      },
      "Status": {
        "type": "object",
        "properties": {
          "service": { "type": "string" },
          "status": { "type": "string", "enum": ["ONLINE", "DEGRADED", "OFFLINE"] },
          "deploymentPhase": { "type": "string", "const": "PRODUCTION" },
          "commerciallyPromoted": { "type": "boolean", "const": false },
          "x402ProtocolVersion": { "type": "integer" },
          "network": { "type": "string" },
          "components": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "status": { "type": "string", "enum": ["OPERATIONAL", "DEGRADED", "DOWN", "ENABLED", "DISABLED"] },
                "detail": { "type": ["string", "null"] }
              }
            }
          },
          "blockNumber": { "type": ["integer", "null"] },
          "uptimeClaim": { "type": ["number", "null"], "description": "Null until enough health samples exist; otherwise the measured 24-hour sample availability." },
          "uptimeNote": { "type": "string" },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "Plan": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "label": { "type": "string" },
          "priceUsd": { "type": ["number", "null"] },
          "monthlyCredits": { "type": ["integer", "null"], "description": "Hard cap per issuance-anchored 31-day access cycle. Never null for a purchasable plan." },
          "dailyCredits": { "type": ["integer", "null"] },
          "burstPerMinute": { "type": ["integer", "null"] },
          "sla": { "type": ["string", "null"] },
          "purchasable": { "type": "boolean" },
          "description": { "type": "string" },
          "usdcBaseUnits": { "type": ["string", "null"] }
        }
      },
      "Plans": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "currency": { "type": "string" },
          "billingModel": { "type": "string" },
          "settlement": { "type": "object" },
          "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } },
          "x402PerDecisionUsd": { "type": "object", "additionalProperties": { "type": "number" } }
        }
      },
      "IntentEnvelope": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "intent": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "tier": { "type": "string" },
              "userWallet": { "type": "string" },
              "durationDays": { "type": "integer", "enum": [31, 90, 365], "description": "Present on paid purchase intents." },
              "renewExistingKey": { "type": "boolean", "description": "Present on paid purchase intents; true when the payment extends the presented key." },
              "expiresAt": { "type": "string", "format": "date-time" },
              "messageToSign": { "type": "string" }
            }
          },
          "next": { "type": "array", "items": { "type": "string" } }
        }
      },
      "PurchaseIntent": {
        "allOf": [
          { "$ref": "#/components/schemas/IntentEnvelope" },
          {
            "type": "object",
            "properties": {
              "payment": {
                "type": "object",
                "properties": {
                  "payTo": { "type": "string" },
                  "network": { "type": "string" },
                  "priceUsd": { "type": "number" },
                  "usdc": { "type": "object", "properties": { "address": { "type": "string" }, "baseUnits": { "type": "string" }, "decimals": { "type": "integer" } } },
                  "nativeEth": { "type": ["object", "null"], "description": "Null when no live ETH quote was available; settle in USDC instead." }
                }
              }
            }
          }
        ]
      },
      "RecoveryIntent": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "const": "ACCEPTED" },
          "intent": {
            "type": "object",
            "required": ["id", "userWallet", "expiresAt", "messageToSign"],
            "properties": {
              "id": { "type": "string" },
              "userWallet": { "type": "string" },
              "expiresAt": { "type": "string", "format": "date-time" },
              "messageToSign": { "type": "string" }
            }
          },
          "next": { "type": "array", "items": { "type": "string" } }
        }
      },
      "IssuedKey": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "message": { "type": "string" },
          "apiKey": { "type": "string", "description": "Returned exactly once for a new or recovered key. Only its SHA-256 digest is stored. Paid keys can later be wallet-rotated; renewal keeps the current raw secret and omits this field." },
          "tier": { "type": "string" },
          "plan": { "$ref": "#/components/schemas/Plan" },
          "expiresAt": { "type": "string", "format": "date-time" },
          "txHash": { "type": "string" },
          "renewed": { "type": "boolean" },
          "durationDays": { "type": "integer", "enum": [31, 90, 365] }
        }
      },
      "KeySelf": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "key": {
            "type": "object",
            "properties": {
              "keyHashPrefix": { "type": "string" },
              "tier": { "type": "string" },
              "created": { "type": ["string", "null"] },
              "expiresAt": { "type": ["string", "null"] },
              "userWallet": { "type": ["string", "null"] },
              "revoked": { "type": "boolean" }
            }
          },
          "plan": { "$ref": "#/components/schemas/Plan" }
        }
      }
    }
  }
}