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:
hartii balance
hartii balance --tokensThe 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
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:
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:
hartii quote buy <token> 5Step 3: dry-run a buy
A dry run simulates the buy against the chain and prints the exact summary, but signs and sends nothing.
hartii buy <token> 5 --dry-runYou will see a summary including:
- the action and network (mainnet),
quaiIn(what you spend) andexpectedTokensOut,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.
Step 4: make a small real buy
Run the same command without --dry-run:
hartii buy <token> 5The 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:
hartii balance --tokens
hartii tx <hash>hartii tx shows success, reverted, pending or not found.
Step 5: sell
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
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 limitsand lower them withhartii 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 | The curve moved between preview and send. Rerun the dry run, then widen --slippage slightly if you accept it. |
| Insufficient funds | Remember the fee. Buy less, or use a percentage such as 25%. |
| Bought the wrong token | Match addresses, not tickers (Step 2). |
| Lock file error | An earlier write crashed. Check your recent transactions on quaiscan first, then remove the spend.lock file at the path the CLI prints. |
Next
- 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