@nullclear/x402-arbiter 1.1.1 → 1.2.0

package/dist/index.cjs

@@ -38,9 +38,15 @@ async function signX402Payment(signer, option, resourceUrl) {
     const account = (0, import_accounts.privateKeyToAccount)(signer);
     accountAddress = account.address;
     signTypedDataFn = (params) => account.signTypedData(params);
-  } else if (typeof signer === "object" && signer !== null && "signTypedData" in signer && "account" in signer && signer.account) {
-    const rawAccount = signer.account;
-    accountAddress = typeof rawAccount === "string" ? rawAccount : rawAccount.address;
+  } else if (typeof signer === "object" && signer !== null && "signTypedData" in signer) {
+    if ("account" in signer && signer.account) {
+      const rawAccount = signer.account;
+      accountAddress = typeof rawAccount === "string" ? rawAccount : rawAccount.address;
+    } else if ("address" in signer && signer.address) {
+      accountAddress = signer.address;
+    } else {
+      throw new Error("Signer object missing address");
+    }
     signTypedDataFn = (params) => signer.signTypedData(params);
   } else {
     throw new Error("Invalid signer provided to signX402Payment: must be private key or viem account/wallet client");
@@ -79,10 +85,14 @@ async function signX402Payment(signer, option, resourceUrl) {
       nonce: authorization.nonce
     }
   });
