@armory-sh/base 0.2.29 → 0.2.30

package/README.md

@@ -14,56 +14,343 @@ bun add @armory-sh/base
 
 Armory enables HTTP API payments via EIP-3009 `transferWithAuthorization`. Let your users pay with USDC directly from their wallet—no credit cards, no middlemen, no gas for payers.
 
-## Key Exports
+## API Reference
+
+### Protocol Types
 
 ```typescript
-import {
-  // Types
-  type PaymentPayload,
-  type PaymentPayloadV2,
-  type PaymentRequirementsV2,
-  type SettlementResponseV2,
-  type CustomToken,
-  type NetworkConfig,
+import type {
+  // V2 Protocol (x402 v2 / CAIP)
+  PaymentPayloadV2,
+  PaymentRequirementsV2,
+  PaymentRequiredV2,
+  SettlementResponseV2,
+  PayToV2,
+  EIP3009Authorization,
+  Extensions,
+  ResourceInfo,
+  Signature,
+  Address,
+  CAIPAssetId,
+
+  // Unified Types
+  PaymentPayload,
+  PaymentRequirements,
+  SettlementResponse,
+} from '@armory-sh/base';
+```
 
-  // Encoding/Decoding
+### Encoding / Decoding
+
+```typescript
+import {
+  // V2 Encoding
   encodePaymentV2,
   decodePaymentV2,
   encodeSettlementV2,
   decodeSettlementV2,
+
+  // x402 Cross-Version Encoding
+  encodePayment,
+  decodePayment,
+  encodeSettlementResponse,
+  decodeSettlementResponse,
+  encodeX402Response,
+  decodeX402Response,
+
+  // Base64 Utilities
   safeBase64Encode,
   safeBase64Decode,
+  toBase64Url,
+  normalizeBase64Url,
+  encodeUtf8ToBase64,
+  decodeBase64ToUtf8,
+
+  // Header Creation
+  createPaymentRequiredHeaders,
+  createSettlementHeaders,
+  extractPaymentFromHeaders,
+
+  // Type Guards
+  isPaymentV2,
+  isSettlementV2,
+  isX402V2Payload,
+  isX402V2PaymentRequired,
+  isX402V2Settlement,
+  isPaymentPayload,
+  detectPaymentVersion,
+} from '@armory-sh/base';
+```
+
+### EIP-712 (EIP-3009 Signing)
 
