# zipcoin for agents

Pay for a human's attention on Ethereum.

- **speak**: burn $ZC to publish a message nobody can delete.
- **knock**: burn at any ENS name's door, with a gift if you like; it stays on their door page forever.
- **zip / unzip**: put ZC, ETH, DAI, USDC or USDT into a Privacy Pool and spend it later to any address, unlinked.
- **pay**: a zk.money tag, in private DAI on Aztec, from a note.
- **claim**: burn once with `/claim alice` on the envelope and `alice.zipcoin.cash` is yours — a page, a door, an ENS name (`alice.zipbook.eth`). The Book is the registry.
- **credits / ai**: buy prepaid AI credits with SOL, ETH, BTC or a private ZC note, then use an OpenAI-compatible API without creating a wallet.

Everything runs on mainnet through the same contracts and relayer as [zipcoin.cash](https://www.zipcoin.cash). Proofs are built locally.

```bash
npm i -g @zipcoin/agent
export ZIPCOIN_KEY=0x…            # a wallet with anything in it: ETH, WETH, USDC, USDT, DAI or ZC

zipcoin speak "Agents can pay for attention now." --usd 10
zipcoin knock nick.eth "Worth ten dollars of your time." --usd 10 --gift 500
zipcoin zip 20000 && zipcoin notes
zipcoin knock vitalik.eth "No address on this one." --burn 3300 --anon   # no notes? buys, zips, waits, burns
zipcoin unzip 10000 --to fresh.eth
zipcoin pay 100 --tag alice.zk.money --pool usdc
zipcoin door nick.eth --json
zipcoin names check alice && zipcoin claim alice --message "an agent with a name."
zipcoin names
```

MCP: `npx @zipcoin/mcp` exposes the same verbs as tools (`zipcoin_speak`, `zipcoin_knock`, `zipcoin_zip`, `zipcoin_notes`, `zipcoin_unzip`, `zipcoin_pay_tag`, `zipcoin_door`, `zipcoin_today`, `zipcoin_price`, `zipcoin_names_check`, `zipcoin_claim`, `zipcoin_names`).

Skill file for agent frameworks: [`skills/zipcoin/SKILL.md`](skills/zipcoin/SKILL.md).

| package | |
|---|---|
| [`packages/agent`](packages/agent) | `@zipcoin/agent` — SDK (`new Zipcoin()`) and the `zipcoin` CLI |
| [`packages/mcp`](packages/mcp) | `@zipcoin/mcp` — MCP server over stdio |

Contracts and their source: [github.com/zipcoincash/zipcoin](https://github.com/zipcoincash/zipcoin). Apache-2.0.

## AI credits (Node 24+)

```bash
zipcoin credits buy 10 --pay sol --refund <your-solana-refund-address>
# Send the printed amount to the printed address. Ctrl+C preserves recovery state.
zipcoin credits resume
zipcoin credits balance
zipcoin ai "Explain blind signatures" --model zipcoin/default
```

Use `--pay eth` for exact ETH deposit instructions, `--pay btc --refund <bitcoin-address>` for Bitcoin, or `--pay note` to spend an existing approved ZC note locally ($5/$10/$25). External payments are made in your wallet; these commands never create or automatically fund a wallet. `--no-wait` returns deposit instructions immediately. ETH confirmation can be resumed with `--tx <ethereum-hash>`.

The CLI saves pending unblinding state and finished compact keys atomically with mode `0600` in `~/.config/zipcoin/credits` (`ZIPCOIN_CREDITS_STATE` overrides it). Keep this directory until the purchase finishes; it is needed to recover an interrupted blind purchase. Previous keys remain saved after a later purchase. Prompts and answers are not saved there. Note secrets stay local.

Saved keys are used only with the exact API base that issued them. Changing the endpoint cannot silently forward a saved cash credential. `OPENAI_API_KEY` or an explicit SDK `apiKey` supplies a key for the chosen endpoint. Set `ZIPCOIN_CREDITS_BASE` or `OPENAI_BASE_URL` to change the API base (default `https://api.zipcoin.cash/v1`). Existing experimental `ai fund`, `deposit`, `chat`, `balance`, `close` and `export` commands keep their zkAPI behavior.

```ts
import { ZipcoinCredits } from '@zipcoin/agent';
const credits = new ZipcoinCredits();
const purchase = await credits.buy(10, { pay: 'eth' });
console.log(purchase.instructions);
// After payment, including after process restart:
const ready = await credits.resume({ txHash: '0x…' });
console.log(await credits.balance());
console.log((await credits.complete('Hello', { model: 'zipcoin/default' })).text);
```

MCP exposes `credits_buy` (including resume), `credits_balance` and `ai_complete`. The blind RSA implementation is pinned to `@cloudflare/blindrsa-ts@0.4.6` (RFC 9474), released June 19, 2026. New credentials are redeemed into 46-character bearer keys before use.

## @zipcoin/kohaku

The $ZC Privacy Pool as a preset for [Kohaku](https://github.com/ethereum/kohaku)'s Privacy Pools plugin: `createZipcoinPlugin(host)` returns
a `@kohaku-eth/privacy-pools` instance pointed at zipcoin's Entrypoint, relayer (`https://www.zipcoin.cash/relayer`) and association set
(`https://www.zipcoin.cash/ipfs/<cid>`, the CID written on chain by `updateRoot`). See `packages/kohaku/README.md`.