Agent API Reference

The agent namespace is served by a NetZero node only on loopback (127.0.0.1). It gives whoever can reach the node full control of the node's wallets, which is exactly what an agent running next to its own node wants and exactly what a public RPC must never offer.

All methods are JSON-RPC 2.0 over HTTP. Amounts are hex-encoded wei (1 USDn = 0xDE0B6B3A7640000).

Wallets

agent_createWallet() → address

Generates a key inside the node, encrypts it with a password derived from the node secret (<datadir>/netzero/agent-secret, created on first use), unlocks it, and returns the address. The key and password never leave the node. Back up the data directory: it is the wallet.

agent_listWallets() → [{address, balance, status}]

All keystore accounts with balance (wei) and "Unlocked" / "Locked".

agent_getBalance(address) → wei

Sending

agent_send(from, to, value) → txHash

Sends value wei of USDn. Gas, gas price and nonce are filled in. A locked agent wallet is unlocked on demand with its derived password (this is how wallets survive restarts).

agent_sendTransaction(from, to, value, data, gas?) → txHash

Any transaction: contract calls with calldata, optional gas limit.

agent_getTransactionReceipt(hash) → receipt or null

Standard receipt fields plus contractAddress for deployments. null while pending. Combine with eth_getBlockByNumber("finalized") to know when it is final.

Contracts

agent_deployContract(from, bytecode, value?) → txHash

Deploys creation bytecode; the receipt carries contractAddress.

agent_callContract(to, data) → returnData

Read-only call at the latest block. Reverts are returned as errors with the revert reason.

Mining

agent_startMining(address, threads?) → true

Starts the share miner paying to address (default 1 thread). The node hashes for mining shares, gossips them to the validators, and the protocol credits address directly, no transaction needed. Live on the public testnet from block 29400.

agent_stopMining() → true

agent_getMiningStatus() → {mining, etherbase, threads, hashrate, shareDifficulty, sharesFound, sharesPaid, earnedWei, pendingShares, currentBlock, sharesActive, sharesStartBlock}

Node

agent_shutdown() → true

Stops the node gracefully a moment after returning, flushing state to disk. Use this instead of killing the process; a killed node rewinds to its last flushed state on restart.

Errors

Security model in one paragraph

Whoever controls the data directory controls the wallets: the node secret plus the keystore files are the keys. Keep the directory private, back it up, and never expose the agent namespace beyond the machine (or container) the agent runs on. Everything the agent sees over RPC is safe to log.

Example: full loop

const rpc = (method, params = []) =>
  fetch("http://127.0.0.1:8545", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ jsonrpc: "2.0", method, params, id: 1 }),
  }).then((r) => r.json()).then((j) => { if (j.error) throw new Error(j.error.message); return j.result; });
 
const me = await rpc("agent_createWallet");
await rpc("agent_startMining", [me, 2]);
const tx = await rpc("agent_send", [me, "0xCounterparty", "0x2386F26FC10000"]); // 0.01 USDn
let receipt = null;
while (!(receipt = await rpc("agent_getTransactionReceipt", [tx]))) await new Promise((r) => setTimeout(r, 1000));
const final = await rpc("eth_getBlockByNumber", ["finalized", false]);
console.log("included in", parseInt(receipt.blockNumber, 16), "final head", parseInt(final.number, 16));