Skip to content

Update faq.mdx #1015

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Aug 5, 2025
Merged

Update faq.mdx #1015

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6d6cf00
Update faq.mdx
UrsaPolarisRecords Aug 1, 2025
46ee373
Update faq.mdx
UrsaPolarisRecords Aug 1, 2025
622886a
Update website/src/pages/en/token-api/faq.mdx
benface Aug 5, 2025
f376bd5
Update website/src/pages/en/token-api/faq.mdx
benface Aug 5, 2025
a3349cd
Update website/src/pages/en/token-api/faq.mdx
benface Aug 5, 2025
4e57fc6
Update website/src/pages/en/token-api/faq.mdx
benface Aug 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 31 additions & 25 deletions website/src/pages/en/token-api/faq.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Get fast answers to easily integrate and scale with The Graph's high-performance

### Which blockchains are supported by the Token API?

Currently, the Token API supports Ethereum, BNB Smart Chain (BSC), Polygon, Optimism, Base, Unichain, Avalanche, Solana, and Arbitrum One. A full list of supported networks can be found under the Token API column [here](/supported-networks/).
Currently, the Token API supports Ethereum, BNB Smart Chain (BSC), Polygon, Optimism, Base, Unichain, Avalanche, Arbitrum One, and Solana. A full list of supported networks can be found under the Token API column [here](/supported-networks/).

### Does the Token API support NFTs?

