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

# JSON-RPC

Armchain exposes a standard Ethereum-compatible JSON-RPC API over HTTP and WebSocket. If you've used Ethereum's JSON-RPC before, everything works the same way: same method names, same parameters, same response format.

## Endpoint

```
HTTP:      http://localhost:18545   (or https://www.armchain.org/devnet for devnet)
WebSocket: ws://localhost:18546     (or wss://www.armchain.org/devnet for devnet)
```

## Request Format

```bash
curl -X POST <RPC_URL> \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "<METHOD>",
    "params": [<PARAMS>],
    "id": 1
  }'
```

***

## eth Namespace

### eth\_blockNumber

Returns the latest block number.

```bash
curl -X POST https://www.armchain.org/devnet -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
```

**Response:**

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

***

### eth\_getBalance

Returns the balance of an address in wei.

**Parameters:**

1. `address`: 20-byte address
2. `blockTag`: Block number or `"latest"`, `"earliest"`, `"pending"`

```bash
curl -X POST https://www.armchain.org/devnet -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0xADDRESS","latest"],"id":1}'
```

**Response:**

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

***

### eth\_getTransactionCount

Returns the number of transactions sent from an address (nonce).

**Parameters:**

1. `address`: 20-byte address
2. `blockTag`: Block number or tag

```bash
curl -X POST https://www.armchain.org/devnet -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0xADDRESS","latest"],"id":1}'
```

***

### eth\_sendRawTransaction

Submits a signed transaction for broadcast.

**Parameters:**

1. `data`: Signed transaction data (hex). Must be a **Type 3 PQC** transaction.

```bash
curl -X POST https://www.armchain.org/devnet -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0x03f9..."],"id":1}'
```

**Response:**

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

***

### eth\_call

Executes a call without creating a transaction (read-only).

**Parameters:**

1. `transaction`: Transaction call object
2. `blockTag`: Block number or tag

```bash
curl -X POST https://www.armchain.org/devnet -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_call",
    "params":[{
      "to": "0xCONTRACT_ADDRESS",
      "data": "0x70a08231000000000000000000000000ADDRESS"
    }, "latest"],
    "id":1
  }'
```

***

### eth\_estimateGas

Estimates gas for a transaction.

**Parameters:**

1. `transaction`: Transaction call object

```bash
curl -X POST https://www.armchain.org/devnet -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_estimateGas",
    "params":[{
      "from": "0xFROM",
      "to": "0xTO",
      "value": "0xde0b6b3a7640000"
    }],
    "id":1
  }'
```

***

### eth\_getBlockByNumber

Returns block information by block number.

**Parameters:**

1. `blockNumber`: Block number (hex) or tag
2. `fullTransactions`: If `true`, returns full transaction objects

```bash
curl -X POST https://www.armchain.org/devnet -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["latest", false],"id":1}'
```

***

### eth\_getTransactionByHash

Returns transaction details by hash.

**Parameters:**

1. `transactionHash`: 32-byte transaction hash

```bash
curl -X POST https://www.armchain.org/devnet -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0xHASH"],"id":1}'
```

**Response (Type 3 PQC Transaction):**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "type": "0x3",
    "hash": "0x...",
    "from": "0x...",
    "to": "0x...",
    "value": "0xde0b6b3a7640000",
    "nonce": "0x1",
    "gasLimit": "0x5208",
    "maxFeePerGas": "0x4a817c800",
    "maxPriorityFeePerGas": "0x77359400",
    "chainId": "0x37",
    "blockNumber": "0x1a4",
    "blockHash": "0x...",
    "transactionIndex": "0x0"
  }
}
```

***

### eth\_getTransactionReceipt

Returns the receipt of a mined transaction.

**Parameters:**

1. `transactionHash`: 32-byte transaction hash

```bash
curl -X POST https://www.armchain.org/devnet -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0xHASH"],"id":1}'
```

***

### eth\_getLogs

Returns logs matching a filter.

**Parameters:**

1. `filter`: Filter object with `fromBlock`, `toBlock`, `address`, `topics`

```bash
curl -X POST https://www.armchain.org/devnet -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_getLogs",
    "params":[{
      "fromBlock": "0x0",
      "toBlock": "latest",
      "address": "0xCONTRACT",
      "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
    }],
    "id":1
  }'
