{"openapi":"3.1.0","info":{"title":"holder-check","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":"Holder Analysis API for Base tokens: top 10 holders with % and type (wallet, contract, LP pool, burn) plus known labels (87 Base exchanges, lockers, bridges, DEX contracts, each with source), concentration excluding labeled exchange/bridge/locker holders, distribution verdict and bundling check from real on-chain data. $0.02 per call via x402 (USDC on Base). Not investment advice.","x-guidance":"Holder analysis for an ERC-20 on Base. Input: address (0x contract). Output: top 10 holders with % and type plus known_label (label, category, source) from a curated list of 87 Base exchanges/lockers/bridges/DEX contracts, top10_wallets_pct, top10_excluding_contracts_pct, top10_excluding_labeled_pct (labeled cex/locker/bridge/dex_contract/burn excluded from concentration and bundling), distribution (bundling/concentrated/distributed/unknown) with its basis, and bundling evidence. ?lang=da for Danish values. Call before an agent buys or lists an unknown Base token. Not investment advice.","x-related":[{"name":"token-verdict","description":"One-call verdict: all 4 checks + English conclusion (Base, $0.05)","url":"https://token-verdict.restockalarm.workers.dev/"},{"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":"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://holder-check.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://holder-check.restockalarm.workers.dev"}],"paths":{"/v1/holders":{"get":{"operationId":"getV1Holders","summary":"Holder analysis for an ERC-20 token on Base: top 10 holders with type and known label (label, category, source), wallet concentration, distribution and bundling check","description":"Holder analysis for an ERC-20 token on Base: top 10 holders with type and known label (label, category, source), wallet concentration, distribution and bundling check. $0.02 USDC per call via x402 (Base or Polygon), or 4 credits per call with header X-API-Key (card credit packs).","x-details":"Method: Top 10 holders by balance from honeypot.is TopHolders (pct = balance / totalSupply). type: burn = 0x0, 0x…dEaD, 0xdead…69420, 0x…01; lp = a DEX pool (listed by honeypot.is GetPairs, or the contract answers token0() plus getReserves() or slot0()); contract = has bytecode; wallet = no bytecode or an EIP-7702 delegated EOA (code 0xef0100…). 'exchange' is only set from the curated label list (known_label), never guessed. top10_wallets_pct counts wallets only; top10_excluding_contracts_pct = top-10 share minus contracts (escrow, vesting, lockers, bridges, treasuries), LP pools and burn addresses. distribution (based on wallets, not on top10_total_pct): bundling if bundling = suspected with strength strong (transfer-timing evidence); concentrated if top10_wallets_pct >= 30% or one wallet >= 10%; else distributed. bundling = suspected (strong) if >= 3 top-10 wallets received the token in the same block or from the same non-pool sender in the last ~2 h (3600 blocks, eth_getLogs). Equal shares (>= 3 top-10 wallets, each >= 0.1%, within 0.5% of each other) count as suspected (weak) only for small tokens (< 5,000 holders); for larger or older tokens the pattern is typical for exchange custody, vesting or airdrop splits and is reported in observations only, never as suspicion. Contracts, LP and burn addresses never count as bundling. known_label = curated public label list (87 Base addresses: exchanges, lockers, bridges, DEX contracts, burn, treasuries), each with its public source URL; no RPC. Holders whose label category is cex, locker, bridge, dex_contract or burn are excluded from concentration (top10_excluding_labeled_pct, top10_unlabeled_wallets_pct, largest_unlabeled_wallet_pct, distribution) and from bundling detection. Unlabeled does not mean retail: the list is not exhaustive.","x-api-key-credits":4,"x-guidance":"Holder analysis for an ERC-20 on Base. Input: address (0x contract). Output: top 10 holders with % and type plus known_label (label, category, source) from a curated list of 87 Base exchanges/lockers/bridges/DEX contracts, top10_wallets_pct, top10_excluding_contracts_pct, top10_excluding_labeled_pct (labeled cex/locker/bridge/dex_contract/burn excluded from concentration and bundling), distribution (bundling/concentrated/distributed/unknown) with its basis, and bundling evidence. ?lang=da for Danish values. Call before an agent buys or lists an unknown Base token. Not investment advice.","tags":["holder-check"],"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.020000"},"protocols":[{"x402":{}}],"networks":["eip155:8453","eip155:137"],"payTo":"0x7B97303d62517eA9E26D1E1b199Eac42a487F430"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["address","chain","token","top10","top10_total_pct","top10_wallets_pct","distribution","bundling","method","signals_measured_list","sources","cached","disclaimer"],"properties":{"address":{"type":"string"},"chain":{"type":"string","const":"base"},"token":{"type":"object"},"total_holders":{"type":["integer","null"]},"top10":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"pct":{"type":["number","null"]},"type":{"type":"string","enum":["wallet","contract","lp","burn","exchange","unknown"]},"label":{"type":"string"}}},"maxItems":10},"top10_total_pct":{"type":"number"},"top10_wallets_pct":{"type":"number","description":"Share held by top-10 wallets only (excl. contract/lp/burn)"},"top10_excluding_contracts_pct":{"type":"number","description":"top10_total_pct minus contracts (escrow/vesting/lockers/bridges), LP pools and burn"},"top10_excluding_labeled_pct":{"type":"number","description":"top10_total_pct minus contracts, LP pools, burn AND holders labeled cex/locker/bridge/dex_contract/burn"},"top10_unlabeled_wallets_pct":{"type":"number","description":"Top-10 wallets without an excluded label (basis for distribution)"},"top10_labeled_excluded_pct":{"type":"number"},"labeled_holders":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"pct":{"type":"number"},"label":{"type":"string"},"category":{"type":"string","enum":["cex","locker","bridge","dex_contract","burn","treasury","other"]},"source":{"type":"string"},"excluded_from_concentration":{"type":"boolean"}}}},"labels_version":{"type":"string"},"distribution":{"type":"string","enum":["bundling","concentrated","distributed","unknown"],"description":"Canonical English (API v2). ?lang=da: bundling/koncentreret/spredt/ukendt"},"distribution_en":{"type":"string","deprecated":true},"distribution_basis":{"type":"string"},"api_version":{"type":"string"},"lang":{"type":"string"},"deprecated":{"type":"string"},"bundling":{"type":"object","properties":{"status":{"type":"string","enum":["suspected","none","unknown"]},"status_en":{"type":"string","deprecated":true},"strength":{"type":["string","null"],"enum":["weak","strong",null]},"evidence":{"type":"array","items":{"type":"string"}},"observations":{"type":"array","items":{"type":"string"},"description":"Patterns seen but not counted as bundling"},"checks_run":{"type":"array","items":{"type":"string"}}}},"method":{"type":"string"},"signals_measured_list":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"cached":{"type":"boolean"},"disclaimer":{"type":"string"}}},"example":{"address":"0x4ed4e862860bed51a9570b96d89af5e1b0efefed","chain":"base","token":{"name":"Degen","symbol":"DEGEN"},"total_holders":1192880,"top10":[{"address":"0x06A19654e0872Ba71c2261EA691Ecf8a0c677156","pct":22.61,"type":"wallet"}],"top10_total_pct":58.4,"top10_wallets_pct":40.1,"top10_excluding_contracts_pct":40.1,"distribution":"concentrated","distribution_basis":"distribution uses wallets only: …","bundling":{"status":"none","evidence":[],"checks_run":["equal_share_check","same_block_check"]},"method":"…","signals_measured_list":["top_holders","holder_types","equal_share_check","same_block_check"],"sources":["https://api.honeypot.is/v1/TopHolders?…"],"cached":false,"disclaimer":"Ikke investeringsråd / not investment advice. Automated analysis of public on-chain data; labels and bundling hints can be wrong or incomplete. 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 holder data"},"503":{"description":"Core fields (holder types, distribution) could not be measured right now. Header Retry-After (s). Not charged: x402 is not settled and API-key credits are refunded."}}}}}}