# chain-data 🔗

**Live multi-chain on-chain data, aggregated in ONE call — built for AI agents.**

Give it a wallet and get its whole **portfolio** across Ethereum, Base, Polygon, Arbitrum and Optimism — native balances + top ERC-20 holdings, each priced in USD — in a single response. Plus token/contract facts, live gas and prices. All read straight from **public RPCs** and **DefiLlama**; no API key, no node.

Available as an **MCP server** (free) and a **pay-per-call x402 API** (`$0.10` USDC on Base, no sign-up).

---

## Why

An agent that wants a wallet's multi-chain net worth would otherwise have to:
fan out N JSON-RPC calls to N chains → ABI-encode `balanceOf`/`decimals`/`symbol` → batch them → join against a price feed → repeat per chain. `chain-data` does all of that server-side and returns one fresh JSON object per call. That convenience on **live** data is the point — agents pay for the aggregation, not for a static answer they could cache.

## Tools (MCP)

| Tool | What it does |
|---|---|
| `wallet_portfolio` | Native + ERC-20 balances with live USD value, across 5 chains, in one call |
| `token_info` | symbol, name, decimals, total supply, is-contract, EIP-1967 proxy + implementation, price |
| `gas_prices` | base fee / gas price / priority fee / latest block, per chain or all at once |
| `token_price` | live USD price by `chain`+`address`, CoinGecko id, or symbol |

## Use as an MCP server (free)

```json
{
  "mcpServers": {
    "chain-data": { "command": "npx", "args": ["-y", "chain-data-mcp"] }
  }
}
```

Or over HTTP: `POST https://chain-data.vercel.app/mcp`.

## Free HTTP API

```
GET /portfolio?wallet=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
GET /token?chain=base&address=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
GET /gas
GET /price?chain=ethereum&address=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2
```

Rate-limited to 30 requests/hour/IP.

## Pay-per-call (x402)

The `/pro/*` routes are gated by [x402](https://x402.org). Your agent pays **$0.10 USDC** per call automatically — no sign-up, no API key. Settles on-chain (Base) to the operator wallet. No rate limit.

```
GET /pro/portfolio?wallet=0x...
GET /pro/token?chain=base&address=0x...
GET /pro/gas
GET /pro/price?chain=ethereum&address=0x...
```

## Supported chains

Ethereum · Base · Polygon · Arbitrum One · OP Mainnet — all via public, key-free RPCs with automatic failover.

## Data sources

- **Balances / token info / gas**: public JSON-RPC endpoints (`mainnet.base.org`, `eth.llamarpc.com`, `polygon-rpc.com`, …).
- **Prices**: [DefiLlama](https://defillama.com) coins API (free) / CoinGecko ids.

No credentials are stored or required. The server holds **no private key** — `payTo` is a public receiving address only.

## Local dev

```bash
npm install
npm run build
npm run test:engine     # live smoke test against real RPCs
npm run dev:http        # local HTTP server on :8080 (payments off unless X402_* set)
npm run dev:mcp         # local stdio MCP server
```

## License

MIT