> For the complete documentation index, see [llms.txt](https://docs.tajirchain.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tajirchain.com/eth-rpc-api.md).

# ETH RPC API

The Tajir Chain Explorer provides a public, Ethereum-compatible JSON-RPC proxy for retrieving blockchain data and broadcasting signed transactions.

This is a limited, security-filtered RPC interface. It supports commonly used Ethereum JSON-RPC methods while blocking administrative, wallet-management and debugging namespaces.

### Endpoint

```
https://explorer.tajirchain.com/api/eth-rpc
```

All requests must:

* Use the HTTP `POST` method
* Use JSON-RPC version `2.0`
* Include the `Content-Type: application/json` header
* Contain a unique request `id`

No API key is currently required for standard public requests.

### Network Information

| Property           | Value                                                               |
| ------------------ | ------------------------------------------------------------------- |
| Network            | Tajir Chain Mainnet                                                 |
| Chain ID           | `3377`                                                              |
| Hex Chain ID       | `0xd31`                                                             |
| Native currency    | TJR                                                                 |
| Currency decimals  | `18`                                                                |
| Block Explorer     | [https://explorer.tajirchain.com](https://explorer.tajirchain.com/) |
| Explorer RPC proxy | `https://explorer.tajirchain.com/api/eth-rpc`                       |
| Direct chain RPC   | `https://rpc.tajirchain.com`                                        |

### Quick Test

Use the following request to confirm that the endpoint is publicly accessible and connected to Tajir Chain Mainnet:

```bash
curl --request POST \
  --url https://explorer.tajirchain.com/api/eth-rpc \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_chainId",
    "params": [],
    "id": 1
  }'
```

Expected response:

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

### Supported Methods

The Explorer RPC proxy supports the following methods.

#### Network and Fee Methods

| Method                     | Parameters | Description                                      |
| -------------------------- | ---------- | ------------------------------------------------ |
| `eth_chainId`              | `[]`       | Returns the Tajir Chain ID in hexadecimal format |
| `eth_blockNumber`          | `[]`       | Returns the latest block number                  |
| `eth_gasPrice`             | `[]`       | Returns the current gas price                    |
| `eth_maxPriorityFeePerGas` | `[]`       | Returns a suggested priority fee                 |

#### Account and Contract State

| Method                    | Parameters                      | Description                                      |
| ------------------------- | ------------------------------- | ------------------------------------------------ |
| `eth_getBalance`          | `[address, blockTag]`           | Returns the TJR balance of an address            |
| `eth_getTransactionCount` | `[address, blockTag]`           | Returns the transaction count for an address     |
| `eth_getCode`             | `[address, blockTag]`           | Returns the bytecode stored at an address        |
| `eth_getStorageAt`        | `[address, position, blockTag]` | Returns a value from a contract storage position |

#### Blocks and Transactions

| Method                      | Parameters                      | Description                                 |
| --------------------------- | ------------------------------- | ------------------------------------------- |
| `eth_getBlockByNumber`      | `[blockTag, fullTransactions]`  | Returns a block using its number or tag     |
| `eth_getBlockByHash`        | `[blockHash, fullTransactions]` | Returns a block using its hash              |
| `eth_getTransactionByHash`  | `[transactionHash]`             | Returns transaction information             |
| `eth_getTransactionReceipt` | `[transactionHash]`             | Returns the receipt for a mined transaction |
| `eth_sendRawTransaction`    | `[signedTransaction]`           | Broadcasts an already signed transaction    |

#### Contract Execution and Logs

| Method            | Parameters                      | Description                                  |
| ----------------- | ------------------------------- | -------------------------------------------- |
| `eth_call`        | `[transactionObject, blockTag]` | Executes a read-only contract call           |
| `eth_estimateGas` | `[transactionObject, blockTag]` | Estimates the gas required for a transaction |
| `eth_getLogs`     | `[filterObject]`                | Returns event logs matching a filter         |

### Request Examples

#### Get the Latest Block Number

```bash
curl --request POST \
  --url https://explorer.tajirchain.com/api/eth-rpc \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }'
```

The block number is returned as a hexadecimal value.

#### Get an Address Balance

Replace `0xYOUR_ADDRESS` with a valid Tajir Chain address.

```bash
curl --request POST \
  --url https://explorer.tajirchain.com/api/eth-rpc \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": [
      "0xYOUR_ADDRESS",
      "latest"
    ],
    "id": 1
  }'
```

The balance is returned in hexadecimal wei. TJR uses 18 decimals.

#### Get a Transaction

Replace `0xTRANSACTION_HASH` with a valid transaction hash.

```bash
curl --request POST \
  --url https://explorer.tajirchain.com/api/eth-rpc \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getTransactionByHash",
    "params": [
      "0xTRANSACTION_HASH"
    ],
    "id": 1
  }'
```

The result will be `null` if the transaction cannot be found.

#### Get a Transaction Receipt

```bash
curl --request POST \
  --url https://explorer.tajirchain.com/api/eth-rpc \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getTransactionReceipt",
    "params": [
      "0xTRANSACTION_HASH"
    ],
    "id": 1
  }'
```

A receipt becomes available after the transaction has been included in a block.

#### Get a Block

```bash
curl --request POST \
  --url https://explorer.tajirchain.com/api/eth-rpc \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getBlockByNumber",
    "params": [
      "latest",
      false
    ],
    "id": 1
  }'
```

Set the second parameter to `true` to request full transaction objects instead of transaction hashes.

#### Read Contract Code

Replace `0xCONTRACT_ADDRESS` with a valid contract address.

```bash
curl --request POST \
  --url https://explorer.tajirchain.com/api/eth-rpc \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getCode",
    "params": [
      "0xCONTRACT_ADDRESS",
      "latest"
    ],
    "id": 1
  }'
```

An externally owned account normally returns `0x`.

#### Execute a Read-Only Contract Call

Replace the contract address and calldata with valid values.

```bash
curl --request POST \
  --url https://explorer.tajirchain.com/api/eth-rpc \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_call",
    "params": [
      {
        "to": "0xCONTRACT_ADDRESS",
        "data": "0xENCODED_CALLDATA"
      },
      "latest"
    ],
    "id": 1
  }'
```

`eth_call` does not create a transaction or modify blockchain state.

#### Estimate Transaction Gas

The Explorer RPC proxy requires both the transaction object and block parameter.

```bash
curl --request POST \
  --url https://explorer.tajirchain.com/api/eth-rpc \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_estimateGas",
    "params": [
      {
        "from": "0xSENDER_ADDRESS",
        "to": "0xRECIPIENT_ADDRESS",
        "value": "0x0"
      },
      "latest"
    ],
    "id": 1
  }'
```

The gas estimate is returned as a hexadecimal value.

#### Get Event Logs

The filter must include at least an `address` or `topics` property.

```bash
curl --request POST \
  --url https://explorer.tajirchain.com/api/eth-rpc \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getLogs",
    "params": [
      {
        "fromBlock": "latest",
        "toBlock": "latest",
        "address": "0xCONTRACT_ADDRESS"
      }
    ],
    "id": 1
  }'
```

Applications should request reasonable block ranges. Large log queries may be limited, rejected or time out.

#### Broadcast a Signed Transaction

Transactions must be signed locally before being submitted. Never send a private key, seed phrase or unsigned private data to an RPC endpoint.

```bash
curl --request POST \
  --url https://explorer.tajirchain.com/api/eth-rpc \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_sendRawTransaction",
    "params": [
      "0xSIGNED_RAW_TRANSACTION"
    ],
    "id": 1
  }'
```

If accepted, the response contains the transaction hash.

### JavaScript Example

The following example uses the standard `fetch` API:

```javascript
const response = await fetch(
  "https://explorer.tajirchain.com/api/eth-rpc",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      method: "eth_chainId",
      params: [],
      id: 1
    })
  }
);

const data = await response.json();
console.log(data);
```

### Error Handling

JSON-RPC errors are returned through an `error` object:

```json
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params"
  },
  "id": 1
}
```

Common JSON-RPC error codes include:

|     Code | Meaning                           |
| -------: | --------------------------------- |
| `-32600` | Invalid JSON-RPC request          |
| `-32601` | Method not found or not supported |
| `-32602` | Missing or invalid parameters     |
| `-32603` | Internal RPC error                |

Execution failures may return additional messages from the chain node. Applications must check for both `result` and `error` fields.

### Restricted Methods

For security reasons, the public Explorer RPC proxy does not provide administrative or node-management methods, including:

* `admin_*`
* `debug_*`
* `personal_*`
* `txpool_*`
* `trace_*`
* `rpc_modules`
* `eth_accounts`

Applications must sign transactions locally. The RPC service will never request or manage private keys.

### Rate Limits and Responsible Use

This endpoint is intended for standard public requests and may apply rate limits, timeouts, response-size restrictions and log-query limits.

Applications with sustained production traffic should:

* Cache responses where appropriate
* Avoid continuously polling unchanged data
* Keep `eth_getLogs` block ranges limited
* Implement retries with exponential backoff
* Treat HTTP `429` and temporary `5xx` responses as retryable
* Use the direct Tajir Chain RPC for wallet and direct chain integrations
* Use the Explorer REST API for indexed explorer data

Do not depend on a public endpoint as the only provider for critical infrastructure.

### Choosing the Correct API

| Requirement                            | Recommended endpoint                          |
| -------------------------------------- | --------------------------------------------- |
| Connect a wallet or Web3 SDK           | `https://rpc.tajirchain.com`                  |
| Submit direct JSON-RPC requests        | `https://rpc.tajirchain.com`                  |
| Use the limited Explorer RPC proxy     | `https://explorer.tajirchain.com/api/eth-rpc` |
| Retrieve indexed explorer data         | `https://explorer.tajirchain.com/api/v2`      |
| Review Explorer REST API documentation | <https://explorer.tajirchain.com/api-docs>    |

The Explorer REST API and Ethereum JSON-RPC API are separate interfaces. REST API paths such as `/api/v2/blocks` must not be sent to the JSON-RPC endpoint.

### Support

Before reporting an issue, verify:

1. The request uses HTTP `POST`.
2. The `Content-Type` is `application/json`.
3. The request contains `jsonrpc`, `method`, `params` and `id`.
4. Addresses and transaction hashes use valid hexadecimal formats.
5. `eth_estimateGas` includes the required block parameter.
6. `eth_getLogs` contains an `address` or `topics` filter.
7. The method appears in the supported-method list above.

When reporting a problem, include the method name, request body, HTTP status and JSON-RPC error response. Never include private keys, recovery phrases or other confidential information.