Expand All @@ -24,32 +24,28 @@ Authentication is managed via API tokens obtained through [The Graph Market](htt

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

The API provides data up to the latest finalized block.
The API provides data up to the latest finalized block. This time varies depending on the blockchain. Improvements to provide data closer to the chain head are planned, and feedback is welcome on [Discord](https://discord.gg/graphprotocol).

### 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.
Token prices are available with the Open-High-Low-Close (OHLC) endpoints. For a given time period, `"open"` represents the price at the start of the time period, `"high"` represents the highest price during the time period, `"low"` represents the lowest price, and `"close"` represents the price at the end of the time period.

### 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}`.
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}`. Historical balances have a similar OHLC format, but return token balances instead of prices.

### What exchanges does the Token API use for token prices?

The Token API currently tracks prices on Uniswap v2, v3, and v4, along with Jupiter, Raydium, and Pump.fun on Solana, with plans to support additional exchanges in the future.

### Does the Token API provide a client SDK?
### Does the Token API provide a client SDK or client library?

While a client SDK is not currently available, please share feedback on any SDKs or integrations you would like to see on [Discord](https://discord.gg/graphprotocol).
While an official client SDK is not currently available, please share feedback on any SDKs or integrations you would like to see on [Discord](https://discord.gg/graphprotocol). Community contributions are welcome to use the [OpenAPI document](https://token-api.thegraph.com/openapi) to build and share their own client libraries.

### 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](https://discord.gg/graphprotocol).

### 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](https://discord.gg/graphprotocol).

### Are there plans to support additional use cases?

The Graph ecosystem is actively determining the [roadmap](https://thegraph.com/blog/token-api-the-graph/) for additional use cases. Please provide feedback on specific features you would like prioritized on [Discord](https://discord.gg/graphprotocol).
Expand All @@ -58,7 +54,7 @@ The Graph ecosystem is actively determining the [roadmap](https://thegraph.com/b

### Is there a time limit for LLM queries?

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

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

Expand All @@ -70,11 +66,23 @@ Beyond that, whether an LLM "works" depends on whether it supports the MCP proto

You can find the code for the MCP client in [The Graph's repo](https://github.com/graphprotocol/mcp-client).

### 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.mcp.thegraph.com/sse`.

### 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.

## Advanced Topics

### I keep seeing a smart contract with the address `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`. What is this address?
### I keep seeing a smart contract with addresses like `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` and `0x000000000000000000000000000000000000`. What is this?

The address `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` is a sentinel (placeholder) address used to represent native tokens in EVM smart contracts. Since native tokens (ETH, BNB, AVAX, etc.) exist at the protocol level rather than as smart contracts, DeFi protocols need a placeholder address when their code expects contract addresses for all tokens. This address represents the native token of whatever chain you're on: ETH on Ethereum and its L2s (Base, Arbitrum, Optimism), BNB on BSC, AVAX on Avalanche, and so forth.

The address `0x0000000000000000000000000000000000000000` was introduced in Uniswap v4 for the same purpose.

The address 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee is a sentinel (placeholder) address used to represent native tokens in EVM smart contracts. Since native tokens (ETH, BNB, AVAX, etc.) exist at the protocol level rather than as smart contracts, DeFi protocols need a placeholder address when their code expects contract addresses for all tokens. This address represents the native token of whatever chain you're on: ETH on Ethereum and its L2s (Base, Arbitrum, Optimism), BNB on BSC, AVAX on Avalanche, FTM on Fantom, and so forth. The repetitive pattern makes it obvious that the address is artificial; it's not a real account anyone controls, just an arbitrarily chosen low-entropy address that developers agreed to use.
Because these addresses have an obvious repetitive pattern, they are clearly not randomly generated, as are other blockchain addresses. These accounts are not real accounts, just arbitrarily chosen low-entropy addresses that developers agreed to use.

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

Expand All @@ -86,20 +94,24 @@ Networks that are currently or temporarily unavailable on a given endpoint will

### Are there rate limits or usage costs?

During Beta, the Token API is free for authorized developers. There are no specific rate limits, but reasonable throttling exists to prevent abuse. High request volumes may trigger HTTP 429 errors. Monitor official announcements for future pricing changes after Beta.
During Beta, the Token API has a generous allowance of free usage. There are no specific rate limits, but reasonable throttling exists to prevent abuse. High request volumes may trigger HTTP 429 errors. Monitor official announcements for future pricing changes after Beta.

### What do I do if I notice data inconsistencies in the data returned by the Token API?

If you notice data inconsistencies, please report the issue on our [Discord](https://discord.gg/graphprotocol). Identifying edge cases can help make sure all data is accurate and up-to-date.

### How do I specify a network?

You can query available networks with [this link](https://token-api.thegraph.com/networks). A full list of the exact network IDs accepted by The Graph can be found [here](/supported-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.
You can query which networks are available with [this endpoint](https://token-api.thegraph.com/networks). Take note that the network IDs differ between the Token API and Subgraphs. For EVM networks, use EVM endpoints with the optional `network_id` parameter (e.g., `mainnet`, `bsc`, `base`, `arbitrum-one`, `optimism`, `polygon`, `unichain`) to target a specific chain. Without this parameter, the API defaults to Ethereum mainnet.

To query Solana, use the SVM endpoints.

### 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).

It is currently possible for the total number of pages to be inexact. This is because the backend provides only an approximation of the number of records in order to improve response time. To avoid getting confused by this approximation, make sure to continue fetching next pages until there is no more data, or the endpoint returns an error.

### 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.
Expand All @@ -114,24 +126,18 @@ All Token API responses consistently wrap results in a top-level `data` array, e

### 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.
Large numeric values (like token amounts or supply) 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.
For EVM addresses, the API accepts hex addresses with either 42 or 40 characters, with or without the `0x` prefix. The endpoint is case-insensitive, so both lower and uppercase hex characters work. Ensure EVM addresses are exactly 42 characters, or 40 if you remove the prefix. For contract queries, use the token's contract address. For balance/transfer queries, use the wallet address.

SVM addresses are base58-encoded strings that are typically 32-44 characters long. They contain a mix of uppercase letters, lowercase letters, and numbers. Unlike Ethereum addresses which are hexadecimal and start with "0x", Solana addresses don't have a consistent prefix pattern.

### 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.mcp.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.