# Blockdaemon's Ethereum JSON-RPC APIs

This guide outlines Blockdaemon's Ethereum JSON-RPC APIs for retrieving transaction and transfer data. One of the key capabilities is retrieving transaction hashes associated with a specific address.

Ethereum custom methods support the following networks:

- `mainnet`
- `sepolia`
- `hoodi`

> 📘  
> See the [Ethereum RPC API connection guide](https://docs.blockdaemon.com/docs/access-ethereum-rpc-api).

## Account API

### `bd_getTransactionHashesByAddress`

Returns transaction hashes by address. Use this method to track transactions associated with a specific address.

> 📘  
> ### Compute Unit Value  
> **50 CU**

**Request Example**

Request exampleRequest example with filter object

```curl
{
    "jsonrpc": "2.0",
    "method": "bd_getTransactionHashesByAddress",
    "id": 1,
    "params": [
        "0x388C818CA8B9251b393131C08a736A67ccB19297"
    ]
}
```

```curl
{
    "jsonrpc": "2.0",
    "method": "bd_getTransactionHashesByAddress",
    "id": 1,
    "params": [
      "0x388C818CA8B9251b393131C08a736A67ccB19297",
      {
        "blockStart": "0x10D4F",
        "blockEnd": "0x10FFFF",
        "order": "asc",
        "pageSize": 50,
     }
   ]
}
```

**Request Parameters**

| Type | Description |
| --- | --- |
| `params`: Hex-encoded EVM address | **(required)** The main account address. |
| `params`: Filter Object | **(optional)** An object with filters. See the table below. |

**Filter Object**

| Argument | Type | Description |
| --- | --- | --- |
| `blockStart` | Unsigned integer or hex-encoded number | **(optional)** Only return hashes higher than or equal to this block number. |
| `blockEnd` | Unsigned integer or hex-encoded number | **(optional)** Only return hashes lower than this block number. |
| `order` | Enum (desc|asc) | **(optional)** Return hashes by block number in ascending or descending order. The default is **descending**. |
| `pageToken` | String | **(optional)** Token for pagination. |
| `pageSize` | Unsigned integer or hex-encoded number | **(optional)** Max results per page (1-100). Default is **100**. |
| `contract` | Comma-separated string of hex-encoded EVM addresses | **(optional)** Only return hashes where the specified contract address was invoked. Multiple addresses are treated as an **OR** filter. |

> ❗️  
> ### Info:  
> The `pageToken` should be used in combination with prior filter arguments to work properly.

**Response Example**

JSON

```json
{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "transactions": [
            "0xf717bf9b76338c275373bf25b48692d4aad2f88b72b8677a5cae00a6c9e60157",
            "0x82d97cb65e4bd8c2f76e45d90f8f09550317b52a95d8c5d6b92a662fe72cac60",
            "0xdebb7de86c2f09f94e23c12c4a09f9abab4391b274febfeef1505b096cd1ad84",
            ...
        ]
    }
}
```

**Response Object**

| Field | Type | Description |
| --- | --- | --- |
| `transactions` | List of hashes | **(required)** List of matching transaction hashes. |
| `pageToken` | String | **(optional)** Token for fetching the next page of results. |

## Blocks API

### `bd_getBlockHeaderByDate`

Returns a block header for the given date (Unix timestamp). If no exact match is found, returns the nearest block.

> 📘  
> ### Compute Unit Value  
> **50 CU**

**Request Example**

cURL

```curl
{
    "jsonrpc": "2.0",
    "method": "bd_getBlockHeaderByDate",
    "id": 1,
    "params": [1728476495]
}
```

**Request Parameter**

| Field | Type | Description |
| --- | --- | --- |
| `params`: Timestamp | `timestamp` | **(required)** The timestamp in Unix seconds can be provided as either a number or a hex-encoded number. |

**Response Example**

JSON

```json
{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "time": "0x6706754f",
        "height": "0x13f55fe",
        "hash": "0xead6af5739422ca8e99fba58943e138c718e5a093c437513973d9945ef89472b"
    }
}
```

**Response Object**

| Field | Type | Description |
| --- | --- | --- |
| `time` | Hex-encoded number | **(required)** The block time in Unix timestamp. |
| `height` | Hex-encoded number | **(required)** The block number. |
| `hash` | String | **(required)** The block hash. |

## Tokens API

### `bd_getTokenBalance`

Returns the token balance of a given address for a specific ERC-20 token contract.

> 🚧  
> ### Info  
> Historical queries only supported on Ethereum mainnet.  
> 📘  
> ### Compute Unit Value  
> **5 CU**

**Request Example**

Get token balance with block numberGet token balance with date

```curl
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "bd_getTokenBalance",
  "params": [
    {
      "contractAddress": "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE",
      "ownerAddress": "0xb8aFF7b6ddbecaF1e094C5a628845fC13e93d7f2",
      "blockNumber": "0x14EC0C9"
    }
  ]
}
```

```curl
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "bd_getTokenBalance",
  "params": [
    {
      "contractAddress": "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE",
      "ownerAddress": "0xb8aFF7b6ddbecaF1e094C5a628845fC13e93d7f2",
      "date": "0x67c07b8f"
    }
  ]
}
```

**Request Parameters**

| Field | Type | Description |
| --- | --- | --- |
| `contractAddress` | String | **(required)** The token contract address for which the balance is being queried |
| `ownerAddress` | String | **(required)** The account address whose token balance you want to retrieve |
| `date` | String/Int (hex/int) | **(optional)** Timestamp to fetch historical balance |
| `blockNumber` | String/Int (hex/int) | **(optional)** Block number to fetch historical balance |

**Response Example**

JSON

```json
{
    "jsonrpc": "2.0",
    "id": 1,
    "result": 0x659abc0a1818f23843ff59b3
}
```

### `bd_getTokenMetadata`

Returns token metadata, such as symbol, name, decimals, and total supply.

> 📘  
> ### Compute Unit Value  
> **5 CU**

**Request Example**

cURL

```curl
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "bd_getTokenMetadata",
    "params": [
        "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE"
    ]
}
```

**Request Parameter**

| Field | Type | Description |
| --- | --- | --- |
| `params`: Token Address | String | **(required)** Token contract address. |

**Response Example**

JSON

```json
{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "decimals": "0x12",
        "totalSupply": "0x314d8d3733f32fa376f039a13d46",
        "name": "SHIBA INU",
        "symbol": "SHIB"
    }
}
```

**Response Object**

| Field | Type | Description |
| --- | --- | --- |
| `decimals` | Hex encoded number | **(required)** The decimal places the token uses. |
| `totalSupply` | Hex encoded number | **(required)** The number of a specific token that can currently exist. |
| `name` | String | **(required)** The token name. |
| `symbol` | String | **(required)** The token symbol. |

### `bd_getContractAbiByAddress`

This method returns the ABI (Application Binary Interface) for a given contract address. It is not limited to token addresses but applies to any contract address. The ABI is required to interact with the contract.

> 📘  
> ### Compute Unit Value  
> **10 CU**

**Request Example**

cURL

```curl
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "bd_getContractAbiByAddress",
  "params": [
    "0x0e5dDA855EB1De2a212cD1F62b2a3EE49D20c444"
  ]
}
```

**Request Parameter**

| Filed | Type | Description |
| --- | --- | --- |
| `params`: Contract Address | String | **(required)** The contract address for which you want to retrieve the ABI. |

**Response Example**

JSON

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "inputs": [
        {
          "internalType": "address",
          "name": "beacon",
          "type": "address"
        },
        {
          "internalType": "bytes",
          "name": "data",
          "type": "bytes"
        }
      ],
      "stateMutability": "payable",
      "type": "constructor"
    },
    {
      "anonymous": false,
      "inputs": [
        {
          "indexed": false,
          "internalType": "address",
          "name": "previousAdmin",
          "type": "address"
        },
        {
          "indexed": false,
          "internalType": "address",
          "name": "newAdmin",
          "type": "address"
        }
      ],
      "name": "AdminChanged",
      "type": "event"
    },
    {
      "anonymous": false,
      "inputs": [
        {
          "indexed": true,
          "internalType": "address",
          "name": "beacon",
          "type": "address"
        }
      ],
      "name": "BeaconUpgraded",
      "type": "event"
    },
    {
      "anonymous": false,
      "inputs": [
        {
          "indexed": true,
          "internalType": "address",
          "name": "implementation",
          "type": "address"
        }
      ],
      "name": "Upgraded",
      "type": "event"
    },
    {
      "stateMutability": "payable",
      "type": "fallback"
    },
    {
      "stateMutability": "payable",
      "type": "receive"
    }
  ]
}
```

**Response Object**

| Field | Type | Description |
| --- | --- | --- |
| `inputs` | Array | An array of input parameters. Each item includes `name`, `type`, and `internalType`. |
| `indexed` | Boolean | Indicates whether the event parameter is indexed. Only present for event ABI items. |
| `internalType` | String | The type used internally, e.g., `address`. |
| `name` | String | Name of the function or event. |
| `type` | String | Type of the ABI item. Can be `constructor`, `function`, `event`, `fallback`, or `receive`. |
| `anonymous` | Boolean | Indicates if the event is anonymous. Only present for `event` types. |
| `stateMutability` | String | The state mutability of the function, e.g., `payable`. |