Rewrite the agent quickstart as a checkpointed runbook - #180
Draft
anderdc wants to merge 1 commit into
Draft
Conversation
Teammates one-prompting bots off the /agents markdown kept failing. The old text was a protocol overview; this one is a runbook: every step names the command and the stdout that proves it worked, every failure line the CLI prints maps to an action, and the cost stack and rate semantics that sink arbitrage bots (0.02 SOL per bid, rate vs counterRate both in the hub unit, --send off without a TTY) are stated up front. Also fixes claims the old text made that were not true: /swaps filters das does not implement, and an untested pipx install path (replaced with the clone + venv path, verified in a clean env). Adds a "coming" section on routed reservations via the Ventura Labs validator (Allways Access credits + planned API keys) — draft until that product is public. Claude-Session: https://claude.ai/code/session_01Qh3CYdsFgdJVHiyn4RZzyD
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Mango one-prompted arbitrage bots off the
/agentscopy-paste markdown several times and they failed. The old text was a protocol overview with no checkpoints; an agent couldn't tell whether a step worked, and the three things that actually sink a bot were never stated.What
AgentMarkdown.tsrewritten from scratch (→public/llms.txtregenerated by the build). Structure is now install → verify → quote → execute → track → bot loop → errors, each step with the command and the expected output.Grounded in the testnet/mainnet swap-testing logs, the CLI source (
swap.py,post_tx.py,quote.py), and live mainnet reads on 2026-08-27.Key content that was missing before:
--sendis OFF without a TTY — a scriptedalw swap nowreserves, prints, exits, and the TTL burns. Agents must pass--send --yes.rate/counterRateare both "spoke per hub" — a same-miner round trip is0.99² × rate / counterRate≈ −4% (what Mango saw). The only arb is miner-vs-external-market; formula included.swap nowcan print → meaning → action, quoted from the CLI.swap quote --jsonexit code,--miner,--send --yes, and theDeposit sent→post-txretry).alw_sk_API keys, marked not-yet-public. This is why the PR is a draft: land it once we're ready to point people at the validator product.Corrections to the old text:
/swapsfilters (status,fromChain, …) that das doesn't implement; the untestedpipx install git+…path (replaced with clone + venv, verified in a clean env).Found along the way (not fixed here)
alw status --jsonechoes the Solana RPC URL including the API key.swap now --sendwith a TAO source and a missing coldkey file still tracebacks (KeyFileError) after reserving.Checks
tsc -b,npm run lint,npm run buildpass; generatedllms.txtdiffed against the source — identical apart from the registry-derived asset/hub/pair substitutions.https://claude.ai/code/session_01Qh3CYdsFgdJVHiyn4RZzyD