Personal holder trader (beta)

The personal holder trader is a program you run on your own computer. It reads Hartii markets, applies fixed rules and records a decision every cycle. It has two modes today: Observe and Paper. Neither mode needs a private key. Neither mode sends a transaction.

New to this? Start with the step-by-step guide.

#Status

You need Hartii CLI 0.3.0 or newer and Node.js 22 or newer. See Hartii CLI.

#How it works

The runner is the program that does the work. When it loops, it waits 60 seconds between cycles. Each cycle has five steps.

1. Read the market. It lists up to 25 tokens from the Hartii directory, sorted by trading volume, plus any token it already holds. It then checks each token on-chain. A token counts only if its route is verified: a bonding curve made by a Hartii factory (generations v1 to v4), or a direct HartiiSwap pair against WQUAI for a token that was launched on a Hartii curve. HBOME is never traded.
2. Apply the rules. Every check uses closed one-minute candles. A candle that is still open never counts. The rules are listed below.
3. Ask a model (optional). If you set up a model, it ranks the tokens that passed. It can only rank or hold. It cannot choose an amount or an address. A second call can veto the pick. With no model, the runner never opens a position.
4. Size and check. Local code picks the size. It asks for a fresh quote and checks price impact, round-trip cost, gas and your budgets.
5. Record the decision. Every cycle ends in a decision: hold, buy or sell. It carries a short reason, the evidence and the guard checks.

#Observe and Paper

Observe shows what the runner would do with the real balance of your trading address. An address with no QUAI cannot get a complete gas estimate, so Observe holds or reports a blocker.

A Paper fill is simulated from a real, fresh quote and includes gas. Real fills can differ. Simulated results do not predict real ones.

#Rules the engine enforces

These limits are fixed in the engine. A policy can make them stricter. It cannot loosen them.

EMA is the exponential moving average of the closing price. EMA5 follows the last few minutes closely. EMA20 is slower. The capital basis is the lower of your approved capital and the verified equity of the account.

Exits are triggers. They are not guaranteed fills. A fast move can fill worse than the trigger.

The daily loss stop does not clear on its own and survives a restart. To start over in Paper, create a new profile with --profile <name>.

#Why small budgets usually hold

Gas on Quai is paid in QUAI, and a contract call can cost several QUAI. On 2026-10-09, hartii gas showed about 8 QUAI for a contract call. The 5% round-trip limit counts gas for the buy, for the sell and for an approval. The runner also reserves your whole --max-fee for each future exit, because it cannot price a sale before it owns the token. A small trade cannot pass a 5% limit with costs like that, so the runner holds. Holding is the rule working. It is not a fault.

#Budgets

You set four absolute QUAI budgets when you create a profile. They are stored with the profile and cannot be changed later. To change them, create a new profile.

#Models (bring your own)

Hartii hosts no model and pays no model costs. You choose a provider, a model and a key.

hartii trader init ... --provider openai --model <model-name> --pricing-file ./pricing.json --model-key-env MY_MODEL_KEY

• --provider is openai or anthropic. --model is a model name you choose. There is no default and there is no fallback to another model.
• --model-key-env <NAME> stores only the name of an environment variable. Without it, a hidden prompt asks for the key and the CLI stores it encrypted with a password you set (12 characters or more).
• The pricing file holds the prices and limits the cost guard uses:

A price of 2 US dollars per million tokens is written "2000000". Take every price from your provider. The guard is only as accurate as the prices you enter.

• The call goes from your computer straight to your provider. It does not pass through Hartii.
• The model sees public candle and quote figures and your exposure ratio. It does not see wallet addresses, balances or keys.
• The guard reserves the worst-case cost before each request. It stops model calls at an estimated 0.10 US dollars per cycle or 1.00 US dollar per day. A failed or unclear call keeps its reservation. When the budget is used up, the runner holds.
• Your provider bills your own key. The guard is an estimate, not your invoice.

#Commands

Every command takes --profile <name> (default default) and --json. Only Cyprus-1 mainnet is supported. --network orchard is refused.

The command also contains arm, run without --observe, reconcile and init --pair. They belong to Live trading and hosted pairing. Neither is available in this release, and this page does not cover them.

