{"openapi":"3.1.0","info":{"title":"TokenLens API","version":"1.0.0","description":"Public read-only endpoints behind the TokenLens crypto analysis app. No authentication. An MCP server with the same capabilities runs at https://token-lens-pi.vercel.app/api/mcp (Streamable HTTP). Versioning: the current API version is 1, echoed on every response as the X-API-Version header. Breaking changes ship only as new /api/v2 paths; the old paths then emit Deprecation and Sunset headers (RFC 8594) at least 90 days before removal, with the timeline documented at /developers and in the repository changelog. Additive changes (new optional fields) do not bump the version. Rate limits: 60 requests per client per 60 seconds. Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and RateLimit-Policy headers; an exhausted window returns 429 with Retry-After. Errors: all 4xx and 5xx responses are RFC 9457 application/problem+json with a stable machine-readable `code`, a human-readable `detail`, and a `hint` describing how to recover.","contact":{"url":"https://github.com/Zapkid/TokenLens/issues"}},"servers":[{"url":"https://token-lens-pi.vercel.app"}],"paths":{"/api/search":{"get":{"operationId":"searchAssets","summary":"Resolve a free-text query to TokenLens asset ids","description":"Ranked token and chain matches for a name, symbol, or slug. Call this first: every other endpoint takes the ids it returns.","parameters":[{"name":"q","in":"query","required":true,"description":"Free-text query, e.g. 'solana' or 'uni'","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Ranked matches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"502":{"description":"Upstream data provider failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/report":{"get":{"operationId":"generateReport","summary":"Full analysis report for one asset","description":"Opportunity and risk scores, pillar breakdowns, risk grade, scenario trajectories, and holding strategy for one token or chain. Unknown ids are rejected, never fabricated.","parameters":[{"name":"type","in":"query","required":true,"description":"Asset kind: 'token' for coins, 'chain' for blockchains","schema":{"type":"string","enum":["token","chain"]}},{"name":"id","in":"query","required":true,"description":"TokenLens asset id from /api/search","schema":{"type":"string"}},{"name":"refresh","in":"query","required":false,"description":"Set to 1 to bypass the report cache","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"The report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportResponse"}}}},"400":{"description":"Missing or invalid type/id (code: invalid_params)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"502":{"description":"Report generation failed (code: report_failed)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/library":{"get":{"operationId":"getLibrary","summary":"Top tokens by market cap and chains by TVL","description":"Ten top tokens (stablecoins excluded) and ten top chains, recomputed on a cache interval.","responses":{"200":{"description":"Library lists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LibraryResponse"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"502":{"description":"Upstream data provider failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/market":{"get":{"operationId":"getMarketRegime","summary":"Global market regime snapshot","description":"Risk-on, neutral, or risk-off composite with its components plus trending assets.","responses":{"200":{"description":"Regime and trending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketResponse"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"502":{"description":"Upstream data provider failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/prices":{"get":{"operationId":"getPrices","summary":"Quotes for known asset ids","description":"Current price and 24h change for up to 100 known ids.","parameters":[{"name":"ids","in":"query","required":true,"description":"Comma-separated TokenLens asset ids from /api/search","schema":{"type":"string"}}],"responses":{"200":{"description":"Quotes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricesResponse"}}}},"400":{"description":"Missing ids (code: invalid_params)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"502":{"description":"Upstream data provider failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"schemas":{"Problem":{"type":"object","description":"RFC 9457 problem details. code is stable and machine-readable; hint says how to recover; error mirrors detail for legacy clients.","required":["type","title","status","code","detail"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string","enum":["invalid_params","rate_limited","upstream_unavailable","report_failed"]},"detail":{"type":"string"},"hint":{"type":"string"},"instance":{"type":"string"},"error":{"type":"string","description":"Legacy alias of detail"}}},"Asset":{"type":"object","required":["id","type","name"],"properties":{"id":{"type":"string","description":"TokenLens asset id"},"type":{"type":"string","enum":["token","chain"]},"name":{"type":"string"},"symbol":{"type":"string"}},"additionalProperties":true},"SearchResponse":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}}}},"ReportResponse":{"type":"object","required":["report"],"properties":{"report":{"type":"object","description":"Full report: asset identity, pillar scores, overall opportunity/risk/grade, scenarios, events, strategy. Field-level documentation lives in the repository docs.","additionalProperties":true}}},"LibraryResponse":{"type":"object","required":["library"],"properties":{"library":{"type":"object","properties":{"tokens":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}},"chains":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}},"asOf":{"type":"string","format":"date-time"},"dataMode":{"type":"string"}},"additionalProperties":true}}},"MarketResponse":{"type":"object","required":["regime"],"properties":{"regime":{"type":"object","properties":{"state":{"type":"string","enum":["risk-on","neutral","risk-off"]},"score":{"type":"number"}},"additionalProperties":true},"trending":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"PricesResponse":{"type":"object","required":["quotes"],"properties":{"quotes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"priceUsd":{"type":["number","null"]}},"additionalProperties":true}}}}}}}