@nevermined-io/payments 1.1.18 → 1.3.2

package/dist/x402/facilitator-api.js

@@ -72,27 +72,27 @@ import { getDefaultNetwork } from '../common/types.js';
  * ```
  */
 export function buildPaymentRequired(planId, options) {
-    const { endpoint, agentId, httpVerb, scheme = 'nvm:erc4337', network, description, environment, } = options || {};
+    const { endpoint, agentId, httpVerb, scheme = 'nvm:erc4337', network, description, mimeType, environment, } = options || {};
     const resolvedNetwork = network ?? getDefaultNetwork(scheme, environment);
-    // Build extra fields if any are provided
-    const extra = agentId || httpVerb
-        ? {
-            ...(agentId && { agentId }),
-            ...(httpVerb && { httpVerb }),
-        }
-        : undefined;
+    // Build extra fields — always include version for scheme versioning
+    const extra = {
+        version: '1',
+        ...(agentId && { agentId }),
+        ...(httpVerb && { httpVerb }),
+    };
     return {
         x402Version: 2,
         resource: {
             url: endpoint || '',
             ...(description && { description }),
+            ...(mimeType && { mimeType }),
         },
         accepts: [
             {
                 scheme,
                 network: resolvedNetwork,
                 planId,
-                ...(extra && { extra }),
+                extra,
             },
         ],
         extensions: {},
@@ -108,14 +108,28 @@ async function fetchPlanMetadata(payments, planId) {
     try {
         const plan = await payments.plans.getPlan(planId);
         const isCrypto = plan.registry?.price?.isCrypto;
+        // fiatPaymentProvider is in plan.metadata.plan, not in registry.price
+        const fiatProvider = plan.metadata?.plan?.fiatPaymentProvider;
         const scheme = isCrypto === false ? 'nvm:card-delegation' : 'nvm:erc4337';
-        planMetadataCache.set(planId, { scheme, cachedAt: Date.now() });
+        planMetadataCache.set(planId, { scheme, fiatProvider, cachedAt: Date.now() });
         return { scheme };
     }
     catch {
         return { scheme: 'nvm:erc4337' };
     }
 }
+/**
+ * Resolve the network for a plan from its fiatPaymentProvider metadata.
+ * For card-delegation plans, returns the provider ('stripe' or 'braintree').
+ * Returns undefined for crypto plans.
+ */
+export async function resolveNetwork(payments, planId, explicitNetwork) {
+    if (explicitNetwork)
+        return explicitNetwork;
+    await fetchPlanMetadata(payments, planId);
+    const cached = planMetadataCache.get(planId);
+    return cached?.fiatProvider;
+}
 /**
  * Resolve the x402 scheme for a plan by fetching plan metadata (cached).
  * Used in callsites that don't have a token to extract scheme from

package/dist/x402/facilitator-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"facilitator-api.js","sourceRoot":"","sources":["../../src/x402/facilitator-api.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The FacilitatorAPI class provides methods to verify and settle AI agent permissions using X402 access tokens.\n * This allows AI agents to act as facilitators, verifying and settling credits on behalf of subscribers.\n *\n * @example\n * ```typescript\n * import { Payments, X402PaymentRequired } from '@nevermined-io/payments'\n *\n * // Initialize the Payments instance\n * const payments = Payments.getInstance({\n *   nvmApiKey: 'your-nvm-api-key',\n *   environment: 'sandbox'\n * })\n *\n * // The server's 402 PaymentRequired response\n * const paymentRequired: X402PaymentRequired = buildPaymentRequired('123456789', {\n *   endpoint: '/api/v1/agents/task',\n *   agentId: '987654321',\n *   httpVerb: 'POST'\n * })\n *\n * // Get X402 access token from subscriber (x402 v2: payment-signature header)\n * const x402Token = req.headers['payment-signature'] as string\n *\n * // Verify if subscriber has sufficient permissions/credits\n * const verification = await payments.facilitator.verifyPermissions({\n *   paymentRequired,\n *   x402AccessToken: x402Token,\n *   maxAmount: 2n\n * })\n *\n * if (verification.isValid) {\n *   // Settle (burn) the credits\n *   const settlement = await payments.facilitator.settlePermissions({\n *     paymentRequired,\n *     x402AccessToken: x402Token,\n *     maxAmount: 2n\n *   })\n *   console.log(`Credits redeemed: ${settlement.creditsRedeemed}`)\n * }\n * ```\n */\n\nimport { BasePaymentsAPI } from '../api/base-payments.js'\nimport { API_URL_SETTLE_PERMISSIONS, API_URL_VERIFY_PERMISSIONS } from '../api/nvm-api.js'\nimport { PaymentsError } from '../common/payments.error.js'\nimport { PaymentOptions, StartAgentRequest, X402SchemeType, getDefaultNetwork } from '../common/types.js'\nimport type { EnvironmentName } from '../environments.js'\nimport type { Payments } from '../payments.js'\nimport type { VisaPaymentRequired } from './visa-facilitator-api.js'\n\n/**\n * x402 Resource information\n */\nexport interface X402Resource {\n  /** The protected resource URL */\n  url: string\n  /** Human-readable description */\n  description?: string\n  /** Expected response MIME type (e.g., \"application/json\") */\n  mimeType?: string\n}\n\n/**\n * x402 Scheme extra fields for nvm:erc4337\n */\nexport interface X402SchemeExtra {\n  /** Scheme version (e.g., \"1\") */\n  version?: string\n  /** Agent identifier */\n  agentId?: string\n  /** HTTP method for the endpoint */\n  httpVerb?: string\n}\n\n/**\n * x402 Scheme definition (nvm:erc4337)\n */\nexport interface X402Scheme {\n  /** Payment scheme identifier (e.g., \"nvm:erc4337\") */\n  scheme: string\n  /** Blockchain network in CAIP-2 format (e.g., \"eip155:84532\") */\n  network: string\n  /** 256-bit plan identifier */\n  planId: string\n  /** Scheme-specific extra fields */\n  extra?: X402SchemeExtra\n}\n\n/**\n * x402 PaymentRequired response (402 response from server)\n */\nexport interface X402PaymentRequired {\n  /** x402 protocol version (always 2) */\n  x402Version: number\n  /** Human-readable error message */\n  error?: string\n  /** Protected resource information */\n  resource: X402Resource\n  /** Array of accepted payment schemes */\n  accepts: X402Scheme[]\n  /** Extensions object (empty object for nvm:erc4337) */\n  extensions: Record<string, unknown>\n}\n\n/**\n * x402 PaymentAccepted response (accepted payment scheme)\n */\nexport interface X402PaymentAccepted {\n  /** The x402 version */\n  x402Version: number\n  /** The accepted payment scheme (nvm:erc4337) */\n  accepted: X402Scheme\n  /** The payload of the payment accepted */\n  payload: {\n    signature: string\n    authorization: {\n      from: string\n      sessionKeysProvider: string\n      sessionKeys: string[]\n    }\n  }\n  extensions: Record<string, unknown>\n}\n\n/**\n * Parameters for verifying permissions\n */\nexport interface VerifyPermissionsParams {\n  /** The server's 402 PaymentRequired response (NVM or Visa flavored) */\n  paymentRequired: X402PaymentRequired | VisaPaymentRequired\n  /** The X402 access token (base64-encoded) */\n  x402AccessToken: string\n  /** Maximum credits to verify (optional) */\n  maxAmount?: bigint\n}\n\n/**\n * x402 Verify Response - per x402 facilitator spec\n * @see https://github.com/coinbase/x402/blob/main/specs/x402-specification-v2.md\n */\nexport interface VerifyPermissionsResult {\n  /** Whether the payment authorization is valid */\n  isValid: boolean\n  /** Reason for invalidity (only present if isValid is false) */\n  invalidReason?: string\n  /** Address of the payer's wallet */\n  payer?: string\n  /** Agent request ID for observability tracking (Nevermined extension) */\n  agentRequestId?: string\n  /** URL pattern that matched the endpoint (Nevermined extension) */\n  urlMatching?: string\n  /** Agent request context for observability (Nevermined extension) */\n  agentRequest?: StartAgentRequest\n}\n\n/**\n * Parameters for settling permissions\n */\nexport interface SettlePermissionsParams {\n  /** The server's 402 PaymentRequired response (NVM or Visa flavored) */\n  paymentRequired: X402PaymentRequired | VisaPaymentRequired\n  /** The X402 access token (base64-encoded) */\n  x402AccessToken: string\n  /** Number of credits to burn (optional) */\n  maxAmount?: bigint\n  /** Agent request ID for observability tracking. Returned by verifyPermissions. */\n  agentRequestId?: string\n  /** Whether this is a batch request (multiple LLM calls under one agentRequestId) */\n  batch?: boolean\n  /** Margin percentage (0-10) for credit calculation. Mutually exclusive with maxAmount when agentRequestId provided. */\n  marginPercent?: number\n}\n\n/**\n * x402 Settle Response - per x402 facilitator spec\n * @see https://github.com/coinbase/x402/blob/main/specs/x402-specification-v2.md\n */\nexport interface SettlePermissionsResult {\n  /** Whether settlement was successful */\n  success: boolean\n  /** Reason for settlement failure (only present if success is false) */\n  errorReason?: string\n  /** Address of the payer's wallet */\n  payer?: string\n  /** Blockchain transaction hash (empty string if settlement failed) */\n  transaction: string\n  /** Blockchain network identifier in CAIP-2 format */\n  network: string\n  /** Number of credits redeemed (Nevermined extension) */\n  creditsRedeemed?: string\n  /** Subscriber's remaining balance (Nevermined extension) */\n  remainingBalance?: string\n  /** Transaction hash of the order operation if auto top-up occurred (Nevermined extension) */\n  orderTx?: string\n}\n\n/**\n * Build an X402PaymentRequired object for verify/settle operations.\n *\n * This helper simplifies the creation of payment requirement objects\n * that are needed for the facilitator API.\n *\n * @param planId - The Nevermined plan identifier (required)\n * @param options - Optional configuration with endpoint, agentId, httpVerb, network, description\n * @returns X402PaymentRequired object ready to use with verifyPermissions/settlePermissions\n *\n * @example\n * ```typescript\n * import { buildPaymentRequired } from '@nevermined-io/payments'\n *\n * const paymentRequired = buildPaymentRequired('123456789', {\n *   endpoint: '/api/v1/agents/task',\n *   agentId: '987654321',\n *   httpVerb: 'POST'\n * })\n *\n * const result = await payments.facilitator.verifyPermissions({\n *   paymentRequired,\n *   x402AccessToken: token,\n *   maxAmount: 2n\n * })\n * ```\n */\nexport function buildPaymentRequired(\n  planId: string,\n  options?: {\n    endpoint?: string\n    agentId?: string\n    httpVerb?: string\n    network?: string\n    description?: string\n    scheme?: X402SchemeType\n    environment?: EnvironmentName\n  },\n): X402PaymentRequired {\n  const {\n    endpoint,\n    agentId,\n    httpVerb,\n    scheme = 'nvm:erc4337',\n    network,\n    description,\n    environment,\n  } = options || {}\n  const resolvedNetwork = network ?? getDefaultNetwork(scheme, environment)\n\n  // Build extra fields if any are provided\n  const extra: X402SchemeExtra | undefined =\n    agentId || httpVerb\n      ? {\n          ...(agentId && { agentId }),\n          ...(httpVerb && { httpVerb }),\n        }\n      : undefined\n\n  return {\n    x402Version: 2,\n    resource: {\n      url: endpoint || '',\n      ...(description && { description }),\n    },\n    accepts: [\n      {\n        scheme,\n        network: resolvedNetwork,\n        planId,\n        ...(extra && { extra }),\n      },\n    ],\n    extensions: {},\n  }\n}\n\ninterface CachedPlanMetadata {\n  scheme: X402SchemeType\n  cachedAt: number\n}\n\nconst CACHE_TTL_MS = 5 * 60 * 1000 // 5 minutes\nconst planMetadataCache = new Map<string, CachedPlanMetadata>()\n\nasync function fetchPlanMetadata(\n  payments: Payments,\n  planId: string,\n): Promise<{ scheme: X402SchemeType }> {\n  const cached = planMetadataCache.get(planId)\n  if (cached && Date.now() - cached.cachedAt < CACHE_TTL_MS) {\n    return { scheme: cached.scheme }\n  }\n  try {\n    const plan = await payments.plans.getPlan(planId)\n    const isCrypto = plan.registry?.price?.isCrypto\n    const scheme: X402SchemeType =\n      isCrypto === false ? 'nvm:card-delegation' : 'nvm:erc4337'\n    planMetadataCache.set(planId, { scheme, cachedAt: Date.now() })\n    return { scheme }\n  } catch {\n    return { scheme: 'nvm:erc4337' }\n  }\n}\n\n/**\n * Resolve the x402 scheme for a plan by fetching plan metadata (cached).\n * Used in callsites that don't have a token to extract scheme from\n * (402 responses and token generation).\n *\n * @param payments - The Payments instance for API access\n * @param planId - The plan identifier\n * @param explicitScheme - Optional explicit override; returned immediately if provided\n * @returns The resolved scheme type\n */\nexport async function resolveScheme(\n  payments: Payments,\n  planId: string,\n  explicitScheme?: X402SchemeType,\n): Promise<X402SchemeType> {\n  if (explicitScheme) return explicitScheme\n  const metadata = await fetchPlanMetadata(payments, planId)\n  return metadata.scheme\n}\n\n/**\n * The FacilitatorAPI class provides methods to verify and settle AI agent permissions.\n * It enables AI agents to act as facilitators, managing credit verification and settlement\n * for subscribers using X402 access tokens.\n */\nexport class FacilitatorAPI extends BasePaymentsAPI {\n  /**\n   * Get a singleton instance of the FacilitatorAPI class.\n   *\n   * @param options - The options to initialize the payments class\n   * @returns The instance of the FacilitatorAPI class\n   */\n  static getInstance(options: PaymentOptions): FacilitatorAPI {\n    return new FacilitatorAPI(options)\n  }\n\n  /**\n   * Verify if a subscriber has permission to use credits from a payment plan.\n   * This method simulates the credit usage without actually burning credits,\n   * checking if the subscriber has sufficient balance and permissions.\n   *\n   * The planId and subscriberAddress are extracted from the x402AccessToken.\n   *\n   * @param params - Verification parameters (see {@link VerifyPermissionsParams}).\n   *   - paymentRequired: x402 PaymentRequired from 402 response (required, for validation)\n   *   - x402AccessToken: X402 access token (contains planId, subscriberAddress, agentId)\n   *   - maxAmount: maximum credits to verify (optional, bigint)\n   * @returns A promise that resolves to a verification result with 'isValid' boolean\n   *\n   * @throws PaymentsError if verification fails\n   */\n  async verifyPermissions(params: VerifyPermissionsParams): Promise<VerifyPermissionsResult> {\n    const { paymentRequired, x402AccessToken, maxAmount } = params\n\n    const url = new URL(API_URL_VERIFY_PERMISSIONS, this.environment.backend)\n\n    const body: Record<string, unknown> = {\n      paymentRequired,\n      x402AccessToken,\n    }\n\n    if (maxAmount !== undefined) {\n      body.maxAmount = maxAmount.toString()\n    }\n\n    const options = this.getPublicHTTPOptions('POST', body)\n\n    try {\n      const response = await fetch(url, options)\n      if (!response.ok) {\n        let errorMessage = 'Permission verification failed'\n        try {\n          const errorData = await response.json()\n          errorMessage = errorData.message || errorMessage\n        } catch {\n          // Use default error message\n        }\n        throw PaymentsError.fromBackend(errorMessage, {\n          message: errorMessage,\n          code: `HTTP ${response.status}`,\n        })\n      }\n      return await response.json()\n    } catch (error) {\n      if (error instanceof PaymentsError) {\n        throw error\n      }\n      throw PaymentsError.fromBackend('Network error during permission verification', {\n        message: error instanceof Error ? error.message : String(error),\n        code: 'network_error',\n      })\n    }\n  }\n\n  /**\n   * Settle (burn) credits from a subscriber's payment plan.\n   * This method executes the actual credit consumption, burning the specified\n   * number of credits from the subscriber's balance. If the subscriber doesn't\n   * have enough credits, it will attempt to order more before settling.\n   *\n   * The planId and subscriberAddress are extracted from the x402AccessToken.\n   *\n   * @param params - Settlement parameters (see {@link SettlePermissionsParams}).\n   *   - paymentRequired: x402 PaymentRequired from 402 response (required, for validation)\n   *   - x402AccessToken: X402 access token (contains planId, subscriberAddress, agentId)\n   *   - maxAmount: number of credits to burn (optional, bigint)\n   *   - agentRequestId: Agent request ID for observability tracking (optional)\n   *   - batch: Whether this is a batch request (optional)\n   *   - marginPercent: Margin percentage for credit calculation (optional)\n   * @returns A promise that resolves to a settlement result with transaction details\n   *\n   * @throws PaymentsError if settlement fails\n   */\n  async settlePermissions(params: SettlePermissionsParams): Promise<SettlePermissionsResult> {\n    const { paymentRequired, x402AccessToken, maxAmount, agentRequestId, batch, marginPercent } =\n      params\n\n    const url = new URL(API_URL_SETTLE_PERMISSIONS, this.environment.backend)\n\n    const body: Record<string, unknown> = {\n      paymentRequired,\n      x402AccessToken,\n    }\n\n    if (maxAmount !== undefined) {\n      body.maxAmount = maxAmount.toString()\n    }\n    if (agentRequestId !== undefined) {\n      body.agentRequestId = agentRequestId\n    }\n    if (batch !== undefined) {\n      body.batch = batch\n    }\n    if (marginPercent !== undefined) {\n      body.marginPercent = marginPercent\n    }\n\n    const options = this.getPublicHTTPOptions('POST', body)\n\n    try {\n      const response = await fetch(url, options)\n      if (!response.ok) {\n        let errorMessage = 'Permission settlement failed'\n        try {\n          const errorData = await response.json()\n          errorMessage = errorData.message || errorMessage\n        } catch {\n          // Use default error message\n        }\n        throw PaymentsError.fromBackend(errorMessage, {\n          message: errorMessage,\n          code: `HTTP ${response.status}`,\n        })\n      }\n      return await response.json()\n    } catch (error) {\n      if (error instanceof PaymentsError) {\n        throw error\n      }\n      throw PaymentsError.fromBackend('Network error during permission settlement', {\n        message: error instanceof Error ? error.message : String(error),\n        code: 'network_error',\n      })\n    }\n  }\n}\n"]}
+{"version":3,"file":"facilitator-api.js","sourceRoot":"","sources":["../../src/x402/facilitator-api.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The FacilitatorAPI class provides methods to verify and settle AI agent permissions using X402 access tokens.\n * This allows AI agents to act as facilitators, verifying and settling credits on behalf of subscribers.\n *\n * @example\n * ```typescript\n * import { Payments, X402PaymentRequired } from '@nevermined-io/payments'\n *\n * // Initialize the Payments instance\n * const payments = Payments.getInstance({\n *   nvmApiKey: 'your-nvm-api-key',\n *   environment: 'sandbox'\n * })\n *\n * // The server's 402 PaymentRequired response\n * const paymentRequired: X402PaymentRequired = buildPaymentRequired('123456789', {\n *   endpoint: '/api/v1/agents/task',\n *   agentId: '987654321',\n *   httpVerb: 'POST'\n * })\n *\n * // Get X402 access token from subscriber (x402 v2: payment-signature header)\n * const x402Token = req.headers['payment-signature'] as string\n *\n * // Verify if subscriber has sufficient permissions/credits\n * const verification = await payments.facilitator.verifyPermissions({\n *   paymentRequired,\n *   x402AccessToken: x402Token,\n *   maxAmount: 2n\n * })\n *\n * if (verification.isValid) {\n *   // Settle (burn) the credits\n *   const settlement = await payments.facilitator.settlePermissions({\n *     paymentRequired,\n *     x402AccessToken: x402Token,\n *     maxAmount: 2n\n *   })\n *   console.log(`Credits redeemed: ${settlement.creditsRedeemed}`)\n * }\n * ```\n */\n\nimport { BasePaymentsAPI } from '../api/base-payments.js'\nimport { API_URL_SETTLE_PERMISSIONS, API_URL_VERIFY_PERMISSIONS } from '../api/nvm-api.js'\nimport { PaymentsError } from '../common/payments.error.js'\nimport { PaymentOptions, StartAgentRequest, X402SchemeType, getDefaultNetwork } from '../common/types.js'\nimport type { EnvironmentName } from '../environments.js'\nimport type { Payments } from '../payments.js'\nimport type { VisaPaymentRequired } from './visa-facilitator-api.js'\n\n/**\n * x402 Resource information\n */\nexport interface X402Resource {\n  /** The protected resource URL */\n  url: string\n  /** Human-readable description */\n  description?: string\n  /** Expected response MIME type (e.g., \"application/json\") */\n  mimeType?: string\n}\n\n/**\n * x402 Scheme extra fields for nvm:erc4337\n */\nexport interface X402SchemeExtra {\n  /** Scheme version (e.g., \"1\") */\n  version?: string\n  /** Agent identifier */\n  agentId?: string\n  /** HTTP method for the endpoint */\n  httpVerb?: string\n}\n\n/**\n * x402 Scheme definition (nvm:erc4337)\n */\nexport interface X402Scheme {\n  /** Payment scheme identifier (e.g., \"nvm:erc4337\") */\n  scheme: string\n  /** Blockchain network in CAIP-2 format (e.g., \"eip155:84532\") */\n  network: string\n  /** 256-bit plan identifier */\n  planId: string\n  /** Scheme-specific extra fields */\n  extra?: X402SchemeExtra\n}\n\n/**\n * x402 PaymentRequired response (402 response from server)\n */\nexport interface X402PaymentRequired {\n  /** x402 protocol version (always 2) */\n  x402Version: number\n  /** Human-readable error message */\n  error?: string\n  /** Protected resource information */\n  resource: X402Resource\n  /** Array of accepted payment schemes */\n  accepts: X402Scheme[]\n  /** Extensions object (empty object for nvm:erc4337) */\n  extensions: Record<string, unknown>\n}\n\n/**\n * x402 PaymentAccepted response (accepted payment scheme)\n */\nexport interface X402PaymentAccepted {\n  /** The x402 version */\n  x402Version: number\n  /** The accepted payment scheme (nvm:erc4337) */\n  accepted: X402Scheme\n  /** The payload of the payment accepted */\n  payload: {\n    signature: string\n    authorization: {\n      from: string\n      sessionKeysProvider: string\n      sessionKeys: string[]\n    }\n  }\n  extensions: Record<string, unknown>\n}\n\n/**\n * Parameters for verifying permissions\n */\nexport interface VerifyPermissionsParams {\n  /** The server's 402 PaymentRequired response (NVM or Visa flavored) */\n  paymentRequired: X402PaymentRequired | VisaPaymentRequired\n  /** The X402 access token (base64-encoded) */\n  x402AccessToken: string\n  /** Maximum credits to verify (optional) */\n  maxAmount?: bigint\n}\n\n/**\n * x402 Verify Response - per x402 facilitator spec\n * @see https://github.com/coinbase/x402/blob/main/specs/x402-specification-v2.md\n */\nexport interface VerifyPermissionsResult {\n  /** Whether the payment authorization is valid */\n  isValid: boolean\n  /** Reason for invalidity (only present if isValid is false) */\n  invalidReason?: string\n  /** Address of the payer's wallet */\n  payer?: string\n  /** Network identifier (e.g., 'stripe', 'braintree', 'eip155:84532') */\n  network?: string\n  /** Agent request ID for observability tracking (Nevermined extension) */\n  agentRequestId?: string\n  /** URL pattern that matched the endpoint (Nevermined extension) */\n  urlMatching?: string\n  /** Agent request context for observability (Nevermined extension) */\n  agentRequest?: StartAgentRequest\n}\n\n/**\n * Parameters for settling permissions\n */\nexport interface SettlePermissionsParams {\n  /** The server's 402 PaymentRequired response (NVM or Visa flavored) */\n  paymentRequired: X402PaymentRequired | VisaPaymentRequired\n  /** The X402 access token (base64-encoded) */\n  x402AccessToken: string\n  /** Number of credits to burn (optional) */\n  maxAmount?: bigint\n  /** Agent request ID for observability tracking. Returned by verifyPermissions. */\n  agentRequestId?: string\n  /** Whether this is a batch request (multiple LLM calls under one agentRequestId) */\n  batch?: boolean\n  /** Margin percentage (0-10) for credit calculation. Mutually exclusive with maxAmount when agentRequestId provided. */\n  marginPercent?: number\n}\n\n/**\n * x402 Settle Response - per x402 facilitator spec\n * @see https://github.com/coinbase/x402/blob/main/specs/x402-specification-v2.md\n */\nexport interface SettlePermissionsResult {\n  /** Whether settlement was successful */\n  success: boolean\n  /** Reason for settlement failure (only present if success is false) */\n  errorReason?: string\n  /** Address of the payer's wallet */\n  payer?: string\n  /** Blockchain transaction hash (empty string if settlement failed) */\n  transaction: string\n  /** Blockchain network identifier in CAIP-2 format */\n  network: string\n  /** Number of credits redeemed (Nevermined extension) */\n  creditsRedeemed?: string\n  /** Subscriber's remaining balance (Nevermined extension) */\n  remainingBalance?: string\n  /** Transaction hash of the order operation if auto top-up occurred (Nevermined extension) */\n  orderTx?: string\n}\n\n/**\n * Build an X402PaymentRequired object for verify/settle operations.\n *\n * This helper simplifies the creation of payment requirement objects\n * that are needed for the facilitator API.\n *\n * @param planId - The Nevermined plan identifier (required)\n * @param options - Optional configuration with endpoint, agentId, httpVerb, network, description\n * @returns X402PaymentRequired object ready to use with verifyPermissions/settlePermissions\n *\n * @example\n * ```typescript\n * import { buildPaymentRequired } from '@nevermined-io/payments'\n *\n * const paymentRequired = buildPaymentRequired('123456789', {\n *   endpoint: '/api/v1/agents/task',\n *   agentId: '987654321',\n *   httpVerb: 'POST'\n * })\n *\n * const result = await payments.facilitator.verifyPermissions({\n *   paymentRequired,\n *   x402AccessToken: token,\n *   maxAmount: 2n\n * })\n * ```\n */\nexport function buildPaymentRequired(\n  planId: string,\n  options?: {\n    endpoint?: string\n    agentId?: string\n    httpVerb?: string\n    network?: string\n    description?: string\n    mimeType?: string\n    scheme?: X402SchemeType\n    environment?: EnvironmentName\n  },\n): X402PaymentRequired {\n  const {\n    endpoint,\n    agentId,\n    httpVerb,\n    scheme = 'nvm:erc4337',\n    network,\n    description,\n    mimeType,\n    environment,\n  } = options || {}\n  const resolvedNetwork = network ?? getDefaultNetwork(scheme, environment)\n\n  // Build extra fields — always include version for scheme versioning\n  const extra: X402SchemeExtra = {\n    version: '1',\n    ...(agentId && { agentId }),\n    ...(httpVerb && { httpVerb }),\n  }\n\n  return {\n    x402Version: 2,\n    resource: {\n      url: endpoint || '',\n      ...(description && { description }),\n      ...(mimeType && { mimeType }),\n    },\n    accepts: [\n      {\n        scheme,\n        network: resolvedNetwork,\n        planId,\n        extra,\n      },\n    ],\n    extensions: {},\n  }\n}\n\ninterface CachedPlanMetadata {\n  scheme: X402SchemeType\n  fiatProvider?: string\n  cachedAt: number\n}\n\nconst CACHE_TTL_MS = 5 * 60 * 1000 // 5 minutes\nconst planMetadataCache = new Map<string, CachedPlanMetadata>()\n\nasync function fetchPlanMetadata(\n  payments: Payments,\n  planId: string,\n): Promise<{ scheme: X402SchemeType }> {\n  const cached = planMetadataCache.get(planId)\n  if (cached && Date.now() - cached.cachedAt < CACHE_TTL_MS) {\n    return { scheme: cached.scheme }\n  }\n  try {\n    const plan = await payments.plans.getPlan(planId)\n    const isCrypto = plan.registry?.price?.isCrypto\n    // fiatPaymentProvider is in plan.metadata.plan, not in registry.price\n    const fiatProvider = (plan as any).metadata?.plan?.fiatPaymentProvider\n    const scheme: X402SchemeType =\n      isCrypto === false ? 'nvm:card-delegation' : 'nvm:erc4337'\n    planMetadataCache.set(planId, { scheme, fiatProvider, cachedAt: Date.now() })\n    return { scheme }\n  } catch {\n    return { scheme: 'nvm:erc4337' }\n  }\n}\n\n/**\n * Resolve the network for a plan from its fiatPaymentProvider metadata.\n * For card-delegation plans, returns the provider ('stripe' or 'braintree').\n * Returns undefined for crypto plans.\n */\nexport async function resolveNetwork(\n  payments: Payments,\n  planId: string,\n  explicitNetwork?: string,\n): Promise<string | undefined> {\n  if (explicitNetwork) return explicitNetwork\n  await fetchPlanMetadata(payments, planId)\n  const cached = planMetadataCache.get(planId)\n  return cached?.fiatProvider\n}\n\n/**\n * Resolve the x402 scheme for a plan by fetching plan metadata (cached).\n * Used in callsites that don't have a token to extract scheme from\n * (402 responses and token generation).\n *\n * @param payments - The Payments instance for API access\n * @param planId - The plan identifier\n * @param explicitScheme - Optional explicit override; returned immediately if provided\n * @returns The resolved scheme type\n */\nexport async function resolveScheme(\n  payments: Payments,\n  planId: string,\n  explicitScheme?: X402SchemeType,\n): Promise<X402SchemeType> {\n  if (explicitScheme) return explicitScheme\n  const metadata = await fetchPlanMetadata(payments, planId)\n  return metadata.scheme\n}\n\n/**\n * The FacilitatorAPI class provides methods to verify and settle AI agent permissions.\n * It enables AI agents to act as facilitators, managing credit verification and settlement\n * for subscribers using X402 access tokens.\n */\nexport class FacilitatorAPI extends BasePaymentsAPI {\n  /**\n   * Get a singleton instance of the FacilitatorAPI class.\n   *\n   * @param options - The options to initialize the payments class\n   * @returns The instance of the FacilitatorAPI class\n   */\n  static getInstance(options: PaymentOptions): FacilitatorAPI {\n    return new FacilitatorAPI(options)\n  }\n\n  /**\n   * Verify if a subscriber has permission to use credits from a payment plan.\n   * This method simulates the credit usage without actually burning credits,\n   * checking if the subscriber has sufficient balance and permissions.\n   *\n   * The planId and subscriberAddress are extracted from the x402AccessToken.\n   *\n   * @param params - Verification parameters (see {@link VerifyPermissionsParams}).\n   *   - paymentRequired: x402 PaymentRequired from 402 response (required, for validation)\n   *   - x402AccessToken: X402 access token (contains planId, subscriberAddress, agentId)\n   *   - maxAmount: maximum credits to verify (optional, bigint)\n   * @returns A promise that resolves to a verification result with 'isValid' boolean\n   *\n   * @throws PaymentsError if verification fails\n   */\n  async verifyPermissions(params: VerifyPermissionsParams): Promise<VerifyPermissionsResult> {\n    const { paymentRequired, x402AccessToken, maxAmount } = params\n\n    const url = new URL(API_URL_VERIFY_PERMISSIONS, this.environment.backend)\n\n    const body: Record<string, unknown> = {\n      paymentRequired,\n      x402AccessToken,\n    }\n\n    if (maxAmount !== undefined) {\n      body.maxAmount = maxAmount.toString()\n    }\n\n    const options = this.getPublicHTTPOptions('POST', body)\n\n    try {\n      const response = await fetch(url, options)\n      if (!response.ok) {\n        let errorMessage = 'Permission verification failed'\n        try {\n          const errorData = await response.json()\n          errorMessage = errorData.message || errorMessage\n        } catch {\n          // Use default error message\n        }\n        throw PaymentsError.fromBackend(errorMessage, {\n          message: errorMessage,\n          code: `HTTP ${response.status}`,\n        })\n      }\n      return await response.json()\n    } catch (error) {\n      if (error instanceof PaymentsError) {\n        throw error\n      }\n      throw PaymentsError.fromBackend('Network error during permission verification', {\n        message: error instanceof Error ? error.message : String(error),\n        code: 'network_error',\n      })\n    }\n  }\n\n  /**\n   * Settle (burn) credits from a subscriber's payment plan.\n   * This method executes the actual credit consumption, burning the specified\n   * number of credits from the subscriber's balance. If the subscriber doesn't\n   * have enough credits, it will attempt to order more before settling.\n   *\n   * The planId and subscriberAddress are extracted from the x402AccessToken.\n   *\n   * @param params - Settlement parameters (see {@link SettlePermissionsParams}).\n   *   - paymentRequired: x402 PaymentRequired from 402 response (required, for validation)\n   *   - x402AccessToken: X402 access token (contains planId, subscriberAddress, agentId)\n   *   - maxAmount: number of credits to burn (optional, bigint)\n   *   - agentRequestId: Agent request ID for observability tracking (optional)\n   *   - batch: Whether this is a batch request (optional)\n   *   - marginPercent: Margin percentage for credit calculation (optional)\n   * @returns A promise that resolves to a settlement result with transaction details\n   *\n   * @throws PaymentsError if settlement fails\n   */\n  async settlePermissions(params: SettlePermissionsParams): Promise<SettlePermissionsResult> {\n    const { paymentRequired, x402AccessToken, maxAmount, agentRequestId, batch, marginPercent } =\n      params\n\n    const url = new URL(API_URL_SETTLE_PERMISSIONS, this.environment.backend)\n\n    const body: Record<string, unknown> = {\n      paymentRequired,\n      x402AccessToken,\n    }\n\n    if (maxAmount !== undefined) {\n      body.maxAmount = maxAmount.toString()\n    }\n    if (agentRequestId !== undefined) {\n      body.agentRequestId = agentRequestId\n    }\n    if (batch !== undefined) {\n      body.batch = batch\n    }\n    if (marginPercent !== undefined) {\n      body.marginPercent = marginPercent\n    }\n\n    const options = this.getPublicHTTPOptions('POST', body)\n\n    try {\n      const response = await fetch(url, options)\n      if (!response.ok) {\n        let errorMessage = 'Permission settlement failed'\n        try {\n          const errorData = await response.json()\n          errorMessage = errorData.message || errorMessage\n        } catch {\n          // Use default error message\n        }\n        throw PaymentsError.fromBackend(errorMessage, {\n          message: errorMessage,\n          code: `HTTP ${response.status}`,\n        })\n      }\n      return await response.json()\n    } catch (error) {\n      if (error instanceof PaymentsError) {\n        throw error\n      }\n      throw PaymentsError.fromBackend('Network error during permission settlement', {\n        message: error instanceof Error ? error.message : String(error),\n        code: 'network_error',\n      })\n    }\n  }\n}\n"]}

