{
  "openapi": "3.1.0",
  "info": {
    "title": "Endpoint Record — Token Safety Verdict",
    "version": "1.0.0",
    "summary": "Token safety verdicts for autonomous agents, paid per call via x402.",
    "description": "Send the contract address of a token on Base and receive a verdict (SAFE, CAUTION or SCAM) with the evidence behind it: contract security, honeypot checks from two independent sources with explicit consensus, DEX liquidity, listing status, blacklist and scam pattern matches. Each call costs 0.02 USDC on Base, paid through the x402 protocol. No account, no API key. Repeating a request with the same requestKey and tokenAddress within 24 hours never charges twice. Verdicts are automated risk signals, not investment advice.",
    "contact": { "email": "contact@endpointrecord.com", "url": "https://endpointrecord.com" }
  },
  "servers": [ { "url": "https://api.endpointrecord.com" } ],
  "x-discovery": {},
  "paths": {
    "/scan": {
      "post": {
        "operationId": "scanToken",
        "summary": "Get a safety verdict for a token on Base",
        "description": "Without a payment the endpoint answers 402 with an x402 v2 payment challenge in the PAYMENT-REQUIRED header. Sign the offered EIP-3009 authorization (exact scheme, USDC on Base) and repeat the same request with the PAYMENT-SIGNATURE header. The receipt comes back in the PAYMENT-RESPONSE header. Typical latency is about 5 seconds, cached tokens answer faster.",
        "x-payment-info": {
          "protocols": ["x402"],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
          "network": "eip155:8453",
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "payTo": "0xCbb4b75c75F1805a8027550071292721258C6cC8"
        },
        "security": [ { "x402": [] } ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ScanRequest" },
              "example": { "requestKey": "c3f1a9e07b4d42c8a6f2e915d0b7c3aa", "tokenAddress": "0x532f27101965dd16442e59d40670faf5ebb142e4" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verdict delivered. A PAYMENT-RESPONSE header carries the settlement receipt on the first delivery.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verdict" } } }
          },
          "400": { "description": "requestKey or tokenAddress missing or invalid. Checked before any payment is taken." },
          "402": {
            "description": "Payment required. The PAYMENT-REQUIRED header holds the base64-encoded x402 v2 challenge (accepts, resource, extensions.bazaar).",
            "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64-encoded x402 v2 PaymentRequired object." } }
          },
          "429": { "description": "Rate limit reached. Retry later." },
          "503": {
            "description": "Payment settlement in progress or temporarily unavailable. Retry with the same requestKey and tokenAddress, without a new payment.",
            "headers": { "Retry-After": { "schema": { "type": "integer" } } }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 v2 payment payload, base64-encoded JSON. Obtain the challenge from the 402 response."
      }
    },
    "schemas": {
      "ScanRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["requestKey", "tokenAddress"],
        "properties": {
          "requestKey": {
            "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[\\x21-\\x7E]+$",
            "description": "Random secret chosen by the caller. Repeating the request with the same requestKey and tokenAddress within 24 hours never charges twice. Anyone who knows both can fetch the result, so keep it secret."
          },
          "tokenAddress": {
            "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$",
            "description": "Contract address of the token to check on Base."
          },
          "frisch": { "type": "boolean", "description": "Optional. true forces a fresh scan instead of a cached result." }
        }
      },
      "Verdict": {
        "type": "object",
        "properties": {
          "token":        { "type": "string" },
          "verdict":      { "type": "string", "enum": ["SAFE", "CAUTION", "SCAM"], "description": "Overall verdict from the consensus of seven checking agents." },
          "verdictLabel": { "type": "string" },
          "score":        { "type": "integer", "minimum": 0, "maximum": 100 },
          "scenario":     { "type": "string", "description": "A: established listed asset, B: blacklisted, C: unknown project." },
          "tokenInfo": {
            "type": "object",
            "properties": {
              "name": { "type": ["string", "null"] }, "symbol": { "type": ["string", "null"] },
              "rank": { "type": ["integer", "null"] }, "marketCapUsd": { "type": "number" },
              "volume24hUsd": { "type": "number" }, "volumeToMarketCap": { "type": ["number", "null"] },
              "website": { "type": ["string", "null"] }, "twitter": { "type": ["string", "null"] },
              "telegram": { "type": ["string", "null"] }, "categories": { "type": "array", "items": { "type": "string" } },
              "chain": { "type": ["string", "null"] }, "hasWhitepaper": { "type": "boolean" },
              "listedOnCoinGecko": { "type": "boolean" }
            }
          },
          "contract": {
            "type": "object",
            "properties": {
              "address": { "type": ["string", "null"] }, "found": { "type": "boolean" }, "chain": { "type": ["string", "null"] },
              "ownerRenounced": { "type": "boolean" }, "hasMint": { "type": "boolean" }, "hasVariableTax": { "type": "boolean" },
              "hasWalletFreeze": { "type": "boolean" }, "isUpgradeable": { "type": "boolean" }, "liquidityLocked": { "type": "boolean" },
              "freeMarket": { "type": "boolean" }, "dexLiquidityUsd": { "type": "number" },
              "checkIncomplete": { "type": "boolean", "description": "true means the contract check is incomplete. Pass this on to end users." },
              "security": {
                "type": "object",
                "description": "Contract security (static analysis). checked:false means no data was available, not that the token is clean.",
                "properties": {
                  "checked": { "type": "boolean" }, "reason": { "type": "string" }, "honeypot": { "type": "boolean" },
                  "mintable": { "type": "boolean" }, "hiddenOwner": { "type": "boolean" }, "selfdestruct": { "type": "boolean" },
                  "proxy": { "type": "boolean" }, "canBlacklist": { "type": "boolean" }, "openSource": { "type": "boolean" },
                  "buyTax": { "type": ["number", "null"] }, "sellTax": { "type": ["number", "null"] }, "holderCount": { "type": ["integer", "null"] }
                }
              },
              "securitySecondSource": {
                "type": "object",
                "description": "Independent buy and sell simulation.",
                "properties": {
                  "checked": { "type": "boolean" }, "reason": { "type": "string" }, "honeypot": { "type": "boolean" },
                  "buyTax": { "type": ["number", "null"] }, "sellTax": { "type": ["number", "null"] },
                  "risk": { "type": ["string", "null"] }, "riskLevel": { "type": ["integer", "null"] }
                }
              },
              "honeypotVerdict": {
                "type": ["object", "null"],
                "description": "Consensus of both sources. honeypot:null means the sources disagree; that is a finding, not a gap.",
                "properties": {
                  "honeypot": { "type": ["boolean", "null"] }, "sources": { "type": "integer" },
                  "consensus": { "type": "boolean" }, "contradiction": { "type": ["string", "null"] }
                }
              }
            }
          },
          "flags":       { "type": "array", "items": { "type": "string" }, "description": "Human-readable findings." },
          "blacklisted": { "type": "boolean" },
          "timestamp":   { "type": "string", "format": "date-time" },
          "cache":       { "type": "object", "properties": { "hit": { "type": "boolean" }, "ageSeconds": { "type": "integer" } } },
          "idempotency": { "type": "object", "properties": { "repeated": { "type": "boolean" }, "ageSeconds": { "type": "integer" } } }
        }
      }
    }
  }
}