>AgentChain

JSON-RPC Reference

AgentChain exposes a standard Ethereum JSON-RPC API over HTTP and WebSocket. Any Ethereum-compatible library, wallet, or tool can interact with an AgentChain node using the same methods they would use for Ethereum mainnet.

Connection

HTTP

http://localhost:8545

WebSocket

ws://localhost:8546

Enable specific API namespaces when starting the node:

geth --datadir ./agentchain-data \
  --networkid 7331 \
  --http --http.port 8545 \
  --http.api eth,net,web3,miner,txpool,admin,debug,agent \
  --ws --ws.port 8546 \
  --ws.api eth,net,web3,agent

Security note: The personal namespace is intentionally excluded from HTTP/WebSocket. Its methods accept private keys and passwords as parameters, which would be logged by LLM providers. Use the agent namespace instead. See Security Architecture for details.

Supported Namespaces

| Namespace | Description | |-----------|-------------| | eth | Core blockchain interaction — blocks, transactions, state queries | | net | Network status and peer information | | web3 | Client metadata and utility functions | | miner | Mining control (start, stop, set etherbase) | | agent | Key-free wallet API for AI agents — create wallets, send CRD, deploy contracts, mine | | txpool | Transaction pool inspection | | debug | Debugging and tracing methods | | admin | Node administration (peers, node info) | | personal | ~~Account management~~ — disabled on HTTP/WS (available via IPC only, see Security) |

Core Methods

eth_chainId

Returns the chain ID of the network.

Request:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_chainId",
    "params": [],
    "id": 1
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1ca3"
}

The hex value 0x1ca3 equals 7331 in decimal.

eth_blockNumber

Returns the number of the most recent block.

Request:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x4b7"
}

eth_getBalance

Returns the balance of an account in wei.

Parameters:

  1. address — The address to query.
  2. block — Block number (hex) or tag ("latest", "earliest", "pending").

Request:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28", "latest"],
    "id": 1
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1bc16d674ec80000"
}

The result is in wei. 0x1bc16d674ec80000 = 2,000,000,000,000,000,000 wei = 2 CRD.

eth_sendTransaction

Sends a transaction from an unlocked account on the node.

Parameters:

  1. Transaction object with from, to, value, gas, gasPrice, data, nonce.

Request:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_sendTransaction",
    "params": [{
      "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
      "to": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
      "value": "0xde0b6b3a7640000",
      "gas": "0x5208",
      "gasPrice": "0x3b9aca00"
    }],
    "id": 1
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331"
}

The result is the transaction hash.

eth_sendRawTransaction

Submits a pre-signed raw transaction. This is the standard method used by wallets and libraries (ethers.js, web3.py) that sign transactions client-side.

Parameters:

  1. data — The signed transaction data (hex-encoded).

Request:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_sendRawTransaction",
    "params": ["0xf86c0a8503b9aca00082520894...signed_tx_hex..."],
    "id": 1
  }'

eth_call

Executes a message call immediately without creating a transaction. Used for reading data from smart contracts.

Parameters:

  1. Transaction call object with to, data (and optionally from, gas, gasPrice, value).
  2. Block number or tag.

Request:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_call",
    "params": [{
      "to": "0xContractAddress...",
      "data": "0x70a08231000000000000000000000000742d35Cc6634C0532925a3b844Bc9e7595f2bD28"
    }, "latest"],
    "id": 1
  }'

The data field contains the ABI-encoded function call. The example above calls balanceOf(address).

eth_estimateGas

Estimates the gas required to execute a transaction.

Request:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_estimateGas",
    "params": [{
      "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
      "to": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
      "value": "0xde0b6b3a7640000"
    }],
    "id": 1
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x5208"
}

0x5208 = 21,000 gas (the standard cost for a simple CRD transfer).

eth_getTransactionReceipt

Returns the receipt of a mined transaction.

Parameters:

  1. transactionHash — The hash of the transaction.

Request:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getTransactionReceipt",
    "params": ["0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331"],
    "id": 1
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "transactionHash": "0xe670ec6434177160...",
    "transactionIndex": "0x0",
    "blockHash": "0xb903239f854...",
    "blockNumber": "0x4b7",
    "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
    "to": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
    "cumulativeGasUsed": "0x5208",
    "gasUsed": "0x5208",
    "contractAddress": null,
    "logs": [],
    "logsBloom": "0x00000...",
    "status": "0x1"
  }
}

Key fields:

  • status: "0x1" for success, "0x0" for revert.
  • contractAddress: Set when the transaction deploys a contract, null otherwise.
  • logs: Array of event logs emitted during execution.

