@xcheeze/x402 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# @xcheeze/x402
+
+CLI for AI agents to pay a human on Cheeze over the open
+[x402](https://developers.circle.com/gateway/nanopayments/concepts/x402)
+protocol (Circle Gateway nanopayments — EIP-3009 `TransferWithAuthorization`
+against the `GatewayWalletBatched` domain). The agent funds its own
+Arc-**testnet** wallet and delivers a paid message into the person's
+Cheeze inbox. **No Cheeze account or API key.** Mainnet is not live.
+
+## Quick start
+
+```bash
+npx @xcheeze/x402 wallet        # create the agent wallet, print address + faucet
+# → at https://faucet.circle.com/ pick "Arc Testnet", paste the address;
+#   the faucet drips 20 testnet USDC per request
+npx @xcheeze/x402 fund          # deposit on-chain USDC → Circle Gateway pocket
+npx @xcheeze/x402 balance       # confirm pocket available > 0
+npx @xcheeze/x402 send @hudson --subject "Hello" --message "…"
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `wallet` | Create / show the local agent wallet (`~/.cheeze/x402.json`, or `CHEEZE_X402_PRIVATE_KEY`). |
+| `balance` | On-chain USDC + Gateway pocket (available / pending). |
+| `fund [--amount N]` | Deposit on-chain USDC into the Gateway pocket (leaves a gas buffer; Arc gas is USDC). |
+| `quote @handle [read\|deliver]` | Show the gross price — no payment. |
+| `read @handle` | Pay to read the public summary. |
+| `send @handle --subject "..." --message "..."` | Pay to deliver a message to the inbox. |
+
+## Constraints
+
+- Subject ≤ 60 chars, message ≤ 420 chars (mirrors the seller; the
+  **server is authoritative** and rejects over-length / filtered
+  content **before** charging — you are never billed for a rejected
+  message).
+- You pay exactly the price the `402` returns — nothing else.
+- Testnet keys only.
+
+## How it works
+
+`send` → `GET /x402/<handle>/deliver` → `402` with the price →
+EIP-3009 authorization signed locally by your key (gasless) → retry
+with the `payment-signature` header + the message body → the message
+is delivered to the person's Cheeze inbox. You pay exactly the price
+returned in the `402`.
+
+Build: `npm i && npm run build` (outputs `dist/`, bin `xcheeze-x402`).

package/dist/config.js

@@ -0,0 +1,20 @@
+import { defineChain } from 'viem';
+export const FACILITATOR_BASE = 'https://facilitator.cheeze.com';
+export const ARC_CHAIN_ID = 5042002;
+export const ARC_RPC = 'https://rpc.testnet.arc.network';
+export const ARC_EXPLORER = 'https://testnet.arcscan.app';
+export const USDC_ADDRESS = '0x3600000000000000000000000000000000000000';
+export const GATEWAY_WALLET = '0x0077777d7EBA4688BDeF3E311b846F25870A19B9';
+export const ARC_GATEWAY_DOMAIN = 26;
+export const FAUCET_URL = 'https://faucet.circle.com/';
+export const FAUCET_AMOUNT_USDC = 20;
+export const MAX_SUBJECT_CHARS = 60;
+export const MAX_MESSAGE_CHARS = 420;
+export const arcTestnet = defineChain({
+    id: ARC_CHAIN_ID,
+    name: 'Arc Testnet',
+    nativeCurrency: { name: 'USDC', symbol: 'USDC', decimals: 18 },
+    rpcUrls: { default: { http: [ARC_RPC] } },
+    blockExplorers: { default: { name: 'Arcscan', url: ARC_EXPLORER } },
+    testnet: true,
+});

package/dist/index.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import { createKey, loadKey, account, onchainUsdc, gatewayPocket, depositToPocket, usdc6, } from './wallet.js';
+import { fetchChallenge, priceUsd, pay } from './x402.js';
+import { FAUCET_URL, FAUCET_AMOUNT_USDC, ARC_EXPLORER, MAX_SUBJECT_CHARS, MAX_MESSAGE_CHARS, } from './config.js';
+function flag(argv, name) {
+    const i = argv.indexOf(`--${name}`);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+function fail(msg) {
+    console.error(`✗ ${msg}`);
+    process.exit(1);
+}
+const USAGE = `@xcheeze/x402 — message a human on Cheeze over x402 (Arc testnet)
+
+  xcheeze-x402 wallet                       create / show your agent wallet
+  xcheeze-x402 balance                      on-chain USDC + Gateway pocket
+  xcheeze-x402 fund [--amount <usdc>]       deposit on-chain USDC into the pocket
+  xcheeze-x402 quote @handle [read|deliver] show the price — no payment
+  xcheeze-x402 read  @handle                pay to read @handle's public summary
+  xcheeze-x402 send  @handle --subject "<s>" --message "<m>"
+
+Setup: 1) wallet  2) send testnet USDC to the address via the faucet
+       3) fund     4) send. No Cheeze account or API key needed.`;
+async function main() {
+    const argv = process.argv.slice(2);
+    const cmd = argv[0];
+    if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+        console.log(USAGE);
+        return;
+    }
+    if (cmd === 'wallet') {
+        let addr;
+        if (loadKey()) {
+            addr = account().address;
+            console.log(`Wallet (existing): ${addr}`);
+        }
+        else {
+            addr = createKey().address;
+            console.log(`Wallet created:    ${addr}`);
+            console.log('Saved to ~/.cheeze/x402.json (chmod 600). Back it up.');
+        }
+        console.log(`\nNext:\n` +
+            `  1. Get testnet USDC: open ${FAUCET_URL}\n` +
+            `     pick "Arc Testnet", paste ${addr}\n` +
+            `     (the faucet drips ${FAUCET_AMOUNT_USDC} USDC per request)\n` +
+            `  2. xcheeze-x402 fund        # deposit it into your Gateway pocket\n` +
+            `  3. xcheeze-x402 balance     # confirm pocket available > 0\n` +
+            `  4. xcheeze-x402 send @handle --subject "..." --message "..."`);
+        return;
+    }
+    if (cmd === 'balance') {
+        const a = account();
+        const [oc, pk] = await Promise.all([onchainUsdc(a.address), gatewayPocket(a.address)]);
+        console.log(`Address:        ${a.address}`);
+        console.log(`On-chain USDC:  ${usdc6(oc)}  (deposit this into the pocket)`);
+        console.log(`Gateway pocket: ${pk.available} available · ${pk.pending} pending  (x402 spends from here)`);
+        return;
+    }
+    if (cmd === 'fund') {
+        const a = account();
+        const oc = await onchainUsdc(a.address);
+        if (oc <= 0n) {
+            fail(`No on-chain USDC at ${a.address}. Get testnet USDC from the faucet first: ${FAUCET_URL}`);
+        }
+        const amt = flag(argv, 'amount');
+        const amountUnits = amt ? BigInt(Math.round(Number(amt) * 1_000_000)) : undefined;
+        console.log(`Depositing into the Gateway pocket (leaving a gas buffer)…`);
+        const r = await depositToPocket(1000000n, amountUnits);
+        console.log(`✓ approve ${ARC_EXPLORER}/tx/${r.approveTx}`);
+        console.log(`✓ deposit ${ARC_EXPLORER}/tx/${r.depositTx}`);
+        console.log(`Pocket available: ${r.pocket} USDC`);
+        return;
+    }
+    if (cmd === 'quote') {
+        const handle = argv[1];
+        const act = argv[2] || 'deliver';
+        if (!handle)
+            fail('Usage: xcheeze-x402 quote @handle [read|deliver]');
+        const { accept } = await fetchChallenge(handle, act);
+        console.log(`${handle} · ${act}: ${priceUsd(accept)} USDC (the price you pay)`);
+        return;
+    }
+    if (cmd === 'read') {
+        const handle = argv[1];
+        if (!handle)
+            fail('Usage: xcheeze-x402 read @handle');
+        const out = await pay(handle, 'read');
+        console.log(JSON.stringify(out, null, 2));
+        return;
+    }
+    if (cmd === 'send') {
+        const handle = argv[1];
+        const subject = flag(argv, 'subject') ?? '';
+        const message = flag(argv, 'message') ?? '';
+        if (!handle)
+            fail('Usage: xcheeze-x402 send @handle --subject "..." --message "..."');
+        if (!message.trim())
+            fail('A non-empty --message is required.');
+        if (subject.length > MAX_SUBJECT_CHARS) {
+            fail(`Subject too long: ${subject.length}/${MAX_SUBJECT_CHARS} chars.`);
+        }
+        if (message.length > MAX_MESSAGE_CHARS) {
+            fail(`Message too long: ${message.length}/${MAX_MESSAGE_CHARS} chars.`);
+        }
+        const { accept } = await fetchChallenge(handle, 'deliver');
+        console.error(`Paying ${priceUsd(accept)} USDC to message ${handle}…`);
+        const out = await pay(handle, 'deliver', { message, subject: subject || undefined });
+        console.log(JSON.stringify(out, null, 2));
+        return;
+    }
+    fail(`Unknown command "${cmd}".\n\n${USAGE}`);
+}
+main().catch((e) => fail(e instanceof Error ? e.message : String(e)));

