{"openapi":"3.1.0","info":{"title":"TokenRanker API","version":"1.0.0","description":"Machine-readable on-chain token ranking for the Robinhood chain: prices, liquidity, volume, AI risk audits, and X/Twitter engagement. Public, read-only, no auth.","x-links":{"docs":"/docs","mcp":"/mcp","llms":"/llms.txt"}},"servers":[{"url":"https://tokenranker.xyz/api/v1"}],"tags":[{"name":"pairs"},{"name":"hyped"},{"name":"surge"},{"name":"audits"},{"name":"stats"},{"name":"meta"}],"paths":{"/api/v1":{"get":{"tags":["meta"],"summary":"API index","description":"Lists all endpoints, docs links, and the MCP endpoint.","responses":{"200":{"description":"Endpoint index."}}}},"/api/v1/pairs":{"get":{"tags":["pairs"],"summary":"List ranked pairs","description":"All Robinhood-chain token pairs with filters, sorting, and pagination.","parameters":[{"$ref":"#/components/parameters/q"},{"$ref":"#/components/parameters/type"},{"$ref":"#/components/parameters/dex"},{"$ref":"#/components/parameters/quote"},{"$ref":"#/components/parameters/minLiq"},{"$ref":"#/components/parameters/minVol"},{"$ref":"#/components/parameters/minScore"},{"$ref":"#/components/parameters/hasAudit"},{"$ref":"#/components/parameters/minFollowerGrowth24h"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/order"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/dedupe"}],"responses":{"200":{"description":"A page of pairs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PairList"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/v1/pairs/{idOrAddress}":{"get":{"tags":["pairs"],"summary":"Get one pair","description":"A single pair matched by pair id, token address, or exact token name.","parameters":[{"name":"idOrAddress","in":"path","required":true,"schema":{"type":"string"},"description":"Pair id, token address (0x...), or exact token name."}],"responses":{"200":{"description":"The pair.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pair"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/hyped":{"get":{"tags":["hyped"],"summary":"List hyped tokens","description":"Tokens ranked by 24h X follower growth. Same parameters as /pairs.","parameters":[{"$ref":"#/components/parameters/q"},{"$ref":"#/components/parameters/type"},{"$ref":"#/components/parameters/dex"},{"$ref":"#/components/parameters/minScore"},{"$ref":"#/components/parameters/minFollowerGrowth24h"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/order"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/dedupe"}],"responses":{"200":{"description":"A page of hyped tokens.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PairList"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/v1/surge":{"get":{"tags":["surge"],"summary":"List surge-zone tokens","description":"Tokens in the surge zone. Same parameters as /pairs.","parameters":[{"$ref":"#/components/parameters/q"},{"$ref":"#/components/parameters/type"},{"$ref":"#/components/parameters/dex"},{"$ref":"#/components/parameters/minScore"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/order"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/dedupe"}],"responses":{"200":{"description":"A page of surge-zone tokens.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PairList"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/v1/audits/{address}":{"get":{"tags":["audits"],"summary":"Get token audit","description":"The AI risk audit for one token address.","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Token contract address (lowercase or mixed case)."}],"responses":{"200":{"description":"The audit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenAudit"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/stats":{"get":{"tags":["stats"],"summary":"Market statistics","description":"Aggregate market statistics across all tracked pairs.","responses":{"200":{"description":"Market statistics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stats"}}}}}}}},"components":{"parameters":{"q":{"name":"q","in":"query","schema":{"type":"string"},"description":"Substring match on token name, pair id, or token address."},"type":{"name":"type","in":"query","schema":{"type":"string","enum":["EQUITY","BASE","MEME"]},"description":"Comma-separated token types."},"dex":{"name":"dex","in":"query","schema":{"type":"string","enum":["V2","V3","V4","SW3"]},"description":"Comma-separated DEX versions."},"quote":{"name":"quote","in":"query","schema":{"type":"string"},"description":"Comma-separated quote symbols (e.g. USDG,ETH)."},"minLiq":{"name":"minLiq","in":"query","schema":{"type":"number","minimum":0},"description":"Minimum liquidity in USD."},"minVol":{"name":"minVol","in":"query","schema":{"type":"number","minimum":0},"description":"Minimum 24h volume in USD."},"minScore":{"name":"minScore","in":"query","schema":{"type":"number","minimum":0,"maximum":100},"description":"Minimum AI audit score."},"hasAudit":{"name":"hasAudit","in":"query","schema":{"type":"boolean"},"description":"Only pairs with an AI audit."},"minFollowerGrowth24h":{"name":"minFollowerGrowth24h","in":"query","schema":{"type":"number"},"description":"Minimum 24h X follower growth rate (%)."},"sort":{"name":"sort","in":"query","schema":{"type":"string","enum":["rank","price","chg24h","volume24h","liquidity","ageMinutes","auditScore","followers","followerGrowth1h","followerGrowth24h","views1h","views24h","views48h","posts1h","posts24h","posts48h","createdAt"]},"description":"Sort key. Default: rank (hyped: followerGrowth24h)."},"order":{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"]},"description":"Sort direction. Default: asc."},"limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500},"description":"Page size (default 100)."},"offset":{"name":"offset","in":"query","schema":{"type":"integer","minimum":0},"description":"Pagination offset (default 0)."},"dedupe":{"name":"dedupe","in":"query","schema":{"type":"boolean"},"description":"Collapse rows for the same token quoted against multiple currencies."}},"responses":{"BadRequest":{"description":"Invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Meta":{"type":"object","properties":{"total":{"type":"integer"},"count":{"type":"integer"},"offset":{"type":"integer"},"limit":{"type":"integer"},"hasMore":{"type":"boolean"},"sort":{"type":"string"},"order":{"type":"string","enum":["asc","desc"]},"ts":{"type":"integer","description":"Server time of the response (unix seconds)."}}},"Windowed":{"type":"object","properties":{"1h":{"type":"number"},"24h":{"type":"number"},"48h":{"type":"number"}}},"TokenAudit":{"type":"object","required":["model","ts","score","summary"],"properties":{"model":{"type":"string"},"ts":{"type":"integer","description":"Audit timestamp (unix seconds)."},"score":{"type":"number","minimum":0,"maximum":100,"description":"Risk score; higher is safer."},"summary":{"type":"string"}}},"Token":{"type":"object","required":["name","address","type","audit"],"properties":{"name":{"type":"string"},"address":{"type":"string"},"type":{"type":"string","enum":["EQUITY","BASE","MEME"]},"website":{"type":"string"},"xAccount":{"type":"string"},"telegram":{"type":"string"},"audit":{"anyOf":[{"$ref":"#/components/schemas/TokenAudit"},{"type":"null"}]}}},"Quote":{"type":"object","required":["symbol","address"],"properties":{"symbol":{"type":"string"},"address":{"type":"string"}}},"XStats":{"type":"object","properties":{"followers":{"type":"number"},"followerGrowth":{"$ref":"#/components/schemas/Windowed"},"posts":{"$ref":"#/components/schemas/Windowed"},"views":{"$ref":"#/components/schemas/Windowed"},"replies":{"$ref":"#/components/schemas/Windowed"},"retweets":{"$ref":"#/components/schemas/Windowed"},"likes":{"$ref":"#/components/schemas/Windowed"}}},"Pair":{"type":"object","required":["id","token","quote","dex","price","volume24h","liquidity","rank","ageMinutes","x"],"properties":{"id":{"type":"string"},"token":{"$ref":"#/components/schemas/Token"},"quote":{"$ref":"#/components/schemas/Quote"},"dex":{"type":"string","enum":["V2","V3","V4","SW3"]},"price":{"type":"number"},"chg24h":{"anyOf":[{"type":"number"},{"type":"null"}]},"volume24h":{"type":"number"},"liquidity":{"type":"number"},"rank":{"type":"integer"},"rankScore":{"type":"number"},"ageMinutes":{"type":"integer"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"x":{"$ref":"#/components/schemas/XStats"}}},"PairList":{"type":"object","required":["meta","data"],"properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Pair"}}}},"Stats":{"type":"object","properties":{"updatedAt":{"type":"integer"},"pairs":{"type":"integer"},"tokens":{"type":"integer"},"auditedPairs":{"type":"integer"},"totalLiquidity":{"type":"number"},"totalVolume24h":{"type":"number"},"avgAuditScore":{"type":"number"},"topGainers":{"type":"array","items":{"$ref":"#/components/schemas/Pair"}},"topLosers":{"type":"array","items":{"$ref":"#/components/schemas/Pair"}},"mostActive":{"type":"array","items":{"$ref":"#/components/schemas/Pair"}},"byType":{"type":"object","additionalProperties":{"type":"integer"}},"byDex":{"type":"object","additionalProperties":{"type":"integer"}},"byQuote":{"type":"object","additionalProperties":{"type":"integer"}}}}}}}