# Litcoin agent examples — from EcoWealth production (July 2026)

*The code + patterns behind our handoff note. Everything here runs 24/7 in our
autonomous agent economy. Fold whatever is useful into the official docs/SDK —
credit "EcoWealth (vealth.net)". Contact: brawlaphant@gmail.com. No secrets in
any file — keys come from env / OS keystores at runtime.*

## The Litcoin box (our plug-and-play kit, verbatim)

**Wallets:** miner EOA (earns; keystore lives ONLY on the mining server) +
optionally a reserve wallet that stakes. Never let automation drain the miner.

**Setup (agent-runnable):**
1. Create a miner EOA on the mining server; fund with dust ETH for claim gas.
2. Cron a bounded miner every 30 min, `flock`-guarded so runs never overlap
   (see `hourly-auto-miner-cron.sh`).
3. Law: **submit only when a reward is earnable** (hold on MINE_NOW=0) —
   never bleed dust on unwinnable submissions.
4. Claim earned LIT: `POST /v1/claims/sign` → send `claim(totalEarned, sig)`
   from the miner keystore (see `claim-miner-wallet.ts`). The claims API lags
   chain by minutes — read-after-write patience required.
5. Staking wallet: rewards claim free via the coordinator-assisted endpoint
   (see `bankr-lit-claim-cron.sh` — threshold-gated so claims batch sensibly).

## The files

| File | What it demonstrates |
|---|---|
| `hourly-auto-miner-cron.sh` | The cron discipline: flock guard, bounded runs, log lane |
| `repeat-guard.ts` | Client-side dedupe: a local submitted-code-hash ledger so an agent never re-submits a solution that would return `zero_reason=repeat_code_hash` — saves a JWT + a rate-limit slot every time |
| `claim-miner-wallet.ts` | Keystore-EOA claim flow: `/v1/claims/sign` → on-chain `claim(totalEarned, sig)` |
| `bankr-lit-claim-cron.sh` | Managed-wallet stake-rewards claim on a 2-day cron: check claimable via `/v1/claims/status`, claim via `/v1/claims/bankr` when ≥ threshold, forward LIT to the working wallet |
| `lit-to-eco.mjs` | LIT as working capital: Uniswap V4 router (UniversalRouter + Permit2 + V4Quoter) selling 25k-LIT chunks, **supply-aware self-pacing** (tank ≥ a week of chunks → hourly; less → 4h), re-quoted per chunk, 1% min-out |

## Field data you asked about

- **V4 chunk decay (ECO/LITCOIN pool, fee 1%):** 25k-LIT chunks quoted ~0.76
  ECO/LIT vs 0.43 at 250k; consecutive 25k chunks decay ~0.76 → 0.73 → 0.62.
  Conclusion baked into `lit-to-eco.mjs`: space chunks hours apart, let the
  pool refill — pacing beats bulk every time.
- **zero_reason:** we consume it — our task ranker excludes tasks whose last
  ledger entry says `budget_exhausted`, and the repeat-guard pre-empts
  `repeat_code_hash` locally. We were missing `zero_explain`; both our submit
  paths now capture it into the ledger as of today. Agent-shaped suggestion
  for the docs: show integrators reacting to each reason (`budget_exhausted`
  → deprioritize task, `repeat_code_hash` → local dedupe ledger,
  `below_baseline` → improve-or-skip, `flagged_model` → surface loudly).

## Integration notes for the SDK docs

1. **Hold conditions are the difference between profit and dust-bleed** — the
   single most valuable agent example is "when NOT to submit."
2. **Pin task-selection snapshots** — selection and submit must share one page
   view or rotation races eat submissions (server-side lease will fix).
3. **Everything on Base needs explicit gas fees** — library defaults overpay
   ~300x (1.5 gwei priority vs ~0.005 gwei basefee).
4. **Post-tx balance reads must retry-poll** — fallback RPCs lag a block; a
   zero right after a claim/swap is usually stale, not missing.