Skip to content
B3Pay homeB3Pay homeB3Pay

Node agent tool

A command-line tool for ICRC-1 ledgers that a person or an AI agent runs with Node 22.18 or newer (node src/cli.ts <command>, no build step). It is @ic-reactor/core with no React at all, one scenario per file:

  • Identity: a fixed Identity from a PEM file (Ed25519 or secp256k1, as icp identity export prints it) or a hex seed, else identity: "anonymous", whose writes the client refuses before sending. Give it an identity of its own that holds little and controls nothing (icp identity new agent-tool --output-seed <file>, which writes the seed phrase to a file instead of printing it, or pnpm exec icp inside the example), never one that controls a canister, and export its key outside the project, readable by you alone. An agent that runs the tool can read its environment, the seed variable included, and so can sign whatever the tool can.
  • Networks: --network ic|local|<url> onto createClient’s network. A root key is fetched only from a replica on this machine; any other URL needs the key given.
  • Many ledgers, one interface: ICP, ckBTC, ckETH or any ledger id, each client.canister<Actor>(actor, { id }) over one generated module.
  • Direct calls: info and balance call the ledger’s methods directly, in parallel; --certified reads through { id, certified: true }.
  • Writes: transfer reads the amount with parseUnits, pays the ledger’s fee and sets created_at_time. Every failure goes through isReactorError and a kind switch, with an exit code per kind. After a failure that may have executed, it reads the balance back and prints the command that re-sends the same argument, which the ledger answers Duplicate if the first went through.
  • JSON for agents: --json on every command, one document per line, bigints as decimal strings, failures as { ok: false, kind, mayHaveExecuted, message }.
  • The cache outside React: watch polls a balance through client.queryClient.fetchQuery(client.queryOptions(...)), prints only changes, and disposes the client on Ctrl-C.
  • Every failure, narrated: pnpm demo runs the same commands on createTestClient() from @ic-reactor/core/testing, with a mocked ledger: a lost reply and its deduplicated re-send, an HTTP 429 the client re-sends by itself, a canister reject, a signed-out write, and input refused before sending. No network, no funds.

Read The client and Errors and mayHaveExecuted for the rules it follows, and Testing for createTestClient(). Give an agent a canister’s tools builds the same ledger as MCP tools, step by step.

Terminal window
pnpm --filter node-agent-tool demo
cd examples/node-agent-tool
node src/cli.ts info --ledger ckbtc
node src/cli.ts balance rkp4c-7iaaa-aaaaa-aaaca-cai --certified --json
pnpm test

StackBlitz installs the example from npm and runs the demo (npm run demo) in its terminal, where npm test runs the tests. The demo and the CLI run their .ts files with Node’s type stripping, so they need Node 22.18 or later, there as on your machine. The commands that call a ledger on mainnet or on a local network, and a PEM identity from your disk, are for your own machine.

Open in StackBlitzRun the demo and the tests in your browser
View on GitHubBrowse the source code

© 2026 B3Pay. Code on GitHub.