@relai-fi/x402 0.6.5 → 0.6.6

package/README.md

@@ -1483,6 +1483,122 @@ Both interfaces are exported from `@relai-fi/x402`.
 
 ---
 
+## Cross-Chain Bridge Flows
+
+The SDK supports transparent cross-chain payments via the RelAI bridge. There are two approaches depending on who manages the bridge logic — the **client** or the **server**.
+
+### x402 Auto-Bridge (client-side)
+
+The server is a standard x402 server. The client has a wallet on a different chain and uses `bridge: { enabled: true }` to auto-bridge.
+
+```mermaid
+sequenceDiagram
+    participant Client as Client (Solana)
+    participant Server as Server (Base)
+    participant Bridge as RelAI Bridge API
+    participant Facilitator as Facilitator
+
+    Client->>Server: GET /api/data
+    Server-->>Client: 402 (accepts: Base USDC)
+
+    Note over Client: No Base wallet → auto-bridge
+
+    Client->>Bridge: GET /bridge/info
+    Bridge-->>Client: source chains, payTo, fees
+
+    Client->>Client: Build Solana SPL transfer to bridge payTo
+    Client->>Bridge: POST /bridge/settle (sourcePayment, targetAccept)
+    Bridge->>Bridge: Co-sign & broadcast Solana tx
+    Bridge->>Bridge: Sign EIP-3009 authorization (Base)
+    Bridge-->>Client: xPayment (base64)
+
+    Client->>Server: GET /api/data + X-PAYMENT header
+    Server->>Facilitator: POST /settle (paymentPayload)
+    Facilitator->>Facilitator: Execute transferWithAuthorization on Base
+    Facilitator-->>Server: tx hash
+    Server-->>Client: 200 OK + data
+```
+
+### MPP Client-Side Bridge (evmChargeWithBridge)
+
+The server exposes a standard `evm/charge` MPP method. The client detects it's on a different chain and bridges transparently — the server never knows.
+
+```mermaid
+sequenceDiagram
+    participant Client as Client (Tempo)
+    participant Server as Server (SKALE)
+    participant Bridge as RelAI Bridge API
+    participant Facilitator as Facilitator
+
+    Client->>Server: GET /api/data
+    Server-->>Client: 402 + WWW-Authenticate: Payment (evm/charge, chainId=SKALE)
+
+    Note over Client: Source chain ≠ target chain → bridge
+
+    Client->>Bridge: GET /bridge/info
+    Bridge-->>Client: source chains, payTo, fees
+
+    Client->>Client: ERC-20 transfer on Tempo → bridge payTo
+    Client->>Client: Sign settle message (ECDSA)
+    Client->>Bridge: POST /bridge/settle (sourceTxHash, signature, targetAccept)
+    Bridge->>Bridge: Verify source tx on-chain + signature
+    Bridge->>Bridge: Sign EIP-3009 authorization (SKALE)
+    Bridge-->>Client: xPayment + targetTxId=pending
+
+    Client->>Facilitator: POST /settle (paymentPayload, paymentRequirements)
+    Facilitator->>Facilitator: Execute transferWithAuthorization on SKALE
+    Facilitator-->>Client: tx hash (SKALE)
+
+    Client->>Server: GET /api/data + Authorization: Payment (hash=SKALE tx)
+    Server->>Server: Verify ERC-20 Transfer on SKALE (standard evm/charge verify)
+    Server-->>Client: 200 OK + data
+```
+
+### MPP Server-Side Bridge (bridge/charge method)
+
+The server explicitly exposes a `bridge/charge` method alongside its direct method. The client picks bridge/charge when it can't pay directly. Use this when the target chain is not EVM (e.g. Solana).
+
+```mermaid
+sequenceDiagram
+    participant Client as Client (Tempo)
+    participant Server as Server (SKALE)
+    participant Bridge as RelAI Bridge API
+    participant Facilitator as Facilitator
+
+    Client->>Server: GET /api/data
+    Server->>Bridge: GET /bridge/info (auto-discover)
+    Server-->>Client: 402 + WWW-Authenticate: Payment<br/>(evm/charge + bridge/charge)
+
+    Note over Client: Can't match evm/charge → picks bridge/charge
+
+    Client->>Client: ERC-20 transfer on Tempo → bridge payTo
+    Client->>Client: Sign settle message (ECDSA)
+    Client->>Bridge: POST /bridge/settle (sourceTxHash, signature, targetAccept)
+    Bridge->>Bridge: Verify source tx on-chain + signature
+    Bridge->>Bridge: Sign EIP-3009 authorization (SKALE)
+    Bridge-->>Client: xPayment + targetTxId=pending
+
+    Client->>Facilitator: POST /settle (paymentPayload, paymentRequirements)
+    Facilitator->>Facilitator: Execute transferWithAuthorization on SKALE
+    Facilitator-->>Client: tx hash (SKALE)
+
+    Client->>Server: Authorization: Payment (targetTxHash=SKALE tx)
+    Server->>Server: bridge/charge verify() — check ERC-20 Transfer on SKALE
+    Server-->>Client: 200 OK + data
+```
+
+### When to use which approach
+
+| Approach | Server config | Client config | Best for |
+|----------|--------------|---------------|----------|
+| **x402 auto-bridge** | Standard x402 (no change) | `bridge: { enabled: true }` | Solana client → EVM server |
+| **MPP client-side** | Standard `evm/charge` (no change) | `evmChargeWithBridge()` | EVM client → different EVM server |
+| **MPP server-side** | `evm/charge` + `bridge/charge` | `bridgeCharge()` client | Any client → Solana server, or when server wants to control bridge options |
+
+See [`examples/bridge/`](./examples/bridge/) for runnable examples of each approach.
+
+---
+
 ## Development
 
 ```bash

package/dist/bridge.cjs

@@ -0,0 +1,109 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/bridge.ts
+var bridge_exports = {};
+__export(bridge_exports, {
+  DEFAULT_EVM_RPC: () => DEFAULT_EVM_RPC,
+  computeSourceAmount: () => computeSourceAmount,
+  getBridgeInfo: () => getBridgeInfo,
+  selectSourceChain: () => selectSourceChain,
+  settleBridge: () => settleBridge
+});
+module.exports = __toCommonJS(bridge_exports);
+var RELAI_API_BASE = "https://api.relai.fi";
+var _cacheMap = /* @__PURE__ */ new Map();
+var CACHE_TTL = 5 * 60 * 1e3;
+async function getBridgeInfo(baseUrl = RELAI_API_BASE) {
+  const key = baseUrl.replace(/\/$/, "");
+  const now = Date.now();
+  const cached = _cacheMap.get(key);
+  if (cached && now - cached.time < CACHE_TTL) return cached.info;
+  const url = `${key}/bridge/info`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    if (cached) return cached.info;
+    throw new Error(`[relai:bridge] Failed to fetch ${url}: ${res.status}`);
+  }
+  const data = await res.json();
+  const info = {
+    settleEndpoint: data.settleEndpoint,
+    supportedSourceChains: data.supportedSourceChains || [],
+    supportedSourceAssets: data.supportedSourceAssets || [],
+    payTo: data.payTo || {},
+    feePayerSvm: data.feePayerSvm ?? null,
+    feeBps: data.feeBps ?? 100,
+    paymentFacilitator: data.paymentFacilitator || "https://facilitator.x402.fi"
+  };
+  _cacheMap.set(key, { info, time: now });
+  return info;
+}
+async function settleBridge(settleEndpoint, body) {
+  const res = await fetch(settleEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(`[relai:bridge] settle failed: ${err.error || res.status}${err.details ? " \u2014 " + err.details : ""}`);
+  }
+  return res.json();
+}
+function selectSourceChain(supportedChains, hasEvmWallet, hasSolanaWallet, preferredSourceChainId) {
+  if (preferredSourceChainId && hasEvmWallet) {
+    const preferred = `eip155:${preferredSourceChainId}`;
+    if (supportedChains.includes(preferred)) {
+      return { type: "evm", chain: preferred };
+    }
+  }
+  if (hasSolanaWallet) {
+    const sol = supportedChains.find((c) => c.startsWith("solana:"));
+    if (sol) return { type: "solana", chain: sol };
+  }
+  if (hasEvmWallet) {
+    for (const chain of supportedChains) {
+      if (chain.startsWith("eip155:")) {
+        return { type: "evm", chain };
+      }
+    }
+  }
+  return null;
+}
+function computeSourceAmount(targetAmount, feeBps) {
+  const fee = targetAmount * BigInt(feeBps) / 10000n;
+  return targetAmount + fee;
+}
+var DEFAULT_EVM_RPC = {
+  "eip155:8453": "https://mainnet.base.org",
+  "eip155:137": "https://polygon-rpc.com",
+  "eip155:1": "https://eth.llamarpc.com",
+  "eip155:42161": "https://arb1.arbitrum.io/rpc",
+  "eip155:43114": "https://api.avax.network/ext/bc/C/rpc",
+  "eip155:1187947933": "https://skale-base.skalenodes.com/v1/base"
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_EVM_RPC,
+  computeSourceAmount,
+  getBridgeInfo,
+  selectSourceChain,
+  settleBridge
+});
+//# sourceMappingURL=bridge.cjs.map

package/dist/bridge.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bridge.ts"],"sourcesContent":["/**\n * Core bridge utilities — shared between x402 and MPP clients.\n *\n * Auto-discovers bridge info from the RelAI API and provides helpers\n * for executing cross-chain payments transparently.\n *\n * Usage (MPP):\n * ```ts\n * import { evmChargeWithBridge } from '@relai-fi/x402/mpp/with-bridge'\n * ```\n *\n * Usage (x402):\n * ```ts\n * import { createX402Client } from '@relai-fi/x402'\n * const client = createX402Client({ ..., bridge: { enabled: true } })\n * ```\n */\n\nconst RELAI_API_BASE = 'https://api.relai.fi'\n\nexport interface BridgeInfo {\n  settleEndpoint: string\n  supportedSourceChains: string[]\n  supportedSourceAssets: string[]\n  payTo: Record<string, string>\n  feePayerSvm: string | null\n  feeBps: number\n  paymentFacilitator: string\n}\n\nexport interface BridgeSettleRequest {\n  /** x402 mode: base64-encoded payment header */\n  sourcePayment?: string\n  /** MPP mode: source tx hash */\n  sourceTxHash?: string\n  /** MPP mode: wallet address that sent the source tx */\n  senderAddress?: string\n  /** MPP mode: signature of (sourceTxHash + JSON(targetAccept)) */\n  senderSignature?: string\n  /** CAIP-2 source chain identifier */\n  sourceChain: string\n  targetAccept: {\n    scheme: 'exact'\n    network: string\n    asset: string\n    payTo: string\n    amount: string\n  }\n  /** x402 payment requirements (full 402 body) — needed by settle for x402 flow */\n  requirements?: any\n  resource?: string\n  paymentFacilitator?: string | null\n}\n\nexport interface BridgeSettleResponse {\n  success?: boolean\n  targetTxId?: string\n  sourceTxId?: string\n  /** x402 payment header (returned by x402-flavored settle) */\n  xPayment?: string\n}\n\n// ── Cache (keyed by base URL) ──────────────────────────────────────────\n\nconst _cacheMap = new Map<string, { info: BridgeInfo; time: number }>()\nconst CACHE_TTL = 5 * 60 * 1000 // 5 minutes\n\n/**\n * Fetch bridge info from the RelAI API (cached per base URL for 5 minutes).\n */\nexport async function getBridgeInfo(baseUrl = RELAI_API_BASE): Promise<BridgeInfo> {\n  const key = baseUrl.replace(/\\/$/, '')\n  const now = Date.now()\n  const cached = _cacheMap.get(key)\n  if (cached && now - cached.time < CACHE_TTL) return cached.info\n\n  const url = `${key}/bridge/info`\n  const res = await fetch(url)\n  if (!res.ok) {\n    if (cached) return cached.info // stale cache better than failure\n    throw new Error(`[relai:bridge] Failed to fetch ${url}: ${res.status}`)\n  }\n\n  const data = (await res.json()) as any\n  const info: BridgeInfo = {\n    settleEndpoint: data.settleEndpoint,\n    supportedSourceChains: data.supportedSourceChains || [],\n    supportedSourceAssets: data.supportedSourceAssets || [],\n    payTo: data.payTo || {},\n    feePayerSvm: data.feePayerSvm ?? null,\n    feeBps: data.feeBps ?? 100,\n    paymentFacilitator: data.paymentFacilitator || 'https://facilitator.x402.fi',\n  }\n  _cacheMap.set(key, { info, time: now })\n  return info\n}\n\n/**\n * Call the bridge settle endpoint.\n */\nexport async function settleBridge(\n  settleEndpoint: string,\n  body: BridgeSettleRequest,\n): Promise<BridgeSettleResponse> {\n  const res = await fetch(settleEndpoint, {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/json' },\n    body: JSON.stringify(body),\n  })\n\n  if (!res.ok) {\n    const err = (await res.json().catch(() => ({}))) as any\n    throw new Error(`[relai:bridge] settle failed: ${err.error || res.status}${err.details ? ' — ' + err.details : ''}`)\n  }\n\n  return res.json() as Promise<BridgeSettleResponse>\n}\n\n/**\n * Select a source chain from supported chains that matches the available wallet.\n */\nexport function selectSourceChain(\n  supportedChains: string[],\n  hasEvmWallet: boolean,\n  hasSolanaWallet: boolean,\n  preferredSourceChainId?: number,\n): { type: 'evm' | 'solana'; chain: string } | null {\n  // If a specific source chain is preferred, try it first\n  if (preferredSourceChainId && hasEvmWallet) {\n    const preferred = `eip155:${preferredSourceChainId}`\n    if (supportedChains.includes(preferred)) {\n      return { type: 'evm', chain: preferred }\n    }\n  }\n\n  // Solana first (lower fees)\n  if (hasSolanaWallet) {\n    const sol = supportedChains.find((c) => c.startsWith('solana:'))\n    if (sol) return { type: 'solana', chain: sol }\n  }\n\n  // Then any EVM chain\n  if (hasEvmWallet) {\n    for (const chain of supportedChains) {\n      if (chain.startsWith('eip155:')) {\n        return { type: 'evm', chain }\n      }\n    }\n  }\n\n  return null\n}\n\n/**\n * Compute source amount including bridge fee.\n */\nexport function computeSourceAmount(targetAmount: bigint, feeBps: number): bigint {\n  const fee = (targetAmount * BigInt(feeBps)) / 10000n\n  return targetAmount + fee\n}\n\n// Known EVM RPC URLs (fallback)\nexport const DEFAULT_EVM_RPC: Record<string, string> = {\n  'eip155:8453': 'https://mainnet.base.org',\n  'eip155:137': 'https://polygon-rpc.com',\n  'eip155:1': 'https://eth.llamarpc.com',\n  'eip155:42161': 'https://arb1.arbitrum.io/rpc',\n  'eip155:43114': 'https://api.avax.network/ext/bc/C/rpc',\n  'eip155:1187947933': 'https://skale-base.skalenodes.com/v1/base',\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAkBA,IAAM,iBAAiB;AA8CvB,IAAM,YAAY,oBAAI,IAAgD;AACtE,IAAM,YAAY,IAAI,KAAK;AAK3B,eAAsB,cAAc,UAAU,gBAAqC;AACjF,QAAM,MAAM,QAAQ,QAAQ,OAAO,EAAE;AACrC,QAAM,MAAM,KAAK,IAAI;AACrB,QAAM,SAAS,UAAU,IAAI,GAAG;AAChC,MAAI,UAAU,MAAM,OAAO,OAAO,UAAW,QAAO,OAAO;AAE3D,QAAM,MAAM,GAAG,GAAG;AAClB,QAAM,MAAM,MAAM,MAAM,GAAG;AAC3B,MAAI,CAAC,IAAI,IAAI;AACX,QAAI,OAAQ,QAAO,OAAO;AAC1B,UAAM,IAAI,MAAM,kCAAkC,GAAG,KAAK,IAAI,MAAM,EAAE;AAAA,EACxE;AAEA,QAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,QAAM,OAAmB;AAAA,IACvB,gBAAgB,KAAK;AAAA,IACrB,uBAAuB,KAAK,yBAAyB,CAAC;AAAA,IACtD,uBAAuB,KAAK,yBAAyB,CAAC;AAAA,IACtD,OAAO,KAAK,SAAS,CAAC;AAAA,IACtB,aAAa,KAAK,eAAe;AAAA,IACjC,QAAQ,KAAK,UAAU;AAAA,IACvB,oBAAoB,KAAK,sBAAsB;AAAA,EACjD;AACA,YAAU,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,CAAC;AACtC,SAAO;AACT;AAKA,eAAsB,aACpB,gBACA,MAC+B;AAC/B,QAAM,MAAM,MAAM,MAAM,gBAAgB;AAAA,IACtC,QAAQ;AAAA,IACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,IAC9C,MAAM,KAAK,UAAU,IAAI;AAAA,EAC3B,CAAC;AAED,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,MAAO,MAAM,IAAI,KAAK,EAAE,MAAM,OAAO,CAAC,EAAE;AAC9C,UAAM,IAAI,MAAM,iCAAiC,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,UAAU,aAAQ,IAAI,UAAU,EAAE,EAAE;AAAA,EACrH;AAEA,SAAO,IAAI,KAAK;AAClB;AAKO,SAAS,kBACd,iBACA,cACA,iBACA,wBACkD;AAElD,MAAI,0BAA0B,cAAc;AAC1C,UAAM,YAAY,UAAU,sBAAsB;AAClD,QAAI,gBAAgB,SAAS,SAAS,GAAG;AACvC,aAAO,EAAE,MAAM,OAAO,OAAO,UAAU;AAAA,IACzC;AAAA,EACF;AAGA,MAAI,iBAAiB;AACnB,UAAM,MAAM,gBAAgB,KAAK,CAAC,MAAM,EAAE,WAAW,SAAS,CAAC;AAC/D,QAAI,IAAK,QAAO,EAAE,MAAM,UAAU,OAAO,IAAI;AAAA,EAC/C;AAGA,MAAI,cAAc;AAChB,eAAW,SAAS,iBAAiB;AACnC,UAAI,MAAM,WAAW,SAAS,GAAG;AAC/B,eAAO,EAAE,MAAM,OAAO,MAAM;AAAA,MAC9B;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAKO,SAAS,oBAAoB,cAAsB,QAAwB;AAChF,QAAM,MAAO,eAAe,OAAO,MAAM,IAAK;AAC9C,SAAO,eAAe;AACxB;AAGO,IAAM,kBAA0C;AAAA,EACrD,eAAe;AAAA,EACf,cAAc;AAAA,EACd,YAAY;AAAA,EACZ,gBAAgB;AAAA,EAChB,gBAAgB;AAAA,EAChB,qBAAqB;AACvB;","names":[]}

package/dist/bridge.d.cts

@@ -0,0 +1,78 @@
+/**
+ * Core bridge utilities — shared between x402 and MPP clients.
+ *
+ * Auto-discovers bridge info from the RelAI API and provides helpers
+ * for executing cross-chain payments transparently.
+ *
+ * Usage (MPP):
+ * ```ts
+ * import { evmChargeWithBridge } from '@relai-fi/x402/mpp/with-bridge'
+ * ```
+ *
+ * Usage (x402):
+ * ```ts
+ * import { createX402Client } from '@relai-fi/x402'
+ * const client = createX402Client({ ..., bridge: { enabled: true } })
+ * ```
+ */
+interface BridgeInfo {
+    settleEndpoint: string;
+    supportedSourceChains: string[];
+    supportedSourceAssets: string[];
+    payTo: Record<string, string>;
+    feePayerSvm: string | null;
+    feeBps: number;
+    paymentFacilitator: string;
+}
+interface BridgeSettleRequest {
+    /** x402 mode: base64-encoded payment header */
+    sourcePayment?: string;
+    /** MPP mode: source tx hash */
+    sourceTxHash?: string;
+    /** MPP mode: wallet address that sent the source tx */
+    senderAddress?: string;
+    /** MPP mode: signature of (sourceTxHash + JSON(targetAccept)) */
+    senderSignature?: string;
+    /** CAIP-2 source chain identifier */
+    sourceChain: string;
+    targetAccept: {
+        scheme: 'exact';
+        network: string;
+        asset: string;
+        payTo: string;
+        amount: string;
+    };
+    /** x402 payment requirements (full 402 body) — needed by settle for x402 flow */
+    requirements?: any;
+    resource?: string;
+    paymentFacilitator?: string | null;
+}
+interface BridgeSettleResponse {
+    success?: boolean;
+    targetTxId?: string;
+    sourceTxId?: string;
+    /** x402 payment header (returned by x402-flavored settle) */
+    xPayment?: string;
+}
+/**
+ * Fetch bridge info from the RelAI API (cached per base URL for 5 minutes).
+ */
+declare function getBridgeInfo(baseUrl?: string): Promise<BridgeInfo>;
+/**
+ * Call the bridge settle endpoint.
+ */
+declare function settleBridge(settleEndpoint: string, body: BridgeSettleRequest): Promise<BridgeSettleResponse>;
+/**
+ * Select a source chain from supported chains that matches the available wallet.
+ */
+declare function selectSourceChain(supportedChains: string[], hasEvmWallet: boolean, hasSolanaWallet: boolean, preferredSourceChainId?: number): {
+    type: 'evm' | 'solana';
+    chain: string;
+} | null;
+/**
+ * Compute source amount including bridge fee.
+ */
+declare function computeSourceAmount(targetAmount: bigint, feeBps: number): bigint;
+declare const DEFAULT_EVM_RPC: Record<string, string>;
+
+export { type BridgeInfo, type BridgeSettleRequest, type BridgeSettleResponse, DEFAULT_EVM_RPC, computeSourceAmount, getBridgeInfo, selectSourceChain, settleBridge };

package/dist/bridge.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Core bridge utilities — shared between x402 and MPP clients.
+ *
+ * Auto-discovers bridge info from the RelAI API and provides helpers
+ * for executing cross-chain payments transparently.
+ *
+ * Usage (MPP):
+ * ```ts
+ * import { evmChargeWithBridge } from '@relai-fi/x402/mpp/with-bridge'
+ * ```
+ *
+ * Usage (x402):
+ * ```ts
+ * import { createX402Client } from '@relai-fi/x402'
+ * const client = createX402Client({ ..., bridge: { enabled: true } })
+ * ```
+ */
+interface BridgeInfo {
+    settleEndpoint: string;
+    supportedSourceChains: string[];
+    supportedSourceAssets: string[];
+    payTo: Record<string, string>;
+    feePayerSvm: string | null;
+    feeBps: number;
+    paymentFacilitator: string;
+}
+interface BridgeSettleRequest {
+    /** x402 mode: base64-encoded payment header */
+    sourcePayment?: string;
+    /** MPP mode: source tx hash */
+    sourceTxHash?: string;
+    /** MPP mode: wallet address that sent the source tx */
+    senderAddress?: string;
+    /** MPP mode: signature of (sourceTxHash + JSON(targetAccept)) */
+    senderSignature?: string;
+    /** CAIP-2 source chain identifier */
+    sourceChain: string;
+    targetAccept: {
+        scheme: 'exact';
+        network: string;
+        asset: string;
+        payTo: string;
+        amount: string;
+    };
+    /** x402 payment requirements (full 402 body) — needed by settle for x402 flow */
+    requirements?: any;
+    resource?: string;
+    paymentFacilitator?: string | null;
+}
+interface BridgeSettleResponse {
+    success?: boolean;
+    targetTxId?: string;
+    sourceTxId?: string;
+    /** x402 payment header (returned by x402-flavored settle) */
+    xPayment?: string;
+}
+/**
+ * Fetch bridge info from the RelAI API (cached per base URL for 5 minutes).
+ */
+declare function getBridgeInfo(baseUrl?: string): Promise<BridgeInfo>;
+/**
+ * Call the bridge settle endpoint.
+ */
+declare function settleBridge(settleEndpoint: string, body: BridgeSettleRequest): Promise<BridgeSettleResponse>;
+/**
+ * Select a source chain from supported chains that matches the available wallet.
+ */
+declare function selectSourceChain(supportedChains: string[], hasEvmWallet: boolean, hasSolanaWallet: boolean, preferredSourceChainId?: number): {
+    type: 'evm' | 'solana';
+    chain: string;
+} | null;
+/**
+ * Compute source amount including bridge fee.
+ */
+declare function computeSourceAmount(targetAmount: bigint, feeBps: number): bigint;
+declare const DEFAULT_EVM_RPC: Record<string, string>;
+
+export { type BridgeInfo, type BridgeSettleRequest, type BridgeSettleResponse, DEFAULT_EVM_RPC, computeSourceAmount, getBridgeInfo, selectSourceChain, settleBridge };

package/dist/bridge.js

@@ -0,0 +1,80 @@
+// src/bridge.ts
+var RELAI_API_BASE = "https://api.relai.fi";
+var _cacheMap = /* @__PURE__ */ new Map();
+var CACHE_TTL = 5 * 60 * 1e3;
+async function getBridgeInfo(baseUrl = RELAI_API_BASE) {
+  const key = baseUrl.replace(/\/$/, "");
+  const now = Date.now();
+  const cached = _cacheMap.get(key);
+  if (cached && now - cached.time < CACHE_TTL) return cached.info;
+  const url = `${key}/bridge/info`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    if (cached) return cached.info;
+    throw new Error(`[relai:bridge] Failed to fetch ${url}: ${res.status}`);
+  }
+  const data = await res.json();
+  const info = {
+    settleEndpoint: data.settleEndpoint,
+    supportedSourceChains: data.supportedSourceChains || [],
+    supportedSourceAssets: data.supportedSourceAssets || [],
+    payTo: data.payTo || {},
+    feePayerSvm: data.feePayerSvm ?? null,
+    feeBps: data.feeBps ?? 100,
+    paymentFacilitator: data.paymentFacilitator || "https://facilitator.x402.fi"
+  };
+  _cacheMap.set(key, { info, time: now });
+  return info;
+}
+async function settleBridge(settleEndpoint, body) {
+  const res = await fetch(settleEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(`[relai:bridge] settle failed: ${err.error || res.status}${err.details ? " \u2014 " + err.details : ""}`);
+  }
+  return res.json();
+}
+function selectSourceChain(supportedChains, hasEvmWallet, hasSolanaWallet, preferredSourceChainId) {
+  if (preferredSourceChainId && hasEvmWallet) {
+    const preferred = `eip155:${preferredSourceChainId}`;
+    if (supportedChains.includes(preferred)) {
+      return { type: "evm", chain: preferred };
+    }
+  }
+  if (hasSolanaWallet) {
+    const sol = supportedChains.find((c) => c.startsWith("solana:"));
+    if (sol) return { type: "solana", chain: sol };
+  }
+  if (hasEvmWallet) {
+    for (const chain of supportedChains) {
+      if (chain.startsWith("eip155:")) {
+        return { type: "evm", chain };
+      }
+    }
+  }
+  return null;
+}
+function computeSourceAmount(targetAmount, feeBps) {
+  const fee = targetAmount * BigInt(feeBps) / 10000n;
+  return targetAmount + fee;
+}
+var DEFAULT_EVM_RPC = {
+  "eip155:8453": "https://mainnet.base.org",
+  "eip155:137": "https://polygon-rpc.com",
+  "eip155:1": "https://eth.llamarpc.com",
+  "eip155:42161": "https://arb1.arbitrum.io/rpc",
+  "eip155:43114": "https://api.avax.network/ext/bc/C/rpc",
+  "eip155:1187947933": "https://skale-base.skalenodes.com/v1/base"
+};
+export {
+  DEFAULT_EVM_RPC,
+  computeSourceAmount,
+  getBridgeInfo,
+  selectSourceChain,
+  settleBridge
+};
+//# sourceMappingURL=bridge.js.map

package/dist/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bridge.ts"],"sourcesContent":["/**\n * Core bridge utilities — shared between x402 and MPP clients.\n *\n * Auto-discovers bridge info from the RelAI API and provides helpers\n * for executing cross-chain payments transparently.\n *\n * Usage (MPP):\n * ```ts\n * import { evmChargeWithBridge } from '@relai-fi/x402/mpp/with-bridge'\n * ```\n *\n * Usage (x402):\n * ```ts\n * import { createX402Client } from '@relai-fi/x402'\n * const client = createX402Client({ ..., bridge: { enabled: true } })\n * ```\n */\n\nconst RELAI_API_BASE = 'https://api.relai.fi'\n\nexport interface BridgeInfo {\n  settleEndpoint: string\n  supportedSourceChains: string[]\n  supportedSourceAssets: string[]\n  payTo: Record<string, string>\n  feePayerSvm: string | null\n  feeBps: number\n  paymentFacilitator: string\n}\n\nexport interface BridgeSettleRequest {\n  /** x402 mode: base64-encoded payment header */\n  sourcePayment?: string\n  /** MPP mode: source tx hash */\n  sourceTxHash?: string\n  /** MPP mode: wallet address that sent the source tx */\n  senderAddress?: string\n  /** MPP mode: signature of (sourceTxHash + JSON(targetAccept)) */\n  senderSignature?: string\n  /** CAIP-2 source chain identifier */\n  sourceChain: string\n  targetAccept: {\n    scheme: 'exact'\n    network: string\n    asset: string\n    payTo: string\n    amount: string\n  }\n  /** x402 payment requirements (full 402 body) — needed by settle for x402 flow */\n  requirements?: any\n  resource?: string\n  paymentFacilitator?: string | null\n}\n\nexport interface BridgeSettleResponse {\n  success?: boolean\n  targetTxId?: string\n  sourceTxId?: string\n  /** x402 payment header (returned by x402-flavored settle) */\n  xPayment?: string\n}\n\n// ── Cache (keyed by base URL) ──────────────────────────────────────────\n\nconst _cacheMap = new Map<string, { info: BridgeInfo; time: number }>()\nconst CACHE_TTL = 5 * 60 * 1000 // 5 minutes\n\n/**\n * Fetch bridge info from the RelAI API (cached per base URL for 5 minutes).\n */\nexport async function getBridgeInfo(baseUrl = RELAI_API_BASE): Promise<BridgeInfo> {\n  const key = baseUrl.replace(/\\/$/, '')\n  const now = Date.now()\n  const cached = _cacheMap.get(key)\n  if (cached && now - cached.time < CACHE_TTL) return cached.info\n\n  const url = `${key}/bridge/info`\n  const res = await fetch(url)\n  if (!res.ok) {\n    if (cached) return cached.info // stale cache better than failure\n    throw new Error(`[relai:bridge] Failed to fetch ${url}: ${res.status}`)\n  }\n\n  const data = (await res.json()) as any\n  const info: BridgeInfo = {\n    settleEndpoint: data.settleEndpoint,\n    supportedSourceChains: data.supportedSourceChains || [],\n    supportedSourceAssets: data.supportedSourceAssets || [],\n    payTo: data.payTo || {},\n    feePayerSvm: data.feePayerSvm ?? null,\n    feeBps: data.feeBps ?? 100,\n    paymentFacilitator: data.paymentFacilitator || 'https://facilitator.x402.fi',\n  }\n  _cacheMap.set(key, { info, time: now })\n  return info\n}\n\n/**\n * Call the bridge settle endpoint.\n */\nexport async function settleBridge(\n  settleEndpoint: string,\n  body: BridgeSettleRequest,\n): Promise<BridgeSettleResponse> {\n  const res = await fetch(settleEndpoint, {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/json' },\n    body: JSON.stringify(body),\n  })\n\n  if (!res.ok) {\n    const err = (await res.json().catch(() => ({}))) as any\n    throw new Error(`[relai:bridge] settle failed: ${err.error || res.status}${err.details ? ' — ' + err.details : ''}`)\n  }\n\n  return res.json() as Promise<BridgeSettleResponse>\n}\n\n/**\n * Select a source chain from supported chains that matches the available wallet.\n */\nexport function selectSourceChain(\n  supportedChains: string[],\n  hasEvmWallet: boolean,\n  hasSolanaWallet: boolean,\n  preferredSourceChainId?: number,\n): { type: 'evm' | 'solana'; chain: string } | null {\n  // If a specific source chain is preferred, try it first\n  if (preferredSourceChainId && hasEvmWallet) {\n    const preferred = `eip155:${preferredSourceChainId}`\n    if (supportedChains.includes(preferred)) {\n      return { type: 'evm', chain: preferred }\n    }\n  }\n\n  // Solana first (lower fees)\n  if (hasSolanaWallet) {\n    const sol = supportedChains.find((c) => c.startsWith('solana:'))\n    if (sol) return { type: 'solana', chain: sol }\n  }\n\n  // Then any EVM chain\n  if (hasEvmWallet) {\n    for (const chain of supportedChains) {\n      if (chain.startsWith('eip155:')) {\n        return { type: 'evm', chain }\n      }\n    }\n  }\n\n  return null\n}\n\n/**\n * Compute source amount including bridge fee.\n */\nexport function computeSourceAmount(targetAmount: bigint, feeBps: number): bigint {\n  const fee = (targetAmount * BigInt(feeBps)) / 10000n\n  return targetAmount + fee\n}\n\n// Known EVM RPC URLs (fallback)\nexport const DEFAULT_EVM_RPC: Record<string, string> = {\n  'eip155:8453': 'https://mainnet.base.org',\n  'eip155:137': 'https://polygon-rpc.com',\n  'eip155:1': 'https://eth.llamarpc.com',\n  'eip155:42161': 'https://arb1.arbitrum.io/rpc',\n  'eip155:43114': 'https://api.avax.network/ext/bc/C/rpc',\n  'eip155:1187947933': 'https://skale-base.skalenodes.com/v1/base',\n}\n"],"mappings":";AAkBA,IAAM,iBAAiB;AA8CvB,IAAM,YAAY,oBAAI,IAAgD;AACtE,IAAM,YAAY,IAAI,KAAK;AAK3B,eAAsB,cAAc,UAAU,gBAAqC;AACjF,QAAM,MAAM,QAAQ,QAAQ,OAAO,EAAE;AACrC,QAAM,MAAM,KAAK,IAAI;AACrB,QAAM,SAAS,UAAU,IAAI,GAAG;AAChC,MAAI,UAAU,MAAM,OAAO,OAAO,UAAW,QAAO,OAAO;AAE3D,QAAM,MAAM,GAAG,GAAG;AAClB,QAAM,MAAM,MAAM,MAAM,GAAG;AAC3B,MAAI,CAAC,IAAI,IAAI;AACX,QAAI,OAAQ,QAAO,OAAO;AAC1B,UAAM,IAAI,MAAM,kCAAkC,GAAG,KAAK,IAAI,MAAM,EAAE;AAAA,EACxE;AAEA,QAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,QAAM,OAAmB;AAAA,IACvB,gBAAgB,KAAK;AAAA,IACrB,uBAAuB,KAAK,yBAAyB,CAAC;AAAA,IACtD,uBAAuB,KAAK,yBAAyB,CAAC;AAAA,IACtD,OAAO,KAAK,SAAS,CAAC;AAAA,IACtB,aAAa,KAAK,eAAe;AAAA,IACjC,QAAQ,KAAK,UAAU;AAAA,IACvB,oBAAoB,KAAK,sBAAsB;AAAA,EACjD;AACA,YAAU,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,CAAC;AACtC,SAAO;AACT;AAKA,eAAsB,aACpB,gBACA,MAC+B;AAC/B,QAAM,MAAM,MAAM,MAAM,gBAAgB;AAAA,IACtC,QAAQ;AAAA,IACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,IAC9C,MAAM,KAAK,UAAU,IAAI;AAAA,EAC3B,CAAC;AAED,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,MAAO,MAAM,IAAI,KAAK,EAAE,MAAM,OAAO,CAAC,EAAE;AAC9C,UAAM,IAAI,MAAM,iCAAiC,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,UAAU,aAAQ,IAAI,UAAU,EAAE,EAAE;AAAA,EACrH;AAEA,SAAO,IAAI,KAAK;AAClB;AAKO,SAAS,kBACd,iBACA,cACA,iBACA,wBACkD;AAElD,MAAI,0BAA0B,cAAc;AAC1C,UAAM,YAAY,UAAU,sBAAsB;AAClD,QAAI,gBAAgB,SAAS,SAAS,GAAG;AACvC,aAAO,EAAE,MAAM,OAAO,OAAO,UAAU;AAAA,IACzC;AAAA,EACF;AAGA,MAAI,iBAAiB;AACnB,UAAM,MAAM,gBAAgB,KAAK,CAAC,MAAM,EAAE,WAAW,SAAS,CAAC;AAC/D,QAAI,IAAK,QAAO,EAAE,MAAM,UAAU,OAAO,IAAI;AAAA,EAC/C;AAGA,MAAI,cAAc;AAChB,eAAW,SAAS,iBAAiB;AACnC,UAAI,MAAM,WAAW,SAAS,GAAG;AAC/B,eAAO,EAAE,MAAM,OAAO,MAAM;AAAA,MAC9B;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAKO,SAAS,oBAAoB,cAAsB,QAAwB;AAChF,QAAM,MAAO,eAAe,OAAO,MAAM,IAAK;AAC9C,SAAO,eAAe;AACxB;AAGO,IAAM,kBAA0C;AAAA,EACrD,eAAe;AAAA,EACf,cAAc;AAAA,EACd,YAAY;AAAA,EACZ,gBAAgB;AAAA,EAChB,gBAAgB;AAAA,EAChB,qBAAqB;AACvB;","names":[]}

package/dist/client.cjs

@@ -240,6 +240,71 @@ function normalizeNetwork(network) {
   return null;
 }
 
+// src/bridge.ts
+var RELAI_API_BASE = "https://api.relai.fi";
+var _cacheMap = /* @__PURE__ */ new Map();
+var CACHE_TTL = 5 * 60 * 1e3;
+async function getBridgeInfo(baseUrl = RELAI_API_BASE) {
+  const key = baseUrl.replace(/\/$/, "");
+  const now = Date.now();
+  const cached = _cacheMap.get(key);
+  if (cached && now - cached.time < CACHE_TTL) return cached.info;
+  const url = `${key}/bridge/info`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    if (cached) return cached.info;
+    throw new Error(`[relai:bridge] Failed to fetch ${url}: ${res.status}`);
+  }
+  const data = await res.json();
+  const info = {
+    settleEndpoint: data.settleEndpoint,
+    supportedSourceChains: data.supportedSourceChains || [],
+    supportedSourceAssets: data.supportedSourceAssets || [],
+    payTo: data.payTo || {},
+    feePayerSvm: data.feePayerSvm ?? null,
+    feeBps: data.feeBps ?? 100,
+    paymentFacilitator: data.paymentFacilitator || "https://facilitator.x402.fi"
+  };
+  _cacheMap.set(key, { info, time: now });
+  return info;
+}
+async function settleBridge(settleEndpoint, body) {
+  const res = await fetch(settleEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(`[relai:bridge] settle failed: ${err.error || res.status}${err.details ? " \u2014 " + err.details : ""}`);
+  }
+  return res.json();
+}
+function selectSourceChain(supportedChains, hasEvmWallet, hasSolanaWallet, preferredSourceChainId) {
+  if (preferredSourceChainId && hasEvmWallet) {
+    const preferred = `eip155:${preferredSourceChainId}`;
+    if (supportedChains.includes(preferred)) {
+      return { type: "evm", chain: preferred };
+    }
+  }
+  if (hasSolanaWallet) {
+    const sol = supportedChains.find((c) => c.startsWith("solana:"));
+    if (sol) return { type: "solana", chain: sol };
+  }
+  if (hasEvmWallet) {
+    for (const chain of supportedChains) {
+      if (chain.startsWith("eip155:")) {
+        return { type: "evm", chain };
+      }
+    }
+  }
+  return null;
+}
+function computeSourceAmount(targetAmount, feeBps) {
+  const fee = targetAmount * BigInt(feeBps) / 10000n;
+  return targetAmount + fee;
+}
+
 // src/client.ts
 var PERMIT_NETWORKS = /* @__PURE__ */ new Set([]);
 var DEFAULT_EVM_RPC_URLS = {
@@ -266,7 +331,8 @@ function createX402Client(config) {
     integritas,
     verbose = false,
     defaultHeaders = {},
-    mpp
+    mpp,
+    bridge: bridgeConfig
   } = config;
   const relayWsEnabled = relayWs?.enabled === true;
   const relayWsPreflightTimeoutMs = relayWs?.preflightTimeoutMs ?? 5e3;
@@ -1381,6 +1447,70 @@ function createX402Client(config) {
           headers: { ...requestHeaders, "X-PAYMENT": paymentHeader }
         });
       }
+      if (bridgeConfig?.enabled) {
+        log("No direct wallet match \u2014 attempting auto-bridge via RelAI API");
+        try {
+          const info = await getBridgeInfo(bridgeConfig.baseUrl);
+          const targetAccept = accepts[0];
+          const hasEvm = !!effectiveWallets.evm;
+          const hasSol = !!hasSolanaWallet;
+          const source = selectSourceChain(info.supportedSourceChains, hasEvm, hasSol);
+          if (source) {
+            const bridgePayTo = info.payTo[source.chain];
+            if (bridgePayTo) {
+              const targetAmount = targetAccept.amount || targetAccept.maxAmountRequired;
+              const sourceAmount = computeSourceAmount(BigInt(targetAmount), info.feeBps).toString();
+              const sourceChainIdx = info.supportedSourceChains.indexOf(source.chain);
+              const sourceAsset = sourceChainIdx >= 0 && info.supportedSourceAssets[sourceChainIdx] || (source.type === "evm" ? info.supportedSourceAssets.find((a) => a.startsWith("0x")) || targetAccept.asset : info.supportedSourceAssets.find((a) => !a.startsWith("0x")) || "");
+              let sourcePaymentHeader;
+              const sourceAccept = {
+                scheme: "exact",
+                network: source.chain,
+                asset: sourceAsset,
+                payTo: bridgePayTo,
+                amount: sourceAmount,
+                extra: {
+                  ...targetAccept.extra || {},
+                  ...source.type === "solana" && info.feePayerSvm ? { feePayer: info.feePayerSvm } : {}
+                }
+              };
+              if (source.type === "solana" && hasSolanaWallet) {
+                sourcePaymentHeader = await buildSolanaPayment(sourceAccept, requirements, url);
+              } else if (source.type === "evm") {
+                const evmNetwork = normalizeNetwork(source.chain);
+                const usePermit = evmNetwork && PERMIT_NETWORKS.has(evmNetwork);
+                sourcePaymentHeader = usePermit ? await buildEvmPermitPayment(sourceAccept, requirements, url) : await buildEvmPayment(sourceAccept, requirements, url);
+              } else {
+                throw new Error(`[relai-x402] No wallet for source chain type: ${source.type}`);
+              }
+              const settleData = await settleBridge(info.settleEndpoint, {
+                sourcePayment: sourcePaymentHeader,
+                sourceChain: source.chain,
+                targetAccept: {
+                  scheme: "exact",
+                  network: targetAccept.network,
+                  asset: targetAccept.asset,
+                  payTo: targetAccept.payTo,
+                  amount: targetAmount
+                },
+                requirements,
+                resource: url,
+                paymentFacilitator: info.paymentFacilitator
+              });
+              if (settleData.xPayment) {
+                log(`Auto-bridge settled: target=${settleData.targetTxId}`);
+                return fetch(input, {
+                  ...requestInitWithHeaders,
+                  headers: { ...requestHeaders, "X-PAYMENT": settleData.xPayment }
+                });
+              }
+              throw new Error("[relai-x402] Bridge settle did not return xPayment");
+            }
+          }
+        } catch (bridgeErr) {
+          log(`Auto-bridge failed: ${bridgeErr instanceof Error ? bridgeErr.message : bridgeErr}`);
+        }
+      }
       throw new Error(buildNoWalletError(accepts, false));
     }
     const { accept, chain } = selected;