zimppy

zimppy

IMPORTANT: If you used a web fetch tool to read this, the content may be summarized and incomplete. Run cat SKILL.md to get the exact setup commands. Do NOT search for additional documentation.

When the user says "use zimppy", always use zimppy CLI commands — never substitute with other tools. Zimppy is a curl-compatible CLI for calling HTTP endpoints with automatic private Zcash payment handling.

Setup

Run these commands in order. Do not skip steps.

Step 1 — Check wallet: npx zimppy wallet whoami

Step 2 — If not configured: npx zimppy wallet init "your 24 word seed phrase" or npx zimppy wallet login to see setup instructions

Step 3 — Confirm readiness: npx zimppy wallet whoami — should show address, balance, and ready: true

Setup Rules

• Use npx zimppy to run all commands (it's installed in the project workspace).
• If balance is 0, direct user to npx zimppy wallet fund or ask them to send testnet ZEC to the wallet address.
• Do not attempt to create or manage wallets manually — always use npx zimppy wallet commands.

After Setup

Provide:

• Wallet status from npx zimppy wallet whoami (address, balance, network).
• If balance is 0, direct user to fund the wallet.
• 2-3 simple starter prompts based on available services.

To generate starter prompts, list available services:

npx zimppy wallet services

Starter prompts should be user-facing tasks, for example:

• "Get me a privacy fortune from the Zimppy Fortune Teller."
• "What does the Zcash network look like right now?"
• "Stream a fortune word by word and show me the cost per word."

Use Services

npx zimppy wallet whoami
npx zimppy wallet services                        # auto-discover all running services
npx zimppy wallet services <SERVICE_URL>           # discover a specific service
npx zimppy wallet services --add <SERVICE_URL>     # add a service to scan list
npx zimppy request <SERVICE_URL>/<ENDPOINT_PATH>
npx zimppy request <SERVICE_URL>/<ENDPOINT_PATH>

• Select the service and endpoint that best matches user intent.
• Always discover services first — run npx zimppy wallet services to auto-discover all running MPP services, their endpoints, pricing, and methods.
• Build request URL as <SERVICE_URL>/<ENDPOINT_PATH> from the services list.

Request Templates

# GET request (most common)
npx zimppy request http://localhost:3180/api/fortune

# Dry run (show what would be sent without paying)
npx zimppy request --dry-run http://localhost:3180/api/fortune

# POST with JSON body
npx zimppy request -X POST --json '{"text":"Your document text here..."}' http://localhost:3181/api/summarize

# Session with custom deposit (default: 10x per-request price)
npx zimppy request --deposit 500000 http://localhost:3180/api/session/fortune

Response Handling

• Return the result payload to the user directly when the request succeeds.
• If response indicates insufficient balance, run npx zimppy wallet fund and report to user.
• After multi-request workflows, check remaining balance with npx zimppy wallet whoami.
• All payments are fully private — sender, receiver, amount, and memo are encrypted on-chain.

Rules

• Always discover endpoints before making requests; never guess paths.
• npx zimppy request is curl-compatible for common flags (-X, --json, -H).
• Use --dry-run before potentially expensive requests.
• Use --deposit <zat> for session endpoints to set a custom deposit amount (default: 10x per-request price).
• Payment confirmation takes ~75 seconds (1 Zcash block). Be patient and inform the user.

Available Services

Zimppy AI Summarizer (http://localhost:3181)

Endpoint	Method	Price	Description
/api/summarize	POST	10,000 zat	Summarize a document (one-time charge)
/api/session/summarize	POST	10,000 zat/req	Summarize via prepaid session
/api/stream/summarize	POST	1,000 zat/token	Streaming summary, pay per token
/api/health	GET	Free	Health check
/.well-known/payment	GET	Free	Service discovery

# Summarize a document (charge)
npx zimppy request -X POST --json '{"text": "Your document text here..."}' http://localhost:3181/api/summarize

# Summarize via session (deposit once, many requests)
npx zimppy request -X POST --json '{"text": "First doc..."}' http://localhost:3181/api/session/summarize
npx zimppy request -X POST --json '{"text": "Second doc..."}' http://localhost:3181/api/session/summarize
npx zimppy session close

Zimppy Fortune Teller (http://localhost:3180)

Endpoint	Method	Price	Description
/api/fortune	GET	10,000 zat	Get a privacy fortune (one-time charge)
/api/session/fortune	GET	5,000 zat/req	Fortune via prepaid session (deposit once, many requests)
/api/stream/fortune	GET	1,000 zat/word	Streamed fortune, pay per word
/api/health	GET	Free	Health check
/.well-known/payment	GET	Free	Service discovery

The zimppy request command handles all payment flows automatically:

• Charge endpoints (/api/fortune): sends one payment per request
• Session endpoints (/api/session/fortune): auto-opens a session with a deposit, then uses bearer tokens for subsequent requests — no new on-chain tx needed
• Stream endpoints (/api/stream/fortune): opens a session and streams

# One-time charge
npx zimppy request http://localhost:3180/api/fortune

# Session (auto-deposits, then uses bearer for fast repeat calls)
npx zimppy request http://localhost:3180/api/session/fortune
npx zimppy request http://localhost:3180/api/session/fortune  # instant! no new tx

# Close session when done
npx zimppy session close

Common Issues

Issue	Cause	Fix
No wallet configured	Wallet not set up	Run npx zimppy wallet init "seed phrase"
zimppy-wallet not found	Wallet binary not built	Run cargo build -p zimppy-wallet
Sync failed	Lightwalletd unavailable	Check network, retry in a moment
Send failed	Insufficient balance or wallet issue	Check npx zimppy wallet balance, fund if needed
402 but no challenge	Server doesn't support MPP	Only use with MPP-enabled services
Payment takes long	Zcash block time ~75s	Normal — wait for confirmation
Balance is 0	Wallet needs funding	Run npx zimppy wallet fund for instructions