@relai-fi/x402 0.5.30 → 0.5.32

package/README.md

@@ -174,6 +174,46 @@ const result = await response.json();
 
 ---
 
+### Crossmint Smart Wallet (server-side / agent)
+
+Use `createCrossmintX402Fetch` from `@relai-fi/x402/crossmint` — no `signTransaction` needed, Crossmint handles signing and broadcasting.
+
+```typescript
+import { createCrossmintX402Fetch } from '@relai-fi/x402/crossmint';
+import { Connection } from '@solana/web3.js';
+
+const fetch402 = createCrossmintX402Fetch({
+  apiKey: process.env.CROSSMINT_API_KEY!,   // sk_production_... or sk_staging_...
+  wallet: process.env.CROSSMINT_WALLET!,    // Crossmint smart wallet address
+  connection: new Connection(process.env.SOLANA_RPC_URL!),
+  onPayment: (txHash) => console.log('On-chain tx:', txHash),
+});
+
+// RelAI sponsors SOL gas — wallet only needs USDC
+const response = await fetch402('https://api.example.com/protected');
+const data = await response.json();
+```
+
+For agents that require explicit transaction approval before Crossmint broadcasts, use the **delegated mode** — an external Ed25519 signer must be registered on the Crossmint smart wallet:
+
+```typescript
+import { createCrossmintDelegatedX402Fetch } from '@relai-fi/x402/crossmint';
+import { Connection } from '@solana/web3.js';
+
+const fetch402 = createCrossmintDelegatedX402Fetch({
+  apiKey: process.env.CROSSMINT_API_KEY!,
+  wallet: process.env.CROSSMINT_WALLET!,
+  signerSecretKey: Buffer.from(process.env.SIGNER_SECRET_KEY!, 'base64'), // 64-byte Ed25519
+  connection: new Connection(process.env.SOLANA_RPC_URL!),
+});
+
+const response = await fetch402('https://api.example.com/protected');
+```
+
+> Both modes use Crossmint's API to sign and broadcast — no private key handling in your code.
+
+---
+
 ### WebSocket relay transport (optional)
 
 If your protected API is behind a relay URL like `https://api.relai.fi/relay/:apiId/...`
@@ -300,6 +340,9 @@ import {
   fromAtomicUnits,
 } from '@relai-fi/x402/utils';
 