package/dist/wallet.js

@@ -0,0 +1,102 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync, chmodSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createPublicClient, createWalletClient, http, parseAbi, formatUnits, } from 'viem';
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+import { arcTestnet, ARC_RPC, USDC_ADDRESS, GATEWAY_WALLET, ARC_GATEWAY_DOMAIN, } from './config.js';
+const KEYSTORE_DIR = join(homedir(), '.cheeze');
+const KEYSTORE = join(KEYSTORE_DIR, 'x402.json');
+const USDC_ABI = parseAbi([
+    'function balanceOf(address) view returns (uint256)',
+    'function approve(address spender, uint256 value) returns (bool)',
+]);
+const GATEWAY_ABI = parseAbi([
+    'function deposit(address token, uint256 value)',
+]);
+function isHexKey(s) {
+    return /^0x[0-9a-fA-F]{64}$/.test(s);
+}
+export function loadKey() {
+    const env = process.env.CHEEZE_X402_PRIVATE_KEY?.trim();
+    if (env && isHexKey(env))
+        return env;
+    if (existsSync(KEYSTORE)) {
+        try {
+            const k = JSON.parse(readFileSync(KEYSTORE, 'utf8'))
+                .privateKey?.trim();
+            if (k && isHexKey(k))
+                return k;
+        }
+        catch { }
+    }
+    return null;
+}
+export function createKey() {
+    if (loadKey())
+        throw new Error('A wallet already exists (env or keystore). Refusing to overwrite.');
+    const pk = generatePrivateKey();
+    mkdirSync(KEYSTORE_DIR, { recursive: true });
+    writeFileSync(KEYSTORE, JSON.stringify({ privateKey: pk }, null, 2));
+    chmodSync(KEYSTORE, 0o600);
+    return { address: privateKeyToAccount(pk).address };
+}
+export function account() {
+    const pk = loadKey();
+    if (!pk)
+        throw new Error('No wallet. Run `xcheeze-x402 wallet` first.');
+    return privateKeyToAccount(pk);
+}
+const publicClient = () => createPublicClient({ chain: arcTestnet, transport: http(ARC_RPC) });
+export async function onchainUsdc(address) {
+    return publicClient().readContract({
+        address: USDC_ADDRESS, abi: USDC_ABI, functionName: 'balanceOf', args: [address],
+    });
+}
+export async function gatewayPocket(address) {
+    const r = await fetch('https://gateway-api-testnet.circle.com/v1/balances', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            token: 'USDC',
+            sources: [{ domain: ARC_GATEWAY_DOMAIN, depositor: address }],
+        }),
+    });
+    if (!r.ok)
+        return { available: 0, pending: 0 };
+    const b = (await r.json())?.balances?.[0];
+    return {
+        available: Number.parseFloat(String(b?.balance ?? '0')) || 0,
+        pending: Number.parseFloat(String(b?.pendingBatch ?? '0')) || 0,
+    };
+}
+export function usdc6(units) {
+    return formatUnits(units, 6);
+}
+export async function depositToPocket(bufferUnits = 1000000n, amountUnits) {
+    const acct = account();
+    const wallet = createWalletClient({ account: acct, chain: arcTestnet, transport: http(ARC_RPC) });
+    const pub = publicClient();
+    const bal = await onchainUsdc(acct.address);
+    const amount = amountUnits ?? (bal > bufferUnits ? bal - bufferUnits : 0n);
+    if (amount <= 0n) {
+        throw new Error(`Not enough on-chain USDC to deposit (have ${usdc6(bal)}, need > ${usdc6(bufferUnits)} for gas buffer). Fund the wallet at the faucet first.`);
+    }
+    const approveTx = await wallet.writeContract({
+        address: USDC_ADDRESS, abi: USDC_ABI, functionName: 'approve',
+        args: [GATEWAY_WALLET, amount],
+    });
+    await pub.waitForTransactionReceipt({ hash: approveTx });
+    const depositTx = await wallet.writeContract({
+        address: GATEWAY_WALLET, abi: GATEWAY_ABI, functionName: 'deposit',
+        args: [USDC_ADDRESS, amount],
+    });
+    await pub.waitForTransactionReceipt({ hash: depositTx });
+    let pocket = 0;
+    for (let i = 0; i < 15; i++) {
+        pocket = (await gatewayPocket(acct.address)).available;
+        if (pocket > 0)
+            break;
+        await new Promise((r) => setTimeout(r, 3000));
+    }
+    return { approveTx, depositTx, pocket };
+}

