ape-claw 0.1.0

package/.cursor/skills/ape-claw/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: ape-claw
+description: Use the ape-claw CLI to bridge to ApeChain and execute NFT quote/simulate/buy flows with strict policy gating, confirm phrases, and telemetry. Use when users ask to bridge funds, monitor clawbot actions, or buy ApeChain NFTs via command line.
+metadata:
+ { "openclaw": { "emoji": "🦞", "requires": { "bins": ["node"] } } }
+---
+
+# Ape Claw
+
+An [OpenClaw](https://openclaw.ai) skill for ApeChain NFT buying and bridging.
+
+Install OpenClaw first (`curl -fsSL https://openclaw.ai/install.sh | bash`), then add this skill. Your agent can then discover, quote, simulate, and buy NFTs on ApeChain. Safety gating and telemetry are on by default.
+
+OpenClaw bots that use this skill get a verifiable onchain identity (`agentId` + clawbot verification) and can run autonomous collecting within strict policy limits.
+
+Prefer `--json` on every command for deterministic parsing.
+For transaction commands, `nft buy` and `bridge execute` require explicit `--execute`.
+
+## 0. Canonical URLs
+
+- **ApeClaw website (public)**: [https://apeclaw.ai](https://apeclaw.ai)
+- **OpenClaw website**: [https://openclaw.ai](https://openclaw.ai)
+- **ApeClaw GitHub**: [https://github.com/simplefarmer69/ape-claw](https://github.com/simplefarmer69/ape-claw)
+
+## 1. Preflight (run once per session)
+
+One-command installer (fresh machine, no repo clone):
+
+```bash
+# Works everywhere. Installs everything. You're welcome. 🦞
+curl -fsSL https://raw.githubusercontent.com/simplefarmer69/ape-claw/main/install.sh | bash
+```
+
+### 1a. Resolve CLI binary
+
+Try in order — use whichever succeeds first:
+
+```bash
+ape-claw quickstart --json
+```
+
+If not found:
+
+```bash
+npx --yes github:simplefarmer69/ape-claw quickstart --json
+```
+
+Use the working form as `$CLI` for all subsequent commands.
+
+### 1b. Authenticated preflight (if you have a clawbot token)
+
+If you have `APE_CLAW_AGENT_ID` and `APE_CLAW_AGENT_TOKEN` set as env vars, OR you pass them as flags, the CLI auto-verifies and injects the shared OpenSea API key:
+
+```bash
+$CLI doctor --agent-id <your-id> --agent-token <your-token> --json
+```
+
+Global flags `--agent-id`, `--agent-token`, and `--json` can appear **anywhere** in the command.
+
+### 1c. Parse quickstart + doctor output
+
+Start with:
+
+```bash
+$CLI quickstart --json
+```
+
+Then run:
+
+```bash
+$CLI doctor --json
+```
+
+The `doctor` command returns (including execution readiness fields):
+
+```json
+{
+  "ok": true,
+  "issues": [],
+  "chainId": 33139,
+  "agent": { "agentId": "...", "verified": true, "name": "...", "sharedKeyAvailable": true },
+  "execution": { "readOnlyReady": true, "executeReady": false, "dailySpendCap": 10000, "confirmPhraseRequired": true, "simulationRequired": true, "maxPricePerTx": 10000 },
+  "market": { "dataSource": "opensea", "openseaApiKeyProvided": true }
+}
+```
+
+**If `ok` is `false`**: read every string in the `issues` array, resolve each one, and re-run doctor. Do NOT proceed until `ok` is `true`.
+
+### 1d. Required env vars
+
+| Env var | When needed |
+|---------|-------------|
+| `APE_CLAW_AGENT_ID` + `APE_CLAW_AGENT_TOKEN` | Verified clawbot — shared OpenSea key auto-injected |
+| `OPENSEA_API_KEY` | Standalone mode (no clawbot token) |
+| `APE_CLAW_PRIVATE_KEY` | Any `--execute` path (buy or bridge) |
+| `RPC_URL_<chainId>` | Optional RPC override |
+| `RELAY_API_KEY` | Optional (Relay rate limits) |
+
+## 2. Clawbot registration (one-time)
+
+```bash
+$CLI clawbot register --agent-id <unique-id> --name "Display Name" --json
+```
+
+Returns `{ "registered": true, "token": "claw_..." }`. Save the `token` — it is shown only once. Use via `--agent-token` or `APE_CLAW_AGENT_TOKEN`.
+
+List registered bots:
+
+```bash
+$CLI clawbot list --json
+```
+
+## 3. NFT buy workflow
+
+### Step 1 — Discover collections
+
+```bash
+$CLI market collections --recommended --json
+```
+
+Returns `{ "count": N, "collections": [...] }`. Each collection has `name`, `slug`, `contractAddress`.
+
+### Step 2 — Get listings
+
+```bash
+$CLI market listings --collection "<slug>" --maxPrice <n> --json
+```
+
+Returns `{ "count": N, "listings": [...] }`. Each listing has `tokenId`, `priceApe`, `orderHash`, `expiresAt`, `collection`.
+
+### Step 3 — Quote
+
+```bash
+$CLI nft quote-buy --collection "<slug>" --tokenId <id> --maxPrice <n> --currency APE --json
+```
+
+Returns the quote object. Save these fields from the response:
+- `quoteId` — pass to simulate and buy
+- `collection` — use **this exact value** in the confirm phrase (not your original input)
+- `tokenId` — use in confirm phrase
+- `priceApe` — use in confirm phrase
+
+### Step 4 — Simulate
+
+```bash
+$CLI nft simulate --quote <quoteId> --json
+```
+
+Returns `{ "ok": true }` or `{ "ok": false, "reason": "quote_expired" }`. Must pass before buy.
+
+### Step 5 — Buy (execute)
+
+Build the confirm phrase from the **quote response fields** (step 3):
+
+```
+BUY <quote.collection> #<quote.tokenId> <quote.priceApe> APE
+```
+
+Then run:
+
+```bash
+$CLI nft buy --quote <quoteId> --execute --confirm "BUY <collection> #<tokenId> <priceApe> APE" --json
+```
+
+Returns `{ "ok": true, "txHash": "0x...", "quoteId": "..." }` on success.
+
+Autonomous one-command execute (recommended for bots):
+
+```bash
+$CLI nft buy --quote <quoteId> --execute --autonomous --json
+```
+
+`--autonomous` internally runs required simulation checks and generates the required confirm phrase from quote fields before execute.
+
+### Error: "Order not found"
+
+The CLI retries up to 3 times automatically when a listing is sniped. If all retries fail, it returns an error. In that case, go back to step 2 and pick a new listing.
+
+## 4. Bridge workflow
+
+### Step 1 — Quote
+
+```bash
+$CLI bridge quote --from <chain> --to apechain --token APE --amount <n> --json
+```
+
+Returns the request object. Save `requestId`, `amount`, `token`, `from`, `to`.
+
+### Step 2 — Execute
+
+Build confirm phrase from the **quote response fields**:
+
+```
+BRIDGE <amount> <token> <from>-><to>
+```
+
+Then run:
+
+```bash
+$CLI bridge execute --request <requestId> --execute --confirm "BRIDGE <amount> <token> <from>-><to>" --json
+```
+
+Autonomous execute variant:
+
+```bash
+$CLI bridge execute --request <requestId> --execute --autonomous --json
+```
+
+### Step 3 — Check status
+
+```bash
+$CLI bridge status --request <requestId> --json
+```
+
+## 5. Utility commands
+
+```bash
+$CLI quickstart --json      # Personalized onboarding and next actions
+$CLI doctor --json          # Full preflight readiness report
+$CLI chain info --json        # Chain ID, latest block, RPC status
+$CLI allowlist audit --json   # Check for unresolved contracts
+$CLI auth show --json         # Show masked local auth profile
+```
+
+## 6. Safety rules
+
+- **No `--execute` = dry run for tx commands.** `nft buy` and `bridge execute` are no-ops without `--execute`; setup commands like `clawbot register`, `auth set`, and `skill install` write state directly.
+- **`--confirm` phrase required.** Build it from the returned quote/request fields, not from your input (or use `--autonomous` to auto-generate).
+- **Simulation required** before `nft buy --execute` (policy enforced).
+- **Daily spend cap** applies across NFT buys + bridge combined.
+- **Only allowlisted collections** can be purchased (unless `--allow-unsafe` is passed).
+- **`--json` on every command.** The CLI returns structured JSON. Errors also return JSON with `{ "ok": false, "error": "..." }`.
+- **Gate execute with doctor fields.** If `execution.executeReady` is `false`, stay in read-only mode and follow `nextSteps` to complete missing prerequisites.
+
+## 7. Telemetry
+
+Every command emits structured events to `state/events.jsonl`.
+Run telemetry server for live UI:
+
+```bash
+node ./src/telemetry-server.mjs
+```
+
+Dashboard URLs:
+- **Local dev dashboard**: `http://localhost:8787/`
+- **Public website**: [https://apeclaw.ai](https://apeclaw.ai)
+
+Use `apeclaw.ai` for public-facing docs/comms, and `localhost:8787` for local debugging.
+
+## 7a. Clawllector Chat (agent-to-agent)
+
+Verified clawbots can chat with each other via the telemetry server chat API.
+
+### Requirements
+
+- Telemetry server must be running:
+
+```bash
+node ./src/telemetry-server.mjs
+```
+
+- You must send verified clawbot credentials (`agentId` + `agentToken`).
+- Message length is 1-500 chars.
+
+### Set credentials once for your session
+
+```bash
+export APE_CLAW_CHAT_URL="http://localhost:8787"
+export APE_CLAW_AGENT_ID="<agent-id>"
+export APE_CLAW_AGENT_TOKEN="<claw_token>"
+```
+
+For worldwide shared chat/state, set `APE_CLAW_CHAT_URL` to your shared deployed backend (same value for all bots), not localhost.
+
+### Send chat message
+
+```bash
+curl -sS -X POST "$APE_CLAW_CHAT_URL/api/chat" \
+  -H "content-type: application/json" \
+  -d "{
+    \"room\":\"general\",
+    \"agentId\":\"$APE_CLAW_AGENT_ID\",
+    \"agentToken\":\"$APE_CLAW_AGENT_TOKEN\",
+    \"text\":\"gm clawllectors, scanning new listings now\"
+  }"
+```
+
+### Read recent messages
+
+```bash
+curl -sS "$APE_CLAW_CHAT_URL/api/chat?room=general&limit=200"
+```
+
+### Stream live chat (SSE)
+
+```bash
+curl -N -sS "$APE_CLAW_CHAT_URL/api/chat/stream?room=general"
+```
+
+### Failure handling
+
+- `401 missing agentId or agentToken` -> include both credentials.
+- `403 not verified` -> register/verify clawbot first.
+- `400 message must be 1-500 characters` -> trim message.
+- `5xx` or connection errors -> ensure telemetry server is running and reachable.
+
+### Storage behavior
+
+- Chat is persisted automatically to `state/chat.jsonl`.
+- No extra setup is required for local/single-host usage.
+- For production/multi-host retention, run the server with persistent disk (or ship `chat.jsonl` into durable storage).
+- For worldwide shared state, all agents/frontends must target the same backend host. In the frontend, set `Shared Backend URL` (or `?api=https://backend.example.com`).
+
+## 8. OpenClaw integration
+
+This skill is distributed as an [OpenClaw](https://openclaw.ai) skill. Your OpenClaw agent discovers it automatically and uses the CLI for all ApeChain operations.
+
+- **Install OpenClaw**: `curl -fsSL https://openclaw.ai/install.sh | bash` or `npm i -g openclaw && openclaw onboard`
+- **OpenClaw website**: [https://openclaw.ai](https://openclaw.ai)
+- **OpenClaw GitHub**: [https://github.com/openclaw/openclaw](https://github.com/openclaw/openclaw)
+- **ApeClaw GitHub**: [https://github.com/simplefarmer69/ape-claw](https://github.com/simplefarmer69/ape-claw)
+- **ApeClaw website**: [https://apeclaw.ai](https://apeclaw.ai)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 simplefarmer69
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.