Agent API Reference

The agent_* namespace is AgentChain's key-free API designed specifically for AI agents. Every method in this namespace handles cryptographic operations inside the node — no private keys, passwords, or signed transaction bytes ever appear in RPC requests or responses.

This is critical when agents run through LLM providers (OpenAI, Anthropic, etc.) because every RPC call may be logged by the provider. The agent API ensures that even with full logging, no sensitive key material is exposed.

Quick Start

Create a wallet and send CRD in two calls — no keys, no passwords, no setup:

Python

import requests
 
rpc = "http://localhost:8545"
 
def call(method, params=[]):
    r = requests.post(rpc, json={
        "jsonrpc": "2.0", "method": method,
        "params": params, "id": 1
    })
    return r.json()["result"]
 
# Create wallet — node generates keys internally
addr = call("agent_createWallet")
print(f"Wallet: {addr}")  # 0xAb5801a7...
 
# Start mining to earn CRD
call("agent_startMining", [addr, 1])
 
# Send 1 CRD (0xDE0B6B3A7640000 = 10^18 wei)
tx = call("agent_send", [addr, "0xRecipient...", "0xDE0B6B3A7640000"])
print(f"TX: {tx}")

JavaScript

const rpc = "http://localhost:8545";
 
async function call(method, params = []) {
  const res = await fetch(rpc, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ jsonrpc: "2.0", method, params, id: 1 }),
  });
  return (await res.json()).result;
}
 
// Create wallet — node generates keys internally
const addr = await call("agent_createWallet");
console.log("Wallet:", addr);  // 0xAb5801a7...
 
// Start mining to earn CRD
await call("agent_startMining", [addr, 1]);
 
// Send 1 CRD (0xDE0B6B3A7640000 = 10^18 wei)
const tx = await call("agent_send", [addr, "0xRecipient...", "0xDE0B6B3A7640000"]);
console.log("TX:", tx);

Methods

agent_createWallet

Creates a new wallet on the node. The node generates a cryptographically random password internally, creates the keystore account, and permanently unlocks it. The password is never returned.

Parameters: none

Returns: string — the new wallet address

Example:

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

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

agent_listWallets

Lists all wallets created through the agent API, including their current balances.

Parameters: none

Returns: array — list of {address, balance} objects (balance in hex wei)

Example:

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "address": "0x41c4d0918e3e77160c1c4b74900c161be4d808cb",
      "balance": "0x1bc16d674ec80000"
    }
  ]
}

agent_send

Sends CRD from one address to another. The node handles gas estimation, nonce management, signing, and submission automatically.

Parameters:

from (string) — sender address (must be an agent wallet)
to (string) — recipient address
value (string) — amount in wei (hex-encoded)

Returns: string — transaction hash

Common values:

1 CRD = "0xDE0B6B3A7640000" (10^18 wei)
0.1 CRD = "0x16345785D8A0000"
0.01 CRD = "0x2386F26FC10000"

Example:

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

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

agent_deployContract

Deploys a smart contract. The node signs the deployment transaction internally.

Parameters:

from (string) — deployer address (must be an agent wallet)
bytecode (string) — contract creation bytecode (hex-encoded, with 0x prefix)
value (string, optional) — CRD to send with deployment (hex wei), defaults to "0x0"

Returns: string — transaction hash (use agent_getTransactionReceipt to get the deployed contract address)

Example:

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

agent_callContract

Executes a read-only call against a deployed contract. Does not create a transaction or cost gas.

Parameters:

to (string) — contract address
data (string) — ABI-encoded function call (hex-encoded)

Returns: string — ABI-encoded return value (hex-encoded)

Example (calling balanceOf(address)):

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

agent_getBalance

Returns the balance of an address in wei.

Parameters:

address (string) — the address to query

Returns: string — balance in wei (hex-encoded)

Example:

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

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

To convert: 0x1bc16d674ec80000 = 2,000,000,000,000,000,000 wei = 2 CRD.

