# ChainList API - Complete Documentation > Free, open-source REST API for blockchain chain information. 2,400+ EVM networks. No API keys required. Base URL: https://chainlistapi.com Source: https://github.com/b3-fun/chain-api Updated: Daily at 00:00 UTC from chainlist.org --- ## Authentication No authentication required for chain data endpoints. Webhook management requires B3 wallet authentication via Bearer token. --- ## Endpoints ### GET /chains/{chainId} Get detailed information about a specific blockchain. **Parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | chainId | number | Yes | The chain ID (e.g., 1 for Ethereum, 137 for Polygon, 8453 for Base) | **Example Request:** ``` curl https://chainlistapi.com/chains/1 ``` **Example Response:** ```json { "chainId": 1, "name": "Ethereum Mainnet", "chain": "ETH", "shortName": "eth", "networkId": 1, "nativeCurrency": { "name": "Ether", "symbol": "ETH", "decimals": 18 }, "rpc": [ { "url": "https://eth.llamarpc.com" }, { "url": "https://rpc.ankr.com/eth" } ], "features": [{ "name": "EIP1559" }], "faucets": [], "infoURL": "https://ethereum.org", "icon": "ethereum", "iconUrl": "https://chainlistapi.com/icons/ethereum.svg", "explorers": [ { "name": "Etherscan", "url": "https://etherscan.io", "standard": "EIP3091" } ], "isTestnet": false, "isDead": false, "tvl": 52000000000, "parent": null } ``` **Response Fields:** | Field | Type | Description | |-------|------|-------------| | chainId | number | Unique chain identifier | | name | string | Full chain name | | chain | string | Short chain identifier | | shortName | string | Abbreviated name | | networkId | number | Network ID (usually same as chainId) | | nativeCurrency | object | Native token: name, symbol, decimals | | rpc | array | RPC endpoint URLs | | features | array | Supported features (e.g., EIP1559) | | faucets | array | Faucet URLs (testnets) | | infoURL | string | Official website | | icon | string | Icon name for /icons/ endpoint | | iconUrl | string | Direct URL to chain icon | | explorers | array | Block explorer URLs | | isTestnet | boolean | Whether chain is a testnet | | isDead | boolean | Whether chain is inactive | | tvl | number | Total Value Locked in USD | | parent | object | Parent chain info (for L2s) | --- ### GET /chains/search Search chains by name, symbol, short name, or chain ID. **Parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | q | string | Yes | Search query | | page | number | No | Page number (default: 1) | | limit | number | No | Results per page (default: 20, max: 100) | **Example Request:** ``` curl "https://chainlistapi.com/chains/search?q=polygon&limit=5" ``` **Example Response:** ```json { "results": [ { "chainId": 137, "name": "Polygon Mainnet", "chain": "Polygon", "shortName": "matic", "nativeCurrency": { "name": "POL", "symbol": "POL", "decimals": 18 }, "rpc": [...], "iconUrl": "https://chainlistapi.com/icons/polygon.svg", "isTestnet": false, "tvl": 1200000000 } ], "total": 12, "page": 1, "perPage": 5 } ``` --- ### GET /chains/all List all chains with optional filtering, sorted by TVL descending. **Parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | page | number | No | Page number (default: 1) | | limit | number | No | Results per page (default: 20, max: 100) | | testnet | boolean | No | Filter by testnet status (true/false) | | isDead | boolean | No | Filter by dead status (true/false) | **Example Requests:** ``` # Get top 10 mainnets by TVL curl "https://chainlistapi.com/chains/all?testnet=false&limit=10" # Get all testnets curl "https://chainlistapi.com/chains/all?testnet=true&limit=50" # Exclude dead chains curl "https://chainlistapi.com/chains/all?isDead=false&limit=20" ``` --- ### GET /icons/{name} Get a chain icon by name. Returns the image file directly. **Parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | name | string | Yes | Icon filename (e.g., ethereum.svg, polygon.svg, base.png) | **Example:** ```html Ethereum Polygon Base Arbitrum ``` 1,800+ icons available. The icon name is in the `icon` field of chain responses. --- ### GET /stats Get API statistics including chain counts and top chains by TVL. **Example Request:** ``` curl https://chainlistapi.com/stats ``` **Example Response:** ```json { "chains": { "total": 2592, "mainnets": 1525, "testnets": 1067, "withIcons": 1816, "withoutIcons": 776, "dead": 245, "alive": 2347 }, "topChainsByTVL": [ { "chainId": 1, "name": "Ethereum Mainnet", "tvl": 52000000000 }, { "chainId": 56, "name": "BNB Smart Chain", "tvl": 5500000000 }, { "chainId": 137, "name": "Polygon Mainnet", "tvl": 1200000000 } ], "lastUpdated": "2026-02-22T00:00:00.000Z" } ``` --- ## Webhook API Requires authentication via B3 wallet. Include Bearer token in Authorization header. ### POST /api/webhooks Create a webhook subscription. **Request Body:** ```json { "webhookUrl": "https://your-server.com/webhook", "events": ["new_chain", "chain_change"] } ``` **Response:** Returns subscription with a signing secret (shown once). ### GET /api/webhooks List your webhook subscriptions. ### DELETE /api/webhooks/{id} Delete a webhook subscription. ### GET /api/webhooks/{id}/deliveries Get delivery history for a webhook. ### POST /api/webhooks/{id}/regenerate-secret Generate a new signing secret. ### Webhook Payload Format ```json { "event": "new_chain", "timestamp": "2026-02-22T12:00:00.000Z", "data": { "chainId": 12345, "name": "Example Chain" } } ``` Each delivery includes an `X-Webhook-Signature` header (HMAC-SHA256). ### Verifying Signatures ```javascript const crypto = require('crypto'); function verifyWebhook(payload, signature, secret) { const expected = 'sha256=' + crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); return signature === expected; } ``` --- ## Code Examples ### JavaScript / Node.js ```javascript // Fetch a chain const res = await fetch('https://chainlistapi.com/chains/1'); const ethereum = await res.json(); console.log(ethereum.name); // "Ethereum Mainnet" console.log(ethereum.chainId); // 1 console.log(ethereum.rpc[0].url); // First RPC URL // Search chains const search = await fetch('https://chainlistapi.com/chains/search?q=base'); const { results } = await search.json(); // List mainnets sorted by TVL const all = await fetch('https://chainlistapi.com/chains/all?testnet=false&limit=50'); const { results: chains } = await all.json(); ``` ### Python ```python import requests def get_chain(chain_id): response = requests.get(f'https://chainlistapi.com/chains/{chain_id}') return response.json() ethereum = get_chain(1) print(f"Chain: {ethereum['name']}") print(f"Symbol: {ethereum['nativeCurrency']['symbol']}") ``` ### Adding to MetaMask ```javascript async function addNetwork(chainId) { const res = await fetch(`https://chainlistapi.com/chains/${chainId}`); const chain = await res.json(); await window.ethereum.request({ method: 'wallet_addEthereumChain', params: [{ chainId: `0x${chainId.toString(16)}`, chainName: chain.name, nativeCurrency: chain.nativeCurrency, rpcUrls: chain.rpc.map(r => r.url), blockExplorerUrls: chain.explorers?.map(e => e.url) }] }); } ``` --- ## Common Chain IDs | Chain ID | Name | Symbol | |----------|------|--------| | 1 | Ethereum Mainnet | ETH | | 10 | OP Mainnet | ETH | | 56 | BNB Smart Chain | BNB | | 137 | Polygon | POL | | 250 | Fantom | FTM | | 324 | zkSync Era | ETH | | 8333 | B3 | ETH | | 8453 | Base | ETH | | 42161 | Arbitrum One | ETH | | 43114 | Avalanche C-Chain | AVAX | | 59144 | Linea | ETH | | 534352 | Scroll | ETH | --- ## Rate Limits No strict rate limits. Please cache responses when possible. Data updates daily at 00:00 UTC. ## CORS All endpoints support CORS from any origin. No API keys required. ## Source Code Open source at https://github.com/b3-fun/chain-api Built by B3 (https://b3.fun) - The open gaming layer for the Superchain.