eth_getBlockByNumber

Returns information about a block by block number.

Parameters:

  1. blockNumber — Block number (hex) or tag.
  2. fullTransactions — If true, returns full transaction objects; if false, returns only transaction hashes.

Request:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBlockByNumber",
    "params": ["latest", false],
    "id": 1
  }'

Response (abbreviated):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "number": "0x4b7",
    "hash": "0xb903239f854...",
    "parentHash": "0xa1e4380a3b...",
    "nonce": "0x4e6f7265...",
    "miner": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
    "difficulty": "0x20000",
    "totalDifficulty": "0x96000000",
    "gasLimit": "0x1c9c380",
    "gasUsed": "0x0",
    "timestamp": "0x65a8d580",
    "transactions": []
  }
}

eth_getLogs

Returns an array of log objects matching the given filter criteria.

Parameters:

  1. Filter object with fromBlock, toBlock, address, topics.

Request:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getLogs",
    "params": [{
      "fromBlock": "0x0",
      "toBlock": "latest",
      "address": "0xContractAddress...",
      "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
    }],
    "id": 1
  }'

The topic in the example is the keccak256 hash of the Transfer(address,address,uint256) event signature.

net_version

Returns the current network ID as a string.

Request:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "net_version",
    "params": [],
    "id": 1
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "7331"
}

web3_clientVersion

Returns the client software version.

Request:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "web3_clientVersion",
    "params": [],
    "id": 1
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Geth/v1.x.x-agentchain/linux-amd64/go1.21"
}

miner_start / miner_stop

Controls mining on the node.

Start mining with 1 thread:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "miner_start",
    "params": [1],
    "id": 1
  }'

Stop mining:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "miner_stop",
    "params": [],
    "id": 1
  }'

Additional Method Reference

eth Namespace

| Method | Description | |--------|-------------| | eth_chainId | Returns chain ID (0x1ca3) | | eth_blockNumber | Latest block number | | eth_getBalance | Account balance in wei | | eth_getTransactionCount | Account nonce | | eth_getCode | Contract bytecode at address | | eth_getStorageAt | Storage value at position | | eth_sendTransaction | Send from unlocked account | | eth_sendRawTransaction | Submit signed transaction | | eth_call | Execute read-only call | | eth_estimateGas | Estimate gas for transaction | | eth_getTransactionByHash | Transaction details by hash | | eth_getTransactionReceipt | Transaction receipt | | eth_getBlockByNumber | Block by number | | eth_getBlockByHash | Block by hash | | eth_getLogs | Query event logs | | eth_newFilter | Create log filter | | eth_newBlockFilter | Create new block filter | | eth_getFilterChanges | Poll filter for changes | | eth_uninstallFilter | Remove a filter | | eth_gasPrice | Current gas price suggestion | | eth_accounts | List node accounts | | eth_sign | Sign data with account | | eth_signTransaction | Sign without broadcasting | | eth_mining | Check if node is mining | | eth_hashrate | Current mining hashrate | | eth_syncing | Sync status |

net Namespace

| Method | Description | |--------|-------------| | net_version | Network ID ("7331") | | net_peerCount | Number of connected peers | | net_listening | Whether the node accepts connections |

web3 Namespace

| Method | Description | |--------|-------------| | web3_clientVersion | Client version string | | web3_sha3 | Keccak-256 hash of input |

miner Namespace

| Method | Description | |--------|-------------| | miner_start | Start mining (parameter: thread count) | | miner_stop | Stop mining | | miner_setEtherbase | Set mining reward address | | miner_setExtra | Set extra data in mined blocks | | miner_setGasPrice | Set minimum gas price to accept |

agent Namespace

The agent namespace provides a key-free API for AI agents. No private keys or passwords are ever sent as parameters. See the Agent API Reference for full documentation with examples.

| Method | Description | |--------|-------------| | agent_createWallet | Create a new wallet (node generates keys internally) | | agent_listWallets | List all agent wallets with balances | | agent_send | Send CRD (node signs internally) | | agent_deployContract | Deploy a smart contract (node signs internally) | | agent_callContract | Read-only contract call | | agent_getBalance | Get address balance | | agent_getTransactionReceipt | Get transaction receipt | | agent_startMining | Start mining with specified etherbase | | agent_stopMining | Stop mining |

personal Namespace (Disabled on HTTP/WS)

Security warning: The personal namespace is disabled on HTTP and WebSocket connections. These methods accept private keys and passwords as plaintext parameters, which would be logged by LLM providers if used by an AI agent. Use the agent namespace instead.

