yeetful 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yeetful
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,307 @@
+# yeetful
+
+**Drop-in [x402](https://www.x402.org) payments for your APIs and clients.** Gate any HTTP route behind a stablecoin micropayment in a few lines — no accounts, no API keys, no webhooks. Built for [Yeetful](https://yeetful.com), MIT-licensed, works anywhere TypeScript does.
+
+```bash
+npm install yeetful viem
+```
+
+```ts
+// Server — gate a route for 1¢ USDC
+import { withPayment } from 'yeetful/next'
+
+export const GET = withPayment(
+  { price: '0.01', recipient: '0xYourAddress', network: 'base' },
+  async () => Response.json({ secret: 'gm' })
+)
+```
+
+```ts
+// Client — auto-pay when a server returns 402
+import { createPaymentClient } from 'yeetful/client'
+import { createWalletClient, http } from 'viem'
+import { base } from 'viem/chains'
+import { privateKeyToAccount } from 'viem/accounts'
+
+const wallet = createWalletClient({
+  account: privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`),
+  chain: base,
+  transport: http(),
+})
+
+const pay = createPaymentClient({ wallet })
+const res = await pay('https://api.example.com/premium')
+console.log(await res.json()) // → { secret: 'gm' }
+```
+
+---
+
+## Why x402?
+
+x402 is a reborn HTTP `402 Payment Required` — a protocol where servers quote a price, clients sign a stablecoin authorization, and a facilitator settles on-chain. No accounts, no Stripe dashboards, no webhook retries. Works on EVM chains today (USDC on Base, Optimism, Arbitrum, Polygon, Ethereum).
+
+**You get:**
+- Per-request pricing for any API — LLM calls, data feeds, premium endpoints, MCP tools.
+- One-sentence paywalls for agents: an LLM with a wallet can now pay for what it uses.
+- Instant settlement on L2 — no chargebacks, no holds, no 30-day payout delay.
+
+---
+
+## Install
+
+```bash
+npm install yeetful viem
+# or
+pnpm add yeetful viem
+# or
+yarn add yeetful viem
+```
+
+`viem` is a peer dependency so the SDK stays light and stays in sync with whatever viem version your app already uses.
+
+---
+
+## Quickstart
+
+### Server: gate a route
+
+#### Next.js (App Router)
+
+```ts
+// app/api/premium/route.ts
+import { withPayment } from 'yeetful/next'
+
+export const GET = withPayment(
+  {
+    price: '0.01',                        // USD
+    recipient: '0xYourWalletAddress',     // gets paid
+    network: 'base',                      // or ['base', 'optimism']
+    description: 'Premium GM endpoint',
+  },
+  async (req) => {
+    return Response.json({ message: 'gm, thanks for the cent' })
+  }
+)
+```
+
+#### Express
+
+```ts
+import express from 'express'
+import { paymentRequired } from 'yeetful/express'
+
+const app = express()
+
+app.get(
+  '/premium',
+  paymentRequired({
+    price: '0.01',
+    recipient: '0xYourWalletAddress',
+    network: 'base',
+  }),
+  (req, res) => {
+    res.json({ message: 'gm', payer: req.x402?.payer })
+  }
+)
+
+app.listen(3000)
+```
+
+#### Anywhere else (Hono, Bun, Cloudflare Workers, raw Node)
+
+Use the runtime-agnostic `gate()` helper. Give it a standard `Request`, get back either a 402 `Response` or a `settle()` handle.
+
+```ts
+import { gate } from 'yeetful/server'
+
+export default {
+  async fetch(request: Request) {
+    const result = await gate(request, {
+      price: '0.01',
+      recipient: '0xYourWalletAddress',
+      network: 'base',
+    })
+
+    if (result.type === 'paymentRequired') return result.response
+
+    // …do the paid work…
+    const body = Response.json({ message: 'gm' })
+
+    const { header } = await result.settle()
+    body.headers.set('X-PAYMENT-RESPONSE', header)
+    return body
+  },
+}
+```
+
+### Client: auto-pay
+
+```ts
+import { createPaymentClient } from 'yeetful/client'
+
+const pay = createPaymentClient({
+  wallet,                           // any viem WalletClient
+  maxAmountAtomic: 1_000_000n,      // cap: 1 USDC per call
+  allowedNetworks: ['base'],        // only pay on Base
+  onPaymentRequired: async (req) => {
+    console.log(`Pay ${req.maxAmountRequired} to ${req.payTo}?`)
+    return true                     // return false to cancel
+  },
+})
+
+// Use exactly like fetch.
+const res = await pay('https://api.example.com/premium')
+```
+
+---
+
+## Configuration
+
+### `RouteGateOptions` — server
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `price` | `string \| number` | **required** | USD amount, e.g. `'0.01'`. Converted to USDC atomic units. |
+| `recipient` | `Address` | **required** | Address that receives the payment. |
+| `network` | `X402Network \| X402Network[]` | `'base'` | Networks you'll accept. Multi-chain = multi-item discovery. |
+| `asset` | `Address` | USDC for network | Override to use a different ERC-20. |
+| `description` | `string` | — | Shown to the paying client. |
+| `maxTimeoutSeconds` | `number` | `600` | Validity window of the signed authorization. |
+| `facilitator` | `FacilitatorConfig \| false` | hosted facilitator | Pass `false` to skip on-chain settlement (testing only). |
+
+Supported networks: `base`, `base-sepolia`, `ethereum`, `optimism`, `arbitrum`, `polygon`.
+
+### `ClientOptions` — client
+
+| Option | Type | Notes |
+| --- | --- | --- |
+| `wallet` | `WalletClient` | Any viem wallet capable of signing EIP-712 typed data. |
+| `maxAmountAtomic` | `bigint` | Reject requirements above this cap — safety belt. |
+| `allowedNetworks` | `X402Network[]` | Only pay on these networks. |
+| `onPaymentRequired` | `(req) => boolean \| Promise<boolean>` | Approval hook; return `false` to cancel. |
+| `fetch` | `typeof fetch` | Override the underlying fetch (e.g. for timeouts). |
+
+---
+
+## How it works
+
+1. **Client requests** a paid resource normally.
+2. **Server** responds with `402 Payment Required` and a JSON body listing acceptable requirements (network, asset, amount, recipient).
+3. **Client** picks the cheapest requirement, signs an [EIP-3009 `TransferWithAuthorization`](https://eips.ethereum.org/EIPS/eip-3009) with the user's wallet, and retries the request with an `X-PAYMENT` header (base64 JSON).
+4. **Server** hands the signed payload to a facilitator which `verify`s the signature and `settle`s the transfer on-chain.
+5. **Server** runs the handler and returns the response with an `X-PAYMENT-RESPONSE` header containing the transaction hash.
+
+The signing is gasless for the payer — the facilitator broadcasts the transfer and picks up gas.
+
+---
+
+## Facilitators
+
+By default the SDK uses the hosted facilitator at `https://facilitator.yeetful.com`. Override it anywhere you configure the server:
+
+```ts
+withPayment(
+  {
+    price: '0.01',
+    recipient: '0xYourAddress',
+    facilitator: {
+      url: 'https://your-facilitator.example.com',
+      authHeader: 'Bearer your-token',
+    },
+  },
+  handler,
+)
+```
+
+Pass `facilitator: false` to skip verification and settlement entirely — only useful for local testing.
+
+---
+
+## Advanced
+
+### Accept multiple networks
+
+```ts
+withPayment(
+  {
+    price: '0.01',
+    recipient: '0xYourAddress',
+    network: ['base', 'optimism', 'arbitrum'],
+  },
+  handler,
+)
+```
+
+Clients automatically pick the cheapest network they're configured to use.
+
+### Sign a payment manually
+
+```ts
+import { signPayment } from 'yeetful/client'
+
+const payment = await signPayment(wallet, {
+  scheme: 'exact',
+  network: 'base',
+  asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
+  maxAmountRequired: '10000', // 0.01 USDC
+  payTo: '0xRecipient',
+})
+```
+
+### Use with AI agents / MCP tools
+
+x402 is a natural fit for agent tooling — drop `withPayment` in front of any MCP tool endpoint and agents with wallets can pay per-call. This SDK is what powers paid tools on [Yeetful](https://yeetful.com).
+
+---
+
+## API reference
+
+### `yeetful/server`
+
+- `gate(request, options)` — runtime-agnostic. Returns `{ type: 'paymentRequired', response }` or `{ type: 'ok', payer, settle }`.
+- `Facilitator` — thin wrapper around verify/settle HTTP endpoints.
+- `DEFAULT_FACILITATOR_URL` — the hosted facilitator URL.
+
+### `yeetful/next`
+
+- `withPayment(options, handler)` — wraps a Next.js route handler.
+
+### `yeetful/express`
+
+- `paymentRequired(options)` — returns an Express `RequestHandler`. Sets `req.x402.payer` after successful verification.
+
+### `yeetful/client`
+
+- `createPaymentClient(options)` — returns a `fetch`-compatible function that handles 402s automatically.
+- `signPayment(wallet, requirement)` — sign a payment payload by hand.
+- `PaymentError` — thrown when the client declines to pay.
+
+### Helpers
+
+- `usdcAddress(network)` — canonical USDC contract for a supported network.
+- `usdToAtomic(amount, decimals?)` — safe USD → atomic-units conversion.
+- `encodePayment` / `decodePayment` — base64 JSON codec for headers.
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build     # bundles ESM + CJS + d.ts via tsup
+npm run typecheck
+npm test
+```
+
+To publish:
+
+```bash
+npm run build
+npm publish
+```
+
+---
+
+## License
+
+MIT © Yeetful

package/dist/client.cjs

@@ -0,0 +1,138 @@
+'use strict';
+
+// src/utils.ts
+var utf8Encoder = new TextEncoder();
+new TextDecoder();
+function encodePayment(value) {
+  const bytes = utf8Encoder.encode(JSON.stringify(value));
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64");
+  }
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+function randomNonce() {
+  const bytes = new Uint8Array(32);
+  globalThis.crypto.getRandomValues(bytes);
+  return "0x" + Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// src/client.ts
+function createPaymentClient(options) {
+  const baseFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  return async function payFetch(input, init = {}) {
+    const first = await baseFetch(input, init);
+    if (first.status !== 402) return first;
+    const requirements = await parsePaymentRequired(first);
+    const requirement = selectRequirement(requirements.accepts, options);
+    if (!requirement) {
+      throw new PaymentError("No acceptable payment requirement matched client constraints", requirements);
+    }
+    if (options.onPaymentRequired) {
+      const approved = await options.onPaymentRequired(requirement);
+      if (!approved) throw new PaymentError("Payment rejected by user", requirements);
+    }
+    const payment = await signPayment(options.wallet, requirement);
+    const headers = new Headers(init.headers);
+    headers.set("X-PAYMENT", encodePayment(payment));
+    return baseFetch(input, { ...init, headers });
+  };
+}
+var PaymentError = class extends Error {
+  requirements;
+  constructor(message, requirements) {
+    super(message);
+    this.name = "PaymentError";
+    this.requirements = requirements;
+  }
+};
+async function parsePaymentRequired(res) {
+  try {
+    return await res.clone().json();
+  } catch {
+    throw new PaymentError("402 response did not contain a valid x402 discovery body");
+  }
+}
+function selectRequirement(accepts, opts) {
+  const filtered = accepts.filter((a) => a.scheme === "exact").filter((a) => !opts.allowedNetworks || opts.allowedNetworks.includes(a.network)).filter((a) => !opts.maxAmountAtomic || BigInt(a.maxAmountRequired) <= opts.maxAmountAtomic);
+  return filtered.sort(
+    (a, b) => BigInt(a.maxAmountRequired) < BigInt(b.maxAmountRequired) ? -1 : 1
+  )[0];
+}
+async function signPayment(wallet, requirement) {
+  const account = wallet.account;
+  if (!account) throw new PaymentError("Wallet has no account attached");
+  const now = Math.floor(Date.now() / 1e3);
+  const validAfter = BigInt(now - 60);
+  const validBefore = BigInt(now + (requirement.maxTimeoutSeconds ?? 600));
+  const nonce = randomNonce();
+  const tokenName = requirement.extra?.name ?? "USD Coin";
+  const tokenVersion = requirement.extra?.version ?? "2";
+  const signature = await wallet.signTypedData({
+    account,
+    domain: {
+      name: tokenName,
+      version: tokenVersion,
+      chainId: chainIdForNetwork(requirement.network),
+      verifyingContract: requirement.asset
+    },
+    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: account.address,
+      to: requirement.payTo,
+      value: BigInt(requirement.maxAmountRequired),
+      validAfter,
+      validBefore,
+      nonce
+    }
+  });
+  return {
+    x402Version: 1,
+    scheme: "exact",
+    network: requirement.network,
+    payload: {
+      signature,
+      authorization: {
+        from: account.address,
+        to: requirement.payTo,
+        value: requirement.maxAmountRequired,
+        validAfter: validAfter.toString(),
+        validBefore: validBefore.toString(),
+        nonce
+      }
+    }
+  };
+}
+function chainIdForNetwork(network) {
+  switch (network) {
+    case "base":
+      return 8453;
+    case "base-sepolia":
+      return 84532;
+    case "ethereum":
+      return 1;
+    case "optimism":
+      return 10;
+    case "arbitrum":
+      return 42161;
+    case "polygon":
+      return 137;
+  }
+}
+
+exports.PaymentError = PaymentError;
+exports.createPaymentClient = createPaymentClient;
+exports.signPayment = signPayment;
+//# sourceMappingURL=client.cjs.map
+//# sourceMappingURL=client.cjs.map

package/dist/client.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils.ts","../src/client.ts"],"names":[],"mappings":";;;AAgCA,IAAM,WAAA,GAAc,IAAI,WAAA,EAAY;AAChB,IAAI,WAAA;AAGjB,SAAS,cAAc,KAAA,EAAwB;AACpD,EAAA,MAAM,QAAQ,WAAA,CAAY,MAAA,CAAO,IAAA,CAAK,SAAA,CAAU,KAAK,CAAC,CAAA;AACtD,EAAA,IAAI,OAAO,WAAW,WAAA,EAAa;AACjC,IAAA,OAAO,MAAA,CAAO,IAAA,CAAK,KAAK,CAAA,CAAE,SAAS,QAAQ,CAAA;AAAA,EAC7C;AACA,EAAA,IAAI,MAAA,GAAS,EAAA;AACb,EAAA,KAAA,MAAW,IAAA,IAAQ,KAAA,EAAO,MAAA,IAAU,MAAA,CAAO,aAAa,IAAI,CAAA;AAC5D,EAAA,OAAO,KAAK,MAAM,CAAA;AACpB;AAgBO,SAAS,WAAA,GAA6B;AAC3C,EAAA,MAAM,KAAA,GAAQ,IAAI,UAAA,CAAW,EAAE,CAAA;AAC/B,EAAA,UAAA,CAAW,MAAA,CAAO,gBAAgB,KAAK,CAAA;AACvC,EAAA,OAAQ,OAAO,KAAA,CAAM,IAAA,CAAK,KAAA,EAAO,CAAC,MAAM,CAAA,CAAE,QAAA,CAAS,EAAE,CAAA,CAAE,SAAS,CAAA,EAAG,GAAG,CAAC,CAAA,CAAE,KAAK,EAAE,CAAA;AAClF;;;AC1BO,SAAS,oBAAoB,OAAA,EAAwB;AAC1D,EAAA,MAAM,YAAY,OAAA,CAAQ,KAAA,IAAS,UAAA,CAAW,KAAA,CAAM,KAAK,UAAU,CAAA;AAEnE,EAAA,OAAO,eAAe,QAAA,CACpB,KAAA,EACA,IAAA,GAAoB,EAAC,EACF;AACnB,IAAA,MAAM,KAAA,GAAQ,MAAM,SAAA,CAAU,KAAA,EAAO,IAAI,CAAA;AACzC,IAAA,IAAI,KAAA,CAAM,MAAA,KAAW,GAAA,EAAK,OAAO,KAAA;AAEjC,IAAA,MAAM,YAAA,GAAe,MAAM,oBAAA,CAAqB,KAAK,CAAA;AACrD,IAAA,MAAM,WAAA,GAAc,iBAAA,CAAkB,YAAA,CAAa,OAAA,EAAS,OAAO,CAAA;AACnE,IAAA,IAAI,CAAC,WAAA,EAAa;AAChB,MAAA,MAAM,IAAI,YAAA,CAAa,8DAAA,EAAgE,YAAY,CAAA;AAAA,IACrG;AAEA,IAAA,IAAI,QAAQ,iBAAA,EAAmB;AAC7B,MAAA,MAAM,QAAA,GAAW,MAAM,OAAA,CAAQ,iBAAA,CAAkB,WAAW,CAAA;AAC5D,MAAA,IAAI,CAAC,QAAA,EAAU,MAAM,IAAI,YAAA,CAAa,4BAA4B,YAAY,CAAA;AAAA,IAChF;AAEA,IAAA,MAAM,OAAA,GAAU,MAAM,WAAA,CAAY,OAAA,CAAQ,QAAQ,WAAW,CAAA;AAC7D,IAAA,MAAM,OAAA,GAAU,IAAI,OAAA,CAAQ,IAAA,CAAK,OAAO,CAAA;AACxC,IAAA,OAAA,CAAQ,GAAA,CAAI,WAAA,EAAa,aAAA,CAAc,OAAO,CAAC,CAAA;AAE/C,IAAA,OAAO,UAAU,KAAA,EAAO,EAAE,GAAG,IAAA,EAAM,SAAS,CAAA;AAAA,EAC9C,CAAA;AACF;AAEO,IAAM,YAAA,GAAN,cAA2B,KAAA,CAAM;AAAA,EAC7B,YAAA;AAAA,EACT,WAAA,CAAY,SAAiB,YAAA,EAAwC;AACnE,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,cAAA;AACZ,IAAA,IAAA,CAAK,YAAA,GAAe,YAAA;AAAA,EACtB;AACF;AAEA,eAAe,qBAAqB,GAAA,EAAiD;AACnF,EAAA,IAAI;AACF,IAAA,OAAQ,MAAM,GAAA,CAAI,KAAA,EAAM,CAAE,IAAA,EAAK;AAAA,EACjC,CAAA,CAAA,MAAQ;AACN,IAAA,MAAM,IAAI,aAAa,0DAA0D,CAAA;AAAA,EACnF;AACF;AAEA,SAAS,iBAAA,CACP,SACA,IAAA,EACgC;AAChC,EAAA,MAAM,QAAA,GAAW,OAAA,CACd,MAAA,CAAO,CAAC,MAAM,CAAA,CAAE,MAAA,KAAW,OAAO,CAAA,CAClC,MAAA,CAAO,CAAC,CAAA,KAAM,CAAC,KAAK,eAAA,IAAmB,IAAA,CAAK,eAAA,CAAgB,QAAA,CAAS,CAAA,CAAE,OAAO,CAAC,CAAA,CAC/E,OAAO,CAAC,CAAA,KAAM,CAAC,IAAA,CAAK,mBAAmB,MAAA,CAAO,CAAA,CAAE,iBAAiB,CAAA,IAAK,KAAK,eAAe,CAAA;AAE7F,EAAA,OAAO,QAAA,CAAS,IAAA;AAAA,IAAK,CAAC,CAAA,EAAG,CAAA,KACvB,MAAA,CAAO,CAAA,CAAE,iBAAiB,CAAA,GAAI,MAAA,CAAO,CAAA,CAAE,iBAAiB,CAAA,GAAI,EAAA,GAAK;AAAA,IACjE,CAAC,CAAA;AACL;AAGA,eAAsB,WAAA,CACpB,QACA,WAAA,EACyB;AACzB,EAAA,MAAM,UAAU,MAAA,CAAO,OAAA;AACvB,EAAA,IAAI,CAAC,OAAA,EAAS,MAAM,IAAI,aAAa,gCAAgC,CAAA;AAErE,EAAA,MAAM,MAAM,IAAA,CAAK,KAAA,CAAM,IAAA,CAAK,GAAA,KAAQ,GAAI,CAAA;AACxC,EAAA,MAAM,UAAA,GAAa,MAAA,CAAO,GAAA,GAAM,EAAE,CAAA;AAClC,EAAA,MAAM,WAAA,GAAc,MAAA,CAAO,GAAA,IAAO,WAAA,CAAY,qBAAqB,GAAA,CAAI,CAAA;AACvE,EAAA,MAAM,QAAQ,WAAA,EAAY;AAE1B,EAAA,MAAM,SAAA,GACH,WAAA,CAAY,KAAA,EAAO,IAAA,IAA+B,UAAA;AACrD,EAAA,MAAM,YAAA,GACH,WAAA,CAAY,KAAA,EAAO,OAAA,IAAkC,GAAA;AAExD,EAAA,MAAM,SAAA,GAAa,MAAM,MAAA,CAAO,aAAA,CAAc;AAAA,IAC5C,OAAA;AAAA,IACA,MAAA,EAAQ;AAAA,MACN,IAAA,EAAM,SAAA;AAAA,MACN,OAAA,EAAS,YAAA;AAAA,MACT,OAAA,EAAS,iBAAA,CAAkB,WAAA,CAAY,OAAO,CAAA;AAAA,MAC9C,mBAAmB,WAAA,CAAY;AAAA,KACjC;AAAA,IACA,KAAA,EAAO;AAAA,MACL,yBAAA,EAA2B;AAAA,QACzB,EAAE,IAAA,EAAM,MAAA,EAAQ,IAAA,EAAM,SAAA,EAAU;AAAA,QAChC,EAAE,IAAA,EAAM,IAAA,EAAM,IAAA,EAAM,SAAA,EAAU;AAAA,QAC9B,EAAE,IAAA,EAAM,OAAA,EAAS,IAAA,EAAM,SAAA,EAAU;AAAA,QACjC,EAAE,IAAA,EAAM,YAAA,EAAc,IAAA,EAAM,SAAA,EAAU;AAAA,QACtC,EAAE,IAAA,EAAM,aAAA,EAAe,IAAA,EAAM,SAAA,EAAU;AAAA,QACvC,EAAE,IAAA,EAAM,OAAA,EAAS,IAAA,EAAM,SAAA;AAAU;AACnC,KACF;AAAA,IACA,WAAA,EAAa,2BAAA;AAAA,IACb,OAAA,EAAS;AAAA,MACP,MAAM,OAAA,CAAQ,OAAA;AAAA,MACd,IAAI,WAAA,CAAY,KAAA;AAAA,MAChB,KAAA,EAAO,MAAA,CAAO,WAAA,CAAY,iBAAiB,CAAA;AAAA,MAC3C,UAAA;AAAA,MACA,WAAA;AAAA,MACA;AAAA;AACF,GACD,CAAA;AAED,EAAA,OAAO;AAAA,IACL,WAAA,EAAa,CAAA;AAAA,IACb,MAAA,EAAQ,OAAA;AAAA,IACR,SAAS,WAAA,CAAY,OAAA;AAAA,IACrB,OAAA,EAAS;AAAA,MACP,SAAA;AAAA,MACA,aAAA,EAAe;AAAA,QACb,MAAM,OAAA,CAAQ,OAAA;AAAA,QACd,IAAI,WAAA,CAAY,KAAA;AAAA,QAChB,OAAO,WAAA,CAAY,iBAAA;AAAA,QACnB,UAAA,EAAY,WAAW,QAAA,EAAS;AAAA,QAChC,WAAA,EAAa,YAAY,QAAA,EAAS;AAAA,QAClC;AAAA;AACF;AACF,GACF;AACF;AAEA,SAAS,kBAAkB,OAAA,EAA8B;AACvD,EAAA,QAAQ,OAAA;AAAS,IACf,KAAK,MAAA;AACH,MAAA,OAAO,IAAA;AAAA,IACT,KAAK,cAAA;AACH,MAAA,OAAO,KAAA;AAAA,IACT,KAAK,UAAA;AACH,MAAA,OAAO,CAAA;AAAA,IACT,KAAK,UAAA;AACH,MAAA,OAAO,EAAA;AAAA,IACT,KAAK,UAAA;AACH,MAAA,OAAO,KAAA;AAAA,IACT,KAAK,SAAA;AACH,MAAA,OAAO,GAAA;AAAA;AAEb","file":"client.cjs","sourcesContent":["import type { X402Network } from './types.js'\n\nconst USDC_BY_NETWORK: Record<X402Network, `0x${string}`> = {\n  base: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',\n  'base-sepolia': '0x036CbD53842c5426634e7929541eC2318f3dCF7e',\n  ethereum: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',\n  optimism: '0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85',\n  arbitrum: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',\n  polygon: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359',\n}\n\nexport const USDC_DECIMALS = 6\n\n/** Returns the canonical USDC contract address for a supported network. */\nexport function usdcAddress(network: X402Network): `0x${string}` {\n  return USDC_BY_NETWORK[network]\n}\n\n/**\n * Convert a human-friendly USD amount (e.g. \"0.01\") into atomic USDC units.\n * Fixed-point to avoid float drift — safer than Number math for payments.\n */\nexport function usdToAtomic(amount: string | number, decimals = USDC_DECIMALS): string {\n  const str = typeof amount === 'number' ? amount.toString() : amount\n  if (!/^\\d+(\\.\\d+)?$/.test(str)) {\n    throw new Error(`Invalid amount: ${str}`)\n  }\n  const [whole, frac = ''] = str.split('.')\n  const padded = frac.slice(0, decimals).padEnd(decimals, '0')\n  return (BigInt(whole ?? '0') * 10n ** BigInt(decimals) + BigInt(padded || '0')).toString()\n}\n\nconst utf8Encoder = new TextEncoder()\nconst utf8Decoder = new TextDecoder()\n\n/** Base64 encode a JSON value — works in Node 18+ and browsers. */\nexport function encodePayment(value: unknown): string {\n  const bytes = utf8Encoder.encode(JSON.stringify(value))\n  if (typeof Buffer !== 'undefined') {\n    return Buffer.from(bytes).toString('base64')\n  }\n  let binary = ''\n  for (const byte of bytes) binary += String.fromCharCode(byte)\n  return btoa(binary)\n}\n\n/** Base64 decode a payment header value back into JSON. */\nexport function decodePayment<T = unknown>(b64: string): T {\n  let bytes: Uint8Array\n  if (typeof Buffer !== 'undefined') {\n    bytes = new Uint8Array(Buffer.from(b64, 'base64'))\n  } else {\n    const binary = atob(b64)\n    bytes = new Uint8Array(binary.length)\n    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)\n  }\n  return JSON.parse(utf8Decoder.decode(bytes)) as T\n}\n\n/** Generate a random 32-byte nonce as a 0x-prefixed hex string. */\nexport function randomNonce(): `0x${string}` {\n  const bytes = new Uint8Array(32)\n  globalThis.crypto.getRandomValues(bytes)\n  return ('0x' + Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')) as `0x${string}`\n}\n","import type { Address, Hex, WalletClient } from 'viem'\nimport type {\n  PaymentPayload,\n  PaymentRequiredResponse,\n  PaymentRequirement,\n  X402Network,\n} from './types.js'\nimport { encodePayment, randomNonce } from './utils.js'\n\nexport interface ClientOptions {\n  /** A viem WalletClient able to sign EIP-712 typed data. */\n  wallet: WalletClient\n  /** Underlying fetch to wrap (defaults to global fetch). */\n  fetch?: typeof fetch\n  /**\n   * Hook called before signing. Return `false` to reject the payment.\n   * Useful for showing a confirmation UI to the user.\n   */\n  onPaymentRequired?: (requirement: PaymentRequirement) => boolean | Promise<boolean>\n  /** Only allow payments up to this atomic-units cap. Safety belt. */\n  maxAmountAtomic?: bigint\n  /** Restrict to specific networks (defaults to all). */\n  allowedNetworks?: X402Network[]\n}\n\n/**\n * Create a fetch wrapper that transparently handles x402 payments.\n *\n * On a 402 response, it picks the cheapest acceptable requirement,\n * signs an EIP-3009 authorization with the provided wallet, and retries\n * the request with an `X-PAYMENT` header.\n *\n * @example\n * ```ts\n * const pay = createPaymentClient({ wallet })\n * const res = await pay('https://api.example.com/premium')\n * ```\n */\nexport function createPaymentClient(options: ClientOptions) {\n  const baseFetch = options.fetch ?? globalThis.fetch.bind(globalThis)\n\n  return async function payFetch(\n    input: string | URL | Request,\n    init: RequestInit = {},\n  ): Promise<Response> {\n    const first = await baseFetch(input, init)\n    if (first.status !== 402) return first\n\n    const requirements = await parsePaymentRequired(first)\n    const requirement = selectRequirement(requirements.accepts, options)\n    if (!requirement) {\n      throw new PaymentError('No acceptable payment requirement matched client constraints', requirements)\n    }\n\n    if (options.onPaymentRequired) {\n      const approved = await options.onPaymentRequired(requirement)\n      if (!approved) throw new PaymentError('Payment rejected by user', requirements)\n    }\n\n    const payment = await signPayment(options.wallet, requirement)\n    const headers = new Headers(init.headers)\n    headers.set('X-PAYMENT', encodePayment(payment))\n\n    return baseFetch(input, { ...init, headers })\n  }\n}\n\nexport class PaymentError extends Error {\n  readonly requirements?: PaymentRequiredResponse\n  constructor(message: string, requirements?: PaymentRequiredResponse) {\n    super(message)\n    this.name = 'PaymentError'\n    this.requirements = requirements\n  }\n}\n\nasync function parsePaymentRequired(res: Response): Promise<PaymentRequiredResponse> {\n  try {\n    return (await res.clone().json()) as PaymentRequiredResponse\n  } catch {\n    throw new PaymentError('402 response did not contain a valid x402 discovery body')\n  }\n}\n\nfunction selectRequirement(\n  accepts: PaymentRequirement[],\n  opts: ClientOptions,\n): PaymentRequirement | undefined {\n  const filtered = accepts\n    .filter((a) => a.scheme === 'exact')\n    .filter((a) => !opts.allowedNetworks || opts.allowedNetworks.includes(a.network))\n    .filter((a) => !opts.maxAmountAtomic || BigInt(a.maxAmountRequired) <= opts.maxAmountAtomic)\n\n  return filtered.sort((a, b) =>\n    BigInt(a.maxAmountRequired) < BigInt(b.maxAmountRequired) ? -1 : 1,\n  )[0]\n}\n\n/** Sign an EIP-3009 `TransferWithAuthorization` for the given requirement. */\nexport async function signPayment(\n  wallet: WalletClient,\n  requirement: PaymentRequirement,\n): Promise<PaymentPayload> {\n  const account = wallet.account\n  if (!account) throw new PaymentError('Wallet has no account attached')\n\n  const now = Math.floor(Date.now() / 1000)\n  const validAfter = BigInt(now - 60)\n  const validBefore = BigInt(now + (requirement.maxTimeoutSeconds ?? 600))\n  const nonce = randomNonce()\n\n  const tokenName =\n    (requirement.extra?.name as string | undefined) ?? 'USD Coin'\n  const tokenVersion =\n    (requirement.extra?.version as string | undefined) ?? '2'\n\n  const signature = (await wallet.signTypedData({\n    account,\n    domain: {\n      name: tokenName,\n      version: tokenVersion,\n      chainId: chainIdForNetwork(requirement.network),\n      verifyingContract: requirement.asset,\n    },\n    types: {\n      TransferWithAuthorization: [\n        { name: 'from', type: 'address' },\n        { name: 'to', type: 'address' },\n        { name: 'value', type: 'uint256' },\n        { name: 'validAfter', type: 'uint256' },\n        { name: 'validBefore', type: 'uint256' },\n        { name: 'nonce', type: 'bytes32' },\n      ],\n    },\n    primaryType: 'TransferWithAuthorization',\n    message: {\n      from: account.address as Address,\n      to: requirement.payTo,\n      value: BigInt(requirement.maxAmountRequired),\n      validAfter,\n      validBefore,\n      nonce,\n    },\n  })) as Hex\n\n  return {\n    x402Version: 1,\n    scheme: 'exact',\n    network: requirement.network,\n    payload: {\n      signature,\n      authorization: {\n        from: account.address as Address,\n        to: requirement.payTo,\n        value: requirement.maxAmountRequired,\n        validAfter: validAfter.toString(),\n        validBefore: validBefore.toString(),\n        nonce,\n      },\n    },\n  }\n}\n\nfunction chainIdForNetwork(network: X402Network): number {\n  switch (network) {\n    case 'base':\n      return 8453\n    case 'base-sepolia':\n      return 84532\n    case 'ethereum':\n      return 1\n    case 'optimism':\n      return 10\n    case 'arbitrum':\n      return 42161\n    case 'polygon':\n      return 137\n  }\n}\n"]}

package/dist/client.d.cts

@@ -0,0 +1,40 @@
+import { WalletClient } from 'viem';
+import { b as PaymentRequirement, X as X402Network, a as PaymentRequiredResponse, P as PaymentPayload } from './types-DzGpKiV3.cjs';
+
+interface ClientOptions {
+    /** A viem WalletClient able to sign EIP-712 typed data. */
+    wallet: WalletClient;
+    /** Underlying fetch to wrap (defaults to global fetch). */
+    fetch?: typeof fetch;
+    /**
+     * Hook called before signing. Return `false` to reject the payment.
+     * Useful for showing a confirmation UI to the user.
+     */
+    onPaymentRequired?: (requirement: PaymentRequirement) => boolean | Promise<boolean>;
+    /** Only allow payments up to this atomic-units cap. Safety belt. */
+    maxAmountAtomic?: bigint;
+    /** Restrict to specific networks (defaults to all). */
+    allowedNetworks?: X402Network[];
+}
+/**
+ * Create a fetch wrapper that transparently handles x402 payments.
+ *
+ * On a 402 response, it picks the cheapest acceptable requirement,
+ * signs an EIP-3009 authorization with the provided wallet, and retries
+ * the request with an `X-PAYMENT` header.
+ *
+ * @example
+ * ```ts
+ * const pay = createPaymentClient({ wallet })
+ * const res = await pay('https://api.example.com/premium')
+ * ```
+ */
+declare function createPaymentClient(options: ClientOptions): (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+declare class PaymentError extends Error {
+    readonly requirements?: PaymentRequiredResponse;
+    constructor(message: string, requirements?: PaymentRequiredResponse);
+}
+/** Sign an EIP-3009 `TransferWithAuthorization` for the given requirement. */
+declare function signPayment(wallet: WalletClient, requirement: PaymentRequirement): Promise<PaymentPayload>;
+
+export { type ClientOptions, PaymentError, createPaymentClient, signPayment };

package/dist/client.d.ts

@@ -0,0 +1,40 @@
+import { WalletClient } from 'viem';
+import { b as PaymentRequirement, X as X402Network, a as PaymentRequiredResponse, P as PaymentPayload } from './types-DzGpKiV3.js';
+
+interface ClientOptions {
+    /** A viem WalletClient able to sign EIP-712 typed data. */
+    wallet: WalletClient;
+    /** Underlying fetch to wrap (defaults to global fetch). */
+    fetch?: typeof fetch;
+    /**
+     * Hook called before signing. Return `false` to reject the payment.
+     * Useful for showing a confirmation UI to the user.
+     */
+    onPaymentRequired?: (requirement: PaymentRequirement) => boolean | Promise<boolean>;
+    /** Only allow payments up to this atomic-units cap. Safety belt. */
+    maxAmountAtomic?: bigint;
+    /** Restrict to specific networks (defaults to all). */
+    allowedNetworks?: X402Network[];
+}
+/**
+ * Create a fetch wrapper that transparently handles x402 payments.
+ *
+ * On a 402 response, it picks the cheapest acceptable requirement,
+ * signs an EIP-3009 authorization with the provided wallet, and retries
+ * the request with an `X-PAYMENT` header.
+ *
+ * @example
+ * ```ts
+ * const pay = createPaymentClient({ wallet })
+ * const res = await pay('https://api.example.com/premium')
+ * ```
+ */
+declare function createPaymentClient(options: ClientOptions): (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+declare class PaymentError extends Error {
+    readonly requirements?: PaymentRequiredResponse;
+    constructor(message: string, requirements?: PaymentRequiredResponse);
+}
+/** Sign an EIP-3009 `TransferWithAuthorization` for the given requirement. */
+declare function signPayment(wallet: WalletClient, requirement: PaymentRequirement): Promise<PaymentPayload>;
+
+export { type ClientOptions, PaymentError, createPaymentClient, signPayment };