HartiiLabs docs

Guides

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 review, but signs and sends nothing.

bash
hartii buy <token> 5 --dry-run

You will see a review that starts with one plain sentence ("You buy about ... for ..."), then the details below. Add --details to see the technical fields too, or --terse for a one-line version. The review includes:

  • 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.

Red warnings appear in the review when something deserves a second look: slippage above 10%, a token you chose by ticker instead of its address, a network fee bigger than the amount, a recipient you never paid, or an address that looks like one you already know. A warning never blocks the trade; it is there so you can stop yourself.

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 review 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, but only works once you have set a spending cap (see below); 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 caps (optional): there are no caps unless you set them; the first-run setup recommends it. Set one with hartii config set limits.perTxQuai 10 (and limits.dailyQuai 50 for a daily total), see them with hartii limits, and remove one with hartii config set limits.perTxQuai none. Caps stop mistakes, not malware.
  • New recipient check: when you send QUAI to an address you have never paid, the review marks it NEW and you type the last 4 characters of the address to confirm. Save people you pay often with hartii contacts add <name> <address>, then hartii send <name> <amount>. A script can send to a new address only with --yes --new-recipient-ok, and never to a look-alike of an address you know.
  • 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

ProblemFix
Estimated network fee ... exceeds the fee ceilingGas is unusually high. Wait, or rerun with --max-fee <quai> if you accept the cost.
Spending limit errorYou set limits.perTxQuai or limits.dailyQuai and this send is over it. Check hartii limits.
--yes skips the review step, so it needs spending capsSet a cap first (hartii config set limits.perTxQuai 25) or leave --yes off.
Slippage or "price moved" revertEstablish that the transaction reverted first. Then rerun the dry run and review its new terms.
Insufficient fundsRemember the fee. Buy less, or use a percentage such as 25%.
Nonce or chain changed after reviewNothing was sent by this attempt. Check the wallet/network and review a fresh dry run.
Unknown outcome, timeout, pending or not foundCheck hartii tx pending and the hash on-chain; do not repeat the write.
Bought the wrong tokenMatch addresses, not tickers (Step 2).
Lock file errorStop all writers and reconcile pending hashes before repairing the lock; follow the reference recovery procedure.

Next

Quai Network mainnet · chain 9 · Cyprus-1. Figures marked "read on" a date were read from the chain that day; re-read before relying on them.