Token API FAQ

Get fast answers to easily integrate and scale with The Graph’s high-performance Token API.

General

What blockchains does the Token API support?

Currently, the Token API supports Ethereum, Binance Smart Chain (BSC), Polygon, Optimism, Base, Unichain, and Arbitrum One.

How do I authenticate requests to the Token API, and why doesn’t my API key from The Graph Market work?

Authentication is managed via API tokens obtained through The Graph Market⁠. If you’re experiencing issues, make sure you’re using the API Token generated from the API key, not the API key itself. An API token can be found on The Graph Market dashboard next to each API key. JWT tokens issued by Pinax⁠, a core developer of The Graph, are also supported.

How current is the data provided by the API relative to the blockchain?

The API provides data up to the latest finalized block.

How do I retrieve token prices?

By default, token prices are returned with token-related responses, including token balances, token transfers, token metadata, and token holders. Historical prices are available with the Open-High-Low-Close (OHLC) endpoints.

Does the Token API support historical token data?

The Token API supports historical token balances with the /historical/balances/evm/{address} endpoint. You can query historical price data by pool at /ohlc/pools/evm/{pool} and by contract at /ohlc/prices/evm/{contract}.

What exchanges does the Token API use for token prices?

The Token API currently tracks prices on Uniswap v2 and Uniswap v3, with plans to support additional exchanges in the future.

Does the Token API provide a client SDK?

While a client SDK is not currently available, please share feedback on any SDKs or integrations you would like to see on Discord⁠.

Are there plans to support additional blockchains in the future?

Yes, more blockchains will be supported in the future. Please share feedback on desired chains on Discord⁠.

Are there plans to offer data closer to the chain head?

Yes, improvements to provide data closer to the chain head are planned. Feedback is welcome on Discord⁠.

Are there plans to support additional use cases such as NFTs?

Support for NFT endpoints is coming soon. The Graph ecosystem is actively determining the roadmap for additional use cases. Please provide feedback on specific features you would like prioritized on Discord⁠.

MCP / LLM / AI Topics

Is there a time limit for LLM queries?

Yes. The maximum time limit for LLM queries is 10 seconds.

Is there a known list of LLMs that work with the API?

Yes, Cline, Cursor, and Claude Desktop integrate successfully with The Graph’s Token API + MCP server.

Beyond that, whether an LLM “works” depends on whether it supports the MCP protocol directly (or has a compatible plugin/adapter).

Where can I find the MCP client?

You can find the code for the MCP client in The Graph’s repo⁠.

Advanced Topics

I’m getting 403/401 errors. What’s wrong?

Check that you included the Authorization: Bearer <jwt> header with the correct, non-expired token. Common issues include using the API key instead of generating a new JWT, forgetting the “Bearer” prefix, using an incorrect token, or omitting the header entirely. Ensure you copied the JWT exactly as provided by The Graph Market.

Are there rate limits or usage costs?

During Beta, the Token API is free for authorized developers. While specific rate limits aren’t documented, reasonable throttling exists to prevent abuse. High request volumes may trigger HTTP 429 errors. Monitor official announcements for future pricing changes after Beta.

How do I specify a network?

You can query available networks with this link⁠. A full list of the exact network IDs accepted by The Graph can be found on The Graph’s Networks. Use the optional network_id parameter (e.g., mainnet, bsc, base, arbitrum-one, optimism, matic, unichain) to target a specific chain. Without this parameter, the API defaults to Ethereum mainnet.

Why do I only see 10 results? How can I get more data?

Endpoints cap output at 10 items by default. Use pagination parameters: limit and page (1-indexed) to return more results. For example, set limit=50 to get 50 results, and increment page for subsequent batches (e.g., page=2 for items 51-100).

How do I fetch older transfer history?

The Transfers endpoint defaults to 30 days of history. To retrieve older events, increase the age parameter up to 180 days maximum (e.g., age=180 for 6 months of transfers). Transfers older than 180 days cannot be fetched in a single call.

What does an empty "data": [] array mean?

An empty data array means no records were found matching the query – not an error. This occurs when querying wallets with no tokens/transfers or token contracts with no holders. Verify you’ve used the correct address and parameters. An invalid address format will trigger a 4xx error.

Why is the JSON response wrapped in a "data" array?

All Token API responses consistently wrap results in a top-level data array, even for single items. This uniform design handles the common case where addresses have multiple balances or transfers. When parsing, be sure to index into the data array (e.g., const results = response.data).

Why are token amounts returned as strings?

Large numeric values (like token amounts or supplies) are returned as strings to avoid precision loss, as they often exceed JavaScript’s safe integer range. Convert these to big number types for arithmetic operations. Fields like decimals are provided as normal numbers to help derive human-readable values.

What format should addresses be in?

The API accepts 40-character hex addresses with or without the 0x prefix. The endpoint is case-insensitive, so both lower and uppercase hex characters work. Ensure addresses are exactly 40 hex digits (20 bytes) if you remove the prefix. For contract queries, use the token’s contract address; for balance/transfer queries, use the wallet address.

Do I need special headers besides authentication?

While recommended, Accept: application/json isn’t strictly required as the API returns JSON by default. The critical header is Authorization: Bearer <token>. Ensure you make a GET request to the correct URL without trailing slashes or path typos (e.g., use /balances/evm/{address} not /balance).

MCP integration with Claude/Cline/Cursor shows errors like “ENOENT” or “Server disconnected”. How do I fix this?

For “ENOENT” errors, ensure Node.js 18+ is installed and the path to npx/bunx is correct (consider using full paths in config). “Server disconnected” usually indicates authentication or connectivity issues – verify your ACCESS_TOKEN is set correctly and your network allows access to https://token-api.thegraph.com/sse.

Is the Token API part of The Graph’s GraphQL service?

No, the Token API is a separate RESTful service. Unlike traditional subgraphs, it provides ready-to-use REST endpoints (HTTP GET) for common token data. You don’t need to write GraphQL queries or deploy subgraphs. Under the hood, it uses The Graph’s infrastructure and MCP with AI for enrichment, but you simply interact with REST endpoints.

Do I need to use MCP or tools like Claude, Cline, or Cursor?

No, these are optional. MCP is an advanced feature allowing AI assistants to interface with the API via streaming. For standard usage, simply call the REST endpoints with any HTTP client using your JWT. Claude Desktop, Cline bot, and Cursor IDE integrations are provided for convenience but aren’t required.