# Account Endpoints
Account endpoints provide access to address-specific data including balances, transaction history, token transfers, and more.
## Table of Contents
- [Get ETH Balance](#get-eth-balance)
- [Get Multi-Address Balance](#get-multi-address-balance)
- [Get Transaction List](#get-transaction-list)
- [Get Internal Transactions](#get-internal-transactions)
- [Get ERC20 Token Transfers](#get-erc20-token-transfers)
- [Get ERC721 Token Transfers](#get-erc721-token-transfers)
- [Get ERC1155 Token Transfers](#get-erc1155-token-transfers)
- [Get Mined Blocks](#get-mined-blocks)
- [Get Beacon Chain Withdrawals](#get-beacon-chain-withdrawals)
---
## Get ETH Balance
Returns the ETH balance for a single address.
### MCP Tool
`check-balance`
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID (e.g., 1 for Ethereum, 137 for Polygon) |
| module | Yes | string | Set to `account` |
| action | Yes | string | Set to `balance` |
| address | Yes | string | Ethereum address (0x format) |
| tag | No | string | Block parameter (latest, earliest, pending, or block number) |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=account&action=balance&address=0x742d35Cc6634C0532925a3b844Bc454e4438f44e&tag=latest&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": "40891626854930000000000"
}
```
### Notes
- Balance is returned in **Wei** (1 ETH = 10^18 Wei)
- To convert to ETH: divide by 1,000,000,000,000,000,000
- The `tag` parameter defaults to `latest`
- For historical balances, use a specific block number as the tag
---
## Get Multi-Address Balance
Get ETH balance for multiple addresses in a single call (up to 20 addresses).
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `account` |
| action | Yes | string | Set to `balancemulti` |
| address | Yes | string | Comma-separated list of addresses (max 20) |
| tag | No | string | Block parameter (default: latest) |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=account&action=balancemulti&address=0x742d35Cc6634C0532925a3b844Bc454e4438f44e,0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae&tag=latest&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"account": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"balance": "40891626854930000000000"
},
{
"account": "0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae",
"balance": "332567136222827062478"
}
]
}
```
### Notes
- Maximum of **20 addresses** per request
- Balances are returned in Wei
- Addresses are returned in lowercase in the response
---
## Get Transaction List
Get a list of transactions for an address.
### MCP Tool
`get-transactions`
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `account` |
| action | Yes | string | Set to `txlist` |
| address | Yes | string | Ethereum address |
| startblock | No | number | Starting block number (default: 0) |
| endblock | No | number | Ending block number (default: 99999999) |
| page | No | number | Page number (default: 1) |
| offset | No | number | Number of transactions per page (max 10000, default: 10) |
| sort | No | string | Sort order: `asc` or `desc` (default: asc) |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=account&action=txlist&address=0x742d35Cc6634C0532925a3b844Bc454e4438f44e&startblock=0&endblock=99999999&page=1&offset=10&sort=desc&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"blockNumber": "18500000",
"timeStamp": "1698765432",
"hash": "0xabc123...",
"nonce": "123",
"blockHash": "0xdef456...",
"transactionIndex": "5",
"from": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"to": "0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae",
"value": "1000000000000000000",
"gas": "21000",
"gasPrice": "20000000000",
"isError": "0",
"txreceipt_status": "1",
"input": "0x",
"contractAddress": "",
"cumulativeGasUsed": "150000",
"gasUsed": "21000",
"confirmations": "12345"
}
]
}
```
### Notes
- Maximum offset is **10,000** records per request
- Use pagination for addresses with many transactions
- `isError`: "0" = success, "1" = error
- `txreceipt_status`: "1" = success, "0" = failed (post-Byzantium fork)
- Values are in Wei
- `timeStamp` is Unix timestamp
---
## Get Internal Transactions
Get a list of internal transactions (contract-to-contract transfers).
### MCP Tool
`get-internal-transactions`
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `account` |
| action | Yes | string | Set to `txlistinternal` |
| address | Yes | string | Ethereum address |
| startblock | No | number | Starting block number |
| endblock | No | number | Ending block number |
| page | No | number | Page number (default: 1) |
| offset | No | number | Records per page (max 10000) |
| sort | No | string | Sort order: `asc` or `desc` |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=account&action=txlistinternal&address=0x742d35Cc6634C0532925a3b844Bc454e4438f44e&startblock=0&endblock=99999999&page=1&offset=10&sort=desc&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"blockNumber": "18500000",
"timeStamp": "1698765432",
"hash": "0xabc123...",
"from": "0x1234567890123456789012345678901234567890",
"to": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"value": "500000000000000000",
"contractAddress": "",
"input": "",
"type": "call",
"gas": "100000",
"gasUsed": "50000",
"traceId": "0",
"isError": "0",
"errCode": ""
}
]
}
```
### Notes
- Internal transactions are ETH transfers that occur within contract execution
- Common in DeFi protocols, token swaps, and complex smart contracts
- `type` can be: `call`, `create`, `suicide`, `delegatecall`, `staticcall`
- `traceId` indicates the position in the call stack
---
## Get ERC20 Token Transfers
Get ERC20 token transfer events for an address.
### MCP Tool
`get-token-transfers`
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `account` |
| action | Yes | string | Set to `tokentx` |
| address | Yes | string | Ethereum address |
| contractaddress | No | string | Token contract address (filter by specific token) |
| startblock | No | number | Starting block number |
| endblock | No | number | Ending block number |
| page | No | number | Page number |
| offset | No | number | Records per page (max 10000) |
| sort | No | string | Sort order: `asc` or `desc` |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=account&action=tokentx&address=0x742d35Cc6634C0532925a3b844Bc454e4438f44e&page=1&offset=10&sort=desc&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"blockNumber": "18500000",
"timeStamp": "1698765432",
"hash": "0xabc123...",
"nonce": "123",
"blockHash": "0xdef456...",
"from": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"contractAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"to": "0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae",
"value": "1000000000",
"tokenName": "USD Coin",
"tokenSymbol": "USDC",
"tokenDecimal": "6",
"transactionIndex": "5",
"gas": "100000",
"gasPrice": "20000000000",
"gasUsed": "65000",
"cumulativeGasUsed": "200000",
"input": "deprecated",
"confirmations": "12345"
}
]
}
```
### Notes
- Returns ERC20 `Transfer` events
- `value` is in the token's smallest unit (use `tokenDecimal` to convert)
- Filter by specific token using `contractaddress` parameter
- Popular tokens: USDC, USDT, DAI, WETH, etc.
---
## Get ERC721 Token Transfers
Get ERC721 (NFT) token transfer events for an address.
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `account` |
| action | Yes | string | Set to `tokennfttx` |
| address | Yes | string | Ethereum address |
| contractaddress | No | string | NFT contract address (filter by collection) |
| startblock | No | number | Starting block number |
| endblock | No | number | Ending block number |
| page | No | number | Page number |
| offset | No | number | Records per page (max 10000) |
| sort | No | string | Sort order: `asc` or `desc` |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=account&action=tokennfttx&address=0x742d35Cc6634C0532925a3b844Bc454e4438f44e&page=1&offset=10&sort=desc&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"blockNumber": "18500000",
"timeStamp": "1698765432",
"hash": "0xabc123...",
"nonce": "123",
"blockHash": "0xdef456...",
"from": "0x0000000000000000000000000000000000000000",
"contractAddress": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
"to": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"tokenID": "1234",
"tokenName": "BoredApeYachtClub",
"tokenSymbol": "BAYC",
"tokenDecimal": "0",
"transactionIndex": "10",
"gas": "150000",
"gasPrice": "50000000000",
"gasUsed": "120000",
"cumulativeGasUsed": "500000",
"input": "deprecated",
"confirmations": "5000"
}
]
}
```
### Notes
- Returns ERC721 `Transfer` events
- `tokenID` identifies the specific NFT
- `from` address of `0x0...0` indicates minting
- `to` address of `0x0...0` indicates burning
- `tokenDecimal` is always "0" for ERC721
---
## Get ERC1155 Token Transfers
Get ERC1155 (multi-token) transfer events for an address.
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `account` |
| action | Yes | string | Set to `token1155tx` |
| address | Yes | string | Ethereum address |
| contractaddress | No | string | ERC1155 contract address |
| startblock | No | number | Starting block number |
| endblock | No | number | Ending block number |
| page | No | number | Page number |
| offset | No | number | Records per page (max 10000) |
| sort | No | string | Sort order: `asc` or `desc` |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=account&action=token1155tx&address=0x742d35Cc6634C0532925a3b844Bc454e4438f44e&page=1&offset=10&sort=desc&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"blockNumber": "18500000",
"timeStamp": "1698765432",
"hash": "0xabc123...",
"nonce": "123",
"blockHash": "0xdef456...",
"from": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"contractAddress": "0x495f947276749ce646f68ac8c248420045cb7b5e",
"to": "0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae",
"tokenID": "12345678901234567890",
"tokenValue": "5",
"tokenName": "OpenSea Collections",
"tokenSymbol": "OPENSTORE",
"transactionIndex": "15",
"gas": "200000",
"gasPrice": "30000000000",
"gasUsed": "180000",
"cumulativeGasUsed": "600000",
"input": "deprecated",
"confirmations": "3000"
}
]
}
```
### Notes
- ERC1155 supports both fungible and non-fungible tokens
- `tokenValue` indicates the quantity transferred
- Single contract can contain multiple token types
- Commonly used for gaming items and multi-edition NFTs
---
## Get Mined Blocks
Get list of blocks mined by an address.
### MCP Tool
`get-mined-blocks`
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `account` |
| action | Yes | string | Set to `getminedblocks` |
| address | Yes | string | Miner address |
| blocktype | No | string | `blocks` (default) or `uncles` |
| page | No | number | Page number |
| offset | No | number | Records per page (max 10000) |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=account&action=getminedblocks&address=0xea674fdde714fd979de3edf0f56aa9716b898ec8&blocktype=blocks&page=1&offset=10&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"blockNumber": "18500000",
"timeStamp": "1698765432",
"blockReward": "2000000000000000000"
},
{
"blockNumber": "18499500",
"timeStamp": "1698759432",
"blockReward": "2050000000000000000"
}
]
}
```
### Notes
- Only applicable to Proof of Work chains (pre-merge Ethereum, etc.)
- Block rewards are in Wei
- `blocktype=uncles` returns uncle blocks (Ethereum PoW only)
- Not available on Proof of Stake chains
---
## Get Beacon Chain Withdrawals
Get beacon chain withdrawal transactions for an address (Ethereum post-merge).
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID (1 for Ethereum mainnet) |
| module | Yes | string | Set to `account` |
| action | Yes | string | Set to `txsBeaconWithdrawal` |
| address | Yes | string | Ethereum address |
| startblock | No | number | Starting block number |
| endblock | No | number | Ending block number |
| page | No | number | Page number |
| offset | No | number | Records per page (max 10000) |
| sort | No | string | Sort order: `asc` or `desc` |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=account&action=txsBeaconWithdrawal&address=0x742d35Cc6634C0532925a3b844Bc454e4438f44e&startblock=0&endblock=99999999&page=1&offset=10&sort=desc&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"withdrawalIndex": "12345",
"validatorIndex": "67890",
"address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"amount": "32000000000",
"blockNumber": "18500000",
"timestamp": "1698765432"
}
]
}
```
### Notes
- Only available on Ethereum mainnet (chainid=1) post-merge
- Returns validator withdrawal transactions
- `amount` is in Gwei (1 ETH = 1,000,000,000 Gwei)
- Related to Ethereum 2.0 staking withdrawals
---
## Common Response Codes
| Status | Message | Description |
|--------|---------|-------------|
| 1 | OK | Request successful |
| 0 | No transactions found | Address has no transactions |
| 0 | Invalid address format | Malformed address parameter |
| 0 | Error! Missing or invalid API key | API key issue |
## Rate Limits
- Free tier: **5 calls/second**
- Offset limit: Maximum **10,000** records per request
- Use pagination for larger datasets
## See Also
- [Block Endpoints](./blocks-endpoints.md)
- [Token Endpoints](./tokens-endpoints.md)
- [Network Support](./NETWORK_SUPPORT.md)