-  // EIP-712
+```typescript
+import {
+  // Domain & Typed Data
   createEIP712Domain,
+  EIP712_TYPES,
+  USDC_DOMAIN,
+
+  // Transfer With Authorization
   createTransferWithAuthorization,
   validateTransferWithAuthorization,
-  EIP712_TYPES,
 
-  // Networks
+  // Types
+  type EIP712Domain,
+  type TransferWithAuthorization,
+  type TypedDataDomain,
+} from '@armory-sh/base';
+```
+
+### Networks
+
+```typescript
+import {
+  // Network Registry
   NETWORKS,
   getNetworkConfig,
   getNetworkByChainId,
   getMainnets,
   getTestnets,
 
-  // Token Registry
+  // Network Resolution
+  resolveNetwork,
+  normalizeNetworkName,
+  getAvailableNetworks,
+
+  // CAIP-2 Conversion
+  networkToCaip2,
+  caip2ToNetwork,
+
+  // Types
+  type NetworkConfig,
+  type ResolvedNetwork,
+} from '@armory-sh/base';
+```
+
+**Supported Networks**
+
+| Key | Chain ID | Name |
+|-----|----------|------|
+| `ethereum` | 1 | Ethereum Mainnet |
+| `base` | 8453 | Base Mainnet |
+| `base-sepolia` | 84532 | Base Sepolia |
+| `skale-base` | 1187947933 | SKALE Base |
+| `skale-base-sepolia` | 324705682 | SKALE Base Sepolia |
+| `ethereum-sepolia` | 11155111 | Ethereum Sepolia |
+
+### Tokens
+
+```typescript
+import {
+  // Pre-configured Tokens
   TOKENS,
+  USDC_BASE,
+  USDC_BASE_SEPOLIA,
+  EURC_BASE,
+  getUSDCTokens,
+  getEURCTokens,
+  getAllTokens,
+  getTokensByChain,
+  getTokensBySymbol,
+
+  // Custom Token Registry
   registerToken,
   getCustomToken,
   getAllCustomTokens,
   unregisterToken,
   isCustomToken,
 
-  // Utilities
+  // Token Resolution
+  resolveToken,
+  getAvailableTokens,
+  addressToAssetId,
+  assetIdToAddress,
+
+  // Types
+  type CustomToken,
+  type ResolvedToken,
+} from '@armory-sh/base';
+```
+
+**Supported Tokens**
+
+USDC, EURC, USDT, WBTC, WETH, SKL across supported networks.
+
+### Protocol Utilities
+
+```typescript
+import {
+  // Nonce & Time
+  generateNonce,
   createNonce,
-  toAtomicUnits,
-  fromAtomicUnits,
+  getCurrentTimestamp,
+  calculateValidBefore,
+
+  // Parsing
+  parseJsonOrBase64,
+
+  // Headers
+  getPaymentHeaderName,
+  PAYMENT_REQUIRED_HEADER,
+  PAYMENT_SIGNATURE_HEADER,
+  PAYMENT_RESPONSE_HEADER,
+
+  // Version Detection
+  detectX402Version,
+  X402_VERSION,
+} from '@armory-sh/base';
+```
+
+### Payment Requirements (Middleware)
+
+```typescript
+import {
+  // Requirement Creation
+  createPaymentRequirements,
+
+  // Requirement Lookup
+  findRequirementByNetwork,
+  findRequirementByAccepted,
+
+  // Types
+  type PaymentConfig,
+  type ResolvedRequirementsConfig,
+} from '@armory-sh/base';
+```
+
+### Validation
+
+```typescript
+import {
+  // Network & Token Validation
   resolveNetwork,
   resolveToken,
+  validatePaymentConfig,
+  validateAcceptConfig,
+
+  // Facilitator Validation
+  resolveFacilitator,
+  checkFacilitatorSupport,
+
+  // Error Creation
+  createError,
+
+  // Type Guards
+  isValidationError,
+  isResolvedNetwork,
+  isResolvedToken,
+
+  // Available Options
+  getAvailableNetworks,
+  getAvailableTokens,
 } from '@armory-sh/base';
 ```
 
+### Utilities
+
+```typescript
+import {
+  // Unit Conversion
+  toAtomicUnits,
+  fromAtomicUnits,
+
+  // Address Utilities
+  normalizeAddress,
+  isValidAddress,
+  isAddress,
+
+  // Route Matching
+  matchRoute,
+  parseRoutePattern,
+  findMatchingRoute,
+  validateRouteConfig,
+
+  // Types
+  type RouteMatcher,
+  type RoutePattern,
+} from '@armory-sh/base';
+```
+
+### Client Hooks Runtime
+
+```typescript
+import {
+  // Hook Execution
+  runOnPaymentRequiredHooks,
+  runBeforeSignPaymentHooks,
+  runAfterPaymentResponseHooks,
+  selectRequirementWithHooks,
+
+  // Types
+  type ClientHook,
+  type OnPaymentRequiredHook,
+  type BeforePaymentHook,
+  type PaymentRequiredContext,
+  type PaymentPayloadContext,
+  type ClientHookErrorContext,
+} from '@armory-sh/base';
+```
+
+### ERC20 ABI
+
+```typescript
+import {
+  ERC20_ABI,
+
+  // Types
+  type ERC20Abi,
+  type TransferWithAuthorizationParams,
+  type BalanceOfParams,
+} from '@armory-sh/base';
+```
+
+### Payment Client (Facilitator)
+
+```typescript
+import {
+  // Payment Operations
+  verifyPayment,
+  settlePayment,
+
+  // Payload Extraction
+  decodePayloadHeader,
+  extractPayerAddress,
+
+  // Facilitator Discovery
+  getSupported,
+
+  // Types
+  type FacilitatorClientConfig,
+  type SupportedResponse,
+} from '@armory-sh/base';
+```
+
+### Error Classes
+
+```typescript
+import {
+  X402ClientError,
+  SigningError,
+  PaymentException,
+} from '@armory-sh/base';
+```
+
+### Headers Constants
+
+```typescript
+import {
+  PAYMENT_REQUIRED_HEADER,
+  PAYMENT_SIGNATURE_HEADER,
+  PAYMENT_RESPONSE_HEADER,
+  V2_HEADERS,
+} from '@armory-sh/base';
+```
+
+---
+
+## Quick Start
+
 ## Quick Start
 
 ### Pre-configured Tokens