package/dist/x402.js

@@ -0,0 +1,97 @@
+import { account } from './wallet.js';
+import { FACILITATOR_BASE, ARC_CHAIN_ID, GATEWAY_WALLET, } from './config.js';
+const b64 = (s) => Buffer.from(s, 'utf8').toString('base64');
+const unb64 = (s) => Buffer.from(s, 'base64').toString('utf8');
+function url(handle, action) {
+    const h = handle.replace(/^@/, '');
+    return `${FACILITATOR_BASE}/x402/${encodeURIComponent(h)}/${action}`;
+}
+export async function fetchChallenge(handle, action) {
+    const res = await fetch(url(handle, action));
+    const hdr = res.headers.get('payment-required') || res.headers.get('PAYMENT-REQUIRED');
+    if (!hdr) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`No PAYMENT-REQUIRED from ${handle} (HTTP ${res.status}). ${body.slice(0, 200)}`);
+    }
+    const challenge = JSON.parse(unb64(hdr));
+    const accept = challenge?.accepts?.[0];
+    if (!accept)
+        throw new Error('Malformed 402 challenge (no accepts).');
+    return { accept, challenge };
+}
+export function priceUsd(accept) {
+    return (Number(accept.amount) || 0) / 1_000_000;
+}
+function randomNonce() {
+    const b = crypto.getRandomValues(new Uint8Array(32));
+    return ('0x' + [...b].map((x) => x.toString(16).padStart(2, '0')).join(''));
+}
+export async function pay(handle, action, body) {
+    const acct = account();
+    const { accept: a, challenge } = await fetchChallenge(handle, action);
+    const nonce = randomNonce();
+    const value = BigInt(a.amount);
+    const validBefore = BigInt(Math.floor(Date.now() / 1000) + 605_000);
+    const signature = await acct.signTypedData({
+        domain: {
+            name: a.extra?.name ?? 'GatewayWalletBatched',
+            version: a.extra?.version ?? '1',
+            chainId: ARC_CHAIN_ID,
+            verifyingContract: a.extra?.verifyingContract ?? GATEWAY_WALLET,
+        },
+        types: {
+            TransferWithAuthorization: [
+                { name: 'from', type: 'address' },
+                { name: 'to', type: 'address' },
+                { name: 'value', type: 'uint256' },
+                { name: 'validAfter', type: 'uint256' },
+                { name: 'validBefore', type: 'uint256' },
+                { name: 'nonce', type: 'bytes32' },
+            ],
+        },
+        primaryType: 'TransferWithAuthorization',
+        message: { from: acct.address, to: a.payTo, value, validAfter: 0n, validBefore, nonce },
+    });
+    const authorization = {
+        from: acct.address,
+        to: a.payTo,
+        value: String(a.amount),
+        validAfter: '0',
+        validBefore: String(validBefore),
+        nonce,
+    };
+    const paymentPayload = {
+        x402Version: 2,
+        scheme: a.scheme,
+        network: a.network,
+        payload: { authorization, signature },
+        resource: challenge?.resource ?? {},
+        accepted: a,
+    };
+    const sigHeader = b64(JSON.stringify(paymentPayload));
+    const res = action === 'deliver'
+        ? await fetch(url(handle, action), {
+            method: 'POST',
+            headers: { 'payment-signature': sigHeader, 'content-type': 'application/json' },
+            body: JSON.stringify({
+                message: String(body?.message ?? ''),
+                ...(body?.subject ? { subject: String(body.subject) } : {}),
+            }),
+        })
+        : await fetch(url(handle, action), { headers: { 'payment-signature': sigHeader } });
+    const text = await res.text();
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        data = text;
+    }
+    if (!res.ok) {
+        const detail = typeof data === 'object' && data
+            ? JSON.stringify(data)
+            : String(data).slice(0, 300);
+        throw new Error(`Rejected (HTTP ${res.status}) — not charged. ${detail}`);
+    }
+    return data;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@xcheeze/x402",
+  "version": "0.1.0",
+  "description": "Pay a human on Cheeze over x402. An AI agent funds an Arc-testnet wallet and sends a paid message that lands in the human's Cheeze inbox. No Cheeze account or API key.",
+  "type": "module",
+  "bin": {
+    "xcheeze-x402": "dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "skill.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "viem": "^2.21.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "@types/node": "^20.14.0"
+  },
+  "keywords": [
+    "x402",
+    "cheeze",
+    "agent",
+    "usdc",
+    "arc",
+    "circle-gateway",
+    "nanopayments"
+  ],
+  "license": "UNLICENSED"
+}

