# Base Chain Data API

> Read Base Mainnet blocks, receipts, logs, balances, token metadata, and contract bytecode from the public JSON-RPC endpoint.

Each POST has a fixed USDC price on Base, paid with the x402 exact scheme. The request is validated first, and payment settles only after a successful (2xx) result. Failed calls are not charged.

1. POST JSON matching the requestBody. Invalid input returns 400 with no payment challenge.
2. A valid unpaid call returns 402 with the exact amount and payTo.
3. Pay and retry with payment-signature. Payment settles only if the operation returns 2xx. A 4xx/5xx is not charged.

- Product: https://www.brainiac.software/api/chain-data
- Docs: https://www.brainiac.software/api/chain-data/docs
- OpenAPI: https://www.brainiac.software/api/chain-data/openapi.json
- Contact: support@brainiac.software (https://www.brainiac.software/contact)

## Operations

### POST /api/v1/chain-data/network-info

$0.01 USDC. Retrieve Base Mainnet chain ID and network information from the public JSON-RPC endpoint.

Inputs: none

Docs: https://www.brainiac.software/api/chain-data/docs#chain-data-network-info

Example request:

```json
{}
```

Example response:

```json
undefined
```

### POST /api/v1/chain-data/block/latest

$0.02 USDC. Retrieve the latest block information from Base Mainnet using the public JSON-RPC endpoint.

Inputs: none

Docs: https://www.brainiac.software/api/chain-data/docs#chain-data-block-latest

Example request:

```json
{}
```

Example response:

```json
undefined
```

### POST /api/v1/chain-data/block/get

$0.02 USDC. Retrieve a specific block by number or hash from Base Mainnet. Supports optional full transaction details.

Inputs: blockNumber?, blockHash?, fullTransactions?

Docs: https://www.brainiac.software/api/chain-data/docs#chain-data-block-get

Example request:

```json
{
  "blockNumber": 12345678,
  "fullTransactions": false
}
```

Example response:

```json
undefined
```

### POST /api/v1/chain-data/block/transactions

$0.03 USDC. Retrieve all transactions included in a specific block by number or hash from Base Mainnet.

Inputs: blockNumber?, blockHash?

Docs: https://www.brainiac.software/api/chain-data/docs#chain-data-block-transactions

Example request:

```json
{
  "blockNumber": 12345678
}
```

Example response:

```json
undefined
```

### POST /api/v1/chain-data/transaction/receipt

$0.02 USDC. Retrieve the receipt and status for a specific transaction on Base Mainnet, including logs and gas used.

Inputs: txHash

Docs: https://www.brainiac.software/api/chain-data/docs#chain-data-transaction-receipt

Example request:

```json
{
  "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}
```

Example response:

```json
undefined
```

### POST /api/v1/chain-data/logs/search

$0.05 USDC. Search for contract event logs on Base Mainnet with filters for block range, address, and topics. Limited to 1000 results per request.

Inputs: fromBlock?, toBlock?, blockHash?, address?, topics?, limit?

Docs: https://www.brainiac.software/api/chain-data/docs#chain-data-logs-search

Example request:

```json
{
  "fromBlock": 12340000,
  "toBlock": 12345000,
  "address": "0x1234567890123456789012345678901234567890",
  "topics": [
    [
      "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
    ]
  ],
  "limit": 100
}
```

Example response:

```json
undefined
```

### POST /api/v1/chain-data/contract/code

$0.02 USDC. Retrieve the bytecode of a smart contract on Base Mainnet at a specific address and optional block number.

Inputs: address, blockNumber?

Docs: https://www.brainiac.software/api/chain-data/docs#chain-data-contract-code

Example request:

```json
{
  "address": "0x1234567890123456789012345678901234567890"
}
```

Example response:

```json
undefined
```

### POST /api/v1/chain-data/contract/read

$0.02 USDC. Execute a read-only call to a smart contract on Base Mainnet using eth_call. Returns the result without submitting a transaction.

Inputs: address, data, blockNumber?

Docs: https://www.brainiac.software/api/chain-data/docs#chain-data-contract-read

Example request:

```json
{
  "address": "0x1234567890123456789012345678901234567890",
  "data": "0x12345678"
}
```

Example response:

```json
undefined
```

### POST /api/v1/chain-data/gas/estimate

$0.02 USDC. Estimate the gas required for a transaction on Base Mainnet using eth_estimateGas.

Inputs: from?, to?, value?, data?

Docs: https://www.brainiac.software/api/chain-data/docs#chain-data-gas-estimate

Example request:

```json
{
  "from": "0x1234567890123456789012345678901234567890",
  "to": "0x1234567890123456789012345678901234567890",
  "data": "0x"
}
```

Example response:

```json
undefined
```

### POST /api/v1/chain-data/gas/fee-history

$0.03 USDC. Retrieve the fee history for Base Mainnet blocks, including base fees and reward percentiles. Supports EIP-1559.

Inputs: blockCount?, newestBlock?, rewardPercentiles?

Docs: https://www.brainiac.software/api/chain-data/docs#chain-data-gas-fee-history

Example request:

```json
{
  "blockCount": 100,
  "rewardPercentiles": [
    25,
    50,
    75
  ]
}
```

Example response:

```json
undefined
```

### POST /api/v1/chain-data/address/native-balance

$0.01 USDC. Retrieve the native ETH balance of a Base Mainnet address from the public JSON-RPC endpoint.

Inputs: address, blockNumber?

Docs: https://www.brainiac.software/api/chain-data/docs#chain-data-address-native-balance

Example request:

```json
{
  "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
}
```

Example response:

```json
undefined
```

### POST /api/v1/chain-data/token/erc20-balance

$0.01 USDC. Retrieve the ERC-20 token balance of a wallet for a specified token contract on Base Mainnet using eth_call.

Inputs: walletAddress, tokenAddress, blockNumber?

Docs: https://www.brainiac.software/api/chain-data/docs#chain-data-token-erc20-balance

Example request:

```json
{
  "walletAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
}
```

Example response:

```json
undefined
```

### POST /api/v1/chain-data/token/erc20-total-supply

$0.01 USDC. Retrieve the total supply of an ERC-20 token on Base Mainnet using eth_call.

Inputs: tokenAddress, blockNumber?

Docs: https://www.brainiac.software/api/chain-data/docs#chain-data-token-erc20-total-supply

Example request:

```json
{
  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
}
```

Example response:

```json
undefined
```

### POST /api/v1/chain-data/token/metadata

$0.02 USDC. Retrieve ERC-20 name, symbol, decimals, and total supply for a token on Base Mainnet where supported.

Inputs: tokenAddress, blockNumber?

Docs: https://www.brainiac.software/api/chain-data/docs#chain-data-token-metadata

Example request:

```json
{
  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
}
```

Example response:

```json
undefined
```

### POST /api/v1/chain-data/token/erc20-transfers

$0.05 USDC. Retrieve ERC-20 Transfer events for a token contract or wallet on Base Mainnet over a bounded block range.

Inputs: tokenAddress?, walletAddress?, fromBlock?, toBlock?, limit?

Docs: https://www.brainiac.software/api/chain-data/docs#chain-data-token-erc20-transfers

Example request:

```json
{
  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "fromBlock": 18000000,
  "toBlock": 18001000,
  "limit": 100
}
```

Example response:

```json
undefined
```

### POST /api/v1/chain-data/address/nonce

$0.01 USDC. Retrieve the transaction nonce for a Base Mainnet address from the public JSON-RPC endpoint.

Inputs: address, blockNumber?

Docs: https://www.brainiac.software/api/chain-data/docs#chain-data-address-nonce

Example request:

```json
{
  "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
}
```

Example response:

```json
undefined
```