package/dist/x402/index.d.ts

@@ -2,11 +2,11 @@
  * X402 API module for token generation and facilitator operations.
  */
 export { X402TokenAPI } from './token.js';
-export { FacilitatorAPI, buildPaymentRequired, resolveScheme } from './facilitator-api.js';
+export { FacilitatorAPI, buildPaymentRequired, resolveNetwork, resolveScheme } from './facilitator-api.js';
 export type { X402Resource, X402SchemeExtra, X402Scheme, X402PaymentRequired, X402PaymentAccepted, VerifyPermissionsParams, VerifyPermissionsResult, SettlePermissionsParams, SettlePermissionsResult, } from './facilitator-api.js';
 export { DelegationAPI } from './delegation-api.js';
-export type { PaymentMethodSummary } from './delegation-api.js';
-export type { X402SchemeType, CardDelegationConfig, X402TokenOptions } from '../common/types.js';
+export type { PaymentMethodSummary, UpdatePaymentMethodDto, DelegationSummary, DelegationListResponse, PurchasingPower, ListOptions, } from './delegation-api.js';
+export type { X402SchemeType, DelegationConfig, CreateDelegationPayload, CreateDelegationResponse, X402TokenOptions, } from '../common/types.js';
 export { X402_SCHEME_NETWORKS, getDefaultNetwork, isValidScheme } from '../common/types.js';
 export { VisaFacilitatorAPI, buildVisaPaymentRequired, VISA_X402_HEADERS } from './visa-facilitator-api.js';
 export type { VisaPaymentExtra, VisaPaymentRequirements, VisaPaymentRequired, VisaVerifyResponse, VisaSettlementResponse, } from './visa-facilitator-api.js';

