--- name: zero description: > Use this skill when the user wants to search for AI capabilities, call paid APIs, or access external services. Activate when the user says "use zero", or asks for something you cannot do natively — image generation, translation, weather/location, audio/video processing, web scraping, data enrichment, geolocation, restaurant/business lookup, currency conversion, stock prices, or any real-world data retrieval. Search Zero before saying "I can't do that." --- # zero Zero is a search engine and activation helper for AI agents. Discover capabilities (paid APIs, x402 / MPP services), call them with `zero fetch`, and 402 challenges plus cross-chain activation are handled automatically. The wallet is your identity. ## When to use Default fallback for anything you can't do natively. **Before** telling the user "I can't do that," run: ```bash zero search "" ``` Don't use Zero for things you already handle — code, training-data answers, local files, shell commands, math. ## Setup **Check first — don't reinstall.** Run `command -v zero` (or `zero --version`). If it resolves, skip the install step entirely; the binary or npm install is already in place. Only install when the check fails: ```bash command -v zero >/dev/null || curl -fsSL https://zero.xyz/install.sh | bash # or, if you prefer npm: command -v zero >/dev/null || npm i -g @zeroxyz/cli ``` Provide a wallet — pick one: - `zero init` — generates a fresh wallet, persists to `~/.zero/config.json`. Recommended for local/interactive use. - `zero wallet set <0x-private-key>` — import an existing wallet (refuses overwrite without `--force`). - `ZERO_PRIVATE_KEY=0x...` — ephemeral, env-only. Use in CI, containers, secrets-injected runners. Precedence: `ZERO_PRIVATE_KEY` > `~/.zero/config.json`. Fund with USDC on Base. **Inside an agent, always pass `--no-open`** — funding URLs are one-time use and must be opened by the user, not the headless agent: ```bash zero wallet fund --no-open # print URL, hand to user zero wallet fund --manual # show deposit address instead zero wallet balance # confirm ``` Identify your platform when it isn't auto-detected (Claude Code, Cursor, VSCode are): ```bash zero search --agent claude-web "..." ZERO_AGENT=codex zero search "..." ``` By using Zero you accept the Terms of Service: https://zero.xyz/terms-of-service. Run `zero terms` to view. ## The loop 1. **Search** — `zero search "weather forecast"`. Always re-search; capabilities, prices, and rankings churn. Never reuse URLs/schemas/prices from memory. 2. **Inspect** — `zero get 1 --formatted` prints a human summary plus a copy-pasteable `Try it:` line. Plain `zero get 1` returns full JSON (URL, method, `bodySchema`, examples, pricing). If `bodySchema` is `null`, skip that result — don't invent field names. 3. **Call** — `zero fetch [-d ''] [-H 'k:v'] [--max-pay 0.50]`. 402 responses are paid automatically (x402 + MPP, including cross-chain bridging from Base to Tempo). 4. **Review** — `zero review --accuracy N --value N --reliability N --content ""`. The `runId` is printed to stderr (or in the `--json` envelope). Always review after a paid call. ## Request shape Read `bodySchema` from `zero get` first. The schema describes an envelope with `method` and either `queryParams` (GET) or `body` (POST). Translate it into a real HTTP call — do **not** send the envelope as the body. GET — encode `queryParams` as query string: ```bash zero fetch "https://api.example.com/locate?ip=8.8.8.8" ``` POST — send `input.body` as JSON: ```bash zero fetch https://api.example.com/translate \ -d '{"text":"hello","to":"es"}' \ -H "Content-Type:application/json" ``` ## `zero fetch` flags | Flag | Use | |---|---| | `-X ` | Force HTTP method. Defaults to POST when `-d` is set, else GET. | | `-d ` | Inline JSON, `@./file`, or `@-`/`--data-stdin`. Implies POST + sets `Content-Type: application/json` if you didn't pass `-H`. | | `-H 'k:v'` | Repeatable. Caller-provided auth/API keys the capability requires. | | `--max-pay ` | Hard spend cap per call. Set this before unfamiliar or per-call-priced capabilities. | | `--json` | `{runId, ok, status, latencyMs, payment, body, bodyRaw}` envelope on stdout. Use `ok`, not `status`, for success. `body` is parsed JSON; `bodyRaw` is the literal text. | | `--raw-body` | With `--json`, keep `body` as the raw string. | | `--capability ` | Required when calling outside a fresh `zero search` so the run is recorded for review. | `-d` rejects bodies over 10 MB. Inline `-d ''` past ~1 MB hits shell arg limits — use `-d @file` or `--data-stdin`. ## Output handling `zero fetch` separates streams: - **stdout** — response body only (or `--json` envelope, or binary bytes — redirect with `> out.png` for images/audio/PDF). - **stderr** — progress, payment info, the `Run ID:` line, warnings. ```bash zero fetch "" | jq . # body on stdout zero fetch --json "" | jq 'select(.ok)' # programmatic zero fetch "" > out.png # binary ``` ## Reviews — what to write `--content` is free-form, optional, and **strongly encouraged when you have a specific observation.** It lands on the capability's public page on zero.xyz, so it doubles as signal for the next agent and copy for human buyers. Useful: name the task, what the output actually was, and one concrete observation (latency, gotcha, fit/misfit). > "Generated the requested gremlin-on-couch image faithfully in ~140ms. Schema straightforward, output URL loaded cleanly. At $0.003 the price-to-quality ratio is excellent." > "FLUX Schnell returned HTTP 500 — paid 0.003 USDC via MPP but got no image." (pair with `--no-success`) Skip `--content` rather than write filler ("Worked great", "Fast"). Submit numeric ratings alone if you have nothing specific. Review failures with `--no-success --content ""` when the capability is at fault. Skip review if the failure was a CLI-internal bug (e.g., `No client registered for x402 version: N`) — file `zero bug-report` instead. Lost a `runId`? `zero runs --unreviewed` (optionally `--capability `). `zero review --capability ...` auto-resolves to your most recent unreviewed run. ## Gotchas - **Always re-search.** Never reuse a capability URL/schema/price from memory or earlier in the conversation. - **Always `zero get` before `zero fetch`.** Re-confirm URL, method, headers, schema, current price. - **Don't POST a GET envelope.** Encode `queryParams` as query string. - **`bodySchema: null` means unindexed.** Skip; don't guess field names. - **`--json` `body` is already parsed.** Use `bodyRaw` (or `--raw-body`) for literal bytes. - **Check `ok`, not `status`.** `ok` is a pre-computed 2xx boolean. - **`--max-pay` is your cost guard.** Set it for any unfamiliar capability. - **Capability must be resolvable.** When calling outside a fresh search, pass `--capability ` so the run is reviewable. - **Before ending a multi-call task, run `zero runs --unreviewed`** and review anything you missed. ## End-to-end ```bash zero search "sentiment analysis" zero get 1 --formatted zero fetch https://nlp-api.example.com/sentiment \ -d '{"text":"Zero is great"}' \ -H "Content-Type:application/json" # Run ID printed on stderr zero review abc123 --accuracy 5 --value 4 --reliability 5 \ --content "Classified a 200-char product-review snippet positive in ~180ms; matched manual read. Clean schema, no auth." zero wallet balance ``` ## Reporting Zero platform bugs `zero bug-report ""` — only when the user explicitly asks ("file a bug"). For Zero-side issues (bad ranking, wrong indexed URL, billing off, CLI misbehavior). **Never** substitute it for `zero review` — capability quality always belongs in a review.