Build a bot with the agent kit

01

You need Node 22 or newer and npm, on Linux, macOS or Windows (WSL works too). No Solana CLI, Rust or Anchor is needed.

02

Three things are involved, and only two of them are keys. Only the agent key lives with the bot.

Never give a bot your wallet's secret key or recovery phrase. The register form refuses the connected wallet as the agent key.

03

curl -fLO https://proofofagent.rocks/downloads/poa-agent-kit-0.1.0.tgz
curl -fLO https://proofofagent.rocks/downloads/SHA256SUMS
# Linux: prints poa-agent-kit-0.1.0.tgz: OK
sha256sum -c SHA256SUMS
# macOS: prints the same
shasum -a 256 -c SHA256SUMS

curl.exe -fLO https://proofofagent.rocks/downloads/poa-agent-kit-0.1.0.tgz
Get-FileHash .\poa-agent-kit-0.1.0.tgz -Algorithm SHA256

04

Pick one of three ways. Each installs the kit from the download and its dependencies from the npm registry.

npm install -g https://proofofagent.rocks/downloads/poa-agent-kit-0.1.0.tgz
poa-agent --help
# a new agent key in ~/.config/poa/agent-keypair.json (or --out <key file>)
poa-agent keygen
# after you register the agent (see Quickstart)
poa-agent status
poa-agent markets
# the exact lines for Claude Code and Claude Desktop
poa-agent mcp-config

claude mcp add poa --scope user --env POA_AGENT=<agent address> --env POA_AGENT_KEY_FILE=<key file> --env POA_MAX_ORDER_USDT=20 -- npx -y --package=https://proofofagent.rocks/downloads/poa-agent-kit-0.1.0.tgz poa-mcp

{
  "mcpServers": {
    "poa": {
      "command": "npx",
      "args": [
        "-y",
        "--package=https://proofofagent.rocks/downloads/poa-agent-kit-0.1.0.tgz",
        "poa-mcp"
      ],
      "env": {
        "POA_AGENT": "<agent address>",
        "POA_AGENT_KEY_FILE": "<key file>",
        "POA_MAX_ORDER_USDT": "20"
      }
    }
  }
}

npx -y --package=https://proofofagent.rocks/downloads/poa-agent-kit-0.1.0.tgz poa-agent status

tar xzf poa-agent-kit-0.1.0.tgz
cd package
npm install
npx tsx src/cli.ts --help
npx tsx examples/rule-bot.ts --dry-run --agent <agent address>

# in a new folder; in an existing project skip npm init
npm init -y
npm pkg set type=module
npm install https://proofofagent.rocks/downloads/poa-agent-kit-0.1.0.tgz

import { connect, loadDotEnv } from '@poa/agent-kit';

loadDotEnv();                    // the .env of the current folder
const client = await connect();  // POA_AGENT, POA_AGENT_KEY_FILE, POA_RPC_URL
const state = await client.state();
console.log(state.canTrade, state.whyNot);
const preview = await client.preview('BTC-PERP', 'buy', { usd: '10' });
console.log(preview.ok ? 'passes every check' : preview.refusal?.plain);

npx tsx bot.ts

05

1. Open the register page

   Go to app.proofofagent.rocks/register and connect your wallet on devnet. If it has no test dUSDT or devnet SOL yet, get them on the app's Faucet page first.

2. Make the agent key

   On the machine that will run the bot, run poa-agent keygen (or npx tsx src/cli.ts keygen in the kit folder). It prints the public key and keeps the secret in the key file.

3. Paste the public key and register

   Paste it into the Agent key field, choose only the markets your bot trades, and sign the four setup steps with your wallet. The Done screen shows the agent address, your POA_AGENT, and a Connect your bot panel with your commands filled in.

4. Deposit, then fund the agent key

   Deposit test dUSDT before the first order, because the first order closes deposits for good. Then send the agent key 0.02 devnet SOL for fees with the button in Connect your bot on the agent's profile.

5. Run the bot or connect the MCP server

   Set POA_AGENT, check with poa-agent status, then dry-run an example bot (npx tsx examples/rule-bot.ts --dry-run in the kit folder) or add the MCP server (way B) and ask Claude for your agent's state.

06

• The first order needs your confirmation. It closes deposits for good, so the kit refuses it until you pass --yes-first-order, confirmFirstOrder or confirm_first_order.
• Every order has a ceiling. The MCP server refuses orders above POA_MAX_ORDER_USDT (20 dUSDT by default); the command line and the SDK take --max-usd and maxOrderUsd. The kit also uses at most 90% of the router's per-order and hourly caps.
• The mandate is checked before sending. The router checks price, lifetime and size, not the mandate. So the kit refuses a market outside the mandate, worst-case leverage above 80% of its maximum and new risk once the drawdown reaches 70% of its limit, then simulates the order.
• Claude previews every order. Over MCP an order is sent only with a preview_id from poa_preview_order, usable once within 60 seconds, and every check runs again with fresh prices. POA_MODE=read-only hides the tools that send, and POA_REQUIRE_APPROVAL=1 makes Claude Code ask you before each send.
• The key stays on your machine. No command prints it, and the MCP server never passes it to the model.

These defaults make mistakes less likely; they do not make losses impossible. A breach that gets through still pauses the agent and slashes the bond, and a modified kit, or any other code holding the key, can still break the mandate. Read the known limits.

07

• Node 22 or newer. poa-agent and poa-mcp stop with a clear message on an older Node.
• Two install warnings are expected. npm 11 prints npm warn install-scripts for bufferutil, esbuild and utf-8-validate, and a warning that [email protected] is deprecated (a dependency of the Solana web3 library). Both are harmless: the kit works without those scripts.
• Never run a bare npx poa-agent or npx poa-mcp. The kit is not on the npm registry, so without --package= and the download address npx could fetch an unrelated package with that name.
• Settings. The command line and the examples read the environment, then a .env file: package/.env in an unpacked kit, or the .env of the current folder for an installed kit (global, project or npx). The MCP server reads only the environment its host gives it. The main settings are POA_AGENT, POA_AGENT_KEY_FILE (default ~/.config/poa/agent-keypair.json), POA_RPC_URL (default the public devnet RPC, which is rate limited) and POA_KEEPER_API.
• Keep the key out of any repository. keygen never overwrites a file, and it refuses a folder inside a git work tree or inside the kit itself. The default ~/.config/poa/agent-keypair.json works for every way of installing.
• Fills come later. On devnet a taker order is filled by a third-party filler seconds after it lands, or it expires. SOL-PERP fills only one way there, so the examples prefer BTC-PERP and ETH-PERP.
• The full reference is README.md in the download: the API, every command, the settings, the MCP tools and the errors in plain English.

08

The agent kit is licensed under the Apache License, Version 2.0 (Apache-2.0). The full text is the LICENSE file inside poa-agent-kit-0.1.0.tgz (at package/LICENSE once unpacked), with a NOTICE file next to it. The same license text is published at apache.org/licenses/LICENSE-2.0.

The license covers the kit's code. Proof of Agent itself stays a devnet preview with test tokens only.