agent_getTransactionReceipt

Returns the receipt of a mined transaction, including contract address for deployments.

Parameters:

txHash (string) — the transaction hash

Returns: object — the transaction receipt, or null if not yet mined

Key receipt fields:

status: "0x1" (success) or "0x0" (reverted)
contractAddress: set when deploying a contract, null otherwise
gasUsed: gas consumed by the transaction
logs: array of emitted event logs

agent_startMining

Starts mining on the node. Sets the etherbase (reward address) and begins mining with the specified number of threads.

Parameters:

address (string) — etherbase address (receives block rewards)
threads (integer) — number of mining threads (use 1 for single-threaded)

Returns: true on success

Example:

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

agent_stopMining

Stops mining on the node.

Parameters: none

Returns: true on success

Example:

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

Why Not Use `personal_*`?

The standard Ethereum personal namespace works, but it is dangerous for AI agents:

| Method | What Gets Sent as a Parameter | |--------|-------------------------------| | personal_newAccount | Password in plaintext | | personal_importRawKey | Private key in plaintext | | personal_sendTransaction | Password in plaintext | | personal_unlockAccount | Password in plaintext |

If an LLM-based agent calls any of these, the key/password appears in the LLM provider's logs.

AgentChain blocks the personal namespace on HTTP/WebSocket entirely. It is only available via IPC (local socket). Use the agent_* namespace instead — it provides the same functionality with zero key exposure.

Compatibility with Standard Tools

The agent API is for LLM-based agents that should never handle keys. If you are a human developer or running a non-LLM agent that manages keys locally (e.g., using ethers.js Wallet or web3.py Account), you can still use the standard eth_sendRawTransaction method. This is safe because the key never leaves your local process.

MetaMask and other browser wallets also work normally — they sign transactions locally and submit raw transactions to the node.

Full Workflow Example

Here is a complete agent workflow: create wallet, mine CRD, send CRD, deploy a contract, and interact with it.

Python

import requests
import time
 
rpc = "http://localhost:8545"
 
def call(method, params=[]):
    r = requests.post(rpc, json={
        "jsonrpc": "2.0", "method": method,
        "params": params, "id": 1
    })
    result = r.json()
    if "error" in result:
        raise Exception(result["error"]["message"])
    return result["result"]
 
# 1. Create two wallets
alice = call("agent_createWallet")
bob = call("agent_createWallet")
print(f"Alice: {alice}")
print(f"Bob:   {bob}")
 
# 2. Mine some CRD for Alice
call("agent_startMining", [alice, 1])
print("Mining started... waiting for blocks")
time.sleep(30)  # Wait for a few blocks
call("agent_stopMining")
 
# 3. Check Alice's balance
balance = call("agent_getBalance", [alice])
print(f"Alice balance: {int(balance, 16) / 1e18} CRD")
 
# 4. Send 1 CRD from Alice to Bob
tx_hash = call("agent_send", [alice, bob, "0xDE0B6B3A7640000"])
print(f"Transfer TX: {tx_hash}")
 
# 5. Wait for confirmation and check receipt
call("agent_startMining", [alice, 1])
time.sleep(12)
receipt = call("agent_getTransactionReceipt", [tx_hash])
print(f"Status: {'success' if receipt['status'] == '0x1' else 'failed'}")
call("agent_stopMining")
 
# 6. Check Bob's balance
bob_balance = call("agent_getBalance", [bob])
print(f"Bob balance: {int(bob_balance, 16) / 1e18} CRD")

At no point does the agent see any private key, password, or signing material. Every call uses only public addresses and transaction hashes.

Agent API Reference

Quick Start

Python

JavaScript

Methods

agent_createWallet

agent_listWallets

agent_send

agent_deployContract

agent_callContract

agent_getBalance

agent_getTransactionReceipt

agent_startMining

agent_stopMining

Why Not Use personal_*?

Compatibility with Standard Tools

Full Workflow Example

Python

Why Not Use `personal_*`?