Command line

In plain words

The command line is a way to use your agent's bank by typing short commands into a terminal: the text window called Terminal on a Mac, PowerShell on Windows. Each command does one thing: show the balance, deposit, withdraw, give a budget.

Use it to try H081 by hand, to check on your agent, or to run small scripts. Every command that moves money first shows a plan (the fee, what arrives, what the public can see) and sends nothing. You add --yes only when the plan looks right.

Everything runs on your computer, with a key stored on your computer. The only thing H081 runs for you is the relayer that sends withdrawals.

How a command works

You need Node.js 20.11 or newer. Nothing else to install: npx, which comes with Node.js, downloads the package the first time and runs it.

Type the command without --yes
You get the plan. Nothing is proven, signed or sent.
any terminal
```
npx -y @h081lll/agent deposit 5
```
what it prints (an illustration)
```
Plan (nothing was sent):
  deposit 5 USDG
  sent by: agent key; SOL needed: 0.02
  proof: transact (download 15 MB)
  public on chain: agent wallet, amount
  ! A deposit is public: the chain shows the agent wallet and the amount. What happens inside the bank afterwards is private.
Add --yes to send it.
```
Read the plan
Check the amount, the fee, what arrives and the lines marked !. They tell you what the public chain will show.
Run it again with --yes
Now it is sent. It prints Sent. and the result, with the transaction signature.
any terminal
```
npx -y @h081lll/agent deposit 5 --yes
```

A shorter name

These docs write npx -y @h081lll/agent so every line works as it is. If you use it a lot, install it once and type h081 instead.

any terminal

npm install -g @h081lll/agent
h081 balance

The built-in help lists every command:

any terminal

npx -y @h081lll/agent --help

All commands at a glance

Command	What it does	Sends?
`init`	Make the agent key and settings	No (offline)
`address`	The wallet and the address code	No (offline)
`info`	Facts about the bank and this setup	No
`fetch-circuits`	Download the proving files	No
`backup`, `restore`	The key as a code, and back	No
`token`	The local API password	No
`balance`	How much money there is	No
`history`	What this computer sent	No
`fee`	What a withdrawal costs	No
`check`	Check an `h081-` code	No (offline)
`deposit`	Wallet into the bank	With `--yes`
`withdraw`	Bank to any wallet	With `--yes`
`pay`	Pay from a budget	With `--yes`
`transfer`	Pay another H081 account privately	With `--yes`
`allow`	Give a budget	With `--yes`
`reclaim`	Take a budget back	With `--yes`
`loan`	Borrow: quote, borrow	borrow, with `--yes`
`lend`	Lend: open, fund, status, claim, collect, settle	With `--yes`
`stake`	Stake H081 for bigger withdrawals	With `--yes`
`serve`	Start the local API	Only what a program confirms
`openapi`	Print the API description	No
`mcp`	The bank as tools for Claude	Only what Claude confirms

Set up and keep your key safe

Make the key, see the address, back it up. None of these move money.

`init`

Creates the agent's own key and settings, offline. It prints the wallet address to fund, the h081-address: code others pay you with, and the exact line that connects Claude. Run it again any time: it keeps the key it already has.

npx -y @h081lll/agent init [--rpc <url>] [--cluster mainnet-beta|localnet]

--rpc <url>: Your Solana RPC address (an http or https URL), saved in config.json. Default: the public mainnet RPC, which is slow and often busy.
--cluster: mainnet-beta (the default) or localnet (only for tests on your own validator).

example

npx -y @h081lll/agent init --rpc <your Solana RPC URL>

what it prints (an illustration; your addresses and numbers differ)

Agent key created: /home/you/.h081/agent.json (only you can read it)
Agent wallet: 7xKX…pQ3
Address code (others pay you privately with it): h081-address:…
Config: /home/you/.h081/config.json (mainnet-beta, RPC your-rpc-host)
API token: /home/you/.h081/api-token

Next: send 0.05 SOL and a few USDG to 7xKX…pQ3 (0.15 SOL if you will grant budgets or lend).
Then: npx -y @h081lll/agent deposit 5 --yes

For Claude Code:
  claude mcp add --scope user h081 -e H081_SOLANA_KEYPAIR=/home/you/.h081/agent.json -e H081_RPC_URL=<your RPC> -- npx -y @h081lll/agent mcp

