{
  "openapi": "3.1.0",
  "info": {
    "title": "token-verdict",
    "version": "2.0.0",
    "x-deprecations": "API v2: enum values are canonical English. Every `<field>_en` mirror is deprecated (identical to the field, removal planned in v3). Add ?lang=da for the previous Danish values (v1 format with _en mirrors). news_sentiment/social level 'neutral' without data is now 'no_data' (old value in legacy_level).",
    "description": "Token Verdict API for Base: one call runs token risk, rug-pull, holder and momentum checks plus contract flags (proxy, blacklist, pause, selfdestruct) and returns one verdict (avoid / high_risk / caution / low_risk) with a one-line English summary; top holders carry known labels (exchanges, bridges, lockers) that are excluded from concentration. $0.05 per call via x402 (USDC on Base or Polygon). Not investment advice.",
    "x-guidance": "One-call due diligence for an ERC-20 on Base. Input: address (0x contract). Output: verdict avoid/high_risk/caution/low_risk, verdict_confidence, a one-line English summary, reasons, key metrics (risk score, rug_pull, named liquidity, wallet concentration with labeled exchanges/lockers/bridges excluded + labeled_top_holders (label, category, source), momentum + direction, contract flags) and the full outputs of the 4 single APIs. Call once before an agent buys, lists or accepts an unknown Base token. Cheaper than 4 single calls ($0.05 vs $0.08). Not investment advice.",
    "x-related": [
      {
        "name": "token-risk",
        "description": "Token risk score (Base)",
        "url": "https://token-risk.restockalarm.workers.dev/"
      },
      {
        "name": "rug-check",
        "description": "Rug-pull detector (Base)",
        "url": "https://rug-check.restockalarm.workers.dev/"
      },
      {
        "name": "holder-check",
        "description": "Holder analysis (Base)",
        "url": "https://holder-check.restockalarm.workers.dev/"
      },
      {
        "name": "momentum-score",
        "description": "Momentum score (Base)",
        "url": "https://momentum-score.restockalarm.workers.dev/"
      },
      {
        "name": "token-safety",
        "description": "Token Safety suite (all Base token APIs incl. one-call verdict)",
        "url": "https://product-katalog.restockalarm.workers.dev/token-safety"
      },
      {
        "name": "token-safety-mcp",
        "description": "Remote MCP server with the same tools ($0.02, token_verdict $0.05 via x402 for MCP)",
        "url": "https://token-safety-mcp.restockalarm.workers.dev/mcp"
      }
    ],
    "contact": {
      "name": "Space Command Kits",
      "email": "spacecommand+circle@mail.grokbot.com",
      "url": "https://token-verdict.restockalarm.workers.dev/"
    }
  },
  "externalDocs": {
    "description": "Token Safety suite — all Base token APIs incl. one-call verdict",
    "url": "https://product-katalog.restockalarm.workers.dev/token-safety"
  },
  "servers": [
    {
      "url": "https://token-verdict.restockalarm.workers.dev"
    }
  ],
  "paths": {
    "/v1/verdict": {
      "get": {
        "operationId": "getV1Verdict",
        "summary": "One-call verdict for an ERC-20 token on Base: risk + rug-pull + holders + momentum + contract flags, verdict avoid/high_risk/caution/low_risk and a one-line English summary",
        "description": "One-call verdict for an ERC-20 token on Base: risk + rug-pull + holders + momentum + contract flags, verdict avoid/high_risk/caution/low_risk and a one-line English summary. $0.05 USDC per call via x402 (Base or Polygon), or 10 credits per call with header X-API-Key (card credit packs).",
        "x-details": "Verdict rule: verdict (first match wins): avoid = rug_pull true, honeypot, risk score >= 70 or token paused right now; high_risk = risk score >= 50, strong bundling evidence or selfdestruct in bytecode; caution = risk score >= 30, concentrated wallet distribution (labeled exchanges/lockers/bridges/DEX contracts/burn excluded), weak bundling suspicion, or an owner-control capability (blacklist, pause, upgradeable proxy, anti-whale limits); low_risk = none of these. mintable is reported but does not change the verdict (normal for emission/bridged tokens). Momentum never changes the verdict (it measures activity, not safety). verdict_confidence: high if all 4 parts answered and rug-check confidence is high or medium, medium if one optional part (holders or momentum) is missing, low if rug-check confidence is low (few signals measured: missing data lowers the confidence, never the verdict).",
        "x-api-key-credits": 10,
        "x-guidance": "One-call due diligence for an ERC-20 on Base. Input: address (0x contract). Output: verdict avoid/high_risk/caution/low_risk, verdict_confidence, a one-line English summary, reasons, key metrics (risk score, rug_pull, named liquidity, wallet concentration with labeled exchanges/lockers/bridges excluded + labeled_top_holders (label, category, source), momentum + direction, contract flags) and the full outputs of the 4 single APIs. Call once before an agent buys, lists or accepts an unknown Base token. Cheaper than 4 single calls ($0.05 vs $0.08). Not investment advice.",
        "tags": [
          "token-verdict"
        ],
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": false,
            "description": "ERC-20 contract address on Base (0x + 40 hex). If omitted, the AERO example is returned with example=true; an invalid address is 400.",
            "schema": {
              "type": "string",
              "pattern": "^0x[0-9a-fA-F]{40}$"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Optional. Output language for enum values: en (default, canonical) or da (previous Danish values + deprecated *_en mirrors)",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "da"
              ],
              "default": "en"
            }
          }
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USDC",
            "amount": "0.050000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ],
          "networks": [
            "eip155:8453",
            "eip155:137"
          ],
          "payTo": "0x7B97303d62517eA9E26D1E1b199Eac42a487F430",
          "assets": [
            {
              "network": "eip155:8453",
              "chain": "Base",
              "symbol": "USDC",
              "decimals": 6,
              "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
            },
            {
              "network": "eip155:137",
              "chain": "Polygon",
              "symbol": "USDC",
              "decimals": 6,
              "asset": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"
            }
          ],
          "asset": "USDC",
          "facilitator": "https://x402.dexter.cash",
          "scheme": "exact",
          "cardAlternative": {
            "method": "API credits bought by card/PayPal (Fourthwall)",
            "header": "X-API-Key",
            "creditsPerCall": 10,
            "creditUsd": 0.005,
            "buy": "https://product-katalog.restockalarm.workers.dev/go/api-credits",
            "claimKey": "https://api-keys.restockalarm.workers.dev/claim",
            "rates": "https://api-keys.restockalarm.workers.dev/"
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "address",
                    "chain",
                    "token",
                    "verdict",
                    "verdict_confidence",
                    "summary",
                    "reasons",
                    "key_metrics",
                    "components",
                    "verdict_rule",
                    "sources",
                    "disclaimer"
                  ],
                  "properties": {
                    "api_version": {
                      "type": "string"
                    },
                    "lang": {
                      "type": "string",
                      "enum": [
                        "en",
                        "da"
                      ]
                    },
                    "address": {
                      "type": "string"
                    },
                    "chain": {
                      "type": "string",
                      "const": "base"
                    },
                    "token": {
                      "type": "object"
                    },
                    "verdict": {
                      "type": "string",
                      "enum": [
                        "avoid",
                        "high_risk",
                        "caution",
                        "low_risk"
                      ],
                      "description": "Canonical English. ?lang=da: undgå/høj_risiko/forsigtig/lav_risiko"
                    },
                    "verdict_confidence": {
                      "type": "string",
                      "enum": [
                        "low",
                        "medium",
                        "high"
                      ]
                    },
                    "summary": {
                      "type": "string",
                      "description": "One-line English conclusion (always English)"
                    },
                    "reasons": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "level": {
                            "type": "string",
                            "enum": [
                              "avoid",
                              "high_risk",
                              "caution"
                            ]
                          },
                          "reason": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "key_metrics": {
                      "type": "object",
                      "properties": {
                        "risk_score": {
                          "type": "integer"
                        },
                        "rug_pull": {
                          "type": "boolean"
                        },
                        "liquidity": {
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "top10_wallets_pct": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "top10_excluding_contracts_pct": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "top10_excluding_labeled_pct": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "top10_unlabeled_wallets_pct": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "labeled_top_holders": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "address": {
                                "type": "string"
                              },
                              "pct": {
                                "type": "number"
                              },
                              "label": {
                                "type": "string"
                              },
                              "category": {
                                "type": "string"
                              },
                              "source": {
                                "type": "string"
                              },
                              "excluded_from_concentration": {
                                "type": "boolean"
                              }
                            }
                          }
                        },
                        "distribution": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "momentum": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "direction": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "enum": [
                            "up",
                            "down",
                            "flat",
                            "no_data",
                            null
                          ]
                        },
                        "contract_flags": {
                          "type": "object",
                          "properties": {
                            "proxy": {
                              "type": [
                                "object",
                                "null"
                              ]
                            },
                            "blacklist": {
                              "oneOf": [
                                {
                                  "type": "boolean"
                                },
                                {
                                  "type": "string",
                                  "const": "unknown"
                                }
                              ]
                            },
                            "pause": {
                              "oneOf": [
                                {
                                  "type": "boolean"
                                },
                                {
                                  "type": "string",
                                  "const": "unknown"
                                }
                              ]
                            },
                            "paused_now": {
                              "oneOf": [
                                {
                                  "type": "boolean"
                                },
                                {
                                  "type": "string",
                                  "const": "unknown"
                                }
                              ]
                            },
                            "anti_whale": {
                              "oneOf": [
                                {
                                  "type": "boolean"
                                },
                                {
                                  "type": "string",
                                  "const": "unknown"
                                }
                              ]
                            },
                            "mintable": {
                              "oneOf": [
                                {
                                  "type": "boolean"
                                },
                                {
                                  "type": "string",
                                  "const": "unknown"
                                }
                              ]
                            },
                            "selfdestruct": {
                              "oneOf": [
                                {
                                  "type": "boolean"
                                },
                                {
                                  "type": "string",
                                  "const": "unknown"
                                }
                              ]
                            },
                            "delegatecall": {
                              "oneOf": [
                                {
                                  "type": "boolean"
                                },
                                {
                                  "type": "string",
                                  "const": "unknown"
                                }
                              ]
                            }
                          }
                        }
                      }
                    },
                    "components": {
                      "type": "object",
                      "description": "Full outputs of token-risk, rug-check, holder-check, momentum-score (method texts removed; see each API's docs)",
                      "properties": {
                        "risk": {
                          "type": "object"
                        },
                        "rug": {
                          "type": "object"
                        },
                        "holders": {
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "momentum": {
                          "type": [
                            "object",
                            "null"
                          ]
                        }
                      }
                    },
                    "verdict_rule": {
                      "type": "string"
                    },
                    "sources": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "deprecated": {
                      "type": "string"
                    },
                    "disclaimer": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "address": "0x940181a94a35a4569e4529a3cdfb74e38fd98631",
                  "chain": "base",
                  "token": {
                    "name": "Aerodrome",
                    "symbol": "AERO"
                  },
                  "verdict": "low_risk",
                  "verdict_confidence": "medium",
                  "summary": "AERO: low_risk — risk 20/100, rug_pull false (3/5 signals measured), top-10 wallets 15.13% (distributed), liquidity $49.65M pooled / top pool $35.11M (dexscreener), momentum 78 (down); contract flags: mintable.",
                  "reasons": [],
                  "key_metrics": {
                    "risk_score": 20,
                    "rug_pull": false,
                    "rug_confidence": "medium",
                    "liquidity": {
                      "pooled_all_pools_usd": 49650000,
                      "top_pool_liquidity_usd": 35110000,
                      "source": "dexscreener"
                    },
                    "top10_wallets_pct": 15.13,
                    "top10_excluding_contracts_pct": 15.13,
                    "distribution": "distributed",
                    "bundling": "none",
                    "momentum": 78,
                    "direction": "down",
                    "contract_flags": {
                      "honeypot": false,
                      "proxy": {
                        "value": false
                      },
                      "blacklist": false,
                      "pause": false,
                      "paused_now": false,
                      "anti_whale": false,
                      "mintable": true,
                      "selfdestruct": false,
                      "delegatecall": false
                    }
                  },
                  "components": {
                    "risk": {
                      "score": 20
                    },
                    "rug": {
                      "rug_pull": false
                    },
                    "holders": {
                      "distribution": "distributed"
                    },
                    "momentum": {
                      "momentum": 78,
                      "direction": "down"
                    }
                  },
                  "verdict_rule": "…",
                  "cached": false,
                  "disclaimer": "Not investment advice. Automated verdict from public on-chain and DEX data, combining four heuristics; it can be incomplete or wrong. Do your own research."
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "402": {
            "description": "Payment Required (x402)"
          },
          "404": {
            "description": "No contract at this address on Base"
          },
          "422": {
            "description": "Contract has no token or market data"
          },
          "503": {
            "description": "A part had a temporary data gap. Header Retry-After (s). Not charged: x402 is not settled and API-key credits are refunded."
          }
        }
      }
    }
  }
}