@@ -155,17 +442,6 @@ const decoded = decodePaymentV2(encoded)
 - **Custom Tokens**: Register your own tokens
 - **Encoding**: Base64URL encoding for HTTP headers
 
-## Supported Networks
-
-| Network | Chain ID |
-|---------|----------|
-| Ethereum | 1 |
-| Base | 8453 |
-| Base Sepolia | 84532 |
-| SKALE Base | 1187947933 |
-| SKALE Base Sepolia | 324705682 |
-| Ethereum Sepolia | 11155111 |
-
 ## License
 
 MIT © [Sawyer Cutler](https://github.com/TheGreatAxios/armory)

package/dist/facilitator-capabilities.d.ts

@@ -0,0 +1,9 @@
+import type { PaymentRequirementsV2 } from "./types/v2";
+import type { FacilitatorRoutingConfig } from "./payment-requirements";
+export declare function filterExtensionsForFacilitator(extensions: Record<string, unknown> | undefined, facilitatorUrl: string | undefined, network: string, ttlMs?: number): Promise<Record<string, unknown>>;
+export declare function filterExtensionsForFacilitators(extensions: Record<string, unknown> | undefined, facilitators: Array<{
+    url?: string;
+    network: string;
+}>, ttlMs?: number): Promise<Record<string, unknown>>;
+export declare function filterExtensionsForRequirements(extensions: Record<string, unknown> | undefined, requirements: PaymentRequirementsV2[], config: FacilitatorRoutingConfig, ttlMs?: number): Promise<Record<string, unknown>>;
+export declare function clearFacilitatorCapabilityCache(): void;

package/dist/index.d.ts

@@ -10,8 +10,9 @@ export { createPaymentRequiredHeaders, createSettlementHeaders, decodePayment, d
 export { PaymentException, SigningError, X402ClientError, } from "./errors";
 export type { FacilitatorClientConfig, SupportedKind, SupportedResponse, } from "./payment-client";
 export { decodePayloadHeader, extractPayerAddress, getSupported, settlePayment, verifyPayment, } from "./payment-client";
+export { clearFacilitatorCapabilityCache, filterExtensionsForFacilitator, filterExtensionsForFacilitators, filterExtensionsForRequirements, } from "./facilitator-capabilities";
 export type { PaymentConfig, ResolvedRequirementsConfig, } from "./payment-requirements";
-export { createPaymentRequirements, findRequirementByAccepted, findRequirementByNetwork, } from "./payment-requirements";
+export { createPaymentRequirements, findRequirementByAccepted, findRequirementByNetwork, resolveFacilitatorUrlFromRequirement, } from "./payment-requirements";
 export { calculateValidBefore, detectX402Version, generateNonce, getPaymentHeaderName, parseJsonOrBase64, } from "./protocol";
 export type { AcceptPaymentOptions, ArmoryPaymentResult, FacilitatorConfig, FacilitatorSettleResult, FacilitatorVerifyResult, NetworkId, PaymentError, PaymentErrorCode, PaymentResult, PayToAddress, PricingConfig, ResolvedFacilitator, ResolvedNetwork, ResolvedPaymentConfig, ResolvedToken, SettlementMode, TokenId, ValidationError, } from "./types/api";
 export type { BeforePaymentHook, ClientHook, ClientHookErrorContext, ExtensionHook, HookConfig, HookRegistry, HookResult, OnPaymentRequiredHook, PaymentPayloadContext, PaymentRequiredContext, } from "./types/hooks";

package/dist/index.js

@@ -1434,6 +1434,37 @@ function resolveFacilitatorUrl(config, network, token) {
   }
   return config.facilitatorUrl;
 }
+function resolveFacilitatorUrlFromRequirement(config, requirement) {
+  const chainId = parseInt(requirement.network.split(":")[1] || "0", 10);
+  const assetAddress = requirement.asset.toLowerCase();
+  if (config.facilitatorUrlByToken) {
+    for (const [chainKey, tokenMap] of Object.entries(
+      config.facilitatorUrlByToken
+    )) {
+      const resolvedChain = resolveNetwork(chainKey);
+      if (isValidationError2(resolvedChain) || resolvedChain.config.chainId !== chainId) {
+        continue;
+      }
+      for (const [tokenKey2, url] of Object.entries(tokenMap)) {
+        const resolvedToken = resolveToken(tokenKey2, resolvedChain);
+        if (!isValidationError2(resolvedToken) && resolvedToken.config.contractAddress.toLowerCase() === assetAddress) {
+          return url;
+        }
+      }
+    }
+  }
+  if (config.facilitatorUrlByChain) {
+    for (const [chainKey, url] of Object.entries(
+      config.facilitatorUrlByChain
+    )) {
+      const resolvedChain = resolveNetwork(chainKey);
+      if (!isValidationError2(resolvedChain) && resolvedChain.config.chainId === chainId) {
+        return url;
+      }
+    }
+  }
+  return config.facilitatorUrl;
+}
 function resolveNetworks(chainInputs) {
   const resolvedNetworks = [];
   const errors = [];
@@ -1540,6 +1571,91 @@ function findRequirementByAccepted(requirements, accepted) {
   );
 }
 
+// src/facilitator-capabilities.ts
+var DEFAULT_CAPABILITY_TTL_MS = 5 * 60 * 1e3;
+var capabilityCache = /* @__PURE__ */ new Map();
+var normalizeNetwork = (network) => {
+  return network.toLowerCase();
+};
+async function getExtensionKeysForFacilitator(url, network, ttlMs) {
+  const cacheKey = `${url}|${normalizeNetwork(network)}`;
+  const now = Date.now();
+  const cached = capabilityCache.get(cacheKey);
+  if (cached && cached.expiresAt > now) {
+    return cached.keys;
+  }
+  try {
+    const supported = await getSupported({ url });
+    const extensionKeys = /* @__PURE__ */ new Set();
+    for (const kind of supported.kinds) {
+      if (normalizeNetwork(kind.network) !== normalizeNetwork(network)) {
+        continue;
+      }
+      if (kind.extra && typeof kind.extra === "object") {
+        for (const key of Object.keys(kind.extra)) {
+          extensionKeys.add(key);
+        }
+      }
+    }
+    capabilityCache.set(cacheKey, {
+      expiresAt: now + ttlMs,
+      keys: extensionKeys
+    });
+    return extensionKeys;
+  } catch {
+    capabilityCache.set(cacheKey, {
+      expiresAt: now + ttlMs,
+      keys: /* @__PURE__ */ new Set()
+    });
+    return /* @__PURE__ */ new Set();
+  }
+}
+async function filterExtensionsForFacilitator(extensions, facilitatorUrl, network, ttlMs = DEFAULT_CAPABILITY_TTL_MS) {
+  if (!extensions || !facilitatorUrl) {
+    return extensions ?? {};
+  }
+  const supportedKeys = await getExtensionKeysForFacilitator(
+    facilitatorUrl,
+    network,
+    ttlMs
+  );
+  const filtered = {};
+  for (const [key, value] of Object.entries(extensions)) {
+    if (supportedKeys.has(key)) {
+      filtered[key] = value;
+    }
+  }
+  return filtered;
+}
+async function filterExtensionsForFacilitators(extensions, facilitators, ttlMs = DEFAULT_CAPABILITY_TTL_MS) {
+  if (!extensions) {
+    return {};
+  }
+  let filtered = { ...extensions };
+  for (const facilitator of facilitators) {
+    filtered = await filterExtensionsForFacilitator(
+      filtered,
+      facilitator.url,
+      facilitator.network,
+      ttlMs
+    );
+    if (Object.keys(filtered).length === 0) {
+      return {};
+    }
+  }
+  return filtered;
+}
+async function filterExtensionsForRequirements(extensions, requirements, config, ttlMs = DEFAULT_CAPABILITY_TTL_MS) {
+  const facilitators = requirements.map((requirement) => ({
+    url: resolveFacilitatorUrlFromRequirement(config, requirement),
+    network: requirement.network
+  }));
+  return filterExtensionsForFacilitators(extensions, facilitators, ttlMs);
+}
+function clearFacilitatorCapabilityCache() {
+  capabilityCache.clear();
+}
+
 // src/protocol.ts
 function parseJsonOrBase64(value) {
   try {
@@ -1753,4 +1869,4 @@ function validateRouteConfig(config) {
   return null;
 }
 
-export { EIP712_TYPES, ERC20_ABI, EURC_BASE, NETWORKS, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PAYMENT_SIGNATURE_HEADER, PaymentException, SCHEMES, SKL_SKALE_BASE, SKL_SKALE_BASE_SEPOLIA, SigningError, TOKENS, USDC_BASE, USDC_BASE_SEPOLIA, USDC_DOMAIN, USDC_SKALE_BASE, USDC_SKALE_BASE_SEPOLIA, USDT_SKALE_BASE, USDT_SKALE_BASE_SEPOLIA, V2_HEADERS, WBTC_SKALE_BASE, WBTC_SKALE_BASE_SEPOLIA, WETH_SKALE_BASE, WETH_SKALE_BASE_SEPOLIA, X402ClientError, X402_VERSION, addressToAssetId, assetIdToAddress, caip2ToNetwork, calculateValidBefore, checkFacilitatorSupport, combineSignature as combineSignatureV2, createEIP712Domain, createError, createNonce, createPaymentRequiredHeaders, createPaymentRequirements, createSettlementHeaders, createTransferWithAuthorization, decodeBase64ToUtf8, decodePayloadHeader, decodePayment, decodePaymentV2, decodeSettlementResponse, decodeSettlementV2, decodeX402Response, detectPaymentVersion, detectX402Version, encodePayment, encodePaymentV2, encodeSettlementResponse, encodeSettlementV2, encodeUtf8ToBase64, encodeX402Response, extractPayerAddress, extractPaymentFromHeaders, findMatchingRoute, findRequirementByAccepted, findRequirementByNetwork, fromAtomicUnits, generateNonce, getAllCustomTokens, getAllTokens, getAvailableNetworks, getAvailableTokens, getCurrentTimestamp, getCustomToken, getEURCTokens, getMainnets, getNetworkByChainId, getNetworkConfig, getPaymentHeaderName, getSKLTokens, getSupported, getTestnets, getToken, getTokensByChain, getTokensBySymbol, getTxHash, getUSDCTokens, getUSDTTokens, getWBTCTokens, getWETHTokens, isAddress2 as isAddress, isCAIP2ChainId, isCAIPAssetId, isCustomToken, isExactEvmPayload, isPaymentPayload, isPaymentPayloadV2, isPaymentRequiredV2, isPaymentV2, isResolvedNetwork, isResolvedToken, isSettlementSuccessful, isSettlementV2, isValidAddress, isValidationError, isX402V2Payload, isX402V2PaymentRequired, isX402V2Requirements, isX402V2Settlement, matchRoute, networkToCaip2, normalizeAddress, normalizeBase64Url, normalizeNetworkName, parseJsonOrBase64, parseRoutePattern, parseSignature as parseSignatureV2, registerToken, resolveFacilitator, resolveNetwork, resolveToken, runAfterPaymentResponseHooks, runBeforeSignPaymentHooks, runOnPaymentRequiredHooks, safeBase64Decode2 as safeBase64Decode, safeBase64Encode2 as safeBase64Encode, selectRequirementWithHooks, settlePayment, toAtomicUnits, toBase64Url, unregisterToken, validateAcceptConfig, validatePaymentConfig, validateRouteConfig, validateTransferWithAuthorization, verifyPayment };
+export { EIP712_TYPES, ERC20_ABI, EURC_BASE, NETWORKS, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PAYMENT_SIGNATURE_HEADER, PaymentException, SCHEMES, SKL_SKALE_BASE, SKL_SKALE_BASE_SEPOLIA, SigningError, TOKENS, USDC_BASE, USDC_BASE_SEPOLIA, USDC_DOMAIN, USDC_SKALE_BASE, USDC_SKALE_BASE_SEPOLIA, USDT_SKALE_BASE, USDT_SKALE_BASE_SEPOLIA, V2_HEADERS, WBTC_SKALE_BASE, WBTC_SKALE_BASE_SEPOLIA, WETH_SKALE_BASE, WETH_SKALE_BASE_SEPOLIA, X402ClientError, X402_VERSION, addressToAssetId, assetIdToAddress, caip2ToNetwork, calculateValidBefore, checkFacilitatorSupport, clearFacilitatorCapabilityCache, combineSignature as combineSignatureV2, createEIP712Domain, createError, createNonce, createPaymentRequiredHeaders, createPaymentRequirements, createSettlementHeaders, createTransferWithAuthorization, decodeBase64ToUtf8, decodePayloadHeader, decodePayment, decodePaymentV2, decodeSettlementResponse, decodeSettlementV2, decodeX402Response, detectPaymentVersion, detectX402Version, encodePayment, encodePaymentV2, encodeSettlementResponse, encodeSettlementV2, encodeUtf8ToBase64, encodeX402Response, extractPayerAddress, extractPaymentFromHeaders, filterExtensionsForFacilitator, filterExtensionsForFacilitators, filterExtensionsForRequirements, findMatchingRoute, findRequirementByAccepted, findRequirementByNetwork, fromAtomicUnits, generateNonce, getAllCustomTokens, getAllTokens, getAvailableNetworks, getAvailableTokens, getCurrentTimestamp, getCustomToken, getEURCTokens, getMainnets, getNetworkByChainId, getNetworkConfig, getPaymentHeaderName, getSKLTokens, getSupported, getTestnets, getToken, getTokensByChain, getTokensBySymbol, getTxHash, getUSDCTokens, getUSDTTokens, getWBTCTokens, getWETHTokens, isAddress2 as isAddress, isCAIP2ChainId, isCAIPAssetId, isCustomToken, isExactEvmPayload, isPaymentPayload, isPaymentPayloadV2, isPaymentRequiredV2, isPaymentV2, isResolvedNetwork, isResolvedToken, isSettlementSuccessful, isSettlementV2, isValidAddress, isValidationError, isX402V2Payload, isX402V2PaymentRequired, isX402V2Requirements, isX402V2Settlement, matchRoute, networkToCaip2, normalizeAddress, normalizeBase64Url, normalizeNetworkName, parseJsonOrBase64, parseRoutePattern, parseSignature as parseSignatureV2, registerToken, resolveFacilitator, resolveFacilitatorUrlFromRequirement, resolveNetwork, resolveToken, runAfterPaymentResponseHooks, runBeforeSignPaymentHooks, runOnPaymentRequiredHooks, safeBase64Decode2 as safeBase64Decode, safeBase64Encode2 as safeBase64Encode, selectRequirementWithHooks, settlePayment, toAtomicUnits, toBase64Url, unregisterToken, validateAcceptConfig, validatePaymentConfig, validateRouteConfig, validateTransferWithAuthorization, verifyPayment };

package/dist/payment-requirements.d.ts

@@ -18,6 +18,12 @@ export interface ResolvedRequirementsConfig {
     requirements: PaymentRequirementsV2[];
     error?: ValidationError;
 }
+export interface FacilitatorRoutingConfig {
+    facilitatorUrl?: string;
+    facilitatorUrlByChain?: Record<string, string>;
+    facilitatorUrlByToken?: Record<string, Record<string, string>>;
+}
+export declare function resolveFacilitatorUrlFromRequirement(config: FacilitatorRoutingConfig, requirement: Pick<PaymentRequirementsV2, "network" | "asset">): string | undefined;
 export declare function createPaymentRequirements(config: PaymentConfig): ResolvedRequirementsConfig;
 export declare function findRequirementByNetwork(requirements: PaymentRequirementsV2[], network: string): PaymentRequirementsV2 | undefined;
 export declare function findRequirementByAccepted(requirements: PaymentRequirementsV2[], accepted: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armory-sh/base",
-  "version": "0.2.29",
+  "version": "0.2.30",
   "license": "MIT",
   "author": "Sawyer Cutler <sawyer@dirtroad.dev>",
   "keywords": [

package/src/facilitator-capabilities.ts

@@ -0,0 +1,125 @@
+import { getSupported } from "./payment-client";
+import type { PaymentRequirementsV2 } from "./types/v2";
+import type { FacilitatorRoutingConfig } from "./payment-requirements";
+import { resolveFacilitatorUrlFromRequirement } from "./payment-requirements";
+
+const DEFAULT_CAPABILITY_TTL_MS = 5 * 60 * 1000;
+
+type CapabilityCacheEntry = {
+  expiresAt: number;
+  keys: Set<string>;
+};
+
+const capabilityCache = new Map<string, CapabilityCacheEntry>();
+
+const normalizeNetwork = (network: string): string => {
+  return network.toLowerCase();
+};
+
+async function getExtensionKeysForFacilitator(
+  url: string,
+  network: string,
+  ttlMs: number,
+): Promise<Set<string>> {
+  const cacheKey = `${url}|${normalizeNetwork(network)}`;
+  const now = Date.now();
+  const cached = capabilityCache.get(cacheKey);
+  if (cached && cached.expiresAt > now) {
+    return cached.keys;
+  }
+
+  try {
+    const supported = await getSupported({ url });
+    const extensionKeys = new Set<string>();
+    for (const kind of supported.kinds) {
+      if (normalizeNetwork(kind.network) !== normalizeNetwork(network)) {
+        continue;
+      }
+      if (kind.extra && typeof kind.extra === "object") {
+        for (const key of Object.keys(kind.extra)) {
+          extensionKeys.add(key);
+        }
+      }
+    }
+    capabilityCache.set(cacheKey, {
+      expiresAt: now + ttlMs,
+      keys: extensionKeys,
+    });
+    return extensionKeys;
+  } catch {
+    capabilityCache.set(cacheKey, {
+      expiresAt: now + ttlMs,
+      keys: new Set<string>(),
+    });
+    return new Set<string>();
+  }
+}
+
+export async function filterExtensionsForFacilitator(
+  extensions: Record<string, unknown> | undefined,
+  facilitatorUrl: string | undefined,
+  network: string,
+  ttlMs: number = DEFAULT_CAPABILITY_TTL_MS,
+): Promise<Record<string, unknown>> {
+  if (!extensions || !facilitatorUrl) {
+    return extensions ?? {};
+  }
+
+  const supportedKeys = await getExtensionKeysForFacilitator(
+    facilitatorUrl,
+    network,
+    ttlMs,
+  );
+
+  const filtered: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(extensions)) {
+    if (supportedKeys.has(key)) {
+      filtered[key] = value;
+    }
+  }
+
+  return filtered;
+}
+
+export async function filterExtensionsForFacilitators(
+  extensions: Record<string, unknown> | undefined,
+  facilitators: Array<{ url?: string; network: string }>,
+  ttlMs: number = DEFAULT_CAPABILITY_TTL_MS,
+): Promise<Record<string, unknown>> {
+  if (!extensions) {
+    return {};
+  }
+
+  let filtered = { ...extensions };
+  for (const facilitator of facilitators) {
+    filtered = await filterExtensionsForFacilitator(
+      filtered,
+      facilitator.url,
+      facilitator.network,
+      ttlMs,
+    );
+    if (Object.keys(filtered).length === 0) {
+      return {};
+    }
+  }
+
+  return filtered;
+}
+
+export async function filterExtensionsForRequirements(
+  extensions: Record<string, unknown> | undefined,
+  requirements: PaymentRequirementsV2[],
+  config: FacilitatorRoutingConfig,
+  ttlMs: number = DEFAULT_CAPABILITY_TTL_MS,
+): Promise<Record<string, unknown>> {
+  const facilitators = requirements.map((requirement) => ({
+    url: resolveFacilitatorUrlFromRequirement(config, requirement),
+    network: requirement.network,
+  }));
+
+  return filterExtensionsForFacilitators(extensions, facilitators, ttlMs);
+}
+
+export function clearFacilitatorCapabilityCache(): void {
+  capabilityCache.clear();
+}

package/src/index.ts

@@ -116,6 +116,12 @@ export {
   settlePayment,
   verifyPayment,
 } from "./payment-client";
+export {
+  clearFacilitatorCapabilityCache,
+  filterExtensionsForFacilitator,
+  filterExtensionsForFacilitators,
+  filterExtensionsForRequirements,
+} from "./facilitator-capabilities";
 export type {
   PaymentConfig,
   ResolvedRequirementsConfig,
@@ -124,6 +130,7 @@ export {
   createPaymentRequirements,
   findRequirementByAccepted,
   findRequirementByNetwork,
+  resolveFacilitatorUrlFromRequirement,
 } from "./payment-requirements";
 // ============================================
 // Protocol utilities (shared across all client packages)

package/src/payment-requirements.ts

@@ -36,6 +36,12 @@ export interface ResolvedRequirementsConfig {
   error?: ValidationError;
 }
 
+export interface FacilitatorRoutingConfig {
+  facilitatorUrl?: string;
+  facilitatorUrlByChain?: Record<string, string>;
+  facilitatorUrlByToken?: Record<string, Record<string, string>>;
+}
+
 const DEFAULT_NETWORKS: NetworkId[] = [
   "ethereum",
   "base",
@@ -141,6 +147,54 @@ function resolveFacilitatorUrl(
   return config.facilitatorUrl;
 }
 
+export function resolveFacilitatorUrlFromRequirement(
+  config: FacilitatorRoutingConfig,
+  requirement: Pick<PaymentRequirementsV2, "network" | "asset">,
+): string | undefined {
+  const chainId = parseInt(requirement.network.split(":")[1] || "0", 10);
+  const assetAddress = requirement.asset.toLowerCase();
+
+  if (config.facilitatorUrlByToken) {
+    for (const [chainKey, tokenMap] of Object.entries(
+      config.facilitatorUrlByToken,
+    )) {
+      const resolvedChain = resolveNetwork(chainKey);
+      if (
+        isValidationError(resolvedChain) ||
+        resolvedChain.config.chainId !== chainId
+      ) {
+        continue;
+      }
+
+      for (const [tokenKey, url] of Object.entries(tokenMap)) {
+        const resolvedToken = resolveToken(tokenKey, resolvedChain);
+        if (
+          !isValidationError(resolvedToken) &&
+          resolvedToken.config.contractAddress.toLowerCase() === assetAddress
+        ) {
+          return url;
+        }
+      }
+    }
+  }
+
+  if (config.facilitatorUrlByChain) {
+    for (const [chainKey, url] of Object.entries(
+      config.facilitatorUrlByChain,
+    )) {
+      const resolvedChain = resolveNetwork(chainKey);
+      if (
+        !isValidationError(resolvedChain) &&
+        resolvedChain.config.chainId === chainId
+      ) {
+        return url;
+      }
+    }
+  }
+
+  return config.facilitatorUrl;
+}
+
 function resolveNetworks(chainInputs: NetworkId[] | undefined): {
   networks: ResolvedNetwork[];
   error?: ValidationError;