package/dist/x402/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/x402/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAC1F,YAAY,EAEV,YAAY,EACZ,eAAe,EACf,UAAU,EACV,mBAAmB,EACnB,mBAAmB,EAEnB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,sBAAsB,CAAA;AAG7B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAG/D,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAChG,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAG3F,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAC3G,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,2BAA2B,CAAA;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAClD,YAAY,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/x402/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAC1G,YAAY,EAEV,YAAY,EACZ,eAAe,EACf,UAAU,EACV,mBAAmB,EACnB,mBAAmB,EAEnB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,sBAAsB,CAAA;AAG7B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,YAAY,EACV,oBAAoB,EACpB,sBAAsB,EACtB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAG5B,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAG3F,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAC3G,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,2BAA2B,CAAA;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAClD,YAAY,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/x402/index.js

@@ -2,8 +2,8 @@
  * X402 API module for token generation and facilitator operations.
  */
 export { X402TokenAPI } from './token.js';
-export { FacilitatorAPI, buildPaymentRequired, resolveScheme } from './facilitator-api.js';
-// Card delegation exports
+export { FacilitatorAPI, buildPaymentRequired, resolveNetwork, resolveScheme } from './facilitator-api.js';
+// Delegation exports
 export { DelegationAPI } from './delegation-api.js';
 export { X402_SCHEME_NETWORKS, getDefaultNetwork, isValidScheme } from '../common/types.js';
 // Visa x402 exports