package/skill.md

@@ -0,0 +1,84 @@
+# Skill: message a human on Cheeze (x402)
+
+You can pay to deliver a short message into a real person's Cheeze
+inbox over the open x402 protocol. The person sets their price; the
+`402` returns the price you pay — that exact amount, nothing else. No
+Cheeze account or API key — you use your own wallet. Arc **testnet**
+only (mainnet is not live).
+
+## When to use this
+
+The user asked you to reach / notify / pitch a specific person who has
+a Cheeze handle (e.g. `@hudson`). One message = one micro-payment.
+
+## One-time setup (do this once, then reuse the wallet)
+
+**Step 1 — create your wallet.**
+```bash
+npx @xcheeze/x402 wallet
+```
+This generates a fresh Arc-testnet key **on this machine only** and
+prints your wallet **address**. The private key is written to
+`~/.cheeze/x402.json` (chmod 600), or you may instead set it in the
+`CHEEZE_X402_PRIVATE_KEY` env var. It is YOUR key — it is never sent
+to Cheeze and Cheeze never holds funds for you.
+
+**Step 2 — get testnet USDC from the faucet.**
+Open **https://faucet.circle.com/** , choose **Arc Testnet**, paste
+the address from Step 1, and request. The faucet drips **20 USDC**
+(testnet) per request. Wait until it arrives (a minute or so).
+
+**Step 3 — move it into your Gateway pocket.**
+```bash
+npx @xcheeze/x402 fund
+```
+x402 does **not** spend from your raw wallet — it spends from your
+**Circle Gateway pocket** (a one-time on-chain deposit; payments
+afterwards are gasless). `fund` runs the `approve` + `deposit` for you
+and leaves a small USDC buffer for gas (Arc gas is paid in USDC).
+
+**Step 4 — confirm.**
+```bash
+npx @xcheeze/x402 balance
+```
+Proceed once `Gateway pocket available` is greater than 0. You only
+repeat Steps 2–3 when the pocket runs low.
+
+## Discover the price (no payment)
+
+```bash
+npx @xcheeze/x402 quote @handle deliver
+```
+
+Returns the USDC price you will pay. The price is also returned
+automatically in the `402` challenge when you send — you never need
+an account to learn it.
+
+## Send a paid message
+
+```bash
+npx @xcheeze/x402 send @handle --subject "<subject>" --message "<message>"
+```
+
+Flow (handled for you): request → `402` price → sign an EIP-3009
+authorization with your wallet (gasless, off-chain) → retry with the
+signed payment → the message lands in the human's Cheeze inbox.
+
+## Rules you must respect
+
+- **Length**: subject ≤ 60 chars, message ≤ 420 chars. Over-length
+  is rejected.
+- **Content**: the recipient's server filters and **rejects**
+  spam/abusive/policy-violating or manipulative content. Rejections
+  happen **before** any charge — you are not billed for a rejected
+  message. Send genuine, relevant, well-formed messages only.
+- One payment delivers one message. Don't retry a rejected message
+  unchanged; fix it or stop.
+- Funds are testnet only. Do not use real-value keys.
+
+## Interpreting results
+
+- Success: JSON receipt with `settlement: "settled"` — delivered, you
+  were charged the quoted price.
+- `Rejected (HTTP 4xx) — not charged`: length/content/validation
+  failure. You were **not** billed. Do not blindly retry.