+  const acceptedOption = {
+    ...option,
+    extra: option.extra || { name: "USD Coin", version: "2" }
+  };
   const payload = {
     x402Version: 2,
     resource: resourceUrl ? { url: resourceUrl } : void 0,
-    accepted: option,
+    accepted: acceptedOption,
     payload: {
       signature,
       authorization
@@ -97,7 +107,7 @@ var NullClearClient = class {
   defaultChainId;
   customFetch;
   constructor(config = {}) {
-    this.arbiterUrl = (config.arbiterUrl || "https://arbiter.nullclear.dev").replace(/\/$/, "");
+    this.arbiterUrl = (config.arbiterUrl || "https://api.nullclear.dev").replace(/\/$/, "");
     this.defaultChainId = config.defaultChainId || 8453;
     this.customFetch = config.fetch || fetch;
   }
@@ -112,14 +122,29 @@ var NullClearClient = class {
     return data.data;
   }
   async clear(request) {
+    const headers = { "Content-Type": "application/json" };
+    if (!request.paymentSignatureHeader || request.paymentSignatureHeader === "free-trial") {
+      headers["x-nullclear-free-trial"] = "true";
+    }
     const res = await this.customFetch(`${this.arbiterUrl}/v1/clear`, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers,
       body: JSON.stringify(request)
     });
     const data = await res.json();
     return data;
   }
+  async safeFetch(targetUrl, init) {
+    return this.customFetch(`${this.arbiterUrl}/${targetUrl}`, init);
+  }
+  async createGateway(params) {
+    const res = await this.customFetch(`${this.arbiterUrl}/v1/gateways`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(params)
+    });
+    return res.json();
+  }
   async getKya(agentId, chainId) {
     const targetChainId = chainId || this.defaultChainId;
     const res = await this.customFetch(`${this.arbiterUrl}/v1/kya/${targetChainId}/${agentId}`);
@@ -220,9 +245,9 @@ function zodToJsonSchema(schema) {
       return {};
   }
 }
-function createNullClearFetch(config) {
+function createNullClearFetch(config = {}) {
   const chainId = config.chainId || 8453;
-  const arbiterUrl = (config.arbiterUrl || "https://arbiter.nullclear.dev").replace(/\/$/, "");
+  const arbiterUrl = (config.arbiterUrl || "https://api.nullclear.dev").replace(/\/$/, "");
   const defaultMinTrustScore = config.defaultMinTrustScore || 50;
   const customFetch = config.customFetch || fetch;
   return async function nullclearFetch(input, init) {
@@ -234,29 +259,33 @@ function createNullClearFetch(config) {
       return initialRes;
     }
     const paymentRequiredHeader = initialRes.headers.get("PAYMENT-REQUIRED") || initialRes.headers.get("payment-required");
-    if (!paymentRequiredHeader) {
-      return initialRes;
-    }
-    let paymentRequired;
-    try {
-      paymentRequired = (0, import_shared2.decodeBase64Json)(paymentRequiredHeader);
-    } catch {
-      return initialRes;
-    }
-    const targetNetwork = `eip155:${chainId}`;
-    const selectedOption = paymentRequired.accepts.find(
-      (opt) => opt.network === targetNetwork && opt.scheme === "exact"
-    );
-    if (!selectedOption) {
-      throw new Error(
-        `Seller does not accept payments on network ${targetNetwork}. Accepted: ${paymentRequired.accepts.map((a) => a.network).join(", ")}`
+    let paymentSignatureHeader;
+    if (config.accountOrPrivateKey && paymentRequiredHeader) {
+      let paymentRequired;
+      try {
+        paymentRequired = (0, import_shared2.decodeBase64Json)(paymentRequiredHeader);
+      } catch {
+        return initialRes;
+      }
+      const targetNetwork = `eip155:${chainId}`;
+      const selectedOption = paymentRequired.accepts.find(
+        (opt) => opt.network === targetNetwork && opt.scheme === "exact"
+      );
+      if (!selectedOption) {
+        throw new Error(
+          `Seller does not accept payments on network ${targetNetwork}. Accepted: ${paymentRequired.accepts.map((a) => a.network).join(", ")}`
+        );
+      }
+      paymentSignatureHeader = await signX402Payment(
+        config.accountOrPrivateKey,
+        selectedOption,
+        targetUrl
       );
+    } else if (!config.accountOrPrivateKey) {
+      paymentSignatureHeader = "free-trial";
+    } else {
+      return initialRes;
     }
-    const paymentSignatureHeader = await signX402Payment(
-      config.accountOrPrivateKey,
-      selectedOption,
-      targetUrl
-    );
     let jsonSchema;
     if (init?.nullclear?.schema) {
       if (init.nullclear.schema instanceof import_zod.z.ZodType) {
@@ -284,9 +313,13 @@ function createNullClearFetch(config) {
       fallbacks: init?.nullclear?.fallbacks,
       spendPolicy: init?.nullclear?.spendPolicy
     };
+    const clearHeaders = { "Content-Type": "application/json" };
+    if (paymentSignatureHeader === "free-trial") {
+      clearHeaders["x-nullclear-free-trial"] = "true";
+    }
     const arbiterRes = await customFetch(`${arbiterUrl}/v1/clear`, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: clearHeaders,
       body: JSON.stringify(clearPayload)
     });
     const arbiterData = await arbiterRes.json();

package/dist/index.d.cts

@@ -24,7 +24,7 @@ interface ClearRequest {
     method?: "GET" | "POST" | "PUT" | "DELETE";
     headers?: Record<string, string>;
     body?: unknown;
-    paymentSignatureHeader: string;
+    paymentSignatureHeader?: string;
     sellerAgentId?: string;
     minTrustScore?: number;
     twoPhaseRelease?: boolean;
@@ -35,12 +35,15 @@ interface ClearRequest {
 interface ClearResult<T = unknown> {
     cleared: boolean;
     settled: boolean;
+    tier?: string;
+    freeTrialRemaining?: number;
     clearingId?: string;
     buyerCharged: string;
     clearingFee?: string;
     settlementRouting?: string;
     transaction?: `0x${string}`;
     attestation?: unknown;
+    executionReceipt?: unknown;
     data?: T;
     stage?: string;
     error?: string;
@@ -61,6 +64,18 @@ declare class NullClearClient {
     constructor(config?: NullClearClientConfig);
     getScore(agentId: string, chainId?: number): Promise<any>;
     clear<T = unknown>(request: ClearRequest): Promise<ClearResult<T>>;
+    safeFetch(targetUrl: string, init?: RequestInit): Promise<Response>;
+    createGateway(params: {
+        upstreamUrl: string;
+        sellerAddress: string;
+        priceUsdc?: string;
+        priceAtomic?: string;
+        slug?: string;
+        description?: string;
+        category?: "data" | "security" | "oracle" | "ai";
+        validationPreset?: "DEFAULT_JSON" | "STRICT_NO_REFUSAL" | "CUSTOM";
+        customSchema?: Record<string, unknown>;
+    }): Promise<any>;
     getKya(agentId: string, chainId?: number): Promise<any>;
     attestKya(mandate: KYAMandate, chainId?: number, signature?: string, signerAddress?: `0x${string}`): Promise<any>;
 }
@@ -111,7 +126,7 @@ interface NullClearOptions {
     spendPolicy?: SpendPolicy;
 }
 interface NullClearFetchConfig {
-    accountOrPrivateKey: SignerInput;
+    accountOrPrivateKey?: SignerInput;
     chainId?: number;
     arbiterUrl?: string;
     defaultMinTrustScore?: number;
@@ -124,6 +139,6 @@ type NullClearRequestInit = RequestInit & {
  * Creates an enhanced fetch client that autonomously intercepts HTTP 402 Payment Required
  * and safely wraps the call in NullClear Deferred Non-Custodial Schema Escrow
  */
-declare function createNullClearFetch(config: NullClearFetchConfig): (input: RequestInfo | URL, init?: NullClearRequestInit) => Promise<Response>;
+declare function createNullClearFetch(config?: NullClearFetchConfig): (input: RequestInfo | URL, init?: NullClearRequestInit) => Promise<Response>;
 
 export { type ClearRequest, type ClearResult, NullClearClient, type NullClearClientConfig, NullClearEscrowAbortedError, type NullClearFetchConfig, type NullClearOptions, type NullClearRequestInit, type SignerInput, createNullClearFetch, signX402Payment, zodToJsonSchema };

package/dist/index.d.ts

@@ -24,7 +24,7 @@ interface ClearRequest {
     method?: "GET" | "POST" | "PUT" | "DELETE";
     headers?: Record<string, string>;
     body?: unknown;
-    paymentSignatureHeader: string;
+    paymentSignatureHeader?: string;
     sellerAgentId?: string;
     minTrustScore?: number;
     twoPhaseRelease?: boolean;
@@ -35,12 +35,15 @@ interface ClearRequest {
 interface ClearResult<T = unknown> {
     cleared: boolean;
     settled: boolean;
+    tier?: string;
+    freeTrialRemaining?: number;
     clearingId?: string;
     buyerCharged: string;
     clearingFee?: string;
     settlementRouting?: string;
     transaction?: `0x${string}`;
     attestation?: unknown;
+    executionReceipt?: unknown;
     data?: T;
     stage?: string;
     error?: string;
@@ -61,6 +64,18 @@ declare class NullClearClient {
     constructor(config?: NullClearClientConfig);
     getScore(agentId: string, chainId?: number): Promise<any>;
     clear<T = unknown>(request: ClearRequest): Promise<ClearResult<T>>;
+    safeFetch(targetUrl: string, init?: RequestInit): Promise<Response>;
+    createGateway(params: {
+        upstreamUrl: string;
+        sellerAddress: string;
+        priceUsdc?: string;
+        priceAtomic?: string;
+        slug?: string;
+        description?: string;
+        category?: "data" | "security" | "oracle" | "ai";
+        validationPreset?: "DEFAULT_JSON" | "STRICT_NO_REFUSAL" | "CUSTOM";
+        customSchema?: Record<string, unknown>;
+    }): Promise<any>;
     getKya(agentId: string, chainId?: number): Promise<any>;
     attestKya(mandate: KYAMandate, chainId?: number, signature?: string, signerAddress?: `0x${string}`): Promise<any>;
 }
@@ -111,7 +126,7 @@ interface NullClearOptions {
     spendPolicy?: SpendPolicy;
 }
 interface NullClearFetchConfig {
-    accountOrPrivateKey: SignerInput;
+    accountOrPrivateKey?: SignerInput;
     chainId?: number;
     arbiterUrl?: string;
     defaultMinTrustScore?: number;
@@ -124,6 +139,6 @@ type NullClearRequestInit = RequestInit & {
  * Creates an enhanced fetch client that autonomously intercepts HTTP 402 Payment Required
  * and safely wraps the call in NullClear Deferred Non-Custodial Schema Escrow
  */
-declare function createNullClearFetch(config: NullClearFetchConfig): (input: RequestInfo | URL, init?: NullClearRequestInit) => Promise<Response>;
+declare function createNullClearFetch(config?: NullClearFetchConfig): (input: RequestInfo | URL, init?: NullClearRequestInit) => Promise<Response>;
 
 export { type ClearRequest, type ClearResult, NullClearClient, type NullClearClientConfig, NullClearEscrowAbortedError, type NullClearFetchConfig, type NullClearOptions, type NullClearRequestInit, type SignerInput, createNullClearFetch, signX402Payment, zodToJsonSchema };

package/dist/index.js

@@ -12,9 +12,15 @@ async function signX402Payment(signer, option, resourceUrl) {
     const account = privateKeyToAccount(signer);
     accountAddress = account.address;
     signTypedDataFn = (params) => account.signTypedData(params);
-  } else if (typeof signer === "object" && signer !== null && "signTypedData" in signer && "account" in signer && signer.account) {
-    const rawAccount = signer.account;
-    accountAddress = typeof rawAccount === "string" ? rawAccount : rawAccount.address;
+  } else if (typeof signer === "object" && signer !== null && "signTypedData" in signer) {
+    if ("account" in signer && signer.account) {
+      const rawAccount = signer.account;
+      accountAddress = typeof rawAccount === "string" ? rawAccount : rawAccount.address;
+    } else if ("address" in signer && signer.address) {
+      accountAddress = signer.address;
+    } else {
+      throw new Error("Signer object missing address");
+    }
     signTypedDataFn = (params) => signer.signTypedData(params);
   } else {
     throw new Error("Invalid signer provided to signX402Payment: must be private key or viem account/wallet client");
@@ -53,10 +59,14 @@ async function signX402Payment(signer, option, resourceUrl) {
       nonce: authorization.nonce
     }
   });
+  const acceptedOption = {
+    ...option,
+    extra: option.extra || { name: "USD Coin", version: "2" }
+  };
   const payload = {
     x402Version: 2,
     resource: resourceUrl ? { url: resourceUrl } : void 0,
-    accepted: option,
+    accepted: acceptedOption,
     payload: {
       signature,
       authorization
@@ -71,7 +81,7 @@ var NullClearClient = class {
   defaultChainId;
   customFetch;
   constructor(config = {}) {
-    this.arbiterUrl = (config.arbiterUrl || "https://arbiter.nullclear.dev").replace(/\/$/, "");
+    this.arbiterUrl = (config.arbiterUrl || "https://api.nullclear.dev").replace(/\/$/, "");
     this.defaultChainId = config.defaultChainId || 8453;
     this.customFetch = config.fetch || fetch;
   }
@@ -86,14 +96,29 @@ var NullClearClient = class {
     return data.data;
   }
   async clear(request) {
+    const headers = { "Content-Type": "application/json" };
+    if (!request.paymentSignatureHeader || request.paymentSignatureHeader === "free-trial") {
+      headers["x-nullclear-free-trial"] = "true";
+    }
     const res = await this.customFetch(`${this.arbiterUrl}/v1/clear`, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers,
       body: JSON.stringify(request)
     });
     const data = await res.json();
     return data;
   }
+  async safeFetch(targetUrl, init) {
+    return this.customFetch(`${this.arbiterUrl}/${targetUrl}`, init);
+  }
+  async createGateway(params) {
+    const res = await this.customFetch(`${this.arbiterUrl}/v1/gateways`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(params)
+    });
+    return res.json();
+  }
   async getKya(agentId, chainId) {
     const targetChainId = chainId || this.defaultChainId;
     const res = await this.customFetch(`${this.arbiterUrl}/v1/kya/${targetChainId}/${agentId}`);
@@ -196,9 +221,9 @@ function zodToJsonSchema(schema) {
       return {};
   }
 }
-function createNullClearFetch(config) {
+function createNullClearFetch(config = {}) {
   const chainId = config.chainId || 8453;
-  const arbiterUrl = (config.arbiterUrl || "https://arbiter.nullclear.dev").replace(/\/$/, "");
+  const arbiterUrl = (config.arbiterUrl || "https://api.nullclear.dev").replace(/\/$/, "");
   const defaultMinTrustScore = config.defaultMinTrustScore || 50;
   const customFetch = config.customFetch || fetch;
   return async function nullclearFetch(input, init) {
@@ -210,29 +235,33 @@ function createNullClearFetch(config) {
       return initialRes;
     }
     const paymentRequiredHeader = initialRes.headers.get("PAYMENT-REQUIRED") || initialRes.headers.get("payment-required");
-    if (!paymentRequiredHeader) {
-      return initialRes;
-    }
-    let paymentRequired;
-    try {
-      paymentRequired = decodeBase64Json(paymentRequiredHeader);
-    } catch {
-      return initialRes;
-    }
-    const targetNetwork = `eip155:${chainId}`;
-    const selectedOption = paymentRequired.accepts.find(
-      (opt) => opt.network === targetNetwork && opt.scheme === "exact"
-    );
-    if (!selectedOption) {
-      throw new Error(
-        `Seller does not accept payments on network ${targetNetwork}. Accepted: ${paymentRequired.accepts.map((a) => a.network).join(", ")}`
+    let paymentSignatureHeader;
+    if (config.accountOrPrivateKey && paymentRequiredHeader) {
+      let paymentRequired;
+      try {
+        paymentRequired = decodeBase64Json(paymentRequiredHeader);
+      } catch {
+        return initialRes;
+      }
+      const targetNetwork = `eip155:${chainId}`;
+      const selectedOption = paymentRequired.accepts.find(
+        (opt) => opt.network === targetNetwork && opt.scheme === "exact"
+      );
+      if (!selectedOption) {
+        throw new Error(
+          `Seller does not accept payments on network ${targetNetwork}. Accepted: ${paymentRequired.accepts.map((a) => a.network).join(", ")}`
+        );
+      }
+      paymentSignatureHeader = await signX402Payment(
+        config.accountOrPrivateKey,
+        selectedOption,
+        targetUrl
       );
+    } else if (!config.accountOrPrivateKey) {
+      paymentSignatureHeader = "free-trial";
+    } else {
+      return initialRes;
     }
-    const paymentSignatureHeader = await signX402Payment(
-      config.accountOrPrivateKey,
-      selectedOption,
-      targetUrl
-    );
     let jsonSchema;
     if (init?.nullclear?.schema) {
       if (init.nullclear.schema instanceof z.ZodType) {
@@ -260,9 +289,13 @@ function createNullClearFetch(config) {
       fallbacks: init?.nullclear?.fallbacks,
       spendPolicy: init?.nullclear?.spendPolicy
     };
+    const clearHeaders = { "Content-Type": "application/json" };
+    if (paymentSignatureHeader === "free-trial") {
+      clearHeaders["x-nullclear-free-trial"] = "true";
+    }
     const arbiterRes = await customFetch(`${arbiterUrl}/v1/clear`, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: clearHeaders,
       body: JSON.stringify(clearPayload)
     });
     const arbiterData = await arbiterRes.json();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullclear/x402-arbiter",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "NullClear Developer and Agent SDK for safe x402 calls with deferred schema escrow",
   "license": "MIT",
   "homepage": "https://nullclear.dev",
@@ -27,12 +27,12 @@
     }
   },
   "dependencies": {
-    "@nullclear/shared": "1.1.1",
+    "@nullclear/shared": "1.2.0",
     "viem": "^2.23.0",
     "zod": "^3.24.2"
   },
   "devDependencies": {
-    "@nullclear/worker-arbiter": "1.1.1",
+    "@nullclear/worker-arbiter": "1.2.0",
     "tsup": "^8.3.6",
     "typescript": "^5.7.3",
     "vitest": "^3.0.5"