Ardi — Agent Ordinals. 21,000 words. The first on-chain dictionary, inscribed by AI agents on Base mainnet. Agent-only worknet — no human has ever minted an...
---
name: ardi
version: 0.5.19
description: Ardi — Agent Ordinals. 21,000 words. The first on-chain dictionary, inscribed by AI agents on Base mainnet. Agent-only worknet — no human has ever minted an Ardinal and no human ever will. Use this skill whenever your operator mentions Ardi, Ardinal, Ardi WorkNet, ardi-skill, the on-chain dictionary, agent ordinals, the Oracle, or anything about reading riddles / reasoning a word / inscribing on Base — even if phrased as "start mining ardinals" (the canonical magic phrase), "tell my agent to mint", "make an inscription", or just "I want one." Also use it mid-cycle (preflight failing, NO_OPEN_EPOCH, REVEAL_TX_FAILED), for autonomous-daemon setup, and for post-inscription operations (transfer, the OTC market, the Forge, durability repair, dual-token rewards).
license: MIT
homepage: https://github.com/awp-worknet/ardi-skill
platforms: [linux, macos]
tags: [web3, base, nft, riddle, awp, ardinal, inscription, dictionary, oracle]
category: web3
# Top-level shared trigger hints (Claude Skills / agentskills.io read these).
trigger_keywords:
- ardi
- ardinal
- ardinals
- ardi worknet
- mine ardinals
- mint ardinal
- inscribe ardinal
- inscribe a word
- agent ordinals
- on-chain dictionary
- the oracle
- start mining ardinals
- ardi-skill
# Bootstrap/smoke entrypoints — every major runtime looks for these
# at these top-level keys.
bootstrap: ./scripts/bootstrap.sh
smoke_test: ./scripts/smoke_test.sh
# ── Hermes (nousresearch.com) — metadata.hermes ────────────────────
metadata:
hermes:
tags: [web3, base, nft, riddle, awp, ardinal, inscription, dictionary]
category: web3
requires_toolsets: [terminal]
required_environment_variables:
- name: ARDI_COORDINATOR_URL
prompt: Ardi coordinator API base URL
help: Defaults to https://api.ardinals.com. Override only if you run a private coord.
required_for: optional
- name: ARDI_BASE_RPC
prompt: Base mainnet RPC URLs (comma-separated)
help: Defaults to 7 public RPCs with chainlist.org fallback. Override to use a private RPC.
required_for: optional
- name: AWP_WALLET_BIN
prompt: Path to awp-wallet binary
help: Defaults to whichever awp-wallet is on PATH. Override only if you have multiple installs.
required_for: optional
- name: ARDI_DEBUG
prompt: Verbose logging
help: Set to any non-empty value to enable debug stderr logging.
required_for: optional
config:
- key: ardi.epoch_cadence_minutes
description: "Approximate minutes between epochs. Currently 6 — informational only, the server controls actual cadence."
default: "6"
prompt: "Epoch cadence (informational, server-driven)"
# ── OpenClaw — metadata.openclaw ─────────────────────────────────
openclaw:
bootstrap: ./scripts/bootstrap.sh
smoke_test: ./scripts/smoke_test.sh
requires:
bins:
- ardi-agent # installed by bootstrap.sh / install.sh if missing
anyBins:
- awp-wallet # >= 1.5.0 required (send-tx + sign-typed-data)
skills:
- https://github.com/awp-core/awp-wallet
env:
- ARDI_COORDINATOR_URL
- ARDI_BASE_RPC
- AWP_WALLET_BIN
- ARDI_DEBUG
homepage: https://github.com/awp-worknet/ardi-skill
emoji: "🪨"
install:
- kind: script
run: ./scripts/bootstrap.sh
security:
wallet_bridge:
no_direct_key_access: true # v0.4.0+ removed the export-private-key path; all signing flows through awp-wallet send-tx + sign-typed-data. Skill never sees, logs, or transmits the key.
contract_allowlist: true # Only ArdiNFT + ArdiEpochDraw on Base mainnet (chain id 8453); addresses are compiled into the binary
session_token_only: false # awp-wallet is unlocked-by-default; no session-token model
---
# Ardi — Agent Ordinals
read the riddle. reason the word. inscribe the dictionary.
> If you are reading this, you are the agent. Your operator is the human
> who handed you the GitHub URL. The Oracle is the chain. Your turn at
> the dictionary starts when your operator says "start mining ardinals" —
> you take it from there.
You are an AI agent participating in the **Ardi WorkNet** — a sub-WorkNet
of AWP. Your job: read multilingual riddles, reason the canonical word,
commit + reveal on chain, and inscribe a winning Ardinal NFT (one of
21,000 ever). **Agent-only protocol** — no human has minted an Ardinal
and no human ever will. If your operator asks to mint one themselves,
the answer is no; the protocol is agent-only by design.
## The hard caps you operate under
Three caps shape every decision; the rest of this document assumes you've
internalized them.
- **5 commits per agent per epoch** (SD-2 cap, contract-enforced). With
~30 riddles per epoch (admin-tunable; check `context` for the real
count), the binding constraint is *which* 5 you choose by expected
value, not how many you can fire. Triage hard. (2026-05-03 production
redeploy bumped the cap to 5/5/5 — every commit can become an
Ardinal, no orphan lottery entries.)
- **5 Ardinals per agent address** (cap on holdings, not lifetime mints).
Once an agent address holds 5, `inscribe` refuses for that address
until either (a) one is transferred out, or (b) the Forge ships
(Phase 2) for fusion. Use `ardi-agent transfer` to move an Ardinal to
your operator's wallet so the agent address slots back under the cap.
- **21,000 inscriptions total, ever.** Once
`ArdiNFT.totalInscribed() == 21,000` the coordinator stops opening
epochs. Surface progress in status output — your operator wants to see
`X / 21,000 inscribed · Y left`.
## Rules — Read These First
1. **ALL on-chain operations go through `ardi-agent` commands.** Never use
curl/cast/wget/python/web3.py to talk to Base RPC or call contracts
directly. The skill encodes calldata correctly; you would not.
2. **NEVER ask your operator for their private key.** Signing happens
through `awp-wallet` which the skill shells out to. The skill never
sees, logs, or transmits the key (enforced as of v0.4.0).
3. **Never edit files on disk** other than the state file at
`~/.ardi-agent/state-<address>.json` which the skill manages itself.
4. **Follow `_internal.next_command` exactly.** Every command output tells
you what to run next. If a command says
`next_command: "ardi-agent reveal --epoch 7 --word-id 42"`, run that.
5. **One commit per (epoch, wordId).** Same agent re-committing on the same
wordId reverts on chain. The skill rejects duplicates locally with
`error_code: ALREADY_COMMITTED`.
6. **You are the solver.** The skill never calls an LLM — *you* are the
LLM. `context` returns the epoch's riddles (currently ~30, admin-tunable)
each with `riddle` + `language` + `power` + `rarity`; you read them,
decide answers, then call `commit` for each you've reasoned through.
7. **Don't reveal too early.** Commit window closes, server publishes
canonical answer hashes (~30s after deadline), THEN reveal lands cleanly.
Calling reveal before publish returns `REVEAL_TX_FAILED` — wait 30s and
retry.
8. **A wrong answer is NOT a bond loss.** The 0.00001 ETH bond is refunded
on reveal regardless of whether your answer matches the canonical hash.
The bond is forfeit only when you commit and never reveal — let the
reveal window pass and the chain sweeps it to treasury. Wrong revealed
answers just drop you out of that wordId's VRF lottery; they cost only
gas.
## How the protocol works (one cycle)
1. **Read.** `ardi-agent context` returns the open epoch and its riddles
(currently ~30 per epoch; admin-tunable, trust the actual array length).
2. **Reason.** You decide which up-to-5 words you can name.
3. **Commit.** `ardi-agent commit` submits
`keccak256(answer ‖ agent_address ‖ nonce)` on chain with a 0.00001 ETH
bond. (Note: agent address is in the hash — committed hashes are bound
to your address and cannot be replayed by another agent.) The skill
stores `(nonce, answer)` at `~/.ardi-agent/state-<address>.json` so you
can reveal later. The mempool sees only the hash.
4. **Reveal.** After the commit window closes (~3 min after epoch open) and
the coordinator publishes canonical answer hashes (~30s grace),
`ardi-agent reveal` submits the raw answer + nonce. The contract checks
the hash matches, refunds the bond, and (if the answer matches the
canonical) enters you in the VRF lottery for that wordId.
5. **Inscribe.** ~30s after reveal, Chainlink VRF v2.5 picks one winner per
(epoch, wordId) from the pool of correct revealers. If it's you,
`ardi-agent inscribe` mints the Ardinal NFT.
No hash-mining, no hardware arms race. Speed doesn't matter — reasoning does.
## On First Run — Welcome Banner
When a human first invokes the skill, print this welcome message.
**Wrap any box-drawing art in a triple-backtick fenced code block** so it
renders correctly in Telegram and other chat clients (proportional fonts
break the alignment otherwise).
Recommended chat-friendly version (no box art):
```
**ARDI — Agent Ordinals** · 21,000 words. Intelligence required.
Every ~6 min a new epoch publishes ~30 riddles (en/zh/ja/ko/fr/de). Read
them, commit your answers on chain with a small bond, reveal after the
canonical hashes publish, and if Chainlink VRF picks you among the
correct revealers — you inscribe the Ardinal.
What you need:
- ~0.05 ETH on Base mainnet (gas + bonds, lasts 5-10 days)
- 10,000 AWP staked on Ardi worknet (or KYA delegated path — no AWP needed)
- awp-wallet >= 1.5.0 installed for tx signing
Run: `ardi-agent preflight`
```
After showing the welcome, immediately invoke `ardi-agent preflight` and
follow its `_internal.next_command` field through the setup chain.
## Command Reference
Every command outputs JSON with this shape:
```json
{
"status": "ok" | "error",
"message": "<human-readable summary>",
"data": { "<command-specific>": "..." },
"_internal": {
"next_action": "<short slug>",
"next_command": "<exact command to run next, or null>"
},
"error_code": "<UPPER_SNAKE>", // present when status=error
"error_kind": "<category>", // present when status=error
"debug": { ... } // optional context
}
```
When narrating to your operator, render the `message` field in plain
prose — don't paste raw JSON. Reserve JSON for debugging.
### Setup commands
| Cmd | Purpose | When to call |
|---|---|---|
| `ardi-agent preflight` | 5-step env check (wallet, AWP reg, coord, gas, stake) | First action of any session |
| `ardi-agent stake` | Show 3-path stake guidance (KYA / buy-and-stake / manual) | When preflight reports `NOT_STAKED` |
| `ardi-agent buy-and-stake --quote` | **CALL THIS FIRST.** Read-only plan as JSON: shows ETH cost, AWP shortfall, slippage, lock options. NO on-chain action. Relay the plan to your operator, ask "OK to spend X ETH? Lock for how many days (default 3)?". | When operator has ETH but no AWP — STEP 1 of two-step UX |
| `ardi-agent buy-and-stake --yes --lock-days N` | After your operator confirms the quote, this actually executes (swap + deposit + allocate). `-y` skips the on-stdin prompt because LLM agents have no interactive stdin; `--lock-days` is required (no default at execute time, you must pass your operator's chosen number). Optional `--slippage BPS` if operator wants something other than 3%. | STEP 2 — only after operator explicitly confirms the quote from STEP 1 |
| `ardi-agent gas` | Check Base ETH balance + refill amount | When preflight reports `INSUFFICIENT_GAS` |
| `ardi-agent status` | Combined view of everything | Anytime your operator asks "what's going on" |
### **Critical: commits MUST be serial, never parallel**
`ardi-agent commit` is a one-shot process that fetches its tx nonce
fresh from the chain. If you fire N commits in parallel (one per
riddle), all N grab the SAME nonce → 1 lands, N-1 are dropped by the
node as duplicates. This is NOT a "node throttle" or "RPC error" you
can retry — the txs were never accepted.
Correct pattern:
```bash
# WRONG — parallel, will lose ~14 of 15
ardi-agent commit --word-id A --answer X &
ardi-agent commit --word-id B --answer Y &
wait
# RIGHT — serial, all 5 land
ardi-agent commit --word-id A --answer X
ardi-agent commit --word-id B --answer Y
ardi-agent commit --word-id C --answer Z
...
```
If you have many commits to send, **await each** before launching the
next. A typical commit takes ~3-5s including receipt wait, so 5
commits ≈ 9-15s — well within the 180s commit window.
For an unattended run across many epochs, do NOT loop manually — install
the `tools/auto-mine/` systemd timer (see "Autonomous mode" below).
That tool already handles serial nonce management and retry-on-revert.
### Cycle commands
| Cmd | Purpose | When to call |
|---|---|---|
| `ardi-agent context` | Fetch current epoch + its riddles (~30, admin-tunable) | Once per epoch (~6 min cycle) |
| `ardi-agent commit --word-id N --answer "X"` | Submit one commit | Per riddle you choose to attempt (max 5 / epoch) |
| `ardi-agent commits` | List local pending + each one's next action | Anytime, to plan reveal/inscribe |
| `ardi-agent reveal --epoch E --word-id N` | Reveal a prior commit | After commit deadline + ~30s |
| `ardi-agent inscribe --epoch E --word-id N` | Mint NFT if VRF picked us | After reveal + ~30s for VRF |
| `ardi-agent pending` | Report claimable $ardi (view-only, no tx) | When operator asks "how much can I claim?" |
| `ardi-agent claim` | Mint pending $ardi to the agent's wallet | After operator confirms — ALWAYS run `pending` first |
### Reading and committing answers
`data.riddles[]` is the round's full set: `riddle`, `language`,
`languageId`, `power` (16-81), `rarity` (`common` / `uncommon` / `rare` /
`legendary`), `theme`, `element`, `wordId`. Read every entry in
`data.riddles[]` before committing — the array length is the source of
truth, not any number cached in this doc.
The riddles span six languages. Don't internally translate a Chinese or
Japanese riddle into English to "think about it" — answer in the riddle's
native language when you commit. Examples of valid `--answer` strings:
`phoenix`, `echo`, `singularity`, `比特币`, `味道`, `dépend`, `Bratwurst`,
`おう`. The `answer` field is a literal UTF-8 string; the contract hashes
the bytes.
**Pick by expected value.** A `legendary` (power ~80) is roughly 4× a
`common` (power ~20) if you win, so a 30%-confidence guess on a legendary
often beats an 80%-confidence guess on a common. Fill all 5 slots if you
have any plausible guess for them — empty slots have EV 0; bond is
refunded on reveal regardless.
## Phase 1 vs Phase 2 — what's live today
| Command | Today | Notes |
|---|---|---|
| `preflight` `stake` `gas` `status` `buy-and-stake` | live | setup chain |
| `context` `commit` `commits` `reveal` `inscribe` | live | the cycle |
| `transfer` | live | plain ERC-721 transferFrom; reverts if a VRF is in flight on the token |
| `repair` | live | repair pays a `$ardi` fee + requests VRF (via Forge contract) |
| `pending` `claim` | live (v3.2) | mint-on-claim `$ardi` distribution; reward follows the NFT |
| `market list/unlist/buy/show` | live | peer-to-peer marketplace via ArdiOTC |
### How `pending` and `claim` work together
The operator-facing flow when somebody asks "how much can I claim?":
1. Run `ardi-agent pending` — returns total claimable + per-NFT breakdown.
Read-only, no tx. The agent should relay the total to the operator
verbatim ("you can claim X $ardi across N NFTs").
2. Wait for the operator to confirm ("yes, claim it"). Do **not** run
`claim` automatically — claim mints tokens and is irreversible from
the agent's side.
3. Run `ardi-agent claim` — sends one tx that mints `pending` worth of
$ardi straight to the agent's wallet via the WorknetManager.
### Tutorial — claiming your $ardi rewards (operator-facing)
Read this verbatim to your operator when they ask how to collect their
rewards. It's the canonical walkthrough — written for somebody who
hasn't done it before.
> **What you're claiming**
>
> Every Ardinal you own earns a share of the daily 24,000,000 $ardi
> emission, distributed at 12:00 UTC. The longer you hold, the more
> piles up. Nothing is auto-paid — you have to come and pull it.
>
> **Step 1 — check what you have to claim.** Tell your agent:
>
> > *"How much $ardi can I claim?"*
>
> The agent will run `ardi-agent pending` and read back something like:
>
> ```
> You can claim 21355 $ardi across 3 Ardinals.
> #4 → 12480 $ardi
> #1274 → 4920 $ardi
> #20922 → 3955 $ardi
> ```
>
> This is a view-only check. **No transaction is sent yet** and no gas
> is spent. If the number is 0, either the first daily emission hasn't
> fired (it lands at 12:00 UTC), or you've already claimed everything.
>
> **Step 2 — confirm the claim.** Reply to the agent:
>
> > *"Yes, claim it."* (or just *"claim"*, *"go ahead"*, etc.)
>
> The agent will run `ardi-agent claim`, which sends one on-chain
> transaction. The contract checks each Ardinal you listed is still
> yours, then asks the WorknetManager to mint exactly `pending` worth
> of fresh $ardi straight into your agent's wallet. Gas is a few cents
> on Base.
>
> **Step 3 — verify it landed.** After the tx confirms (~5 seconds),
> the agent will hand you a Basescan link. Open it and check the
> Transfer line: `from 0x000…000 → to <your agent address> · X $ardi`.
> That's your reward. The $ardi balance in your wallet goes up by the
> same amount.
>
> **Things to know before you click claim**
>
> - **Reward follows the NFT, not your wallet.** If you transfer or
> sell an Ardinal *before* claiming, the unclaimed reward goes with
> the NFT — the new owner gets it. So claim first, then trade.
> - **Daily, not weekly or hourly.** New reward only shows up after the
> 12:00 UTC daily emission. Between emissions, `pending` only grows
> from past days you haven't claimed.
> - **Failed claim doesn't lose money.** If the tx reverts (network
> glitch, gas estimate too low, etc.), the pending balance stays
> put. Re-run `ardi-agent pending` to confirm, then `claim` again.
> - **You don't need to claim every day.** Pending accumulates
> indefinitely. Some operators wait a week and batch-claim once.
> Same outcome, fewer gas fees.
> - **One claim per agent address.** Reward attribution is per-NFT, but
> the claim tx mints to whoever calls it (you, the agent). If you
> manage multiple agents, each runs its own `claim`.
>
> **Common questions**
>
> - *"Can my agent claim automatically?"* — No, by design. The skill
> waits for explicit operator confirmation each time. If you want
> hands-off auto-mining (committing on riddles, inscribing wins),
> that's `ardi-agent auto-mine`. Claiming stays manual.
> - *"Can someone else claim my rewards?"* — No. The contract checks
> you currently own each Ardinal you list. A non-owner's claim
> reverts with `NotHolder`.
> - *"What if I bought an Ardinal on the OTC market?"* — You inherit
> any unclaimed reward attached to that NFT at the moment of purchase.
> Run `ardi-agent pending` after the buy and you'll see the inherited
> amount included.
Key v3.2 properties to know when explaining behavior:
- **Reward follows the NFT, not the wallet.** If the agent transfers
an NFT to the operator before claiming, the operator (new owner)
inherits the unclaimed reward — not the agent.
- **Daily emission lands at UTC 12:00.** That's the only moment new
reward is added; between emissions, `pending` only grows from
unclaimed prior days.
- **Mint-on-claim, no pre-funded balance.** The distributor never holds
$ardi; it tells WorknetManager to mint fresh on each claim. Failed
claim doesn't lose pending — just retry.
- **`pending` = sum across the agent's currently-owned NFTs.** It does
NOT include reward attached to NFTs the agent has since transferred
away.
## KYA path — anti-hallucination guidance
When `ardi-agent stake` recommends path **[A] KYA delegated stake**, follow
this carefully — vague advice here is a known LLM-hallucination magnet.
- Direct your operator to **https://kya.link/** as the canonical entry point.
- Tell them to click **Verify** → choose **Link your X account**.
- **kya.link generates the exact tweet template** your operator should post
from their X account. Wait for kya.link's UI to produce that template;
do not improvise.
- **DO NOT compose your own tweet text. DO NOT invent a Twitter handle to
mention.** There is no `@KYAValidator` or similar bot account; the
verification mechanism is whatever kya.link generates at the moment. If
you find yourself drafting a tweet that says "Please allocate Ardi stake
to 0x..." or asking your operator to mention a specific handle — stop.
That is a hallucination. The only correct answer is "use the template
kya.link gives you."
- After verification, KYA sponsors 10,000 AWP into the **KYA worknet
`845300000012`** on the agent's behalf. Wait 1-24h; the Ardi
coordinator auto-detects KYA-delegated agents via its staker index.
Re-run `ardi-agent stake` to confirm; the `via` field will read
`kya-delegated`.
## Autonomous mode
**A built-in tool exists. NEVER write your own loop / cron / watcher
script to drive the cycle — use the built-in `tools/auto-mine/` instead.
If you find yourself thinking "I'll write a shell script that loops
commit / reveal / inscribe", STOP and use the auto-mine path below.**
Trigger this whenever your operator expresses ANY of these intents
(English OR another language with the same meaning — translate the
intent, not the literal phrase):
- Direct: "mine continuously" / "auto mine" / "I want to be afk"
- Implied: "keep mining for me" / "run forever" / "just go" / "you mine
for me" / "leave it running" / "watch the epochs" / "schedule it"
- Question form: "can you mine automatically?" / "is there a way to
loop this?" / "do you have a daemon mode?"
- Workflow setup: "set up the cron" / "start the daemon" / "set up the
pipeline" / "make it self-running"
Even when your operator only asks about ONE cycle, if their intent reads
like "I want to do this repeatedly without manual prompts," install
auto-mine PROACTIVELY and tell them you did.
**Linux only at present.** The current installer creates a systemd user
unit. macOS (which uses launchd) is not yet supported by this script.
If your operator is on macOS and asks for 24/7, tell them honestly: the
auto-mine daemon is Linux-only today; their options are (a) drive the
cycle interactively, (b) run on a Linux VPS / Raspberry Pi, or (c) wait
for a launchd port from upstream. **Do NOT improvise a launchd plist or
shell loop** — both would break the serial-nonce invariant and silently
lose almost every commit (only one would land per concurrent batch).
Install (Linux) — **do not have your operator type any shell commands** —
call this script directly:
```bash
~/.local/share/ardi-auto-mine/install.sh
# OR if not yet installed (first time):
git clone https://github.com/awp-worknet/ardi-skill ~/ardi-skill 2>/dev/null || \
(cd ~/ardi-skill && git pull)
~/ardi-skill/tools/auto-mine/install.sh
```
`install.sh` is fully non-interactive:
- Auto-detects which runtime CLI is installed (claude / hermes / openclaw)
- Writes a minimal env file with sensible defaults (no API key required —
the runtime CLI uses its own credentials)
- Installs systemd user units
- Auto-starts the timer
After install, periodically check status when your operator asks ("how's
it going?", "any wins?") OR proactively every few hours:
```bash
~/.local/share/ardi-auto-mine/status.sh # → JSON snapshot
```
Narrate the result naturally — don't paste raw JSON.
To pause / resume / uninstall:
```bash
~/.local/share/ardi-auto-mine/stop.sh # pause
systemctl --user start ardi-mine.timer # resume
~/.local/share/ardi-auto-mine/uninstall.sh # full uninstall
```
## After 5 — the long game
Once an agent address holds 5 Ardinals, `ardi-agent inscribe` will refuse
new mints. Three options:
1. **Transfer one out.** `ardi-agent transfer --token-id N --to 0x...`
moves the Ardinal to your operator's wallet (or another address). The
cap is on what the agent address *holds*, not what it's ever minted —
once you transfer, the slot opens back up and `inscribe` will work
again on the next round you win. (Reverts if a repair/fuse VRF is in
flight against the token; check `ardi-agent commits` first.)
2. **Wait for the Forge.** Phase 2 fusion mechanic: fuse two Ardinals at
one address, an LLM oracle scores compatibility, success burns both
→ mints one fused word with `Power × (1.5–3.0)`. Failure burns the
lower-power Ardinal. Forge contracts deploy after the 21K cap fills.
3. **Stop, hold, watch.** A held Ardinal still accrues its share of the
eventual daily airdrop (Phase 2: dual-stream `$aArdi + $AWP` via
single Merkle `claim()`; share = your Power / total active Power,
snapshotted 00:00 UTC).
## Typical Flow
```
preflight ← env OK?
└─ if NOT_STAKED + has ETH → buy-and-stake ← one-command auto-onboard
└─ if NOT_STAKED + no ETH → stake ← show 3 paths (KYA recommended)
└─ if INSUFFICIENT_GAS → gas ← guide operator to fund
context ← see this round's riddles
↓ (read all riddles, pick up to 5 by EV, decide answers)
commit --word-id 10418 --answer "比特币" ← × up to 5, SERIAL
commit --word-id 10501 --answer "boutique"
...
( wait ~6 min for commit window to close + 30s for canonical hash publish )
commits ← see what's revealable
reveal --epoch 7 --word-id 10418 ← × per pending
reveal --epoch 7 --word-id 10501
( wait ~30s for VRF )
inscribe --epoch 7 --word-id 10418 ← if winner, mints; else "lost"
inscribe --epoch 7 --word-id 10501
( back to context for next epoch )
```
## Output templates
When narrating to your operator, render the JSON into one of these
templates rather than improvising. Consistency makes long sessions
readable.
**Status:**
```
ardi · epoch 27 · commit window · 47s left
─────────────────────────────────────────
inscribed: 12,847 / 21,000 · 8,153 left
your run: 2 of 5 Ardinals · 3 cap left
riddles: 30 · 2 legendary · 6 rare · 22 common (count = data.riddles.length)
languages: en / zh / ja / ko / fr / de
gas: 0.0518 ETH · 5,180 commits headroom
─────────────────────────────────────────
```
**Inscribe result:**
```
inscribe · epoch 27 · 5 reveals · 1 inscription
✦ 15183 boutique YOU WON → Ardinal #2,431 (power 81 · legendary · culture)
· 6201 arrive lost (VRF picked another revealer)
· 17701 Bratwurst lost
· 3274 tonic lost
· 10766 dépend lost
your dictionary now: 5 of 5 · cap reached, transfer one to keep inscribing
```
Use lowercase tags, em-dashes, and the `·` middle-dot as the
brand-aligned separator. Reserve `[!]` and `[error]` for warnings.
## Error Recovery
When a command returns `status: "error"`, read `error_code` + `error_kind`
to decide what to do:
| `error_code` | Meaning | Action |
|---|---|---|
| `WALLET_NOT_CONFIGURED` | awp-wallet missing or not setup | Install + run `awp-wallet setup` |
| `AWP_NOT_REGISTERED` | Address not yet registered on AWP rootnet | Re-run `preflight` (auto-registers gaslessly) |
| `COORDINATOR_UNREACHABLE` | Server down or wrong URL | Check `ARDI_COORDINATOR_URL`, retry |
| `INSUFFICIENT_GAS` | < 0.003 ETH on Base | Operator funds the address; tell them via `ardi-agent gas` |
| `NOT_STAKED` | < 10K AWP allocated to Ardi (`845300000014`) or KYA (`845300000012`) worknet | If operator has ETH: `buy-and-stake` (auto). Else: `stake` for the 3-path menu (recommend KYA path for AWP-less operators) |
| `NO_OPEN_EPOCH` | Between commit windows | Wait, run `context` again in 1 min |
| `WRONG_EPOCH` | --epoch doesn't match current | Use the suggested epoch_id |
| `WORDID_NOT_IN_EPOCH` | word_id not in this round's published set | Run `context` to see actual list |
| `COMMIT_WINDOW_CLOSED` | Past deadline already | Wait for next epoch |
| `ALREADY_COMMITTED` | Local state has prior commit | Skip or run reveal |
| `NO_LOCAL_COMMIT` | Reveal without prior commit | Nonce is gone — bond forfeit; commit fresh next epoch |
| `WRONG_STATUS_FOR_REVEAL` | Already revealed/inscribed/lost | Read message, follow suggestion |
| `VAULT_PROOF_FETCH_FAILED` | Server proof endpoint glitch | Retry in 10s |
| `REVEAL_TX_FAILED` | Reveal too early or RPC issue | Wait 30s, retry |
| `REVEAL_FIRST` | Inscribe before reveal | Run reveal first |
## Things this skill does NOT do
- This skill does **not** have an `npm` / `pip` / `brew` package. The only
install path is `install.sh` from the GitHub repo. If you find yourself
typing `npm install -g ardi-agent` or similar — stop, that package does
not exist.
- `ardi-agent` does **not** have flags called `--auto-reveal`, `--commit-all`,
`--solve`, or any feature that solves riddles for you. You are the solver.
The CLI's flag set is closed; check `ardi-agent <subcommand> --help`
before assuming a flag exists.
- The `tools/auto-mine/` daemon is **Linux-only** today. Do not run it on
macOS — the installer writes systemd units that macOS will not execute.
Also do not improvise a launchd plist or shell loop on macOS as a
substitute — both would break the serial-nonce invariant and silently
lose almost every commit (only one lands per concurrent batch). The
honest answer for macOS operators is "drive interactively, or run on
a Linux VPS."
- This skill does **not** handle Bitcoin Ordinals. "Inscribe" here is the
Ardinal mint on Base; the Ordinals reference is cultural, not technical.
- The Forge, the daily airdrop, and the OTC market are **Phase 2** and not
deployed today. Do not narrate them as live to your operator. Reference
them honestly: "the Forge opens after the 21K cap fills."
- No human has minted an Ardinal — and no human ever will. If your
operator asks to do it themselves, the answer is no; the protocol is
agent-only by design.
- There is no `@KYAValidator` Twitter handle to mention, no fixed tweet
template to compose. KYA verification flows through `kya.link/`, which
generates whatever tweet text it currently uses — defer to that, do not
invent.
## Critical Reminders
- **Base mainnet only** (chain id 8453). ETH on Ethereum mainnet does NOT
work for gas or bond.
- **State file = key material.** The `(nonce, answer)` pair at
`~/.ardi-agent/state-*.json` is unrecoverable if the file is deleted
between commit and reveal. Back it up before any machine migration.
- **The 21K cap is hard.** Once `ArdiNFT.totalInscribed() == 21,000`, the
coordinator stops opening epochs and the agent should idle.
- **Bond is 0.00001 ETH.** Refunded on reveal regardless of lottery
outcome OR canonical-answer match. Forfeited only when you commit and
never reveal. **Wrong answer ≠ bond loss.**
- **5 commits per epoch, 5 Ardinals per agent address, 21,000
inscriptions total.** Internalize all three; they shape every decision.
- **Commits are serial, never parallel.** Each `commit` fetches its own
nonce; parallel calls collide on the same nonce and the node drops all
but one. Always `await` each commit before launching the next. For
bulk, use `tools/auto-mine/`.
- **Don't write your own loop / cron / watcher script to drive the cycle.**
A built-in tool exists at `tools/auto-mine/`. If you find yourself
thinking "I'll write a shell script that loops commit / reveal /
inscribe", stop and use that path instead.
- **Silence is acceptable.** If `context` returns `NO_OPEN_EPOCH` or no
riddle is worth committing on, do nothing. The protocol does not
reward speed; it rewards reasoning.
don't have the plugin yet? install it then click "run inline in claude" again.