uvd-x402-sdk 2.22.0 → 2.24.0

package/dist/backend/index.d.mts

@@ -1037,7 +1037,7 @@ declare function escrowTimeRemaining(escrow: EscrowPayment): number;
  */
 declare const ERC8004_EXTENSION_ID = "8004-reputation";
 /**
- * ERC-8004 contract addresses per network (12 networks)
+ * ERC-8004 contract addresses per network (16 networks)
  */
 declare const ERC8004_CONTRACTS: Record<string, {
     identityRegistry?: string;
@@ -1048,9 +1048,9 @@ declare const ERC8004_CONTRACTS: Record<string, {
  * Network type for ERC-8004 operations
  */
 /**
- * Network type for ERC-8004 operations (12 networks)
+ * Network type for ERC-8004 operations (16 networks)
  */
-type Erc8004Network = 'ethereum' | 'base-mainnet' | 'polygon' | 'arbitrum' | 'celo' | 'bsc' | 'monad' | 'ethereum-sepolia' | 'base-sepolia' | 'polygon-amoy' | 'arbitrum-sepolia' | 'celo-sepolia';
+type Erc8004Network = 'ethereum' | 'base-mainnet' | 'polygon' | 'arbitrum' | 'optimism' | 'celo' | 'bsc' | 'monad' | 'avalanche' | 'ethereum-sepolia' | 'base-sepolia' | 'polygon-amoy' | 'arbitrum-sepolia' | 'optimism-sepolia' | 'celo-sepolia' | 'avalanche-fuji';
 /**
  * Proof of payment returned when settling with ERC-8004 extension
  */
@@ -1643,6 +1643,22 @@ interface AdvancedTransactionResult {
     gasUsed?: number;
     error?: string;
 }
+/**
+ * Response from the facilitator's /escrow/state endpoint.
+ * Represents the on-chain state of an escrow for a given paymentInfo + payer.
+ */
+interface EscrowStateResponse {
+    /** Whether the payment has already been collected (released) */
+    hasCollectedPayment: boolean;
+    /** Amount that can still be captured/released (in atomic units) */
+    capturableAmount: string;
+    /** Amount that can still be refunded to the payer (in atomic units) */
+    refundableAmount: string;
+    /** Keccak256 hash of the paymentInfo struct */
+    paymentInfoHash: string;
+    /** Network in CAIP-2 format (e.g., "eip155:8453") */
+    network: string;
+}
 /**
  * Contract addresses configuration for AdvancedEscrowClient.
  *
@@ -1792,6 +1808,69 @@ declare class AdvancedEscrowClient {
      * @param amount - Amount to refund (defaults to maxAmount)
      */
     refundInEscrow(paymentInfo: AdvancedPaymentInfo, amount?: string): Promise<AdvancedTransactionResult>;
+    /**
+     * GASLESS RELEASE: Release escrowed funds via the facilitator.
+     *
+     * Instead of calling the PaymentOperator contract directly (which requires
+     * gas), this sends a release request to the facilitator, which submits
+     * the transaction on your behalf.
+     *
+     * @param paymentInfo - PaymentInfo from the authorize step
+     * @param amount - Amount to release in atomic units (defaults to maxAmount)
+     * @returns Transaction result from the facilitator
+     *
+     * @example
+     * ```typescript
+     * const pi = client.buildPaymentInfo('0xWorker...', '5000000', 'standard');
+     * await client.authorize(pi);
+     * // Worker completes task...
+     * const result = await client.releaseViaFacilitator(pi);
+     * console.log(result.transactionHash);
+     * ```
+     */
+    releaseViaFacilitator(paymentInfo: AdvancedPaymentInfo, amount?: string): Promise<AdvancedTransactionResult>;
+    /**
+     * GASLESS REFUND: Refund escrowed funds via the facilitator.
+     *
+     * Instead of calling the PaymentOperator contract directly (which requires
+     * gas), this sends a refundInEscrow request to the facilitator, which
+     * submits the transaction on your behalf.
+     *
+     * @param paymentInfo - PaymentInfo from the authorize step
+     * @param amount - Amount to refund in atomic units (defaults to maxAmount)
+     * @returns Transaction result from the facilitator
+     *
+     * @example
+     * ```typescript
+     * const pi = client.buildPaymentInfo('0xWorker...', '5000000', 'standard');
+     * await client.authorize(pi);
+     * // Task cancelled...
+     * const result = await client.refundViaFacilitator(pi);
+     * console.log(result.transactionHash);
+     * ```
+     */
+    refundViaFacilitator(paymentInfo: AdvancedPaymentInfo, amount?: string): Promise<AdvancedTransactionResult>;
+    /**
+     * QUERY ESCROW STATE: Read on-chain escrow state via the facilitator.
+     *
+     * This is a read-only operation that queries the facilitator for the
+     * current escrow state without requiring gas or a signer.
+     *
+     * @param paymentInfo - PaymentInfo to query state for
+     * @returns Escrow state including capturable/refundable amounts
+     *
+     * @example
+     * ```typescript
+     * const pi = client.buildPaymentInfo('0xWorker...', '5000000', 'standard');
+     * await client.authorize(pi);
+     *
+     * const state = await client.queryEscrowState(pi);
+     * console.log(`Capturable: ${state.capturableAmount}`);
+     * console.log(`Refundable: ${state.refundableAmount}`);
+     * console.log(`Already collected: ${state.hasCollectedPayment}`);
+     * ```
+     */
+    queryEscrowState(paymentInfo: AdvancedPaymentInfo): Promise<EscrowStateResponse>;
     /**
      * CHARGE: Direct instant payment (no escrow hold).
      *
@@ -1825,4 +1904,4 @@ declare class AdvancedEscrowClient {
     refundPostEscrow(paymentInfo: AdvancedPaymentInfo, amount?: string, tokenCollector?: string, collectorData?: string): Promise<AdvancedTransactionResult>;
 }
 
-export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, type MetadataEntryParam, OPERATOR_ABI, PAYMENT_INFO_TYPEHASH, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isEscrowExpired, isEscrowSupportedOnChain, parsePaymentHeader };
+export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, type MetadataEntryParam, OPERATOR_ABI, PAYMENT_INFO_TYPEHASH, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isEscrowExpired, isEscrowSupportedOnChain, parsePaymentHeader };

package/dist/backend/index.d.ts

@@ -1037,7 +1037,7 @@ declare function escrowTimeRemaining(escrow: EscrowPayment): number;
  */
 declare const ERC8004_EXTENSION_ID = "8004-reputation";
 /**
- * ERC-8004 contract addresses per network (12 networks)
+ * ERC-8004 contract addresses per network (16 networks)
  */
 declare const ERC8004_CONTRACTS: Record<string, {
     identityRegistry?: string;
@@ -1048,9 +1048,9 @@ declare const ERC8004_CONTRACTS: Record<string, {
  * Network type for ERC-8004 operations
  */
 /**
- * Network type for ERC-8004 operations (12 networks)
+ * Network type for ERC-8004 operations (16 networks)
  */
-type Erc8004Network = 'ethereum' | 'base-mainnet' | 'polygon' | 'arbitrum' | 'celo' | 'bsc' | 'monad' | 'ethereum-sepolia' | 'base-sepolia' | 'polygon-amoy' | 'arbitrum-sepolia' | 'celo-sepolia';
+type Erc8004Network = 'ethereum' | 'base-mainnet' | 'polygon' | 'arbitrum' | 'optimism' | 'celo' | 'bsc' | 'monad' | 'avalanche' | 'ethereum-sepolia' | 'base-sepolia' | 'polygon-amoy' | 'arbitrum-sepolia' | 'optimism-sepolia' | 'celo-sepolia' | 'avalanche-fuji';
 /**
  * Proof of payment returned when settling with ERC-8004 extension
  */
@@ -1643,6 +1643,22 @@ interface AdvancedTransactionResult {
     gasUsed?: number;
     error?: string;
 }
+/**
+ * Response from the facilitator's /escrow/state endpoint.
+ * Represents the on-chain state of an escrow for a given paymentInfo + payer.
+ */
+interface EscrowStateResponse {
+    /** Whether the payment has already been collected (released) */
+    hasCollectedPayment: boolean;
+    /** Amount that can still be captured/released (in atomic units) */
+    capturableAmount: string;
+    /** Amount that can still be refunded to the payer (in atomic units) */
+    refundableAmount: string;
+    /** Keccak256 hash of the paymentInfo struct */
+    paymentInfoHash: string;
+    /** Network in CAIP-2 format (e.g., "eip155:8453") */
+    network: string;
+}
 /**
  * Contract addresses configuration for AdvancedEscrowClient.
  *
@@ -1792,6 +1808,69 @@ declare class AdvancedEscrowClient {
      * @param amount - Amount to refund (defaults to maxAmount)
      */
     refundInEscrow(paymentInfo: AdvancedPaymentInfo, amount?: string): Promise<AdvancedTransactionResult>;
+    /**
+     * GASLESS RELEASE: Release escrowed funds via the facilitator.
+     *
+     * Instead of calling the PaymentOperator contract directly (which requires
+     * gas), this sends a release request to the facilitator, which submits
+     * the transaction on your behalf.
+     *
+     * @param paymentInfo - PaymentInfo from the authorize step
+     * @param amount - Amount to release in atomic units (defaults to maxAmount)
+     * @returns Transaction result from the facilitator
+     *
+     * @example
+     * ```typescript
+     * const pi = client.buildPaymentInfo('0xWorker...', '5000000', 'standard');
+     * await client.authorize(pi);
+     * // Worker completes task...
+     * const result = await client.releaseViaFacilitator(pi);
+     * console.log(result.transactionHash);
+     * ```
+     */
+    releaseViaFacilitator(paymentInfo: AdvancedPaymentInfo, amount?: string): Promise<AdvancedTransactionResult>;
+    /**
+     * GASLESS REFUND: Refund escrowed funds via the facilitator.
+     *
+     * Instead of calling the PaymentOperator contract directly (which requires
+     * gas), this sends a refundInEscrow request to the facilitator, which
+     * submits the transaction on your behalf.
+     *
+     * @param paymentInfo - PaymentInfo from the authorize step
+     * @param amount - Amount to refund in atomic units (defaults to maxAmount)
+     * @returns Transaction result from the facilitator
+     *
+     * @example
+     * ```typescript
+     * const pi = client.buildPaymentInfo('0xWorker...', '5000000', 'standard');
+     * await client.authorize(pi);
+     * // Task cancelled...
+     * const result = await client.refundViaFacilitator(pi);
+     * console.log(result.transactionHash);
+     * ```
+     */
+    refundViaFacilitator(paymentInfo: AdvancedPaymentInfo, amount?: string): Promise<AdvancedTransactionResult>;
+    /**
+     * QUERY ESCROW STATE: Read on-chain escrow state via the facilitator.
+     *
+     * This is a read-only operation that queries the facilitator for the
+     * current escrow state without requiring gas or a signer.
+     *
+     * @param paymentInfo - PaymentInfo to query state for
+     * @returns Escrow state including capturable/refundable amounts
+     *
+     * @example
+     * ```typescript
+     * const pi = client.buildPaymentInfo('0xWorker...', '5000000', 'standard');
+     * await client.authorize(pi);
+     *
+     * const state = await client.queryEscrowState(pi);
+     * console.log(`Capturable: ${state.capturableAmount}`);
+     * console.log(`Refundable: ${state.refundableAmount}`);
+     * console.log(`Already collected: ${state.hasCollectedPayment}`);
+     * ```
+     */
+    queryEscrowState(paymentInfo: AdvancedPaymentInfo): Promise<EscrowStateResponse>;
     /**
      * CHARGE: Direct instant payment (no escrow hold).
      *
@@ -1825,4 +1904,4 @@ declare class AdvancedEscrowClient {
     refundPostEscrow(paymentInfo: AdvancedPaymentInfo, amount?: string, tokenCollector?: string, collectorData?: string): Promise<AdvancedTransactionResult>;
 }
 
-export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, type MetadataEntryParam, OPERATOR_ABI, PAYMENT_INFO_TYPEHASH, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isEscrowExpired, isEscrowSupportedOnChain, parsePaymentHeader };
+export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, type MetadataEntryParam, OPERATOR_ABI, PAYMENT_INFO_TYPEHASH, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isEscrowExpired, isEscrowSupportedOnChain, parsePaymentHeader };

package/dist/backend/index.js

@@ -1921,7 +1921,7 @@ var TESTNET_IDENTITY = "0x8004A818BFB912233c491871b3d84c89A494BD9e";
 var TESTNET_REPUTATION = "0x8004B663056A597Dffe9eCcC1965A193B7388713";
 var TESTNET_VALIDATION = "0x8004Cb1BF31DAf7788923b405b754f57acEB4272";
 var ERC8004_CONTRACTS = {
-  // Mainnets (7)
+  // Mainnets (9)
   ethereum: {
     identityRegistry: MAINNET_IDENTITY,
     reputationRegistry: MAINNET_REPUTATION
@@ -1938,6 +1938,10 @@ var ERC8004_CONTRACTS = {
     identityRegistry: MAINNET_IDENTITY,
     reputationRegistry: MAINNET_REPUTATION
   },
+  optimism: {
+    identityRegistry: MAINNET_IDENTITY,
+    reputationRegistry: MAINNET_REPUTATION
+  },
   celo: {
     identityRegistry: MAINNET_IDENTITY,
     reputationRegistry: MAINNET_REPUTATION
@@ -1950,7 +1954,11 @@ var ERC8004_CONTRACTS = {
     identityRegistry: MAINNET_IDENTITY,
     reputationRegistry: MAINNET_REPUTATION
   },
-  // Testnets (5)
+  avalanche: {
+    identityRegistry: MAINNET_IDENTITY,
+    reputationRegistry: MAINNET_REPUTATION
+  },
+  // Testnets (7)
   "ethereum-sepolia": {
     identityRegistry: TESTNET_IDENTITY,
     reputationRegistry: TESTNET_REPUTATION,
@@ -1971,10 +1979,20 @@ var ERC8004_CONTRACTS = {
     reputationRegistry: TESTNET_REPUTATION,
     validationRegistry: TESTNET_VALIDATION
   },
+  "optimism-sepolia": {
+    identityRegistry: TESTNET_IDENTITY,
+    reputationRegistry: TESTNET_REPUTATION,
+    validationRegistry: TESTNET_VALIDATION
+  },
   "celo-sepolia": {
     identityRegistry: TESTNET_IDENTITY,
     reputationRegistry: TESTNET_REPUTATION,
     validationRegistry: TESTNET_VALIDATION
+  },
+  "avalanche-fuji": {
+    identityRegistry: TESTNET_IDENTITY,
+    reputationRegistry: TESTNET_REPUTATION,
+    validationRegistry: TESTNET_VALIDATION
   }
 };
 var Erc8004Client = class {
@@ -2846,6 +2864,206 @@ var AdvancedEscrowClient = class {
       return { success: false, error: e.message || String(e) };
     }
   }
+  // ==========================================================================
+  // GASLESS FACILITATOR METHODS
+  // ==========================================================================
+  /**
+   * GASLESS RELEASE: Release escrowed funds via the facilitator.
+   *
+   * Instead of calling the PaymentOperator contract directly (which requires
+   * gas), this sends a release request to the facilitator, which submits
+   * the transaction on your behalf.
+   *
+   * @param paymentInfo - PaymentInfo from the authorize step
+   * @param amount - Amount to release in atomic units (defaults to maxAmount)
+   * @returns Transaction result from the facilitator
+   *
+   * @example
+   * ```typescript
+   * const pi = client.buildPaymentInfo('0xWorker...', '5000000', 'standard');
+   * await client.authorize(pi);
+   * // Worker completes task...
+   * const result = await client.releaseViaFacilitator(pi);
+   * console.log(result.transactionHash);
+   * ```
+   */
+  async releaseViaFacilitator(paymentInfo, amount) {
+    if (!this.payerAddress) await this.init();
+    try {
+      const payload = {
+        x402Version: 2,
+        scheme: "escrow",
+        action: "release",
+        payload: {
+          paymentInfo: {
+            operator: paymentInfo.operator,
+            receiver: paymentInfo.receiver,
+            token: paymentInfo.token,
+            maxAmount: paymentInfo.maxAmount,
+            preApprovalExpiry: paymentInfo.preApprovalExpiry,
+            authorizationExpiry: paymentInfo.authorizationExpiry,
+            refundExpiry: paymentInfo.refundExpiry,
+            minFeeBps: paymentInfo.minFeeBps,
+            maxFeeBps: paymentInfo.maxFeeBps,
+            feeReceiver: paymentInfo.feeReceiver,
+            salt: paymentInfo.salt
+          },
+          payer: this.payerAddress,
+          amount: amount || paymentInfo.maxAmount
+        },
+        paymentRequirements: {
+          scheme: "escrow",
+          network: `eip155:${this.chainId}`,
+          extra: {
+            escrowAddress: this.contracts.escrow,
+            operatorAddress: this.contracts.operator,
+            tokenCollector: this.contracts.tokenCollector
+          }
+        }
+      };
+      const response = await fetch(`${this.facilitatorUrl}/settle`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload)
+      });
+      const result = await response.json();
+      if (result.success) {
+        return {
+          success: true,
+          transactionHash: result.transaction || result.transactionHash || result.transaction_hash
+        };
+      }
+      return { success: false, error: result.errorReason || result.error || "Release failed" };
+    } catch (e) {
+      return { success: false, error: e.message || String(e) };
+    }
+  }
+  /**
+   * GASLESS REFUND: Refund escrowed funds via the facilitator.
+   *
+   * Instead of calling the PaymentOperator contract directly (which requires
+   * gas), this sends a refundInEscrow request to the facilitator, which
+   * submits the transaction on your behalf.
+   *
+   * @param paymentInfo - PaymentInfo from the authorize step
+   * @param amount - Amount to refund in atomic units (defaults to maxAmount)
+   * @returns Transaction result from the facilitator
+   *
+   * @example
+   * ```typescript
+   * const pi = client.buildPaymentInfo('0xWorker...', '5000000', 'standard');
+   * await client.authorize(pi);
+   * // Task cancelled...
+   * const result = await client.refundViaFacilitator(pi);
+   * console.log(result.transactionHash);
+   * ```
+   */
+  async refundViaFacilitator(paymentInfo, amount) {
+    if (!this.payerAddress) await this.init();
+    try {
+      const payload = {
+        x402Version: 2,
+        scheme: "escrow",
+        action: "refundInEscrow",
+        payload: {
+          paymentInfo: {
+            operator: paymentInfo.operator,
+            receiver: paymentInfo.receiver,
+            token: paymentInfo.token,
+            maxAmount: paymentInfo.maxAmount,
+            preApprovalExpiry: paymentInfo.preApprovalExpiry,
+            authorizationExpiry: paymentInfo.authorizationExpiry,
+            refundExpiry: paymentInfo.refundExpiry,
+            minFeeBps: paymentInfo.minFeeBps,
+            maxFeeBps: paymentInfo.maxFeeBps,
+            feeReceiver: paymentInfo.feeReceiver,
+            salt: paymentInfo.salt
+          },
+          payer: this.payerAddress,
+          amount: amount || paymentInfo.maxAmount
+        },
+        paymentRequirements: {
+          scheme: "escrow",
+          network: `eip155:${this.chainId}`,
+          extra: {
+            escrowAddress: this.contracts.escrow,
+            operatorAddress: this.contracts.operator,
+            tokenCollector: this.contracts.tokenCollector
+          }
+        }
+      };
+      const response = await fetch(`${this.facilitatorUrl}/settle`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload)
+      });
+      const result = await response.json();
+      if (result.success) {
+        return {
+          success: true,
+          transactionHash: result.transaction || result.transactionHash || result.transaction_hash
+        };
+      }
+      return { success: false, error: result.errorReason || result.error || "Refund failed" };
+    } catch (e) {
+      return { success: false, error: e.message || String(e) };
+    }
+  }
+  /**
+   * QUERY ESCROW STATE: Read on-chain escrow state via the facilitator.
+   *
+   * This is a read-only operation that queries the facilitator for the
+   * current escrow state without requiring gas or a signer.
+   *
+   * @param paymentInfo - PaymentInfo to query state for
+   * @returns Escrow state including capturable/refundable amounts
+   *
+   * @example
+   * ```typescript
+   * const pi = client.buildPaymentInfo('0xWorker...', '5000000', 'standard');
+   * await client.authorize(pi);
+   *
+   * const state = await client.queryEscrowState(pi);
+   * console.log(`Capturable: ${state.capturableAmount}`);
+   * console.log(`Refundable: ${state.refundableAmount}`);
+   * console.log(`Already collected: ${state.hasCollectedPayment}`);
+   * ```
+   */
+  async queryEscrowState(paymentInfo) {
+    if (!this.payerAddress) await this.init();
+    const payload = {
+      paymentInfo: {
+        operator: paymentInfo.operator,
+        receiver: paymentInfo.receiver,
+        token: paymentInfo.token,
+        maxAmount: paymentInfo.maxAmount,
+        preApprovalExpiry: paymentInfo.preApprovalExpiry,
+        authorizationExpiry: paymentInfo.authorizationExpiry,
+        refundExpiry: paymentInfo.refundExpiry,
+        minFeeBps: paymentInfo.minFeeBps,
+        maxFeeBps: paymentInfo.maxFeeBps,
+        feeReceiver: paymentInfo.feeReceiver,
+        salt: paymentInfo.salt
+      },
+      payer: this.payerAddress,
+      network: `eip155:${this.chainId}`,
+      extra: {
+        escrowAddress: this.contracts.escrow,
+        operatorAddress: this.contracts.operator,
+        tokenCollector: this.contracts.tokenCollector
+      }
+    };
+    const response = await fetch(`${this.facilitatorUrl}/escrow/state`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload)
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Escrow state query failed: ${response.status} - ${errorText}`);
+    }
+    return await response.json();
+  }
   /**
    * CHARGE: Direct instant payment (no escrow hold).
    *