@dexterai/x402 1.4.1 → 1.5.1

package/README.md

@@ -24,7 +24,7 @@
 
 x402 is a protocol for HTTP-native micropayments. When a server returns HTTP status `402 Payment Required`, it includes payment details in a `PAYMENT-REQUIRED` header. The client signs a payment transaction and retries the request with a `PAYMENT-SIGNATURE` header. The server verifies and settles the payment, then returns the protected content.
 
-This SDK handles the entire flow automatically—you just call `fetch()` and payments happen transparently.
+This SDK handles the entire flow automatically—you just call `fetch()` and payments happen transparently. With **Access Pass** mode, buyers pay once and get unlimited access for a time window—no per-request signing needed.
 
 ---
 
@@ -36,6 +36,8 @@ This SDK handles the entire flow automatically—you just call `fetch()` and pay
 
 **Token-accurate LLM pricing.** Built-in [tiktoken](https://github.com/openai/tiktoken) support prices AI requests by actual token count. Works with OpenAI models out of the box, or bring your own rates for Anthropic, Gemini, Mistral, or local models.
 
+**Access Pass.** Pay once, get unlimited access for a time window. Buyers connect a wallet, make one payment, and receive a JWT token that works like an API key—no per-request signing, no private keys in code. The Stripe replacement for crypto-native APIs.
+
 **Full-stack.** Client SDK for browsers, server SDK for backends. React hooks, Express middleware patterns, facilitator client—everything you need.
 
 **Multi-chain.** Solana and Base (Ethereum L2) with the same API. Add wallets for both and the SDK picks the right one automatically.
@@ -158,12 +160,18 @@ import { useX402Payment } from '@dexterai/x402/react';
 // Server - Express middleware
 import { x402Middleware } from '@dexterai/x402/server';
 
+// Server - Access Pass (pay once, unlimited requests)
+import { x402AccessPass } from '@dexterai/x402/server';
+
 // Server - manual control
 import { createX402Server } from '@dexterai/x402/server';
 
 // Server - dynamic pricing
 import { createDynamicPricing, createTokenPricing } from '@dexterai/x402/server';
 
+// React - Access Pass hook
+import { useAccessPass } from '@dexterai/x402/react';
+
 // Chain adapters (advanced)
 import { createSolanaAdapter, createEvmAdapter } from '@dexterai/x402/adapters';
 
@@ -221,6 +229,96 @@ Options:
 - `facilitatorUrl` — Override facilitator (default: x402.dexter.cash)
 - `verbose` — Enable debug logging
 
+### Access Pass — Pay Once, Unlimited Requests
+
+Replace API keys with time-limited access passes. Buyers make one payment and get a JWT token for unlimited requests during a time window.
+
+**Server:**
+
+```typescript
+import express from 'express';
+import { x402AccessPass } from '@dexterai/x402/server';
+
+const app = express();
+
+// Protect all /api routes with access pass
+app.use('/api', x402AccessPass({
+  payTo: 'YourSolanaAddress...',
+  tiers: {
+    '1h':  '0.50',   // $0.50 for 1 hour
+    '24h': '2.00',   // $2.00 for 24 hours
+  },
+  ratePerHour: '0.50',  // also accept custom durations
+}));
+
+app.get('/api/data', (req, res) => {
+  // Only runs with a valid access pass
+  res.json({ data: 'premium content' });
+});
+```
+
+**Client (Node.js):**
+
+```typescript
+import { wrapFetch } from '@dexterai/x402/client';
+
+const x402Fetch = wrapFetch(fetch, {
+  walletPrivateKey: process.env.SOLANA_PRIVATE_KEY,
+  accessPass: { preferTier: '1h', maxSpend: '1.00' },
+});
+
+// First call: auto-purchases a 1-hour pass ($0.50 USDC)
+const res1 = await x402Fetch('https://api.example.com/api/data');
+
+// All subsequent calls for the next hour: uses cached JWT, zero payment
+const res2 = await x402Fetch('https://api.example.com/api/data');
+const res3 = await x402Fetch('https://api.example.com/api/data');
+```
+
+**React:**
+
+```tsx
+import { useAccessPass } from '@dexterai/x402/react';
+
+function Dashboard() {
+  const { tiers, pass, isPassValid, purchasePass, fetch: apFetch } = useAccessPass({
+    wallets: { solana: solanaWallet },
+    resourceUrl: 'https://api.example.com',
+  });
+
+  return (
+    <div>
+      {!isPassValid && tiers?.map(t => (
+        <button key={t.id} onClick={() => purchasePass(t.id)}>
+          {t.label} — ${t.price}
+        </button>
+      ))}
+      {isPassValid && <p>Pass active! {pass?.remainingSeconds}s remaining</p>}
+      <button onClick={() => apFetch('/api/data')}>Fetch Data</button>
+    </div>
+  );
+}
+```
+
+**How it works:**
+1. Client requests a protected endpoint → Server returns `402` with `X-ACCESS-PASS-TIERS` header
+2. Client selects a tier and pays via x402 → Server verifies, settles, issues a JWT
+3. Server returns `200` with `ACCESS-PASS` header containing the JWT
+4. Client caches the JWT and includes it as `Authorization: Bearer <token>` on all subsequent requests
+5. Server validates the JWT locally (no facilitator call) → instant response
+
+Options:
+- `payTo` — Address to receive payments
+- `tiers` — Named duration tiers with prices (e.g., `{ '1h': '0.50' }`)
+- `ratePerHour` — Rate for custom durations (buyer sends `?duration=<seconds>`)
+- `network` — CAIP-2 network (default: Solana mainnet)
+- `secret` — HMAC secret for JWT signing (auto-generated if not provided)
+- `facilitatorUrl` — Override facilitator (default: x402.dexter.cash)
+
+**[Live demo →](https://dexter.cash/access-pass)**
+
+---
+
 ### Manual Server (Advanced)
 
 For more control over the payment flow:
@@ -429,6 +527,18 @@ tiktoken's default encoding works well for most transformer models. Only use a c
 | `maxAmountAtomic` | `string` | No | Maximum payment cap |
 | `verbose` | `boolean` | No | Enable debug logging |
 
+### `x402AccessPass(options)`
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `payTo` | `string` | Yes | Address to receive payments |
+| `tiers` | `Record<string, string>` | One of `tiers` or `ratePerHour` | Named tiers (e.g., `{ '1h': '0.50' }`) |
+| `ratePerHour` | `string` | One of `tiers` or `ratePerHour` | USD rate for custom durations |
+| `network` | `string` | No | CAIP-2 network (default: Solana mainnet) |
+| `secret` | `Buffer` | No | HMAC secret for JWT (auto-generated) |
+| `facilitatorUrl` | `string` | No | Facilitator URL (default: x402.dexter.cash) |
+| `verbose` | `boolean` | No | Enable debug logging |
+
 ### `useX402Payment(options)`
 
 Returns:
@@ -444,6 +554,27 @@ Returns:
 | `balances` | `Balance[]` | Token balances per chain |
 | `refreshBalances` | `function` | Manual refresh |
 | `reset` | `function` | Clear state |
+| `accessPass` | `object?` | Active pass state (tier, expiresAt, remainingSeconds) |
+
+### `useAccessPass(options)`
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `wallets` | `{ solana?, evm? }` | Yes | Multi-chain wallets |
+| `resourceUrl` | `string` | Yes | The x402 resource base URL |
+| `preferredNetwork` | `string` | No | Prefer this network |
+| `autoConnect` | `boolean` | No | Auto-fetch tiers on mount (default: true) |
+
+Returns:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `tiers` | `AccessPassTier[]?` | Available tiers from server |
+| `pass` | `object?` | Active pass (jwt, tier, expiresAt, remainingSeconds) |
+| `isPassValid` | `boolean` | Whether pass is active and not expired |
+| `purchasePass` | `function` | Buy a pass for a tier or custom duration |
+| `isPurchasing` | `boolean` | Purchase in progress |
+| `fetch` | `function` | Fetch with auto pass inclusion |
 
 ---
 
@@ -466,5 +597,6 @@ MIT — see [LICENSE](./LICENSE)
 <p align="center">
   <a href="https://x402.dexter.cash">Dexter Facilitator</a> · 
   <a href="https://dexter.cash/sdk">Live Demo</a> · 
+  <a href="https://dexter.cash/access-pass">Access Pass Demo</a> · 
   <a href="https://dexter.cash/onboard">Become a Seller</a>
 </p>

package/dist/adapters/index.d.cts

@@ -1,7 +1,7 @@
-import { C as ChainAdapter } from '../types-CQGDK_7X.cjs';
-export { A as AdapterConfig, B as BalanceInfo, G as GenericWallet, S as SignedTransaction, W as WalletSet } from '../types-CQGDK_7X.cjs';
-export { A as ARBITRUM_ONE, B as BASE_MAINNET, h as BASE_SEPOLIA, j as ETHEREUM_MAINNET, E as EvmAdapter, k as EvmWallet, d as SOLANA_DEVNET, S as SOLANA_MAINNET, e as SOLANA_TESTNET, b as SolanaAdapter, f as SolanaWallet, a as createEvmAdapter, c as createSolanaAdapter, g as isEvmWallet, i as isSolanaWallet } from '../evm-BaoETN1Y.cjs';
-import '../types-B7T6dZ-y.cjs';
+import { C as ChainAdapter } from '../types--r7urkVI.cjs';
+export { A as AdapterConfig, B as BalanceInfo, G as GenericWallet, S as SignedTransaction, W as WalletSet } from '../types--r7urkVI.cjs';
+export { A as ARBITRUM_ONE, B as BASE_MAINNET, h as BASE_SEPOLIA, j as ETHEREUM_MAINNET, E as EvmAdapter, k as EvmWallet, d as SOLANA_DEVNET, S as SOLANA_MAINNET, e as SOLANA_TESTNET, b as SolanaAdapter, f as SolanaWallet, a as createEvmAdapter, c as createSolanaAdapter, g as isEvmWallet, i as isSolanaWallet } from '../evm-BYjwU6ZW.cjs';
+import '../types-CcVAaoro.cjs';
 
 /**
  * Create all default adapters

package/dist/adapters/index.d.ts

@@ -1,7 +1,7 @@
-import { C as ChainAdapter } from '../types-DNx7-QUN.js';
-export { A as AdapterConfig, B as BalanceInfo, G as GenericWallet, S as SignedTransaction, W as WalletSet } from '../types-DNx7-QUN.js';
-export { A as ARBITRUM_ONE, B as BASE_MAINNET, h as BASE_SEPOLIA, j as ETHEREUM_MAINNET, E as EvmAdapter, k as EvmWallet, d as SOLANA_DEVNET, S as SOLANA_MAINNET, e as SOLANA_TESTNET, b as SolanaAdapter, f as SolanaWallet, a as createEvmAdapter, c as createSolanaAdapter, g as isEvmWallet, i as isSolanaWallet } from '../evm-ZDwQi4QL.js';
-import '../types-B7T6dZ-y.js';
+import { C as ChainAdapter } from '../types-BtpD4ULe.js';
+export { A as AdapterConfig, B as BalanceInfo, G as GenericWallet, S as SignedTransaction, W as WalletSet } from '../types-BtpD4ULe.js';
+export { A as ARBITRUM_ONE, B as BASE_MAINNET, h as BASE_SEPOLIA, j as ETHEREUM_MAINNET, E as EvmAdapter, k as EvmWallet, d as SOLANA_DEVNET, S as SOLANA_MAINNET, e as SOLANA_TESTNET, b as SolanaAdapter, f as SolanaWallet, a as createEvmAdapter, c as createSolanaAdapter, g as isEvmWallet, i as isSolanaWallet } from '../evm-71SZ7cjW.js';
+import '../types-CcVAaoro.js';
 
 /**
  * Create all default adapters

package/dist/client/index.cjs

@@ -614,10 +614,41 @@ function createX402Client(config) {
     rpcUrls = {},
     maxAmountAtomic,
     fetch: customFetch = globalThis.fetch,
-    verbose = false
+    verbose = false,
+    accessPass: accessPassConfig
   } = config;
   const log = verbose ? console.log.bind(console, "[x402]") : () => {
   };
+  const passCache = /* @__PURE__ */ new Map();
+  function getCachedPass(url) {
+    try {
+      const host = new URL(url).host;
+      const cached = passCache.get(host);
+      if (cached && cached.expiresAt > Date.now() / 1e3 + 10) {
+        return cached.jwt;
+      }
+      if (cached) {
+        passCache.delete(host);
+      }
+    } catch {
+    }
+    return null;
+  }
+  function cachePass(url, jwt) {
+    try {
+      const host = new URL(url).host;
+      const parts = jwt.split(".");
+      if (parts.length === 3) {
+        const payload = JSON.parse(atob(parts[1].replace(/-/g, "+").replace(/_/g, "/")));
+        if (payload.exp) {
+          passCache.set(host, { jwt, expiresAt: payload.exp });
+          log("Access pass cached for", host, "| expires:", new Date(payload.exp * 1e3).toISOString());
+        }
+      }
+    } catch {
+      log("Failed to cache access pass");
+    }
+  }
   const wallets = walletSet || {};
   if (legacyWallet && !wallets.solana && isSolanaWallet(legacyWallet)) {
     wallets.solana = legacyWallet;
@@ -652,13 +683,160 @@ function createX402Client(config) {
   function getRpcUrl(network, adapter) {
     return rpcUrls[network] || adapter.getDefaultRpcUrl(network);
   }
+  async function purchaseAccessPass(input, init, originalResponse, passInfo, url) {
+    let tierQuery = "";
+    if (accessPassConfig?.preferTier && passInfo.tiers) {
+      const match2 = passInfo.tiers.find((t) => t.id === accessPassConfig.preferTier);
+      if (match2) {
+        if (accessPassConfig.maxSpend && parseFloat(match2.price) > parseFloat(accessPassConfig.maxSpend)) {
+          throw new X402Error(
+            "access_pass_exceeds_max_spend",
+            `Access pass tier "${match2.id}" costs $${match2.price}, exceeds max spend $${accessPassConfig.maxSpend}`
+          );
+        }
+        tierQuery = `tier=${match2.id}`;
+      }
+    } else if (accessPassConfig?.preferDuration && passInfo.ratePerHour) {
+      tierQuery = `duration=${accessPassConfig.preferDuration}`;
+    } else if (passInfo.tiers && passInfo.tiers.length > 0) {
+      const cheapest = passInfo.tiers[0];
+      if (accessPassConfig?.maxSpend && parseFloat(cheapest.price) > parseFloat(accessPassConfig.maxSpend)) {
+        throw new X402Error(
+          "access_pass_exceeds_max_spend",
+          `Cheapest access pass costs $${cheapest.price}, exceeds max spend $${accessPassConfig?.maxSpend}`
+        );
+      }
+      tierQuery = `tier=${cheapest.id}`;
+    }
+    const passUrl = tierQuery ? url.includes("?") ? `${url}&${tierQuery}` : `${url}?${tierQuery}` : url;
+    log("Purchasing access pass:", tierQuery || "default tier");
+    const paymentRequiredHeader = originalResponse.headers.get("PAYMENT-REQUIRED");
+    if (!paymentRequiredHeader) return null;
+    let requirements;
+    try {
+      requirements = JSON.parse(atob(paymentRequiredHeader));
+    } catch {
+      return null;
+    }
+    const match = findPaymentOption(requirements.accepts);
+    if (!match) return null;
+    const { accept, adapter, wallet } = match;
+    if (adapter.name === "Solana" && !accept.extra?.feePayer) return null;
+    const USDC_MINTS = [
+      "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+      "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
+      "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+      "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+    ];
+    const decimals = accept.extra?.decimals ?? (USDC_MINTS.includes(accept.asset) ? 6 : void 0);
+    if (typeof decimals !== "number") return null;
+    const paymentAmount = accept.amount || accept.maxAmountRequired;
+    if (!paymentAmount) return null;
+    const rpcUrl = getRpcUrl(accept.network, adapter);
+    const balance = await adapter.getBalance(accept, wallet, rpcUrl);
+    const requiredAmount = Number(paymentAmount) / Math.pow(10, decimals);
+    if (balance < requiredAmount) {
+      throw new X402Error(
+        "insufficient_balance",
+        `Insufficient balance for access pass. Have $${balance.toFixed(4)}, need $${requiredAmount.toFixed(4)}`
+      );
+    }
+    const signedTx = await adapter.buildTransaction(accept, wallet, rpcUrl);
+    let payload;
+    if (adapter.name === "EVM") {
+      payload = JSON.parse(signedTx.serialized);
+    } else {
+      payload = { transaction: signedTx.serialized };
+    }
+    const originalUrl = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    let resolvedResource = requirements.resource;
+    if (typeof requirements.resource === "string") {
+      try {
+        resolvedResource = new URL(requirements.resource, originalUrl).toString();
+      } catch {
+      }
+    } else if (requirements.resource && typeof requirements.resource === "object" && "url" in requirements.resource) {
+      const rObj = requirements.resource;
+      try {
+        resolvedResource = { ...rObj, url: new URL(rObj.url, originalUrl).toString() };
+      } catch {
+      }
+    }
+    const paymentSignature = {
+      x402Version: accept.x402Version ?? 2,
+      resource: resolvedResource,
+      accepted: accept,
+      payload
+    };
+    const paymentSignatureHeader = btoa(JSON.stringify(paymentSignature));
+    const passResponse = await customFetch(passUrl, {
+      ...init,
+      method: "POST",
+      headers: {
+        ...init?.headers || {},
+        "Content-Type": "application/json",
+        "PAYMENT-SIGNATURE": paymentSignatureHeader
+      }
+    });
+    if (!passResponse.ok) {
+      log("Pass purchase failed:", passResponse.status);
+      return null;
+    }
+    const accessPassJwt = passResponse.headers.get("ACCESS-PASS");
+    if (!accessPassJwt) {
+      return passResponse;
+    }
+    cachePass(url, accessPassJwt);
+    log("Access pass purchased and cached");
+    const retryResponse = await customFetch(input, {
+      ...init,
+      headers: {
+        ...init?.headers || {},
+        "Authorization": `Bearer ${accessPassJwt}`
+      }
+    });
+    return retryResponse;
+  }
   async function x402Fetch(input, init) {
-    log("Making request:", input);
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    log("Making request:", url);
+    if (accessPassConfig) {
+      const cachedJwt = getCachedPass(url);
+      if (cachedJwt) {
+        log("Using cached access pass");
+        const passResponse = await customFetch(input, {
+          ...init,
+          headers: {
+            ...init?.headers || {},
+            "Authorization": `Bearer ${cachedJwt}`
+          }
+        });
+        if (passResponse.status !== 401 && passResponse.status !== 402) {
+          return passResponse;
+        }
+        log("Cached pass rejected (status", passResponse.status, "), purchasing new pass");
+        try {
+          passCache.delete(new URL(url).host);
+        } catch {
+        }
+      }
+    }
     const response = await customFetch(input, init);
     if (response.status !== 402) {
       return response;
     }
     log("Received 402 Payment Required");
+    const passTiersHeader = response.headers.get("X-ACCESS-PASS-TIERS");
+    if (accessPassConfig && passTiersHeader) {
+      log("Server offers access passes, purchasing...");
+      try {
+        const passInfo = JSON.parse(atob(passTiersHeader));
+        const passResponse = await purchaseAccessPass(input, init, response, passInfo, url);
+        if (passResponse) return passResponse;
+      } catch (e) {
+        log("Access pass purchase failed, falling back to per-request payment:", e);
+      }
+    }
     const paymentRequiredHeader = response.headers.get("PAYMENT-REQUIRED");
     if (!paymentRequiredHeader) {
       throw new X402Error(
@@ -875,7 +1053,8 @@ function wrapFetch(fetchImpl, options) {
     // facilitatorUrl is reserved for future use when we add facilitator selection
     rpcUrls,
     maxAmountAtomic,
-    verbose
+    verbose,
+    accessPass
   } = options;
   if (!walletPrivateKey && !evmPrivateKey) {
     throw new Error("At least one wallet private key is required (walletPrivateKey or evmPrivateKey)");
@@ -893,7 +1072,8 @@ function wrapFetch(fetchImpl, options) {
     rpcUrls,
     maxAmountAtomic,
     fetch: fetchImpl,
-    verbose
+    verbose,
+    accessPass
   };
   const client = createX402Client(clientConfig);
   return client.fetch.bind(client);