# On-chain (Ethereum & BSC) — Zapi reference

> Multi-chain on-chain data for Ethereum and BNB Smart Chain: top token holders per ERC20/BEP20 contract and wallet balances (native + tokens) with USD portfolio value. All amounts are exact raw integers plus decimal strings.

**Base URL:** `https://api.zapi.ink`
**Auth:** Send `x-api-key: YOUR_KEY` header on every request. Get a free key at https://zapi.ink/dashboard/keys.
**Response envelope:** success `{ project, data, timestamp }` (`data` is the payload); errors `{ content, message, errors }`
**Rate limit:** free tier 100 req/min and 600 req/month; paid plans at https://zapi.ink/pricing.

**Related:**
- Detail page: https://zapi.ink/api/finance/onchain
- Category in the catalog: https://zapi.ink/?cat=finance
- Category reference: https://zapi.ink/category/finance/llms.txt
- Concise index: https://zapi.ink/llms.txt
- Full reference: https://zapi.ink/llms-full.txt

---

## On-chain (Ethereum & BSC)

**Category:** finance · **Slug:** `onchain`
**Detail page:** https://zapi.ink/api/finance/onchain

Multi-chain on-chain data for Ethereum and BNB Smart Chain: top token holders per ERC20/BEP20 contract and wallet balances (native + tokens) with USD portfolio value. All amounts are exact raw integers plus decimal strings.

**Tags:** finance, crypto, on-chain, ethereum, bsc, wallet, token

### Token Holders (ETH/BSC)

Top holders of an ERC20 (Ethereum) or BEP20 (BNB Smart Chain) token contract: address, exact raw balance, decimal balance and % of total supply, with paging over the top 100 holders. Also returns token info (name, symbol, decimals, total supply, holder count, USD price). Non-token addresses return 400.

- **Method:** `GET`
- **Endpoint:** `https://api.zapi.ink/v1/finance:onchain/token-holders`
- **Cache TTL:** 300s

**Parameters:**

| Name | Type | Location | Required | Description |
|------|------|----------|----------|-------------|
| `chain` | enum(eth|bsc) | query | yes | Chain: `eth` (Ethereum) or `bsc` (BNB Smart Chain) |
| `contract` | string | query | yes | ERC20/BEP20 token contract address (0x + 40 hex) |
| `page` | number | query | no | Page number. Default 1 |
| `limit` | number | query | no | Holders per page (1-100). Default 50. The top 100 holders are available |

**cURL:**
```bash
curl "https://api.zapi.ink/v1/finance:onchain/token-holders?chain=eth&contract=0xdAC17F958D2ee523a2206206994597C13D831ec7&page=1&limit=50" \
  -H "x-api-key: YOUR_API_KEY"
```

**JavaScript / TypeScript:**
```javascript
const res = await fetch("https://api.zapi.ink/v1/finance:onchain/token-holders?chain=eth&contract=0xdAC17F958D2ee523a2206206994597C13D831ec7&page=1&limit=50", {
  headers: { "x-api-key": process.env.ZAPI_KEY }
});
const data = await res.json();
```

**Python:**
```python
import requests
r = requests.get("https://api.zapi.ink/v1/finance:onchain/token-holders?chain=eth&contract=0xdAC17F958D2ee523a2206206994597C13D831ec7&page=1&limit=50",
  headers={"x-api-key": "YOUR_API_KEY"})
data = r.json()
```

---

### Wallet Balances & Portfolio (ETH/BSC)

Wallet portfolio on Ethereum or BNB Smart Chain: exact native balance (ETH/BNB, wei precision, with block number), all ERC20/BEP20 token balances (raw + decimal), USD price and value per token, and total portfolio value in USD. Tokens sorted by USD value; onlyPriced=true hides unpriced/spam tokens. Empty wallets return 0.

- **Method:** `GET`
- **Endpoint:** `https://api.zapi.ink/v1/finance:onchain/wallet`
- **Cache TTL:** 60s

**Parameters:**

| Name | Type | Location | Required | Description |
|------|------|----------|----------|-------------|
| `chain` | enum(eth|bsc) | query | yes | Chain: `eth` (Ethereum) or `bsc` (BNB Smart Chain) |
| `address` | string | query | yes | Wallet address (0x + 40 hex) |
| `onlyPriced` | boolean | query | no | true = only return tokens that have a USD price (hides most spam tokens). Default false |
| `limit` | number | query | no | Max tokens returned, sorted by USD value (1-1000). Default 100. totalValueUsd always covers all tokens |

**cURL:**
```bash
curl "https://api.zapi.ink/v1/finance:onchain/wallet?chain=eth&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&onlyPriced=false&limit=100" \
  -H "x-api-key: YOUR_API_KEY"
```

**JavaScript / TypeScript:**
```javascript
const res = await fetch("https://api.zapi.ink/v1/finance:onchain/wallet?chain=eth&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&onlyPriced=false&limit=100", {
  headers: { "x-api-key": process.env.ZAPI_KEY }
});
const data = await res.json();
```

**Python:**
```python
import requests
r = requests.get("https://api.zapi.ink/v1/finance:onchain/wallet?chain=eth&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&onlyPriced=false&limit=100",
  headers={"x-api-key": "YOUR_API_KEY"})
data = r.json()
```

---


_Generated: 2026-10-31T06:23:43.149Z_