@xcheeze/x402 0.1.0 → 0.1.2

package/README.md

@@ -10,23 +10,24 @@ 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 wallet        # create the agent wallet, print its address
+npx @xcheeze/x402 faucet        # auto top-up the wallet with test USDC
 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 "…"
 ```
 
+If `faucet` says it's exhausted, top up manually at
+https://faucet.circle.com/ ("Arc Testnet", paste the wallet address).
+
 ## Commands
 
 | Command | Purpose |
 |---|---|
 | `wallet` | Create / show the local agent wallet (`~/.cheeze/x402.json`, or `CHEEZE_X402_PRIVATE_KEY`). |
+| `faucet` | Auto top-up the wallet with test USDC (capped per wallet; falls back to faucet.circle.com). |
 | `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. |
+| `quote @handle` | Show the price to deliver a message — no payment. |
 | `send @handle --subject "..." --message "..."` | Pay to deliver a message to the inbox. |
 
 ## Constraints

package/dist/config.js

@@ -1,5 +1,6 @@
 import { defineChain } from 'viem';
 export const FACILITATOR_BASE = 'https://facilitator.cheeze.com';
+export const FAUCET_RELAY = 'https://agents.cheeze.com/faucet';
 export const ARC_CHAIN_ID = 5042002;
 export const ARC_RPC = 'https://rpc.testnet.arc.network';
 export const ARC_EXPLORER = 'https://testnet.arcscan.app';

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/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';
+import { FAUCET_URL, FAUCET_AMOUNT_USDC, FAUCET_RELAY, 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;
@@ -13,14 +13,14 @@ function fail(msg) {
 const USAGE = `@xcheeze/x402 — message a human on Cheeze over x402 (Arc testnet)
 
   xcheeze-x402 wallet                       create / show your agent wallet
+  xcheeze-x402 faucet                       auto top-up the wallet with test USDC
   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 quote @handle                show the price — no payment
   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.`;
+Setup: 1) wallet  2) 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];
@@ -48,6 +48,28 @@ async function main() {
             `  4. xcheeze-x402 send @handle --subject "..." --message "..."`);
         return;
     }
+    if (cmd === 'faucet') {
+        const a = account();
+        process.stderr.write('Requesting test USDC for your wallet…\n');
+        const res = await fetch(FAUCET_RELAY, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ address: a.address }),
+        });
+        const out = (await res.json().catch(() => ({})));
+        if (!res.ok || !out.ok) {
+            fail(`${out.detail || out.error || `faucet error (HTTP ${res.status})`}\n` +
+                `  Get test USDC manually: ${FAUCET_URL} (choose "Arc Testnet"),\n` +
+                `  paste ${a.address}, then run \`xcheeze-x402 fund\`.`);
+        }
+        console.log(`✓ ${out.amount_usdc} test USDC sent to ${a.address}` +
+            (out.tx ? `\n  ${ARC_EXPLORER}/tx/${out.tx}` : '') +
+            (typeof out.remaining_draws === 'number'
+                ? `\n  ${out.remaining_draws} free top-up(s) left for this wallet.`
+                : '') +
+            `\nNext: xcheeze-x402 fund`);
+        return;
+    }
     if (cmd === 'balance') {
         const a = account();
         const [oc, pk] = await Promise.all([onchainUsdc(a.address), gatewayPocket(a.address)]);
@@ -72,20 +94,11 @@ async function main() {
         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));
+            fail('Usage: xcheeze-x402 quote @handle');
+        const { accept } = await fetchChallenge(handle, 'deliver');
+        console.log(`${handle}: ${priceUsd(accept)} USDC to deliver a message (the price you pay)`);
         return;
     }
     if (cmd === 'send') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xcheeze/x402",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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": {

package/skill.md

@@ -23,10 +23,14 @@ prints your wallet **address**. The private key is written to
 `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 2 — top up the wallet (automatic).**
+```bash
+npx @xcheeze/x402 faucet
+```
+Auto-sends test USDC to your wallet — no website, no human. If it
+reports the faucet is exhausted for this wallet, top up manually at
+**https://faucet.circle.com/** (choose **Arc Testnet**, paste your
+address from Step 1).
 
 **Step 3 — move it into your Gateway pocket.**
 ```bash
@@ -47,7 +51,7 @@ repeat Steps 2–3 when the pocket runs low.
 ## Discover the price (no payment)
 
 ```bash
-npx @xcheeze/x402 quote @handle deliver
+npx @xcheeze/x402 quote @handle
 ```
 
 Returns the USDC price you will pay. The price is also returned