Getting started

In plain words

This page takes you from nothing to a working private bank account for your agent, in about ten minutes.

You will make a new key on your own computer, send it a few dollars, put some of that money into the bank, and take part of it out again to another wallet. Every step shows what you should see.

You type a few short commands in a terminal (the window where you type commands: Terminal on a Mac, PowerShell on Windows). You do not need to write any code.

Words on this page

You only need a handful of terms. Each one in a sentence:

USDG: A digital dollar on Solana. 1 USDG is meant to be worth 1 US dollar. All amounts in H081 are in USDG.
SOL: Solana's own coin. Every Solana transaction costs a tiny bit of it, so your agent needs a little.
Agent key: A secret file on your computer (~/.h081/agent.json). Whoever has it controls the agent's money. It never leaves your machine.
Agent wallet: The public Solana address that belongs to the agent key. You send SOL and USDG here.
Shielded balance: The money inside the bank. Only your agent key can read it; the public chain cannot.
Relayer: H081's sending service (https://api.h081.xyz). It sends withdrawals for you, so your agent wallet does not appear as the sender.
Plan: What a command would do (fee, what arrives, what is public), shown before anything is sent. More in Plan first.

What you need

What	How much	Why
Node.js	20.11 or newer	Runs the H081 program. Free from nodejs.org.
SOL	about 0.05 SOL	Network fees for deposits and withdrawals.
SOL, for budgets or lending	about 0.15 SOL	Giving budgets and lending need more for fees and rent.
USDG	a few USDG	The money you put in the bank. This guide uses 5.
A Solana RPC URL	a free plan is enough	The address your computer uses to read and write the Solana chain.
Disk space	about 98 MB, once	The proving files. Each one downloads the first time it is needed and is checked against a pinned hash.
A second, fresh wallet	any empty Solana address	Where your first withdrawal goes. See step 6.

Use your own RPC URL. Solana's free public endpoint limits the history reads the balance needs, and they fail with "429 Too Many Requests". A free key from any Solana RPC provider works.

Step by step

Check that Node.js is installed
Open a terminal and type this. It should print 20.11 or a higher number.
any terminal
```
node --version
```
you should see something like
```
v20.11.0
```
An error or a lower number means you need to install or update Node.js first.

Create the agent key

This makes a brand-new Solana key just for your agent. It works offline: nothing is sent anywhere. Put your RPC URL where it says so.

any terminal (macOS, Linux, Windows PowerShell)

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

you should see