The personal namespace is only available via IPC (local Unix socket) for direct node administration.

| Method | Description | Risk | |--------|-------------|------| | personal_newAccount | Create account with passphrase | Password in request | | personal_importRawKey | Import private key | Private key in request | | personal_unlockAccount | Unlock account for signing | Password in request | | personal_lockAccount | Lock a previously unlocked account | — | | personal_listAccounts | List all accounts on the node | — | | personal_sendTransaction | Sign and send in one call | Password in request |

txpool Namespace

| Method | Description | |--------|-------------| | txpool_status | Pending and queued transaction counts | | txpool_content | Full transaction pool contents | | txpool_inspect | Summary of transaction pool |

debug Namespace

| Method | Description | |--------|-------------| | debug_traceTransaction | Detailed execution trace of a transaction | | debug_traceBlockByNumber | Trace all transactions in a block | | debug_getBlockRlp | RLP-encoded block data | | debug_dumpBlock | Full state dump at a block | | debug_gcStats | Garbage collection statistics | | debug_memStats | Memory allocation statistics |

admin Namespace

| Method | Description | |--------|-------------| | admin_nodeInfo | Node identity and protocol info | | admin_peers | Connected peer details | | admin_addPeer | Connect to a specific peer | | admin_removePeer | Disconnect from a peer | | admin_datadir | Path to the data directory |

WebSocket Subscriptions

AgentChain supports real-time event streaming via WebSocket subscriptions using eth_subscribe. This is essential for applications that need immediate notification of new blocks, transactions, or contract events.

Connecting

Use any WebSocket client to connect:

wscat -c ws://localhost:8546

Subscribe to New Block Headers

Receive a notification every time a new block is mined.

Request:

{
  "jsonrpc": "2.0",
  "method": "eth_subscribe",
  "params": ["newHeads"],
  "id": 1
}

Subscription confirmation:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1a2b3c4d..."
}

Notification (received for each new block):

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x1a2b3c4d...",
    "result": {
      "number": "0x4b8",
      "hash": "0xabc123...",
      "parentHash": "0xdef456...",
      "miner": "0x742d35Cc...",
      "difficulty": "0x20100",
      "gasLimit": "0x1c9c380",
      "gasUsed": "0x0",
      "timestamp": "0x65a8d586"
    }
  }
}

Subscribe to Logs

Receive notifications when specific contract events are emitted.

Request:

{
  "jsonrpc": "2.0",
  "method": "eth_subscribe",
  "params": [
    "logs",
    {
      "address": "0xContractAddress...",
      "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
    }
  ],
  "id": 1
}

Subscribe to Pending Transactions

Receive notification of each new pending transaction hash as it enters the mempool.

Request:

{
  "jsonrpc": "2.0",
  "method": "eth_subscribe",
  "params": ["newPendingTransactions"],
  "id": 1
}

Subscribe to Sync Status

Receive notifications about sync progress.

Request:

{
  "jsonrpc": "2.0",
  "method": "eth_subscribe",
  "params": ["syncing"],
  "id": 1
}

Unsubscribe

Cancel an active subscription.

Request:

{
  "jsonrpc": "2.0",
  "method": "eth_unsubscribe",
  "params": ["0x1a2b3c4d..."],
  "id": 1
}

AgentChain-Specific Notes

No EIP-1559 Methods

The following methods behave differently on AgentChain compared to post-London Ethereum:

  • eth_gasPrice returns a suggested gas price based on recent transactions (no base fee calculation).
  • eth_feeHistory is not available (this method was introduced with EIP-1559).
  • eth_maxPriorityFeePerGas is not available.

Transaction Format

When constructing transactions for AgentChain, use the legacy format:

const tx = {
  to: "0x...",
  value: ethers.parseEther("1.0"),
  gasLimit: 21000,
  gasPrice: ethers.parseUnits("1", "gwei"),
  nonce: 0,
  chainId: 7331
};

Do not use maxFeePerGas or maxPriorityFeePerGas fields.

Library Configuration

When using ethers.js or web3.js, ensure the provider is configured for legacy transactions:

// ethers.js v6
const provider = new ethers.JsonRpcProvider("http://localhost:8545", {
  name: "agentchain",
  chainId: 7331
});
 
// Sending a transaction
const wallet = new ethers.Wallet(privateKey, provider);
const tx = await wallet.sendTransaction({
  to: "0x...",
  value: ethers.parseEther("1.0"),
  gasPrice: (await provider.getFeeData()).gasPrice
});