TokenLens for developers and agents

REST API

Public, read-only, no authentication. Responses are JSON. A machine-readable description lives at /openapi.json. Please keep request rates modest: upstream data comes from free-tier providers.

  • GET /api/search?q=<query>Resolve tokens and chains to TokenLens ids
  • GET /api/report?type=token|chain&id=<id>Full analysis report for one asset
  • GET /api/libraryTop tokens by market cap and chains by TVL
  • GET /api/marketGlobal market regime snapshot
  • GET /api/prices?ids=<id,id>Quotes for known asset ids

Versioning, rate limits, and errors

Versioning: the current API version is 1 and every response carries an 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 announced here and in the repository changelog. Additive optional fields do not bump the version.

Rate limits: 60 requests per client per 60 seconds. Responses carry RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and RateLimit-Policy headers; an exhausted window returns 429 with Retry-After. Self-throttle from the headers rather than retrying blindly.

Errors: all 4xx and 5xx responses are RFC 9457 application/problem+json with a stable machine-readable code (invalid_params, rate_limited, upstream_unavailable, report_failed), a human-readable detail, and a hint describing how to recover. The schema is in /openapi.json.

MCP server (for AI agents)

TokenLens doubles as a Model Context Protocol server over Streamable HTTP at /api/mcp. Add it to Claude or any MCP client as a custom connector with that URL. The handshake manifest is published at /.well-known/mcp. Resolve asset ids with search_assets before calling the other tools.

  • search_assetsResolve a free-text query to TokenLens asset ids (tokens and chains).
  • generate_reportFull analysis report for one asset: scores, pillars, risk grade, strategy.
  • get_scenariosBear, base, and bull trajectory scenarios for an asset across three horizons.
  • compare_assetsScore matrix and pillar comparison for 2 to 4 assets.
  • get_market_regimeGlobal risk-on, neutral, or risk-off market regime with components.

Six additional personal tools (watchlist and portfolio) exist but require the owner's bearer token.

Machine-readable surfaces

Scoring definitions are on the methodology page. TokenLens is decision support for personal use, not financial advice.