# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.armchain.org/api-reference/json-rpc.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.