```

***

### eth\_chainId

Returns the chain ID.

```bash
curl -X POST https://www.armchain.org/devnet -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
```

**Response:**

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

***

### eth\_gasPrice

Returns the current gas price.

```bash
curl -X POST https://www.armchain.org/devnet -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}'
```

***

### eth\_getCode

Returns the code at a given address (for contracts).

**Parameters:**

1. `address`: Contract address
2. `blockTag`: Block number or tag

```bash
curl -X POST https://www.armchain.org/devnet -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getCode","params":["0xCONTRACT","latest"],"id":1}'
```

***

## Other Standard Methods

| Method                                    | Description                               |
| ----------------------------------------- | ----------------------------------------- |
| `eth_accounts`                            | Returns list of owned addresses           |
| `eth_sign`                                | Signs data with account key               |
| `eth_signTransaction`                     | Signs a transaction without sending       |
| `eth_getBlockByHash`                      | Get block by hash                         |
| `eth_getTransactionByBlockHashAndIndex`   | Get tx by block hash and index            |
| `eth_getTransactionByBlockNumberAndIndex` | Get tx by block number and index          |
| `eth_getStorageAt`                        | Get storage value at position             |
| `eth_syncing`                             | Returns sync status                       |
| `eth_mining`                              | Returns whether node is mining/validating |
| `eth_coinbase`                            | Returns validator address                 |

***

## net Namespace

| Method          | Description                               |
| --------------- | ----------------------------------------- |
| `net_version`   | Returns network ID                        |
| `net_listening` | Whether node is listening for connections |
| `net_peerCount` | Number of connected peers                 |

***

## web3 Namespace

| Method               | Description                   |
| -------------------- | ----------------------------- |
| `web3_clientVersion` | Returns client version string |
| `web3_sha3`          | Returns Keccak-256 of input   |

***

## txpool Namespace

| Method           | Description                          |
| ---------------- | ------------------------------------ |
| `txpool_status`  | Returns pending and queued tx counts |
| `txpool_content` | Returns all pending and queued txs   |
| `txpool_inspect` | Returns textual summary of pool      |

***

## personal Namespace

> **Warning**: Only use on local/private nodes. Never expose on public endpoints.

| Method                     | Description                   |
| -------------------------- | ----------------------------- |
| `personal_newAccount`      | Create a new account          |
| `personal_unlockAccount`   | Unlock an account for signing |
| `personal_lockAccount`     | Lock an account               |
| `personal_listAccounts`    | List all accounts             |
| `personal_sendTransaction` | Sign and send a transaction   |

***

## admin Namespace

| Method             | Description                     |
| ------------------ | ------------------------------- |
| `admin_nodeInfo`   | Returns node information        |
| `admin_peers`      | Returns connected peers         |
| `admin_addPeer`    | Add a peer by enode URL         |
| `admin_removePeer` | Remove a peer                   |
| `admin_datadir`    | Returns the data directory path |

***

## WebSocket Subscriptions

### Subscribe to New Blocks

```javascript
// eth_subscribe: newHeads
ws.send(JSON.stringify({
  jsonrpc: "2.0",
  method: "eth_subscribe",
  params: ["newHeads"],
  id: 1
}));
```

### Subscribe to Logs

```javascript
// eth_subscribe: logs
ws.send(JSON.stringify({
  jsonrpc: "2.0",
  method: "eth_subscribe",
  params: ["logs", {
    address: "0xCONTRACT",
    topics: ["0xTOPIC_HASH"]
  }],
  id: 1
}));
```

### Subscribe to Pending Transactions

```javascript
ws.send(JSON.stringify({
  jsonrpc: "2.0",
  method: "eth_subscribe",
  params: ["newPendingTransactions"],
  id: 1
}));
```

### Unsubscribe

```javascript
ws.send(JSON.stringify({
  jsonrpc: "2.0",
  method: "eth_unsubscribe",
  params: ["SUBSCRIPTION_ID"],
  id: 2
}));
```

***

## Rate Limits

Public RPC endpoints may enforce rate limits.

## Further Reading

* [Armchain-Specific APIs](/api-reference/armchain-api.md): DAG and PQC-specific endpoints
* [Network Configuration](/get-started/network-configuration.md): Endpoints and chain details