CLI guide 2: your first trade

This guide walks through one careful trade on a HartiiLabs bonding curve: look, preview, buy small, sell. Every step that moves money is previewed first.

You will need: the CLI and a wallet from guide 1, and a small amount of QUAI in that wallet. Every transaction also pays a network fee in QUAI.

Step 1: check your balance

Send a small amount of QUAI to your address (hartii wallet address), then:

bash

hartii balance
hartii balance --tokens

The first prints your QUAI balance and the network. --tokens adds a table of token holdings with the columns TOKEN, BALANCE, VALUE and PRICE SOURCE. Shortcut: hartii bal.

Step 2: browse tokens

bash

hartii tokens trending
hartii tokens new
hartii tokens search <word>

Each row shows SYMBOL, the reference price, HOLDERS, PHASE (active means still on its bonding curve, graduated means it has moved to a pool) and the token's ADDRESS.

Look at one token in detail:

bash

hartii token <address-or-ticker>

This shows live curve state, graduation progress, holders and links. For an exact on-chain quote that needs no wallet:

bash

hartii quote buy <token> 5

Step 3: dry-run a buy

A dry run simulates the buy against the chain and prints the exact summary, but signs and sends nothing.

bash

hartii buy <token> 5 --dry-run

You will see a summary including:

the action and network (mainnet),
quaiIn (what you spend) and expectedTokensOut,
minTokensOut, the least you will accept (set by slippage, default 3%),
the fee in basis points and the estimated network fee,
phase (bonding curve or pool) and whether this buy would finish the curve.

Read it. If anything surprises you, stop. Use --slippage 2 for a tighter tolerance.

CLI 0.2.2 also accepts balance-based buys, for example:

bash

hartii buy <token> 90% --dry-run
hartii buy <token> all --dry-run

It leaves room for gas and requotes if the requested amount would consume that reserve. The final quaiIn can be less than the typed percentage. A decimal buy such as 5 needs that amount plus gas. Check your installed version with hartii --version; these changes target CLI 0.2.2.

Step 4: make a small real buy

Run the same command without --dry-run:

bash

hartii buy <token> 5

The CLI prints the same summary and asks y/N. On y it asks for your wallet password (hidden) and sends. It reports success only after the transaction is mined with status 1, then prints a quaiscan link. --yes skips the question; keep it for scripts you trust.

Check it landed:

bash

hartii balance --tokens
hartii tx <hash>

hartii tx shows success, reverted, pending or not found.

CLI 0.3.2 keeps UNCONFIRMED separate from a confirmed revert and preserves the public hash in the TUI. Result pages scroll with arrows, Page Up/Down, Home/End. A displayed error after submission does not establish that the trade failed on-chain.

If sending reports an unknown outcome, stop and inspect the locally retained hash:

bash

hartii tx pending
hartii tx <hash>

A missing or delayed receipt is not proof of failure. Do not repeat the buy or delete its reservation to bypass the pending block. A status read does not automatically reconcile local pending state. Follow the pending recovery procedure.

Step 5: sell

bash

hartii sell <token> 50% --dry-run
hartii sell <token> 50%

The amount can be a number, a percentage, or all. A sale first needs permission for the exact amount, so the CLI may show an approval step before the sale. With --dry-run it simulates the approval and stops there, telling you to rerun without --dry-run. That is expected.

Safety built in

For faster manual navigation, select the watched token and press Enter for Buy or s for Sell; the form pins its resolved token address. Every new order still obtains current terms and follows the normal review/signing path. Automatic signing restricted to tokens is proposed, not available in this release.

Every write is simulated from your address, given an access list and an explicit gas limit, then confirmed. On top of that:

Spending guard: by default 100 QUAI per transaction and 500 QUAI per day. See your numbers with hartii limits and lower them with hartii config set limits.perTxQuai 10.
Fee ceiling: a transaction is refused if its network fee is above the larger of 25 QUAI and 5% of the value moved. A human can raise it for one command with --max-fee <quai>.
Curves are checked against Hartii's launch factories before any buy or sell.

Gas on Quai can be a large share of a small trade. Read the fee line before you confirm.

Common mistakes

Problem	Fix
`Estimated network fee ... exceeds the fee ceiling`	Gas is unusually high. Wait, or rerun with `--max-fee <quai>` if you accept the cost.
Spending limit error	You hit `limits.perTxQuai` or `limits.dailyQuai`. Check `hartii limits`.
Slippage or "price moved" revert	Establish that the transaction reverted first. Then rerun the dry run and review its new terms.
Insufficient funds	Remember the fee. Buy less, or use a percentage such as `25%`.
Nonce or chain changed after review	Nothing was sent by this attempt. Check the wallet/network and review a fresh dry run.
Unknown outcome, timeout, `pending` or `not found`	Check `hartii tx pending` and the hash on-chain; do not repeat the write.
Bought the wrong token	Match addresses, not tickers (Step 2).
Lock file error	Stop all writers and reconcile pending hashes before repairing the lock; follow the reference recovery procedure.

CLI guide 3: connect an AI agent, read-only first
Agent Terminal: a capped vault if you want an agent trading under on-chain limits
Reference: Hartii CLI, Bonding curve

CLI guide 2: your first trade

#Step 1: check your balance

#Step 2: browse tokens

#Step 3: dry-run a buy

#Step 4: make a small real buy

#Step 5: sell

#Safety built in

#Common mistakes

#Next

Step 1: check your balance

Step 2: browse tokens

Step 3: dry-run a buy

Step 4: make a small real buy

Step 5: sell

Safety built in

Common mistakes

Next