Pause is a latch. hartii trader pause stops every later run of that profile, in every mode. Resuming needs the hosted pairing flow, which is not available in this release. To keep going, create a new profile. To stop one run, press Ctrl+C.

#Files and privacy

A profile lives in ~/.hartii/trader/<profile>/ (under HARTII_HOME if you set it).

Other files in the folder (such as telemetry.journal.jsonl) are a queue for the dashboard. They hold public events only.

• Files are written atomically, and the CLI refuses paths that go through a link. On Windows it cannot check file permissions, so keep the folder private through your account.
• One process may write a journal at a time. A crash leaves a .lock file next to it. The CLI never removes it for you. Remove it yourself only after you are sure nothing is running.
• A profile is tied to the trader release that created it. After an update that changes the release, an old profile refuses new runs. Export its history, then start a new profile.
• Observe and Paper contact hartiilabs.com, the Quai RPC and, if you set one, your model provider. Those services can see your IP address and the tokens you ask about. There is no telemetry otherwise.

#The /trader dashboard

hartiilabs.com/trader is the private cockpit for a runner. The page is titled Holder Trader, and its menu entry is Personal trader. In this release only the demo works.

• Explore demo shows sample data from a simulated Paper runner that holds. It reads no wallet, calls no model and sends nothing. A selector previews each scene state.
• Everything else needs the hosted service and the access registry. Both are off. If you connect a wallet, the page tells you the service is unavailable.

When a runner is connected, the page shows its mode, heartbeat and membership, five account figures (trading equity, available QUAI, managed exposure, realized and unrealized P&L), the latest decision, and six tabs.

The page can pause a runner with Pause runner. It cannot start one, unlock a wallet, raise a limit or withdraw funds.

#Hosted pairing (not available)

This is how pairing is built. It is off in this release.

1. You sign a message with your owner wallet. It costs no gas and sends no transaction. It opens a private session that lasts 15 minutes.
2. You enter your trading address. The page makes a one-time pairing code that expires in 5 minutes.
3. You paste the code into a hidden prompt on your machine. The CLI makes an Ed25519 device key, stores it encrypted, and redeems the code.
4. You compare the device fingerprint on the page with the one in your terminal and confirm the device.
5. The runner then sends signed heartbeats and events. The hosted service keeps them for 30 days. Your full history stays in your local journal.

#Live trading is not available

Live means the runner signs and sends real transactions from the trading wallet. That is not available, and this page does not describe how to switch it on. The engine stays blocked unless every item here is true:

• The installed release has seven full days of recorded Paper observation, and the operator has signed off its replay, Orchard rehearsal and mainnet canary evidence.
• The owner wallet has an active HBOME membership. That needs the registry.
• You approved a policy of at most 24 hours with your owner wallet and confirmed it by typing on your own machine.
• The hosted service has granted this runner exclusive authority over the trading wallet.

None of these exist in this release.

If Live ever ships, the trading wallet is an ordinary wallet. Its limits are software on your machine. They are not a contract, and anyone who holds its key can bypass them. An AgentVault enforces its caps on-chain. The personal trader does not.

#The HBOME access registry (proposed, not deployed)

The hosted parts of the personal trader are meant for HBOME holders. The registry would be the on-chain record of the smallest HBOME balance that counts as a Member. Observe and Paper on your own computer never need it. See the contract reference for the interface.

Until it is deployed, the public membership read answers HTTP 503 with configured: false and reason: "registry-not-configured":

GET https://hartiilabs.com/api/hbome/tier?address=<owner wallet address>

#Reading the trader with an AI agent

hartii mcp has three read-only tools for the trader: hartii_trader_status, hartii_trader_limits and hartii_trader_activity. They read the local profile named default. There is no MCP tool that starts, arms, pauses or unlocks the trader, changes a limit or withdraws. See Connect an AI agent.

#Common errors

Reasons appear as rationale in a decision, and as blockers in a snapshot.

#Related

• Guide: try the personal trader in Paper
• Hartii CLI and Connect an AI agent
• Agent Terminal security and contract reference
• Versions and changelog