Agent key created: /home/you/.h081/agent.json (only you can read it)
Agent wallet: 7Gm4…your agent's Solana address…
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 7Gm4… (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

On Windows the paths look like C:\Users\you\.h081\agent.json, and the last line ends in -- cmd /c npx -y @h081lll/agent mcp.

It creates a folder called .h081 in your home folder with three files:

File	What it is	Why it matters
`~/.h081/agent.json`	The agent key	It controls the money, and it also opens the private account. Only your user can read it.
`~/.h081/config.json`	Settings: network, RPC URL, port	So you do not have to type the RPC URL every time.
`~/.h081/api-token`	A password for the local API	Only needed if you use the local API.

Later you will also see ~/.h081/ops.jsonl (a record of what this computer sent), and the cache and circuits folders (public chain data and the proving files).

Send the agent a little money
From any Solana wallet or exchange, send 0.05 SOL and a few USDG to the agent wallet address that init printed. Send 0.15 SOL instead if you plan to give budgets to other agents or to lend.
Lost the address? This prints it again:
any terminal
```
npx -y @h081lll/agent address
```
When the money has arrived, the balance shows it in the agent wallet (not in the bank yet):
any terminal
```
npx -y @h081lll/agent balance
```
you should see something like
```
Shielded: 0 USDG
Wallet:   5 USDG, 0.05 SOL
Address code: h081-address:…
```
No SOL or USDG yet? Buy SOL on an exchange, withdraw it on the Solana network to a wallet you control, swap a few dollars of it to USDG, then send both to the agent wallet. Always check the USDG mint: 2u1tszSeqZ3qBWF3uNGPFc8TzMk2tdiwknnRMWGWjGWH.
Make your first deposit
A deposit moves USDG from the agent wallet into the bank. First, look at the plan. Without --yes, nothing is sent.
1 · see the plan (nothing is sent)
```
npx -y @h081lll/agent deposit 5
```
you should see
```
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.
```
If the plan looks right, run the same command with --yes at the end:
2 · send it
```
npx -y @h081lll/agent deposit 5 --yes
```
you should see something like
```
Sent.
{
  "signature": "4vJ…",
  "amountUsdg": "5",
  "shieldedUsdg": "5",
  …
}
```
The first time, it downloads the proof files it needs (15 MB) and makes a proof on your computer. That takes a moment.
What others can see
A deposit is public: anyone can see that the agent wallet put 5 USDG in. After that, the balance and everything you do inside the bank is private.
Check the fee before you withdraw
This asks what a withdrawal of 2 USDG would cost. It only asks; nothing is proven or sent.
any terminal
```
npx -y @h081lll/agent fee 2
```
you should see
```
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), the relayer adds 1 USDG to create it, so less arrives.
```
The fee is 0.20% of what arrives, or 0.05 USDG, whichever is more. It goes to the H081 treasury.
Withdraw to a fresh wallet
A withdrawal takes money out of the bank and sends it to any Solana wallet. The relayer sends it, so your agent wallet is not shown as the sender.
Use a fresh wallet
Withdrawing to the wallet that deposited, right after depositing, links the two. Use a fresh wallet (one that never touched the agent) and wait a while.
1 · see the plan (nothing is sent)
```
npx -y @h081lll/agent withdraw 2 --to <a wallet that never touched the agent>
```
you should see something like
```
Plan (nothing was sent):
  withdraw 2 USDG to 9xQe…
  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
  ! If 9xQe… has no USDG account yet, the relayer adds 1 USDG to create it.
Add --yes to send it.
```
2 · send it
```
npx -y @h081lll/agent withdraw 2 --to <a wallet that never touched the agent> --yes
```
A wallet that has never held USDG has no USDG account yet. The relayer creates one for 1 USDG more, so in this example 0.95 USDG arrives instead of 1.95. The plan warns you about this.
Up to 100 USDG per withdrawal goes through the relayer with nothing staked. --to self sends it back to the agent wallet, which links the two; avoid it unless you mean it.
Check the balance
any terminal
```
npx -y @h081lll/agent balance
```
you should see something like
```
Shielded: 3 USDG
Wallet:   0 USDG, 0.03 SOL
Address code: h081-address:…
```
5 USDG went in and 2 came out, so 3 USDG is left in the private (shielded) balance. If a number looks out of date, add --fresh to read it again from the chain:
any terminal
```
npx -y @h081lll/agent balance --fresh
```
See what you have done
History lists what this computer sent, newest first, with each transaction's signature.
any terminal
```
npx -y @h081lll/agent history
```
you should see something like
```
2026-11-11T10:02:41.000Z  withdraw          2  done    2Hn…
2026-11-11T09:58:12.000Z  deposit           5  done    4vJ…
```
only the last 10
```
npx -y @h081lll/agent history --limit 10
```
History comes from ~/.h081/ops.jsonl on this computer. It does not show what other machines sent with the same key.

Plan first: nothing is sent until you say so

Every command that moves money works in two steps. The first time you run it, you get a plan: the fee, what arrives, how much SOL it needs, and what the public chain will see. Nothing is proven, signed or sent.

You send it only when you repeat it with the "yes" switch. Each way of using H081 has its own switch:

You use	Plan (nothing sent)	Send
Command line	no `--yes`	add `--yes`
Local API	no `confirm`	`"confirm": true` and an `Idempotency-Key` header
TypeScript SDK	no `confirm`	`{ confirm: true }`
Claude	ask Claude to show you the plan	you say "yes"

A good habit: run every money command once without --yes, read the plan, then run it again with --yes.

The same deposit from code

Optional. If you write code, the same deposit works from any language. For curl, PowerShell and Python, start the local API in one terminal and leave it running:

terminal 1

npx -y @h081lll/agent serve

Then use it from another terminal or your program. TypeScript calls the bank directly and needs no server.

macOS / Linux (bash)

TOKEN=$(cat ~/.h081/api-token)
# the plan: nothing is sent
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"usdg":"5"}' http://127.0.0.1:8081/v1/deposit
# send it: "confirm": true and a new Idempotency-Key
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "Idempotency-Key: dep-1" \
  -d '{"usdg":"5","confirm":true}' http://127.0.0.1:8081/v1/deposit
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8081/v1/balance