+// Plugins — extend protect() with free tier, custom logic
+import { freeTier } from '@relai-fi/x402/plugins';
+
 // Management API — create/manage APIs, pricing, analytics, agent bootstrap
 import {
   createManagementClient,
@@ -468,6 +511,105 @@ app.get('/api/solana-data', relai.protect({
 
 ---
 
+## Plugins
+
+Extend `Relai.protect()` with plugins that run before payment checks. Plugins can skip payment (e.g. free tier), add headers, or attach metadata to requests.
+
+### Free Tier Plugin
+
+Allow buyers to make free API calls before requiring x402 payment. Usage is tracked per buyer (by JWT `sub`, wallet address, or IP) with optional global caps and periodic resets.
+
+```typescript
+import Relai from '@relai-fi/x402/server';
+import { freeTier } from '@relai-fi/x402/plugins';
+
+const relai = new Relai({
+  network: 'base',
+  plugins: [
+    freeTier({
+      serviceKey: process.env.RELAI_SERVICE_KEY!,
+      perBuyerLimit: 10,        // 10 free calls per buyer
+      resetPeriod: 'daily',     // reset daily (or 'monthly', 'never')
+      globalCap: 1000,          // optional: max 1000 free calls total
+      paths: ['*'],             // optional: apply to all endpoints (default)
+    }),
+  ],
+});
+
+app.get('/api/data', relai.protect({
+  payTo: '0xYourWallet',
+  price: 0.01,
+}), (req, res) => {
+  if (req.x402Free) {
+    // Free tier call — no payment was made
+    console.log('Free call from:', req.x402Plugin);
+  }
+  res.json({ data: 'content' });
+});
+```
+
+**How it works:**
+1. On server start, the plugin syncs its config to the RelAI backend via your service key.
+2. On each request, `beforePaymentCheck` asks the RelAI API if the buyer has free calls remaining.
+3. If free → `next()` is called without payment, `req.x402Free = true`, and usage is recorded.
+4. If exhausted → normal x402 payment flow continues.
+
+**Free Tier config:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `serviceKey` | `string` | **required** | Your RelAI service key (`sk_live_...`) |
+| `perBuyerLimit` | `number` | **required** | Free calls each buyer gets per period |
+| `resetPeriod` | `'never' \| 'daily' \| 'monthly'` | `'never'` | When counters reset |
+| `globalCap` | `number` | — | Max total free calls across all buyers |
+| `paths` | `string[]` | `['*']` | Which endpoints the free tier applies to |
+| `baseUrl` | `string` | `https://api.relai.fi` | RelAI API URL (override for testing) |
+
+**Request properties set on free-tier bypass:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `req.x402Free` | `boolean` | `true` when request was served for free |
+| `req.x402Paid` | `boolean` | `false` on free tier, `true` on paid |
+| `req.x402Plugin` | `string` | Plugin name that granted the bypass (`'freeTier'`) |
+| `req.pluginMeta` | `object` | `{ freeTier: true, remaining: number }` |
+
+**Dashboard:** Manage plugin config and view usage in the RelAI dashboard under **SDK Plugins**.
+
+### Custom Plugins
+
+```typescript
+import type { RelaiPlugin } from '@relai-fi/x402';
+
+const myPlugin: RelaiPlugin = {
+  name: 'myPlugin',
+  beforePaymentCheck: async (ctx) => {
+    if (ctx.req.headers['x-vip'] === 'true') {
+      return { skip: true, reason: 'VIP bypass' };
+    }
+    return {};
+  },
+};
+
+const relai = new Relai({
+  network: 'base',
+  plugins: [myPlugin],
+});
+```
+
+**Plugin interface:**
+
+```typescript
+interface RelaiPlugin {
+  name: string;
+  beforePaymentCheck?: (ctx: PluginContext) => Promise<PluginResult>;
+  afterSettled?: (ctx: PluginContext) => Promise<void>;
+  onInit?: (config: RelaiServerConfig) => Promise<void>;
+}
+```
+
+---
+
 ## Management API
 
 Programmatically create and manage monetised APIs, update pricing, and read analytics. Designed for agents and CI/CD — no browser needed.

package/dist/client.cjs

@@ -742,7 +742,7 @@ function createX402Client(config) {
   }
   function getBridgeExtension(requirements) {
     const ext = requirements?.extensions?.bridge;
-    if (!ext?.info?.endpoint || !Array.isArray(ext.info.supportedSourceChains)) return null;
+    if (!ext?.info?.settleEndpoint || !Array.isArray(ext.info.supportedSourceChains)) return null;
     return ext.info;
   }
   function selectBridgeSource(bridge) {
@@ -783,7 +783,7 @@ function createX402Client(config) {
         payTo: bridge.payTo,
         amount: targetAccept.amount || targetAccept.maxAmountRequired,
         extra: {
-          ...bridge.feePayer ? { feePayer: bridge.feePayer } : {},
+          ...bridge.feePayerSvm ? { feePayer: bridge.feePayerSvm } : {},
           decimals: 6
         }
       };
@@ -799,7 +799,7 @@ function createX402Client(config) {
       };
       sourcePaymentHeader = usePermit ? await buildEvmPermitPayment(sourceAccept, requirements, url) : await buildEvmPayment(sourceAccept, requirements, url);
     }
-    const bridgeRes = await fetch(bridge.endpoint, {
+    const bridgeRes = await fetch(bridge.settleEndpoint, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({