It writes ~/.h081/agent.json (the key), ~/.h081/config.json and ~/.h081/api-token. The second time, it prints "key already exists at <path>, keeping it".

`address`

Shows the agent's public wallet (where you send SOL and USDG) and its h081-address: code (what you give someone so they can pay the agent privately, or give it a budget). Offline.

npx -y @h081lll/agent address

example

npx -y @h081lll/agent address

what it prints (an illustration; your addresses and numbers differ)

Agent wallet: 7xKX…pQ3
Address code: h081-address:…

`info`

Facts about the bank and this setup: the network, the deposit caps, the relayer, where the key comes from, which RPC host is used (never the full URL) and how much SOL each kind of use needs. Prints JSON.

npx -y @h081lll/agent info

example

npx -y @h081lll/agent info

`fetch-circuits`

Downloads the proving files (about 98 MB, once) and checks each one against a fixed fingerprint (a sha256 hash). Every proof needs them. You never have to run this, because the first proof downloads them on its own. Run it ahead of time so your first payment does not wait, or when a file is damaged.

npx -y @h081lll/agent fetch-circuits

example

npx -y @h081lll/agent fetch-circuits

The files go to ~/.h081/circuits. It ends with "all hashes match", or stops with an error and uses nothing.

`backup`

Prints the agent key as an h081-key: code: letters and digits with a checksum and the network built in, so a typo is caught. Anyone with this code controls the agent's money. Write it down or store it offline. Command line only: the API, the SDK and Claude cannot read it.

npx -y @h081lll/agent backup

example

npx -y @h081lll/agent backup

what it prints (an illustration; your addresses and numbers differ)

h081-key:…
Anyone with this code controls the agent's funds. Store it offline.

`restore`

Puts a key back from an h081-key: code, for example on a new computer. It checks the code first. It never replaces a key that is already there unless you add --force.

npx -y @h081lll/agent restore <code> [--force]

<code>: The h081-key: code that backup printed.
--force: Replace the key already in agent.json. Back that key up first, or its money is lost.

example

npx -y @h081lll/agent restore <your h081-key: code>

what it prints (an illustration; your addresses and numbers differ)

check: agent key code, mainnet-beta, checksum ok
Restored /home/you/.h081/agent.json: agent wallet 7xKX…pQ3

`token`

Prints the password (the "API token") your programs send to the local API. --rotate makes a new one, which locks out every program that had the old one.

npx -y @h081lll/agent token [--rotate]

--rotate: Replace the token. Restart serve afterwards and update your scripts.

example

npx -y @h081lll/agent token

Look things up

Read-only: these never send anything.

`balance`

How much money there is: the private (shielded) balance inside the bank, the public USDG and SOL in the agent wallet, and every budget (allowance) with its id.

npx -y @h081lll/agent balance [--fresh]

--fresh: Skip the 15-second balance cache. Each command-line run starts fresh anyway, so this matters mostly for the local API and the SDK.

example

npx -y @h081lll/agent balance

what it prints (an illustration; your addresses and numbers differ)

Shielded: 3 USDG
Wallet:   0 USDG, 0.04 SOL
Allowance 12345: 4.5 USDG left (sub-account 1)
Address code: h081-address:…

`history`

What this computer has sent, newest first: time, kind, amount, state and the transaction signature. It reads ~/.h081/ops.jsonl, so it only knows what was sent from here, and records older than 7 days are dropped.

npx -y @h081lll/agent history [--limit N] [--after <id>]

--limit N: How many lines, 1 to 200. Default 50.
--after <id>: The next page: the value printed after "more: --after".

example

npx -y @h081lll/agent history --limit 5

what it prints (an illustration; your addresses and numbers differ)

2026-11-10T14:02:11.000Z  withdraw          2  done    5hQ…
2026-11-10T13:58:40.000Z  deposit           5  done    3vR…

`fee`

What a withdrawal of this amount would cost and how much arrives. Nothing is proven or sent. The relayer fee is the larger of 0.05 USDG and 0.20% of the amount.

npx -y @h081lll/agent fee <usdg>

example

npx -y @h081lll/agent fee 2

what it prints (an illustration; your addresses and numbers differ)