Windows PowerShell

$h = @{ Authorization = "Bearer $(Get-Content $HOME\.h081\api-token)" }
# the plan: nothing is sent
Invoke-RestMethod -Method Post -Headers $h -ContentType application/json -Body '{"usdg":"5"}' http://127.0.0.1:8081/v1/deposit
# send it: "confirm": true and a new Idempotency-Key
$h["Idempotency-Key"] = "dep-1"
Invoke-RestMethod -Method Post -Headers $h -ContentType application/json -Body '{"usdg":"5","confirm":true}' http://127.0.0.1:8081/v1/deposit
Invoke-RestMethod -Headers $h http://127.0.0.1:8081/v1/balance

Python (requests)

import pathlib, uuid, requests

API = "http://127.0.0.1:8081/v1"
s = requests.Session()
s.headers["Authorization"] = "Bearer " + (pathlib.Path.home() / ".h081" / "api-token").read_text().strip()

plan = s.post(API + "/deposit", json={"usdg": "5"}).json()
print(plan["status"], plan["result"])                 # "plan": nothing is sent

key = str(uuid.uuid4())                               # reuse this key if you retry this call
sent = s.post(API + "/deposit", json={"usdg": "5", "confirm": True}, headers={"Idempotency-Key": key}).json()
print(sent["status"], sent["result"])                 # "sent"
print(s.get(API + "/balance").json()["result"]["shielded"])

TypeScript (Node.js)

import { H081 } from '@h081lll/agent';   // npm install @h081lll/agent; no gateway needed

const bank = await H081.open();                  // ~/.h081/agent.json + ~/.h081/config.json
console.log(await bank.deposit('5'));            // the plan: nothing is sent
console.log(await bank.deposit('5', { confirm: true, idempotencyKey: 'dep-1' }));
console.log(await bank.balance());

Every route and field: Local API. Every SDK method: TypeScript SDK.

Back up your key

If your computer breaks or you delete ~/.h081/agent.json, the money in the bank is gone with it. Make a backup now.

any terminal

npx -y @h081lll/agent backup

you should see

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

To put the key back on a new computer:

any terminal

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

It checks the code first (its checksum and network), then writes ~/.h081/agent.json. If a key is already there, it refuses to replace it. Back that key up first, then add --force to replace it:

replace an existing key (careful)

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

Backup and restore exist only on the command line, not in the local API and not in Claude.

If something goes wrong

"429 Too Many Requests": The public Solana RPC is limiting you. Run init --rpc again with your own RPC URL, or set H081_RPC_URL.
"cannot reach the Solana RPC at …": The RPC URL is wrong or down. Check it, then set it again with init --rpc.
needs_sol: The agent wallet is short of SOL for fees. The error says how much it needs.
insufficient_wallet_usdg: The agent wallet does not hold enough USDG for that deposit. Check with balance.
needs_stake: The withdrawal is over 100 USDG. Split it into smaller ones.
"does not match the pinned … refusing to use it": A downloaded proof file is damaged. Delete the ~/.h081/circuits folder and run npx -y @h081lll/agent fetch-circuits.

Every error code and what to do: Errors and fixes.

Next steps

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.

Words on this page

What you need

Step by step

Check that Node.js is installed

Create the agent key

Send the agent a little money

Make your first deposit

Check the fee before you withdraw

Withdraw to a fresh wallet

Check the balance

See what you have done

Plan first: nothing is sent until you say so

The same deposit from code

Back up your key

If something goes wrong

Next steps