Personal trader guide: try it in Paper

By the end of this guide you will have a personal trader profile on your computer. You will run it in Paper and watch it read real Hartii markets and record its decisions. It signs nothing and sends nothing.

Who this is for: anyone comfortable typing commands in a terminal. You do not need HBOME to follow this guide.

What you will need

• Hartii CLI 0.3.0 or newer and Node.js 22 or newer (CLI guide 1).
• The address of your owner wallet, the wallet you use for HBOME. It starts with 0x00.
• A second, separate address for trading. Step 3 shows how to make one.
• No QUAI. Paper uses a simulated balance.

#Step 1: update the CLI

node --version      # v22 or higher
hartii update
hartii --version    # 0.3.0 or newer

hartii update asks, downloads the new version, checks its checksum and installs it. On Node.js 20 or older, install Node.js 22 first. On CLI 0.2.2 or older, run the install command from CLI guide 1 once.

#Step 2: run the offline demo

hartii trader paper --demo --once --json

This runs one cycle on fixed sample data. It needs no wallet, no internet and no files. Look for these fields:

{
  "ok": true,
  "demo": true,
  "snapshot": {
    "mode": "paper",
    "state": "holding",
    "latestDecision": { "action": "hold", "rationale": "no-qualified-candidates", "outcome": "held" },
    "qualification": { "days": 0, "requiredDays": 7, "liveEnabled": false }
  }
}

The demo holds because the sample market is empty. liveEnabled is false because Live is not available.

#Step 3: create a profile

A profile stores two public addresses and four budgets. It stores no key. This command also makes a new encrypted wallet for the trading address:

hartii trader init --owner <your owner wallet address> --create-wallet --capital 100 --max-per-tx 10 --max-per-day 30 --max-fee 1

The CLI asks for a new password for that wallet. Paper never unlocks it. You see your addresses, a runnerId and your budgets. The note says: "Ready for keyless Observe/Paper." These budgets are small on purpose, to learn the commands. Step 4 explains why they will always hold.

Leave an option out and the CLI asks for it. To use an address you already have, replace --create-wallet with --trading-address <address>. To use an encrypted wallet from hartii wallet, use --wallet <name>.

#Step 4: run one Paper cycle

hartii trader paper --once

This reads real Hartii markets, so you need internet. It signs nothing. Read the latestDecision. A hold with a reason is the usual result.

#Why it will hold with these numbers

With the budgets above, the trader holds every cycle. A trade is at most 10 QUAI. The trader reserves your whole --max-fee (1 QUAI) for the future sale. That is already more than the 5% cost limit on a 10 QUAI trade.

Gas on Quai can be large. Run hartii gas to see what a contract call costs now. On 2026-10-09 it was about 8 QUAI. The cost limit counts gas for the buy, the sell and an approval. A small trade cannot pass. Use these numbers to learn the commands. Then try a new profile with larger budgets. Paper costs nothing, so you can try several. The reference explains the math.

#Step 5: watch it run

Start a loop. It waits 60 seconds between cycles and prints nothing until you stop it:

hartii trader paper

In a second terminal, watch the latest snapshot. It refreshes every 2 seconds:

hartii trader watch

hartii trader status --json prints the same snapshot once. Press Ctrl+C in the first terminal to stop. Run the same command again to continue. After a stop, watch can show paused with the blocker process-stopped. That describes the process. It is not a pause latch.

#Step 6: add a model (optional)

Without a model, Paper never opens a position. A model ranks the tokens that pass the rules. It cannot choose an amount or an address.

1. Write a pricing file with the four prices and two limits. The reference lists every key.
2. Put your model key in an environment variable in your shell. Never type a key into a command line or a chat.
3. Make a new profile. A profile cannot gain a model later.

hartii trader init --profile with-model --owner <owner address> --trading-address <trading address> --capital <QUAI> --max-per-tx <QUAI> --max-per-day <QUAI> --max-fee <QUAI> --provider openai --model <model name> --pricing-file ./pricing.json --model-key-env MY_MODEL_KEY

Use --provider anthropic for Anthropic. The profile stores only the variable name MY_MODEL_KEY. The guard stops model calls at an estimated 0.10 US dollars per cycle and 1.00 US dollar per day. Run it with hartii trader paper --profile with-model.

#Step 7: try Observe (optional)

hartii trader run --observe --once

Observe works like Paper, with two differences. It uses the real QUAI balance of the trading address, and it makes no simulated fills. A buy or sell is only noted as observed.

An address with no QUAI cannot get a complete gas estimate, so Observe holds or reports a blocker. This guide does not ask you to fund the address. If you choose to, back up the wallet first with hartii wallet export <name> and send only an amount you can afford to lose. Observe never moves it.

#Step 8: export, pause and start over

hartii trader export --mode all --out trader-history.jsonl

Stop every runner first. The export is a verified copy of the full journal. It refuses to overwrite a file.

hartii trader pause is a one-way latch for that profile in this release. Resuming needs hosted pairing, which is not available. To stop one run, press Ctrl+C instead. To start over, make a new profile with --profile <name>.

#Step 9: let an AI agent read the trader

hartii mcp has three read-only tools: hartii_trader_status, hartii_trader_limits and hartii_trader_activity. They read the profile named default. Ask your agent "What is my Hartii trader status?". It should call hartii_trader_status. No tool can start, pause, unlock or change the trader. Setup is in CLI guide 3.

#Step 10: look at the dashboard demo

Open hartiilabs.com/trader and click Explore demo. A banner says "DEMO / PAPER". The data is made up. Use Preview scene to see each state. Nothing is read from a wallet or sent anywhere.

#What is not available

• Live trading. It stays blocked. This guide does not cover it.
• The private dashboard and hosted pairing. The hosted service is off.
• The HBOME access registry. It is proposed, not deployed. No address exists.

#Safety

• Observe and Paper never sign and never send. They need no key.
• Never paste a recovery phrase, a private key or a model key into a chat, an AI agent or a website.
• Paper results are simulated. Real fills can differ.
• Keep the folder ~/.hartii/trader/ private. On Windows the CLI cannot check file permissions for you.

#Common mistakes

#Next

• Reference: Personal holder trader
• CLI guide 3: connect an AI agent
• Hartii CLI