Fee: 0.05 USDG; the recipient gets 1.95 USDG (relayer https://api.h081.xyz)

If the recipient has no USDG account yet (a fresh wallet usually has none), it also says how much the relayer adds to create one, so less arrives. Above 100 USDG it says the relayer needs H081 staked (see stake).

`check`

Checks any code that starts with h081- before you use it: what kind it is (address, key, loan terms, loan proof), which network it was made for, and whether its checksum is right. Offline. It ends with exit code 1 when the code is not valid, so scripts can test it.

npx -y @h081lll/agent check <code>

example

npx -y @h081lll/agent check <an h081-address: code>

what it prints (an illustration; your addresses and numbers differ)

valid address code for mainnet-beta

Move money

Each of these shows a plan first and sends only with --yes.

`deposit`

Moves USDG from the agent's public wallet into its private bank balance. A deposit is public: the chain shows the agent wallet and the amount. What happens inside the bank afterwards is private.

npx -y @h081lll/agent deposit <usdg> [--yes]

1 · the plan (nothing is sent), 2 · send it

npx -y @h081lll/agent deposit 5
npx -y @h081lll/agent deposit 5 --yes

Caps on mainnet: 1,000 USDG per deposit and 10,000 USDG in the bank in total. Needs about 0.02 SOL in the agent wallet for fees.

`withdraw`

Takes USDG out of the bank to any wallet. By default the H081 relayer sends it, so the chain shows who received how much but not that it came from your agent. Send it to a fresh wallet, never to the one that deposited.

npx -y @h081lll/agent withdraw <usdg> --to <wallet|self> [--direct] [--yes]

--to <wallet>: Required. A Solana wallet address. self sends it to the agent wallet itself (that links the two; the plan warns you).
--direct: The agent key sends it instead of the relayer: no relay fee and no 100 USDG limit, but the chain shows the agent wallet as the sender.

1 · the fee, 2 · the plan (nothing is sent), 3 · send it

npx -y @h081lll/agent fee 2
npx -y @h081lll/agent withdraw 2 --to <a wallet that never touched the agent>
npx -y @h081lll/agent withdraw 2 --to <a wallet that never touched the agent> --yes

what it prints (an illustration; your addresses and numbers differ)

Plan (nothing was sent):
  withdraw 2 USDG to <a wallet that never touched the agent>
  fee: 0.05 USDG
  arrives: 1.95 USDG
  sent by: relayer; SOL needed: 0
  proof: transact (download 0 MB (already downloaded))
  public on chain: recipient, amount received
Add --yes to send it.

Up to 100 USDG per withdrawal with nothing staked. If the relayer cannot be reached or refuses, nothing is sent and the error says why: the agent key never sends it in its place unless you ask with --direct.

`pay`

Pays someone from a budget (an allowance) this agent holds, inside that budget's limits. Pay a wallet (a public payout, sent by the relayer) or an h081-address: code (a private payment: the amount and the recipient stay hidden).

npx -y @h081lll/agent pay <usdg> (--to <wallet> | --to-code <h081-address:...>) [--allowance <id>] [--agent-index N] [--direct] [--allow-pledged] [--yes]

--to <wallet>: Pay a Solana wallet. Fee: the larger of 0.05 USDG and 0.20%.
--to-code <code>: Pay an h081-address: code privately. Give --to or --to-code, not both.
--allowance <id>: Which budget to pay from (the id balance shows). Default: one whose limits allow this amount now.
--agent-index N: Pay from a budget your sub-account N holds.
--direct: With --to: the agent key sends it (no fee, but the agent wallet shows as the sender).
--allow-pledged: Also use a budget pledged to a loan. That puts the loan next to the payment on chain, so it is off by default.

1 · the plan (nothing is sent), 2 · send it

npx -y @h081lll/agent pay 0.5 --to-code <their h081-address: code> --agent-index 1
npx -y @h081lll/agent pay 0.5 --to-code <their h081-address: code> --agent-index 1 --yes

When no budget can pay, the error allowance_blocked names the limit that stopped it, and nothing is sent.

`transfer`

Pays from the main private balance to another H081 account, using its h081-address: code. The amount and the recipient stay hidden; the chain only shows that the agent wallet used the bank.

npx -y @h081lll/agent transfer <usdg> --to-code <h081-address:...> [--yes]

--to-code <code>: Required. The other account's h081-address: code. Check it first with check.

1 · check the code, 2 · the plan, 3 · send it

npx -y @h081lll/agent check <their h081-address: code>
npx -y @h081lll/agent transfer 1 --to-code <their h081-address: code>
npx -y @h081lll/agent transfer 1 --to-code <their h081-address: code> --yes

Budgets for other agents

Give a sub-account or another agent money to spend, with limits.

`allow`

Gives a budget (an allowance) out of your private balance to one of your sub-accounts, or to another agent. The limits are checked on every payment, and you can take back what is left at any time with reclaim.

npx -y @h081lll/agent allow <usdg> [--daily-cap X] [--max-per-tx X] [--days N] [--unlock-days N] [--agent-index N] [--to-code C] [--yes]

<usdg>: The whole budget, in USDG.
--daily-cap X: At most X USDG per day.
--max-per-tx X: At most X USDG per payment.
--days N: The budget ends after N days. Default: no end.
--unlock-days N: The budget becomes spendable bit by bit over N days instead of all at once.
--agent-index N: Give it to your sub-account N. Default: the first free one.
--to-code C: Give it to another agent, by its h081-address: code.

1 · the plan (nothing is sent), 2 · send it

npx -y @h081lll/agent allow 5 --daily-cap 1 --max-per-tx 0.5 --days 30 --agent-index 1
npx -y @h081lll/agent allow 5 --daily-cap 1 --max-per-tx 0.5 --days 30 --agent-index 1 --yes

Needs about 0.15 SOL in the agent wallet (most of it is refunded). The chain shows that the agent wallet made a grant, not the amount, the limits or who got it. More on Allowances.

`reclaim`

Takes back what is left of a budget you gave, into your private balance.

npx -y @h081lll/agent reclaim <id> [--yes]

<id>: The budget's id from balance. It changes after every payment, so read balance again just before.

1 · the current id, 2 · the plan, 3 · send it

npx -y @h081lll/agent balance --fresh
npx -y @h081lll/agent reclaim 12345
npx -y @h081lll/agent reclaim 12345 --yes

Loans and staking

Advanced. Plan first, --yes to send, like everything else.

`loan`

The borrower's side. loan quote prices a loan from a lender's h081-loan-terms: code: the most you can borrow, the 0.25% origination fee and what you receive. loan borrow pledges a budget to that lender and prints an h081-loan-proof: code to give back to them. Nothing is borrowed until the lender funds it.

npx -y @h081lll/agent loan quote <termsCode> [--principal X]npx -y @h081lll/agent loan borrow <termsCode> --days N --unlock-days N [--principal X] [--budget X] [--daily-cap X] [--max-per-tx X] [--agent-index N] [--yes]

--days N: Required for borrow. How long the pledged budget lasts, in days.
--unlock-days N: Required for borrow. The budget unlocks over this many days (no more than --days).
--principal X: Borrow exactly X USDG. The lender can fund this amount and nothing else.
--budget X: The pledged budget. With --principal it is sized for you, and a bigger one is refused.
--daily-cap X, --max-per-tx X, --agent-index N: Limits and sub-account for the pledged budget, as in allow.

1 · the price, 2 · the plan, 3 · pledge and get the proof code

npx -y @h081lll/agent loan quote <h081-loan-terms: code> --principal 10
npx -y @h081lll/agent loan borrow <h081-loan-terms: code> --days 30 --unlock-days 30 --principal 10
npx -y @h081lll/agent loan borrow <h081-loan-terms: code> --days 30 --unlock-days 30 --principal 10 --yes

Step by step, for both sides, on Loans.

`lend`

The lender's side. Open a loan slot and hand out its terms code, fund it against the borrower's proof code, then collect repayments. A lender can never receive more than the principal: anything paid beyond it goes back to the borrower's payout account.

npx -y @h081lll/agent lend open --pledge-bps N [--yes]npx -y @h081lll/agent lend fund <proofCode> [--principal X] [--loan-ref N] [--yes]npx -y @h081lll/agent lend status [--loan-ref N]npx -y @h081lll/agent lend claim <loanRef> [--usdg X] [--yes]npx -y @h081lll/agent lend collect <loanRef> [--yes]npx -y @h081lll/agent lend settle <loanRef> [--yes]

open: Opens a slot and gives its h081-loan-terms: code. --pledge-bps N (100 to 9000) is your share of each borrower payment: 2000 means 20%.
fund: Checks the borrower's h081-loan-proof: code and pays the principal from the agent wallet's public USDG. The borrower receives it minus the 0.25% fee. The principal is exactly what the proof backs: --principal X is only a check, and funding is refused if X is a different amount.
status: Your slots: funded, repaid, still owed, claimable, collectable.
claim: Pulls your share of what the borrower's budget has paid, never more than the loan still owes. --usdg X claims at most X.
collect: Takes repayments already sent to the slot.
settle: Closes the books on a loan.

open, fund, check, claim (each: the plan first, then --yes)

npx -y @h081lll/agent lend open --pledge-bps 2000
npx -y @h081lll/agent lend open --pledge-bps 2000 --yes
npx -y @h081lll/agent lend fund <h081-loan-proof: code>
npx -y @h081lll/agent lend fund <h081-loan-proof: code> --yes
npx -y @h081lll/agent lend status --loan-ref 3
npx -y @h081lll/agent lend claim 3
npx -y @h081lll/agent lend claim 3 --yes

The loan program needs the slot owner's signature, so the agent key sends every lender action: the agent wallet is public as the lender, and so are the principal and the borrower's payout account.

`stake`

Stakes H081 tokens from the agent wallet. You only need this to withdraw more than 100 USDG at a time through the relayer: what you stake sets how much it relays for you per 30 days. Unstaking takes a 30-day wait.

npx -y @h081lll/agent stake viewnpx -y @h081lll/agent stake stake <h081> [--yes]npx -y @h081lll/agent stake request-unstake <h081> [--yes]npx -y @h081lll/agent stake unstake [--yes]

view: What is staked and what is waiting to unstake.
stake <h081>: Stake this many H081 (at most 100,000 per stake).
request-unstake <h081>: Start the 30-day wait.
unstake: Take it back after the wait.

look, plan, send

npx -y @h081lll/agent stake view
npx -y @h081lll/agent stake stake 1000
npx -y @h081lll/agent stake stake 1000 --yes

Staking names the agent wallet to the relayer as the one whose withdrawals use that capacity.

Run it for programs and Claude

The same bank, for code (the local API) and for AI apps (MCP).

`serve`

Starts the local API on http://127.0.0.1:8081/v1, so programs in any language can use the bank. Only programs on this computer can reach it, and they need the token. Leave the window open; Ctrl+C stops it.

npx -y @h081lll/agent serve [--port 8081] [--poll 20] [--allow-origin <url>]

--port N: The port. Default 8081 (or H081_API_PORT).
--poll N: How often, in seconds, live updates re-read the balance while a program listens to /v1/events. Default 20.
--allow-origin <url>: The one web page origin allowed to call it from a browser, matched exactly. Default: none.

example

npx -y @h081lll/agent serve

what it prints (an illustration; your addresses and numbers differ)

H081 gateway 0.1.0 on http://127.0.0.1:8081/v1 (mainnet-beta, agent 7xKX…pQ3, RPC your-rpc-host)
token: /home/you/.h081/api-token   docs: http://127.0.0.1:8081/v1/openapi.json   …

It always listens on 127.0.0.1 only; there is no option to open it to the network. It downloads the proving files in the background so the first proof does not wait.

`openapi`

Prints the OpenAPI document: a machine-readable description of every API route, for code generators and API tools. The same file is on this site.

npx -y @h081lll/agent openapi

example

npx -y @h081lll/agent openapi > h081-openapi.json

`mcp`

Runs the bank as tools for Claude and other AI apps (an "MCP server"). You do not run this by hand: Claude starts it. Use it with Claude shows the setup.

npx -y @h081lll/agent mcp

connect Claude Code (macOS, Linux)

claude mcp add --scope user h081 -e H081_SOLANA_KEYPAIR=<absolute path to ~/.h081/agent.json> -e H081_RPC_URL=<your RPC> -- npx -y @h081lll/agent mcp

On Windows (not WSL) the end of the line is -- cmd /c npx -y @h081lll/agent mcp. The line init prints already has your real path and the right ending.

Flags every command takes

--yes (or -y): Send it. Without it, a command that moves money prints the plan and sends nothing.
--json: Print the same JSON "envelope" as the local API on stdout, and the log lines on stderr. Use it in scripts.
--home <dir>: Use another data folder instead of ~/.h081: one folder per agent, each with its own key.
--cluster mainnet-beta|localnet: The network. mainnet-beta is real money; localnet is only for tests on your own validator.
--idempotency-key <k>: A name you choose for this one send (1 to 128 of A-Z a-z 0-9 _ . : -). Run the same command with the same key again and it is not sent twice: you get the first result back. Default: a new random key on every run.
--help (or -h): The list of commands.

JSON output

With --json, stdout carries exactly one JSON object. ok says whether it worked; status is plan (nothing sent), sent, or done (a read).

any terminal

npx -y @h081lll/agent withdraw 2 --to <fresh wallet> --json

stdout (an illustration)

{
  "ok": true,
  "network": "mainnet-beta",
  "status": "plan",
  "result": {
    "op": "withdraw", "usdg": "2", "to": "<fresh wallet>", "fee": "0.05", "payout": "1.95",
    "solNeeded": "0", "circuit": "transact", "download": "15 MB",
    "publicOnChain": ["recipient", "amount received"], "sentBy": "relayer", "warnings": [],
    "next": "Nothing was sent. Send it again with confirm: true (CLI: --yes) to do it."
  }
}

stdout when it fails (exit code 1)

{
  "ok": false,
  "network": "mainnet-beta",
  "error": { "code": "needs_sol", "message": "…", "retryable": false, "details": { "needSol": "…" } }
}

Every error code is explained on Errors and fixes.

Retrying without paying twice

If a send is cut off (the network drops, the window closes) and you are not sure it went out, run it again with the same --idempotency-key. If it already went out, you get the stored result instead of a second payment. The records are kept for 7 days.

any terminal

npx -y @h081lll/agent withdraw 2 --to <fresh wallet> --yes --idempotency-key wd-2026-11-11-a

what it prints the second time (an illustration)

Already sent earlier with this idempotency key (wd-2026-11-11-a):
{
  "signature": "5hQ…",
  "receivedUsdg": "1.95",
  …
}

Two agents on one computer

--home keeps each agent in its own folder, with its own key, settings and token.

any terminal

npx -y @h081lll/agent init --home ~/agent-two --rpc <your Solana RPC URL>
npx -y @h081lll/agent balance --home ~/agent-two

Exit codes

Scripts can tell what happened from the exit code alone.

Code	Meaning
`0`	It worked: a plan was printed, something was sent, or a read answered.
`1`	An error, for example not enough SOL or an unreachable relayer. With `--json`, stdout carries the error envelope. `check` also ends with 1 when the code is not valid.
`2`	Wrong usage: an unknown command, a missing argument or a bad flag value. Nothing was tried.

Scripting the command line

The same small job three ways: withdraw 2 USDG to a fresh wallet if the private balance has at least 2, with one idempotency key per day so a re-run never pays twice. In TypeScript, use the SDK instead of calling the command line.

macOS / Linux (bash)

#!/usr/bin/env bash
# Withdraw 2 USDG if the private balance has at least 2. Needs jq.
set -euo pipefail
shielded=$(npx -y @h081lll/agent balance --json | jq -r '.result.shielded')
if awk "BEGIN{exit !($shielded >= 2)}"; then
  npx -y @h081lll/agent withdraw 2 --to <fresh wallet> --yes --json --idempotency-key "wd-$(date +%Y%m%d)"
else
  echo "only $shielded USDG in the bank" >&2
fi

Windows PowerShell

# Withdraw 2 USDG if the private balance has at least 2.
$b = npx -y @h081lll/agent balance --json | ConvertFrom-Json
if ([decimal]$b.result.shielded -ge 2) {
  $key = "wd-" + (Get-Date -Format yyyyMMdd)
  $r = npx -y @h081lll/agent withdraw 2 --to <fresh wallet> --yes --json --idempotency-key $key | ConvertFrom-Json
  if ($r.ok) { "sent: " + $r.result.signature } else { "error: " + $r.error.code }
} else {
  "only $($b.result.shielded) USDG in the bank"
}

Python (subprocess)

import datetime, json, os, subprocess

def h081(*args):
    p = subprocess.run(["npx", "-y", "@h081lll/agent", *args, "--json"],
                       capture_output=True, text=True, shell=(os.name == "nt"))
    out = json.loads(p.stdout)          # stdout is always the JSON envelope; logs go to stderr
    if not out["ok"]:
        raise RuntimeError(out["error"]["code"] + ": " + out["error"]["message"])
    return out["result"]

if float(h081("balance")["shielded"]) >= 2:
    key = "wd-" + datetime.date.today().strftime("%Y%m%d")
    r = h081("withdraw", "2", "--to", "<fresh wallet>", "--yes", "--idempotency-key", key)
    print("sent:", r["signature"])

Environment variables

Settings come from the environment first, then ~/.h081/config.json, then the mainnet defaults. Most people never set any of these: init writes what you need.

macOS / Linux (bash)

H081_RPC_URL=https://YOUR-RPC-URL H081_MAX_PAY=1000000 npx -y @h081lll/agent balance

Windows PowerShell

$env:H081_RPC_URL = "https://YOUR-RPC-URL"
$env:H081_MAX_PAY = "1000000"
npx -y @h081lll/agent balance

Variable	Default	What it does
`H081_HOME`	`~/.h081`	The data folder (the same as `--home`).
`H081_SOLANA_KEYPAIR`	`~/.h081/agent.json`	The path to the agent key file.
`H081_SOLANA_KEY`	none	The key itself instead of a file. `H081_SOLANA_KEYPAIR` wins when both are set.
`H081_RPC_URL`	from config.json, else the public mainnet RPC	Your Solana RPC. Only its host name is ever shown or logged.
`H081_CLUSTER`	`mainnet-beta`	`mainnet-beta`, or `localnet` for tests.
`H081_API_PORT`	`8081`	The local API's port.
`H081_API_TOKEN_FILE`	`$H081_HOME/api-token`	Where the API token is kept.
`H081_API_MAX_SENDS_PER_MIN`	`30`	At most this many sends a minute from this computer.
`H081_MAX_DEPOSIT`	none	The largest deposit, in base units (1 USDG = 1000000). Checked before anything is proven.
`H081_MAX_PAY`	none	The largest payment, in base units.
`H081_MAX_GRANT`	none	The largest budget you can give, in base units.
`H081_MAX_LEND`	none	The largest loan you can fund, in base units.
`H081_RELAYER_URL`, `H081_CIRCUITS_DIR`, `H081_CIRCUITS_URL`, `H081_USDG_MINT`	mainnet	Overrides for a test validator. Leave them alone on mainnet.

Files in ~/.h081

Everything the agent keeps lives in one folder: ~/.h081 on macOS and Linux, the .h081 folder in your user folder on Windows (or wherever H081_HOME points). Only your user can read it.

File	What it is	Private?
`agent.json`	The agent key (a Solana keypair file). It also unlocks the private balance and the sub-accounts.	Yes. Whoever has it has the money. Back it up with backup.
`config.json`	The network, your RPC URL and the port, written by `init`.	Yes: an RPC URL can hold your RPC provider's key.
`api-token`	The local API password.	Yes.
`ops.jsonl`	What this computer sent, and the idempotency records (kept 7 days).	Yes.
`cache`, `circuits`	Public chain data and the proving files.	No. They come back if deleted.

New here? The 5-minute quickstart does a first private payment end to end. The package is @h081lll/agent on npm. Questions: @H081CAP on X.

How a command works

Type the command without --yes

Read the plan

Run it again with --yes

All commands at a glance

Set up and keep your key safe

init

address

info

fetch-circuits

backup

restore

token

Look things up

balance

history

fee

check

Move money

deposit

withdraw

pay

transfer

Budgets for other agents

allow

reclaim

Loans and staking

loan

lend

stake

Run it for programs and Claude

serve

openapi

mcp

Flags every command takes

JSON output

Retrying without paying twice

Two agents on one computer

Exit codes

Scripting the command line

Environment variables

Files in ~/.h081

Next

`init`

`address`

`info`

`fetch-circuits`

`backup`

`restore`

`token`

`balance`

`history`

`fee`

`check`

`deposit`

`withdraw`

`pay`

`transfer`

`allow`

`reclaim`

`loan`

`lend`

`stake`

`serve`

`openapi`

`mcp`