package/dist/x402/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/x402/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAe1F,0BAA0B;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAKnD,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAE3F,oBAAoB;AACpB,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAQ3G,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA","sourcesContent":["/**\n * X402 API module for token generation and facilitator operations.\n */\n\nexport { X402TokenAPI } from './token.js'\nexport { FacilitatorAPI, buildPaymentRequired, resolveScheme } from './facilitator-api.js'\nexport type {\n  // x402 types\n  X402Resource,\n  X402SchemeExtra,\n  X402Scheme,\n  X402PaymentRequired,\n  X402PaymentAccepted,\n  // Facilitator params and results\n  VerifyPermissionsParams,\n  VerifyPermissionsResult,\n  SettlePermissionsParams,\n  SettlePermissionsResult,\n} from './facilitator-api.js'\n\n// Card delegation exports\nexport { DelegationAPI } from './delegation-api.js'\nexport type { PaymentMethodSummary } from './delegation-api.js'\n\n// Scheme types\nexport type { X402SchemeType, CardDelegationConfig, X402TokenOptions } from '../common/types.js'\nexport { X402_SCHEME_NETWORKS, getDefaultNetwork, isValidScheme } from '../common/types.js'\n\n// Visa x402 exports\nexport { VisaFacilitatorAPI, buildVisaPaymentRequired, VISA_X402_HEADERS } from './visa-facilitator-api.js'\nexport type {\n  VisaPaymentExtra,\n  VisaPaymentRequirements,\n  VisaPaymentRequired,\n  VisaVerifyResponse,\n  VisaSettlementResponse,\n} from './visa-facilitator-api.js'\nexport { VisaTokenAPI } from './visa-token-api.js'\nexport type { VisaPaymentPayloadResponse } from './visa-token-api.js'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/x402/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAe1G,qBAAqB;AACrB,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAkBnD,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAE3F,oBAAoB;AACpB,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAQ3G,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA","sourcesContent":["/**\n * X402 API module for token generation and facilitator operations.\n */\n\nexport { X402TokenAPI } from './token.js'\nexport { FacilitatorAPI, buildPaymentRequired, resolveNetwork, resolveScheme } from './facilitator-api.js'\nexport type {\n  // x402 types\n  X402Resource,\n  X402SchemeExtra,\n  X402Scheme,\n  X402PaymentRequired,\n  X402PaymentAccepted,\n  // Facilitator params and results\n  VerifyPermissionsParams,\n  VerifyPermissionsResult,\n  SettlePermissionsParams,\n  SettlePermissionsResult,\n} from './facilitator-api.js'\n\n// Delegation exports\nexport { DelegationAPI } from './delegation-api.js'\nexport type {\n  PaymentMethodSummary,\n  UpdatePaymentMethodDto,\n  DelegationSummary,\n  DelegationListResponse,\n  PurchasingPower,\n  ListOptions,\n} from './delegation-api.js'\n\n// Scheme and delegation types\nexport type {\n  X402SchemeType,\n  DelegationConfig,\n  CreateDelegationPayload,\n  CreateDelegationResponse,\n  X402TokenOptions,\n} from '../common/types.js'\nexport { X402_SCHEME_NETWORKS, getDefaultNetwork, isValidScheme } from '../common/types.js'\n\n// Visa x402 exports\nexport { VisaFacilitatorAPI, buildVisaPaymentRequired, VISA_X402_HEADERS } from './visa-facilitator-api.js'\nexport type {\n  VisaPaymentExtra,\n  VisaPaymentRequirements,\n  VisaPaymentRequired,\n  VisaVerifyResponse,\n  VisaSettlementResponse,\n} from './visa-facilitator-api.js'\nexport { VisaTokenAPI } from './visa-token-api.js'\nexport type { VisaPaymentPayloadResponse } from './visa-token-api.js'\n"]}

package/dist/x402/token.d.ts

@@ -21,37 +21,37 @@ export declare class X402TokenAPI extends BasePaymentsAPI {
      */
     static getInstance(options: PaymentOptions): X402TokenAPI;
     /**
-     * Create a permission and get an X402 access token for the given plan.
+     * Create a delegation and get an X402 access token for the given plan.
      *
-     * This token allows the agent to verify and settle permissions on behalf
-     * of the subscriber. The token contains cryptographically signed session keys
-     * that delegate specific permissions (order, burn) to the agent.
+     * This token allows the agent to verify and settle delegations on behalf
+     * of the subscriber.
+     *
+     * For erc4337 scheme, you must pass `tokenOptions.delegationConfig` with either:
+     * - `delegationId` to reuse an existing delegation, or
+     * - `spendingLimitCents` + `durationSecs` to auto-create a new one.
      *
      * @param planId - The unique identifier of the payment plan
-     * @param agentId - The unique identifier of the AI agent (optional). If provided, permissions are restricted to that specific agent.
-     * @param redemptionLimit - Maximum number of interactions/redemptions allowed (optional)
-     * @param orderLimit - Maximum spend limit in token units (wei) for ordering (optional)
-     * @param expiration - Expiration date in ISO 8601 format, e.g. "2025-02-01T10:00:00Z" (optional)
+     * @param agentId - The unique identifier of the AI agent (optional)
+     * @param tokenOptions - Options controlling scheme and delegation behavior (optional)
      * @returns A promise that resolves to an object containing:
      *   - accessToken: The X402 access token string
-     *   - Additional metadata about the token
      *
      * @throws PaymentsError if the request fails
      *
      * @example
      * ```typescript
-     * import { Payments } from '@nevermined-io/payments'
-     *
-     * const payments = Payments.getInstance({
-     *   nvmApiKey: 'nvm:subscriber-key',
-     *   environment: 'sandbox'
+     * // Pattern A — auto-create delegation
+     * const result = await payments.x402.getX402AccessToken(planId, agentId, {
+     *   delegationConfig: { spendingLimitCents: 10000, durationSecs: 604800 }
      * })
      *
-     * const result = await payments.x402.getX402AccessToken(planId, agentId)
-     * const token = result.accessToken
+     * // Pattern B — reuse existing delegation
+     * const result = await payments.x402.getX402AccessToken(planId, agentId, {
+     *   delegationConfig: { delegationId: 'existing-delegation-uuid' }
+     * })
      * ```
      */
-    getX402AccessToken(planId: string, agentId?: string, redemptionLimit?: number, orderLimit?: string, expiration?: string, tokenOptions?: X402TokenOptions): Promise<{
+    getX402AccessToken(planId: string, agentId?: string, tokenOptions?: X402TokenOptions): Promise<{
         accessToken: string;
         [key: string]: any;
     }>;

package/dist/x402/token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/x402/token.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAGzD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAqB,MAAM,oBAAoB,CAAA;AAExF;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,eAAe;IAC/C;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY;IAIzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,kBAAkB,CACtB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,MAAM,EACxB,UAAU,CAAC,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,gBAAgB,GAC9B,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAA,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAC;CAiEvD"}
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/x402/token.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAGzD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAqB,MAAM,oBAAoB,CAAA;AAExF;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,eAAe;IAC/C;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY;IAIzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,kBAAkB,CACtB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,gBAAgB,GAC9B,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAC;CAyDxD"}

package/dist/x402/token.js

@@ -25,41 +25,47 @@ export class X402TokenAPI extends BasePaymentsAPI {
         return new X402TokenAPI(options);
     }
     /**
-     * Create a permission and get an X402 access token for the given plan.
+     * Create a delegation and get an X402 access token for the given plan.
      *
-     * This token allows the agent to verify and settle permissions on behalf
-     * of the subscriber. The token contains cryptographically signed session keys
-     * that delegate specific permissions (order, burn) to the agent.
+     * This token allows the agent to verify and settle delegations on behalf
+     * of the subscriber.
+     *
+     * For erc4337 scheme, you must pass `tokenOptions.delegationConfig` with either:
+     * - `delegationId` to reuse an existing delegation, or
+     * - `spendingLimitCents` + `durationSecs` to auto-create a new one.
      *
      * @param planId - The unique identifier of the payment plan
-     * @param agentId - The unique identifier of the AI agent (optional). If provided, permissions are restricted to that specific agent.
-     * @param redemptionLimit - Maximum number of interactions/redemptions allowed (optional)
-     * @param orderLimit - Maximum spend limit in token units (wei) for ordering (optional)
-     * @param expiration - Expiration date in ISO 8601 format, e.g. "2025-02-01T10:00:00Z" (optional)
+     * @param agentId - The unique identifier of the AI agent (optional)
+     * @param tokenOptions - Options controlling scheme and delegation behavior (optional)
      * @returns A promise that resolves to an object containing:
      *   - accessToken: The X402 access token string
-     *   - Additional metadata about the token
      *
      * @throws PaymentsError if the request fails
      *
      * @example
      * ```typescript
-     * import { Payments } from '@nevermined-io/payments'
-     *
-     * const payments = Payments.getInstance({
-     *   nvmApiKey: 'nvm:subscriber-key',
-     *   environment: 'sandbox'
+     * // Pattern A — auto-create delegation
+     * const result = await payments.x402.getX402AccessToken(planId, agentId, {
+     *   delegationConfig: { spendingLimitCents: 10000, durationSecs: 604800 }
      * })
      *
-     * const result = await payments.x402.getX402AccessToken(planId, agentId)
-     * const token = result.accessToken
+     * // Pattern B — reuse existing delegation
+     * const result = await payments.x402.getX402AccessToken(planId, agentId, {
+     *   delegationConfig: { delegationId: 'existing-delegation-uuid' }
+     * })
      * ```
      */
-    async getX402AccessToken(planId, agentId, redemptionLimit, orderLimit, expiration, tokenOptions) {
+    async getX402AccessToken(planId, agentId, tokenOptions) {
         const urlPath = API_URL_CREATE_PERMISSION;
         const url = new URL(urlPath, this.environment.backend);
         const scheme = tokenOptions?.scheme ?? 'nvm:erc4337';
         const network = tokenOptions?.network ?? getDefaultNetwork(scheme, this.environmentName);
+        // Validate delegationConfig is provided — the backend requires it for token generation
+        if (!tokenOptions?.delegationConfig) {
+            throw PaymentsError.validation(`delegationConfig is required for ${scheme} token generation. ` +
+                'Provide delegationConfig.delegationId to reuse an existing delegation, ' +
+                'or delegationConfig.spendingLimitCents + durationSecs to auto-create one.');
+        }
         // Build x402-aligned request body
         const body = {
             accepted: {
@@ -71,31 +77,15 @@ export class X402TokenAPI extends BasePaymentsAPI {
                 },
             },
         };
-        // Add delegation config for card-delegation scheme
-        if (scheme === 'nvm:card-delegation' && tokenOptions?.delegationConfig) {
+        // Add delegation config for both erc4337 and card-delegation schemes
+        if (tokenOptions?.delegationConfig) {
             body.delegationConfig = tokenOptions.delegationConfig;
         }
-        // Add session key config if any options are provided (erc4337 only)
-        if (scheme === 'nvm:erc4337') {
-            const sessionKeyConfig = {};
-            if (redemptionLimit !== undefined) {
-                sessionKeyConfig.redemptionLimit = redemptionLimit;
-            }
-            if (orderLimit !== undefined) {
-                sessionKeyConfig.orderLimit = orderLimit;
-            }
-            if (expiration !== undefined) {
-                sessionKeyConfig.expiration = expiration;
-            }
-            if (Object.keys(sessionKeyConfig).length > 0) {
-                body.sessionKeyConfig = sessionKeyConfig;
-            }
-        }
         const options = this.getBackendHTTPOptions('POST', body);
         try {
             const response = await fetch(url, options);
             if (!response.ok) {
-                let errorMessage = 'Failed to create X402 permission';
+                let errorMessage = 'Failed to create X402 delegation token';
                 try {
                     const errorData = await response.json();
                     errorMessage = errorData.message || errorMessage;
@@ -111,7 +101,7 @@ export class X402TokenAPI extends BasePaymentsAPI {
             if (error instanceof PaymentsError) {
                 throw error;
             }
-            throw PaymentsError.internal(`Network error while creating X402 permission: ${error instanceof Error ? error.message : String(error)}`);
+            throw PaymentsError.internal(`Network error while creating X402 delegation token: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
 }

package/dist/x402/token.js.map

@@ -1 +1 @@
-{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/x402/token.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * X402 Token Generation API.\n *\n * Provides X402 access token generation functionality for subscribers.\n * Tokens are used to authorize payment verification and settlement.\n */\n\nimport { BasePaymentsAPI } from '../api/base-payments.js'\nimport { API_URL_CREATE_PERMISSION } from '../api/nvm-api.js'\nimport { PaymentsError } from '../common/payments.error.js'\nimport { PaymentOptions, X402TokenOptions, getDefaultNetwork } from '../common/types.js'\n\n/**\n * X402 Token API for generating access tokens.\n *\n * Handles X402 access token generation for subscribers to authorize\n * payment operations with AI agents.\n */\nexport class X402TokenAPI extends BasePaymentsAPI {\n  /**\n   * Get a singleton instance of the X402TokenAPI class.\n   *\n   * @param options - The options to initialize the API\n   * @returns The instance of the X402TokenAPI class\n   */\n  static getInstance(options: PaymentOptions): X402TokenAPI {\n    return new X402TokenAPI(options)\n  }\n\n  /**\n   * Create a permission and get an X402 access token for the given plan.\n   *\n   * This token allows the agent to verify and settle permissions on behalf\n   * of the subscriber. The token contains cryptographically signed session keys\n   * that delegate specific permissions (order, burn) to the agent.\n   *\n   * @param planId - The unique identifier of the payment plan\n   * @param agentId - The unique identifier of the AI agent (optional). If provided, permissions are restricted to that specific agent.\n   * @param redemptionLimit - Maximum number of interactions/redemptions allowed (optional)\n   * @param orderLimit - Maximum spend limit in token units (wei) for ordering (optional)\n   * @param expiration - Expiration date in ISO 8601 format, e.g. \"2025-02-01T10:00:00Z\" (optional)\n   * @returns A promise that resolves to an object containing:\n   *   - accessToken: The X402 access token string\n   *   - Additional metadata about the token\n   *\n   * @throws PaymentsError if the request fails\n   *\n   * @example\n   * ```typescript\n   * import { Payments } from '@nevermined-io/payments'\n   *\n   * const payments = Payments.getInstance({\n   *   nvmApiKey: 'nvm:subscriber-key',\n   *   environment: 'sandbox'\n   * })\n   *\n   * const result = await payments.x402.getX402AccessToken(planId, agentId)\n   * const token = result.accessToken\n   * ```\n   */\n  async getX402AccessToken(\n    planId: string,\n    agentId?: string,\n    redemptionLimit?: number,\n    orderLimit?: string,\n    expiration?: string,\n    tokenOptions?: X402TokenOptions,\n  ): Promise<{ accessToken: string;[key: string]: any }> {\n    const urlPath = API_URL_CREATE_PERMISSION\n    const url = new URL(urlPath, this.environment.backend)\n\n    const scheme = tokenOptions?.scheme ?? 'nvm:erc4337'\n    const network = tokenOptions?.network ?? getDefaultNetwork(scheme, this.environmentName)\n\n    // Build x402-aligned request body\n    const body: Record<string, any> = {\n      accepted: {\n        scheme,\n        network,\n        planId,\n        extra: {\n          ...(agentId && { agentId }),\n        },\n      },\n    }\n\n    // Add delegation config for card-delegation scheme\n    if (scheme === 'nvm:card-delegation' && tokenOptions?.delegationConfig) {\n      body.delegationConfig = tokenOptions.delegationConfig\n    }\n\n    // Add session key config if any options are provided (erc4337 only)\n    if (scheme === 'nvm:erc4337') {\n      const sessionKeyConfig: Record<string, any> = {}\n      if (redemptionLimit !== undefined) {\n        sessionKeyConfig.redemptionLimit = redemptionLimit\n      }\n      if (orderLimit !== undefined) {\n        sessionKeyConfig.orderLimit = orderLimit\n      }\n      if (expiration !== undefined) {\n        sessionKeyConfig.expiration = expiration\n      }\n      if (Object.keys(sessionKeyConfig).length > 0) {\n        body.sessionKeyConfig = sessionKeyConfig\n      }\n    }\n\n    const options = this.getBackendHTTPOptions('POST', body)\n\n    try {\n      const response = await fetch(url, options)\n      if (!response.ok) {\n        let errorMessage = 'Failed to create X402 permission'\n        try {\n          const errorData = await response.json()\n          errorMessage = errorData.message || errorMessage\n        } catch {\n          // Use default error message\n        }\n        throw PaymentsError.internal(`${errorMessage} (HTTP ${response.status})`)\n      }\n      return await response.json()\n    } catch (error) {\n      if (error instanceof PaymentsError) {\n        throw error\n      }\n      throw PaymentsError.internal(\n        `Network error while creating X402 permission: ${error instanceof Error ? error.message : String(error)}`,\n      )\n    }\n  }\n}\n"]}
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/x402/token.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAC3D,OAAO,EAAoC,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAExF;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,eAAe;IAC/C;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,OAAuB;QACxC,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,CAAA;IAClC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,KAAK,CAAC,kBAAkB,CACtB,MAAc,EACd,OAAgB,EAChB,YAA+B;QAE/B,MAAM,OAAO,GAAG,yBAAyB,CAAA;QACzC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;QAEtD,MAAM,MAAM,GAAG,YAAY,EAAE,MAAM,IAAI,aAAa,CAAA;QACpD,MAAM,OAAO,GAAG,YAAY,EAAE,OAAO,IAAI,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,eAAe,CAAC,CAAA;QAExF,uFAAuF;QACvF,IAAI,CAAC,YAAY,EAAE,gBAAgB,EAAE,CAAC;YACpC,MAAM,aAAa,CAAC,UAAU,CAC5B,oCAAoC,MAAM,qBAAqB;gBAC7D,yEAAyE;gBACzE,2EAA2E,CAC9E,CAAA;QACH,CAAC;QAED,kCAAkC;QAClC,MAAM,IAAI,GAAwB;YAChC,QAAQ,EAAE;gBACR,MAAM;gBACN,OAAO;gBACP,MAAM;gBACN,KAAK,EAAE;oBACL,GAAG,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,CAAC;iBAC5B;aACF;SACF,CAAA;QAED,qEAAqE;QACrE,IAAI,YAAY,EAAE,gBAAgB,EAAE,CAAC;YACnC,IAAI,CAAC,gBAAgB,GAAG,YAAY,CAAC,gBAAgB,CAAA;QACvD,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QAExD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;YAC1C,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,IAAI,YAAY,GAAG,wCAAwC,CAAA;gBAC3D,IAAI,CAAC;oBACH,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;oBACvC,YAAY,GAAG,SAAS,CAAC,OAAO,IAAI,YAAY,CAAA;gBAClD,CAAC;gBAAC,MAAM,CAAC;oBACP,4BAA4B;gBAC9B,CAAC;gBACD,MAAM,aAAa,CAAC,QAAQ,CAAC,GAAG,YAAY,UAAU,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAA;YAC3E,CAAC;YACD,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;QAC9B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;gBACnC,MAAM,KAAK,CAAA;YACb,CAAC;YACD,MAAM,aAAa,CAAC,QAAQ,CAC1B,uDAAuD,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAChH,CAAA;QACH,CAAC;IACH,CAAC;CACF","sourcesContent":["/**\n * X402 Token Generation API.\n *\n * Provides X402 access token generation functionality for subscribers.\n * Tokens are used to authorize payment verification and settlement.\n */\n\nimport { BasePaymentsAPI } from '../api/base-payments.js'\nimport { API_URL_CREATE_PERMISSION } from '../api/nvm-api.js'\nimport { PaymentsError } from '../common/payments.error.js'\nimport { PaymentOptions, X402TokenOptions, getDefaultNetwork } from '../common/types.js'\n\n/**\n * X402 Token API for generating access tokens.\n *\n * Handles X402 access token generation for subscribers to authorize\n * payment operations with AI agents.\n */\nexport class X402TokenAPI extends BasePaymentsAPI {\n  /**\n   * Get a singleton instance of the X402TokenAPI class.\n   *\n   * @param options - The options to initialize the API\n   * @returns The instance of the X402TokenAPI class\n   */\n  static getInstance(options: PaymentOptions): X402TokenAPI {\n    return new X402TokenAPI(options)\n  }\n\n  /**\n   * Create a delegation and get an X402 access token for the given plan.\n   *\n   * This token allows the agent to verify and settle delegations on behalf\n   * of the subscriber.\n   *\n   * For erc4337 scheme, you must pass `tokenOptions.delegationConfig` with either:\n   * - `delegationId` to reuse an existing delegation, or\n   * - `spendingLimitCents` + `durationSecs` to auto-create a new one.\n   *\n   * @param planId - The unique identifier of the payment plan\n   * @param agentId - The unique identifier of the AI agent (optional)\n   * @param tokenOptions - Options controlling scheme and delegation behavior (optional)\n   * @returns A promise that resolves to an object containing:\n   *   - accessToken: The X402 access token string\n   *\n   * @throws PaymentsError if the request fails\n   *\n   * @example\n   * ```typescript\n   * // Pattern A — auto-create delegation\n   * const result = await payments.x402.getX402AccessToken(planId, agentId, {\n   *   delegationConfig: { spendingLimitCents: 10000, durationSecs: 604800 }\n   * })\n   *\n   * // Pattern B — reuse existing delegation\n   * const result = await payments.x402.getX402AccessToken(planId, agentId, {\n   *   delegationConfig: { delegationId: 'existing-delegation-uuid' }\n   * })\n   * ```\n   */\n  async getX402AccessToken(\n    planId: string,\n    agentId?: string,\n    tokenOptions?: X402TokenOptions,\n  ): Promise<{ accessToken: string; [key: string]: any }> {\n    const urlPath = API_URL_CREATE_PERMISSION\n    const url = new URL(urlPath, this.environment.backend)\n\n    const scheme = tokenOptions?.scheme ?? 'nvm:erc4337'\n    const network = tokenOptions?.network ?? getDefaultNetwork(scheme, this.environmentName)\n\n    // Validate delegationConfig is provided — the backend requires it for token generation\n    if (!tokenOptions?.delegationConfig) {\n      throw PaymentsError.validation(\n        `delegationConfig is required for ${scheme} token generation. ` +\n          'Provide delegationConfig.delegationId to reuse an existing delegation, ' +\n          'or delegationConfig.spendingLimitCents + durationSecs to auto-create one.',\n      )\n    }\n\n    // Build x402-aligned request body\n    const body: Record<string, any> = {\n      accepted: {\n        scheme,\n        network,\n        planId,\n        extra: {\n          ...(agentId && { agentId }),\n        },\n      },\n    }\n\n    // Add delegation config for both erc4337 and card-delegation schemes\n    if (tokenOptions?.delegationConfig) {\n      body.delegationConfig = tokenOptions.delegationConfig\n    }\n\n    const options = this.getBackendHTTPOptions('POST', body)\n\n    try {\n      const response = await fetch(url, options)\n      if (!response.ok) {\n        let errorMessage = 'Failed to create X402 delegation token'\n        try {\n          const errorData = await response.json()\n          errorMessage = errorData.message || errorMessage\n        } catch {\n          // Use default error message\n        }\n        throw PaymentsError.internal(`${errorMessage} (HTTP ${response.status})`)\n      }\n      return await response.json()\n    } catch (error) {\n      if (error instanceof PaymentsError) {\n        throw error\n      }\n      throw PaymentsError.internal(\n        `Network error while creating X402 delegation token: ${error instanceof Error ? error.message : String(error)}`,\n      )\n    }\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nevermined-io/payments",
-  "version": "1.1.18",
+  "version": "1.3.2",
   "description": "Typescript SDK to interact with the Nevermined Payments Protocol",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",