@agent-score/commerce 1.0.3 → 1.1.0

package/dist/core.d.mts

@@ -161,18 +161,45 @@ interface AgentScoreData {
         }>;
     } | null;
 }
+/**
+ * Reason a failOpen allow short-circuited an evaluate call due to AgentScore-side
+ * infrastructure issues. Surfaced on `EvaluateOutcome` so merchants can log/alert when
+ * their gate is running in degraded mode (compliance not actually enforced this request).
+ *
+ * - `quota_exceeded` — AgentScore returned 429
+ * - `api_error` — AgentScore returned 5xx or non-2xx that isn't 429
+ * - `network_timeout` — request to /v1/assess timed out or failed at the network layer
+ */
+type FailOpenInfraReason = 'quota_exceeded' | 'api_error' | 'network_timeout';
+/** Per-account assess quota observability, captured from `X-Quota-*` response headers
+ *  on the success path. Mirrors the SDK's `QuotaInfo` shape — re-exported from gate state
+ *  so merchants can monitor approach-to-cap proactively (warn at 80%, alert at 95%). */
+interface GateQuotaInfo {
+    limit: number | null;
+    used: number | null;
+    /** ISO-8601 timestamp, or the literal string `"never"` for unlimited tiers. */
+    reset: string | null;
+}
 /**
  * Outcome from `AgentScoreCore.evaluate()`. Adapters map this to framework-specific responses.
  *
  * - `{ kind: 'allow', data }` — the request passed the policy. `data` is present on a normal
  *   allow; `undefined` when fail-open short-circuited (identity missing, API unreachable,
  *   timeout, or 402 paid-tier required).
+ * - When `failOpen: true` and the allow was the result of an AgentScore-side infrastructure
+ *   failure (429/5xx/timeout), the result also carries `degraded: true` + `infraReason` so
+ *   merchants can alert/log without parsing console output.
+ * - `quota` propagates the SDK's per-request quota observability when the API emits the
+ *   `X-Quota-*` headers. Optional; absent on Enterprise / unlimited tiers.
  * - `{ kind: 'deny', reason }` — the request was denied. Adapters should render a 403 with the
  *   reason, or invoke the caller's custom denial handler.
  */
 type EvaluateOutcome = {
     kind: 'allow';
     data?: AgentScoreData;
+    degraded?: boolean;
+    infraReason?: FailOpenInfraReason;
+    quota?: GateQuotaInfo;
 } | {
     kind: 'deny';
     reason: DenialReason;
@@ -249,4 +276,4 @@ interface AgentScoreCore {
 declare function buildAgentMemoryHint(): AgentMemoryHint;
 declare function createAgentScoreCore(options: AgentScoreCoreOptions): AgentScoreCore;
 
-export { type AgentIdentity, type AgentMemoryHint, type AgentScoreCore, type AgentScoreCoreOptions, type AgentScoreData, type CaptureWalletOptions, type CreateSessionOnMissing, type DenialCode, type DenialReason, type EvaluateOutcome, type SessionMetadata, type VerifyWalletSignerMatchOptions, type VerifyWalletSignerResult, buildAgentMemoryHint, createAgentScoreCore };
+export { type AgentIdentity, type AgentMemoryHint, type AgentScoreCore, type AgentScoreCoreOptions, type AgentScoreData, type CaptureWalletOptions, type CreateSessionOnMissing, type DenialCode, type DenialReason, type EvaluateOutcome, type FailOpenInfraReason, type GateQuotaInfo, type SessionMetadata, type VerifyWalletSignerMatchOptions, type VerifyWalletSignerResult, buildAgentMemoryHint, createAgentScoreCore };

package/dist/core.d.ts

@@ -161,18 +161,45 @@ interface AgentScoreData {
         }>;
     } | null;
 }
+/**
+ * Reason a failOpen allow short-circuited an evaluate call due to AgentScore-side
+ * infrastructure issues. Surfaced on `EvaluateOutcome` so merchants can log/alert when
+ * their gate is running in degraded mode (compliance not actually enforced this request).
+ *
+ * - `quota_exceeded` — AgentScore returned 429
+ * - `api_error` — AgentScore returned 5xx or non-2xx that isn't 429
+ * - `network_timeout` — request to /v1/assess timed out or failed at the network layer
+ */
+type FailOpenInfraReason = 'quota_exceeded' | 'api_error' | 'network_timeout';
+/** Per-account assess quota observability, captured from `X-Quota-*` response headers
+ *  on the success path. Mirrors the SDK's `QuotaInfo` shape — re-exported from gate state
+ *  so merchants can monitor approach-to-cap proactively (warn at 80%, alert at 95%). */
+interface GateQuotaInfo {
+    limit: number | null;
+    used: number | null;
+    /** ISO-8601 timestamp, or the literal string `"never"` for unlimited tiers. */
+    reset: string | null;
+}
 /**
  * Outcome from `AgentScoreCore.evaluate()`. Adapters map this to framework-specific responses.
  *
  * - `{ kind: 'allow', data }` — the request passed the policy. `data` is present on a normal
  *   allow; `undefined` when fail-open short-circuited (identity missing, API unreachable,
  *   timeout, or 402 paid-tier required).
+ * - When `failOpen: true` and the allow was the result of an AgentScore-side infrastructure
+ *   failure (429/5xx/timeout), the result also carries `degraded: true` + `infraReason` so
+ *   merchants can alert/log without parsing console output.
+ * - `quota` propagates the SDK's per-request quota observability when the API emits the
+ *   `X-Quota-*` headers. Optional; absent on Enterprise / unlimited tiers.
  * - `{ kind: 'deny', reason }` — the request was denied. Adapters should render a 403 with the
  *   reason, or invoke the caller's custom denial handler.
  */
 type EvaluateOutcome = {
     kind: 'allow';
     data?: AgentScoreData;
+    degraded?: boolean;
+    infraReason?: FailOpenInfraReason;
+    quota?: GateQuotaInfo;
 } | {
     kind: 'deny';
     reason: DenialReason;
@@ -249,4 +276,4 @@ interface AgentScoreCore {
 declare function buildAgentMemoryHint(): AgentMemoryHint;
 declare function createAgentScoreCore(options: AgentScoreCoreOptions): AgentScoreCore;
 
-export { type AgentIdentity, type AgentMemoryHint, type AgentScoreCore, type AgentScoreCoreOptions, type AgentScoreData, type CaptureWalletOptions, type CreateSessionOnMissing, type DenialCode, type DenialReason, type EvaluateOutcome, type SessionMetadata, type VerifyWalletSignerMatchOptions, type VerifyWalletSignerResult, buildAgentMemoryHint, createAgentScoreCore };
+export { type AgentIdentity, type AgentMemoryHint, type AgentScoreCore, type AgentScoreCoreOptions, type AgentScoreData, type CaptureWalletOptions, type CreateSessionOnMissing, type DenialCode, type DenialReason, type EvaluateOutcome, type FailOpenInfraReason, type GateQuotaInfo, type SessionMetadata, type VerifyWalletSignerMatchOptions, type VerifyWalletSignerResult, buildAgentMemoryHint, createAgentScoreCore };

package/dist/core.js

@@ -24,6 +24,7 @@ __export(core_exports, {
   createAgentScoreCore: () => createAgentScoreCore
 });
 module.exports = __toCommonJS(core_exports);
+var import_sdk = require("@agent-score/sdk");
 
 // src/_denial.ts
 var FIXABLE_DENIAL_REASONS = /* @__PURE__ */ new Set([
@@ -36,6 +37,61 @@ function isFixableDenial(reasons) {
   return reasons.every((r) => FIXABLE_DENIAL_REASONS.has(r));
 }
 
+// src/_response.ts
+var WALLET_NOT_TRUSTED_INSTRUCTIONS = JSON.stringify({
+  action: "contact_support",
+  steps: [
+    "The wallet's operator failed an UNFIXABLE compliance check (sanctions, age, or jurisdiction). `reasons` lists which: `sanctions_flagged` / `age_insufficient` / `jurisdiction_restricted`. KYC re-verification won't change the outcome \u2014 the policy denial is structural.",
+    "Surface the denial to the user with the merchant's support contact. Do not retry the same merchant request; do not hand the user a verify_url (verification won't fix this code path).",
+    "Fixable compliance reasons (`kyc_required`, `kyc_pending`, `kyc_failed`) do NOT land on this code \u2014 the gate auto-mints a verification session for those and returns `identity_verification_required` with poll endpoints, same shape as `missing_identity`. `jurisdiction_restricted` IS in the unfixable bucket because the API only emits it after KYC is verified (the user's KYC'd country is in the blocked list \u2014 re-doing KYC won't change the country)."
+  ],
+  user_message: "This purchase is denied by the merchant's compliance policy and cannot be resolved by re-verifying. Contact the merchant's support if you believe this is in error."
+});
+var PAYMENT_REQUIRED_INSTRUCTIONS = JSON.stringify({
+  action: "contact_merchant",
+  steps: [
+    "The merchant's AgentScore account does not have the assess endpoint enabled, so agent identity cannot be evaluated. This is a merchant-side configuration gap \u2014 there is no agent-side recovery.",
+    "Contact the merchant (their support channel \u2014 typically listed in /llms.txt or the OpenAPI servers metadata) so they can resolve the configuration on their side."
+  ],
+  user_message: "This merchant's identity gate is misconfigured. Contact the merchant \u2014 there's nothing to fix on the agent side."
+});
+var IDENTITY_VERIFICATION_REQUIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({
+  action: "deliver_verify_url_and_poll",
+  steps: [
+    "Share verify_url with the user \u2014 they complete identity verification on AgentScore.",
+    "If session_id + poll_secret are present in the body, poll poll_url every 5 seconds with header `X-Poll-Secret: <poll_secret>` until status=verified. The poll returns a one-time operator_token.",
+    "Retry the original request with header `X-Operator-Token: <opc_...>`."
+  ],
+  user_message: "Identity verification is required. Visit verify_url, then poll poll_url for the operator token and retry."
+});
+var API_ERROR_INSTRUCTIONS = JSON.stringify({
+  action: "retry_with_backoff",
+  steps: [
+    "Verification is temporarily unavailable. Retry the request after 5\u201330 seconds with exponential backoff.",
+    "This is NOT a compliance denial \u2014 the user does not need to re-verify their identity. Send the same identity headers (X-Wallet-Address or X-Operator-Token) on retry.",
+    "If the request continues to fail after 3+ retries (~60 seconds total), surface the error to the user with the merchant's support contact."
+  ],
+  user_message: "Verification is temporarily unavailable. Please try again in a moment \u2014 this is a transient issue, not a problem with your account."
+});
+var QUOTA_EXCEEDED_INSTRUCTIONS = JSON.stringify({
+  action: "contact_merchant",
+  steps: [
+    "AgentScore identity verification is unavailable for this merchant. This is a merchant-side issue and is NOT recoverable via retry.",
+    "Do not retry: the same 503 will be returned until the merchant resolves the issue on their side.",
+    "Surface to the user with the merchant's support contact. The merchant (not the agent) needs to act."
+  ],
+  user_message: "This merchant's identity verification is temporarily unavailable. Try again later, or contact the merchant directly."
+});
+var TOKEN_EXPIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({
+  action: "deliver_verify_url_and_poll",
+  steps: [
+    "The operator token is expired or revoked. AgentScore auto-mints a fresh verification session \u2014 complete it to receive a new opc_...",
+    "Share verify_url with the user, then poll poll_url every 5 seconds with header `X-Poll-Secret: <poll_secret>` until status=verified. The poll returns a fresh one-time operator_token.",
+    "Retry the original request with header `X-Operator-Token: <new_opc_...>`."
+  ],
+  user_message: "Operator token is expired or revoked. A new verification session has been minted \u2014 visit verify_url to refresh."
+});
+
 // src/address.ts
 var SOLANA_BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
 var isSolanaAddress = (address) => SOLANA_BASE58_RE.test(address) && !address.startsWith("0x");
@@ -164,9 +220,23 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint();
-  const defaultUa = `@agent-score/commerce@${"1.0.3"}`;
+  const defaultUa = `@agent-score/commerce@${"1.1.0"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
-  const API_TIMEOUT_MS = 1e4;
+  const sdk = new import_sdk.AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
+  const sessionSdkCache = /* @__PURE__ */ new Map();
+  function getSessionSdk(sessionApiKey, sessionBaseUrl) {
+    const key = `${sessionApiKey}|${sessionBaseUrl ?? ""}`;
+    let s = sessionSdkCache.get(key);
+    if (!s) {
+      s = new import_sdk.AgentScore({
+        apiKey: sessionApiKey,
+        baseUrl: sessionBaseUrl ?? baseUrl,
+        userAgent: userAgentHeader
+      });
+      sessionSdkCache.set(key, s);
+    }
+    return s;
+  }
   const cache = new TTLCache(cacheSeconds * 1e3);
   async function tryMintSessionDenial(ctx) {
     if (!createSessionOnMissing) return void 0;
@@ -183,20 +253,11 @@ function createAgentScoreCore(options) {
           console.warn("[gate] createSessionOnMissing.getSessionOptions hook failed:", err instanceof Error ? err.message : err);
         }
       }
-      const sessionBaseUrl = stripTrailingSlashes(createSessionOnMissing.baseUrl ?? "https://api.agentscore.sh");
-      const sessionRes = await fetch(`${sessionBaseUrl}/v1/sessions`, {
-        method: "POST",
-        headers: {
-          "X-API-Key": createSessionOnMissing.apiKey,
-          "Content-Type": "application/json",
-          Accept: "application/json",
-          "User-Agent": userAgentHeader
-        },
-        body: JSON.stringify(sessionBody),
-        signal: AbortSignal.timeout(API_TIMEOUT_MS)
+      const sessionSdk = getSessionSdk(createSessionOnMissing.apiKey, createSessionOnMissing.baseUrl);
+      const data = await sessionSdk.createSession({
+        ...sessionBody.context !== void 0 ? { context: sessionBody.context } : {},
+        ...sessionBody.product_name !== void 0 ? { product_name: sessionBody.product_name } : {}
       });
-      if (!sessionRes.ok) return void 0;
-      const data = await sessionRes.json();
       if (typeof data.session_id !== "string" || typeof data.poll_secret !== "string" || typeof data.verify_url !== "string") {
         console.warn("[gate] /v1/sessions returned 200 without required fields \u2014 falling back to bare denial");
         return void 0;
@@ -260,7 +321,13 @@ function createAgentScoreCore(options) {
     const cached = cache.get(cacheKey);
     if (cached) {
       if (cached.allow) {
-        return { kind: "allow", data: cached.raw };
+        const cachedRaw = cached.raw;
+        const cachedQuota = cachedRaw?.quota;
+        return {
+          kind: "allow",
+          data: cachedRaw,
+          ...cachedQuota !== void 0 && { quota: cachedQuota }
+        };
       }
       if (isFixableDenial(cached.reasons)) {
         const sessionReason = await tryMintSessionDenial(ctx);
@@ -277,130 +344,119 @@ function createAgentScoreCore(options) {
         }
       };
     }
+    const policy = {};
+    if (requireKyc != null) policy.require_kyc = requireKyc;
+    if (requireSanctionsClear != null) policy.require_sanctions_clear = requireSanctionsClear;
+    if (minAge != null) policy.min_age = minAge;
+    if (blockedJurisdictions != null) policy.blocked_jurisdictions = blockedJurisdictions;
+    if (allowedJurisdictions != null) policy.allowed_jurisdictions = allowedJurisdictions;
+    let data;
     try {
-      const body = {};
-      if (identity.address) body.address = identity.address;
-      if (identity.operatorToken) body.operator_token = identity.operatorToken;
-      if (gateChain) body.chain = gateChain;
-      const policy = {};
-      if (requireKyc != null) policy.require_kyc = requireKyc;
-      if (requireSanctionsClear != null) policy.require_sanctions_clear = requireSanctionsClear;
-      if (minAge != null) policy.min_age = minAge;
-      if (blockedJurisdictions != null) policy.blocked_jurisdictions = blockedJurisdictions;
-      if (allowedJurisdictions != null) policy.allowed_jurisdictions = allowedJurisdictions;
-      if (Object.keys(policy).length > 0) body.policy = policy;
-      const response = await fetch(`${baseUrl}/v1/assess`, {
-        method: "POST",
-        headers: {
-          "X-API-Key": apiKey,
-          "Content-Type": "application/json",
-          Accept: "application/json",
-          "User-Agent": userAgentHeader
-        },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(API_TIMEOUT_MS)
-      });
-      if (response.status === 402) {
+      const opts = {
+        chain: gateChain,
+        ...Object.keys(policy).length > 0 ? { policy } : {}
+      };
+      const result = identity.address ? await sdk.assess(identity.address, { ...opts, operatorToken: identity.operatorToken }) : await sdk.assess(null, { ...opts, operatorToken: identity.operatorToken });
+      data = result;
+    } catch (err) {
+      if (err instanceof import_sdk.PaymentRequiredError) {
         if (failOpen) return { kind: "allow" };
         return { kind: "deny", reason: { code: "payment_required" } };
       }
-      if (response.status === 401) {
-        try {
-          const errData = await response.clone().json();
-          const code = errData?.error?.code;
-          if (code === "token_expired") {
-            return {
-              kind: "deny",
-              reason: {
-                code,
-                data: errData,
-                ...typeof errData.verify_url === "string" ? { verify_url: errData.verify_url } : {},
-                ...typeof errData.session_id === "string" ? { session_id: errData.session_id } : {},
-                ...typeof errData.poll_secret === "string" ? { poll_secret: errData.poll_secret } : {},
-                ...typeof errData.poll_url === "string" ? { poll_url: errData.poll_url } : {},
-                ...errData.next_steps ? { agent_instructions: JSON.stringify(errData.next_steps) } : {},
-                ...errData.agent_memory ? { agent_memory: errData.agent_memory } : {}
-              }
-            };
-          }
-          if (code === "invalid_credential") {
-            return {
-              kind: "deny",
-              reason: {
-                code: "invalid_credential",
-                agent_instructions: INVALID_CREDENTIAL_INSTRUCTIONS,
-                agent_memory: agentMemoryHint
-              }
-            };
+      if (err instanceof import_sdk.TokenExpiredError) {
+        return {
+          kind: "deny",
+          reason: {
+            code: "token_expired",
+            data: err.details,
+            ...err.verifyUrl ? { verify_url: err.verifyUrl } : {},
+            ...err.sessionId ? { session_id: err.sessionId } : {},
+            ...err.pollSecret ? { poll_secret: err.pollSecret } : {},
+            ...err.pollUrl ? { poll_url: err.pollUrl } : {},
+            ...err.nextSteps ? { agent_instructions: JSON.stringify(err.nextSteps) } : {},
+            ...err.agentMemory ? { agent_memory: err.agentMemory } : {}
           }
-          if (code) {
-            console.warn(`[gate] /v1/assess returned 401 ${code} \u2014 no specific handler, surfacing as api_error.`);
-          }
-        } catch (err) {
-          console.warn("[gate] /v1/assess 401 body parse failed:", err instanceof Error ? err.message : err);
-        }
+        };
       }
-      if (response.status >= 400 && response.status < 500 && response.status !== 402) {
-        try {
-          const errData = await response.clone().json();
-          const code = errData?.error?.code;
-          if (code && code !== "token_expired" && code !== "invalid_credential") {
-            console.warn(
-              `[gate] /v1/assess returned ${response.status} ${code} \u2014 surfacing as api_error. Validate input shape before invoking the gate to avoid this.`
-            );
+      if (err instanceof import_sdk.InvalidCredentialError) {
+        return {
+          kind: "deny",
+          reason: {
+            code: "invalid_credential",
+            agent_instructions: INVALID_CREDENTIAL_INSTRUCTIONS,
+            agent_memory: agentMemoryHint
           }
-        } catch {
-        }
+        };
       }
-      if (!response.ok) {
-        throw new Error(`AgentScore API returned ${response.status}`);
+      if (err instanceof import_sdk.QuotaExceededError) {
+        console.warn("[gate] /v1/assess returned 429 quota_exceeded");
+        if (failOpen) return { kind: "allow", degraded: true, infraReason: "quota_exceeded" };
+        return {
+          kind: "deny",
+          reason: { code: "api_error", agent_instructions: QUOTA_EXCEEDED_INSTRUCTIONS }
+        };
       }
-      const data = await response.json();
-      const decision = data.decision;
-      const decisionReasons = data.decision_reasons ?? [];
-      const allow = decision === "allow" || decision == null;
-      cache.set(cacheKey, { allow, decision: decision ?? void 0, reasons: decisionReasons, raw: data });
-      if (allow) {
-        return { kind: "allow", data };
+      if (err instanceof import_sdk.TimeoutError) {
+        console.warn("[gate] /v1/assess timed out:", err.message);
+        if (failOpen) return { kind: "allow", degraded: true, infraReason: "network_timeout" };
+        return { kind: "deny", reason: { code: "api_error" } };
       }
-      if (isFixableDenial(decisionReasons)) {
-        const sessionReason = await tryMintSessionDenial(ctx);
-        if (sessionReason) return { kind: "deny", reason: sessionReason };
+      const status = err?.status;
+      const errName = err instanceof Error ? err.name : "";
+      if (status === 429) {
+        console.warn("[gate] /v1/assess returned 429 (untyped \u2014 defensive)");
+        if (failOpen) return { kind: "allow", degraded: true, infraReason: "quota_exceeded" };
+        return {
+          kind: "deny",
+          reason: { code: "api_error", agent_instructions: QUOTA_EXCEEDED_INSTRUCTIONS }
+        };
       }
+      if (errName === "TimeoutError" || errName === "AbortError") {
+        console.warn("[gate] /v1/assess timed out (by Error.name):", err instanceof Error ? err.message : err);
+        if (failOpen) return { kind: "allow", degraded: true, infraReason: "network_timeout" };
+        return { kind: "deny", reason: { code: "api_error" } };
+      }
+      const errCode = err?.code;
+      const msg = err instanceof Error ? err.message : String(err);
+      const detail = errCode ? `${errCode}: ${msg}` : msg;
+      console.warn(`[gate] /v1/assess call failed \u2014 surfacing as api_error: ${detail}`);
+      if (failOpen) return { kind: "allow", degraded: true, infraReason: "api_error" };
+      return { kind: "deny", reason: { code: "api_error" } };
+    }
+    const decision = data.decision;
+    const decisionReasons = data.decision_reasons ?? [];
+    const allow = decision === "allow" || decision == null;
+    cache.set(cacheKey, { allow, decision: decision ?? void 0, reasons: decisionReasons, raw: data });
+    if (allow) {
+      const quota = data.quota;
       return {
-        kind: "deny",
-        reason: {
-          code: "wallet_not_trusted",
-          decision: decision ?? void 0,
-          reasons: decisionReasons,
-          verify_url: data.verify_url,
-          data
-        }
+        kind: "allow",
+        data,
+        ...quota !== void 0 && { quota }
       };
-    } catch (err) {
-      console.warn("[gate] /v1/assess call failed \u2014 surfacing as api_error:", err instanceof Error ? err.message : err);
-      if (failOpen) return { kind: "allow" };
-      return { kind: "deny", reason: { code: "api_error" } };
     }
+    if (isFixableDenial(decisionReasons)) {
+      const sessionReason = await tryMintSessionDenial(ctx);
+      if (sessionReason) return { kind: "deny", reason: sessionReason };
+    }
+    return {
+      kind: "deny",
+      reason: {
+        code: "wallet_not_trusted",
+        decision: decision ?? void 0,
+        reasons: decisionReasons,
+        verify_url: data.verify_url,
+        data
+      }
+    };
   }
   async function captureWallet(options2) {
     try {
-      const body = {
-        operator_token: options2.operatorToken,
-        wallet_address: options2.walletAddress,
-        network: options2.network
-      };
-      if (options2.idempotencyKey) body.idempotency_key = options2.idempotencyKey;
-      await fetch(`${baseUrl}/v1/credentials/wallets`, {
-        method: "POST",
-        headers: {
-          "X-API-Key": apiKey,
-          "Content-Type": "application/json",
-          Accept: "application/json",
-          "User-Agent": userAgentHeader
-        },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(API_TIMEOUT_MS)
+      await sdk.associateWallet({
+        operatorToken: options2.operatorToken,
+        walletAddress: options2.walletAddress,
+        network: options2.network,
+        ...options2.idempotencyKey ? { idempotencyKey: options2.idempotencyKey } : {}
       });
     } catch (err) {
       console.warn("[agentscore-commerce] captureWallet failed:", err instanceof Error ? err.message : err);
@@ -425,19 +481,7 @@ function createAgentScoreCore(options) {
       return { ok: true, ...extractFromCached(resolveCached.raw) };
     }
     try {
-      const response = await fetch(`${baseUrl}/v1/assess`, {
-        method: "POST",
-        headers: {
-          "X-API-Key": apiKey,
-          "Content-Type": "application/json",
-          Accept: "application/json",
-          "User-Agent": userAgentHeader
-        },
-        body: JSON.stringify({ address: walletAddress }),
-        signal: AbortSignal.timeout(API_TIMEOUT_MS)
-      });
-      if (!response.ok) return { ok: false };
-      const data = await response.json();
+      const data = await sdk.assess(walletAddress);
       cache.set(`resolve:${wallet}`, { allow: true, raw: data });
       return { ok: true, ...extractFromCached(data) };
     } catch (err) {
@@ -446,28 +490,37 @@ function createAgentScoreCore(options) {
     }
   }
   function reportSignerEvent(kind) {
-    try {
-      const pending = fetch(`${baseUrl}/v1/telemetry/signer-match`, {
-        method: "POST",
-        headers: {
-          "X-API-Key": apiKey,
-          "Content-Type": "application/json",
-          Accept: "application/json",
-          "User-Agent": userAgentHeader
-        },
-        body: JSON.stringify({ kind }),
-        signal: AbortSignal.timeout(API_TIMEOUT_MS)
-      });
-      if (pending && typeof pending.catch === "function") {
-        pending.catch((err) => {
-          console.warn("[agentscore-commerce] signer-match telemetry failed:", err instanceof Error ? err.message : err);
-        });
-      }
-    } catch {
+    void sdk.telemetrySignerMatch({ kind });
+  }
+  function projectSignerMatch(sm, claimedNorm, signerNorm) {
+    const kind = sm.kind;
+    if (kind === "pass") {
+      return {
+        kind: "pass",
+        claimedOperator: sm.claimed_operator ?? null,
+        signerOperator: sm.signer_operator ?? null
+      };
     }
+    if (kind === "wallet_auth_requires_wallet_signing") {
+      return {
+        kind: "wallet_auth_requires_wallet_signing",
+        claimedWallet: sm.claimed_wallet ?? claimedNorm,
+        agentInstructions: sm.agent_instructions ?? WALLET_AUTH_REQUIRES_WALLET_SIGNING_INSTRUCTIONS
+      };
+    }
+    const linked = sm.linked_wallets;
+    return {
+      kind: "wallet_signer_mismatch",
+      claimedOperator: sm.claimed_operator ?? null,
+      actualSignerOperator: sm.signer_operator ?? null,
+      expectedSigner: sm.expected_signer ?? claimedNorm,
+      actualSigner: sm.actual_signer ?? signerNorm,
+      linkedWallets: Array.isArray(linked) ? linked.filter((w) => typeof w === "string") : [],
+      agentInstructions: sm.agent_instructions ?? WALLET_SIGNER_MISMATCH_INSTRUCTIONS
+    };
   }
   async function verifyWalletSignerMatch(options2) {
-    const { claimedWallet, signer } = options2;
+    const { claimedWallet, signer, network } = options2;
     if (!signer) {
       reportSignerEvent("wallet_auth_requires_wallet_signing");
       return {
@@ -482,6 +535,35 @@ function createAgentScoreCore(options) {
       reportSignerEvent("pass");
       return { kind: "pass", claimedOperator: null, signerOperator: null };
     }
+    const cachedEntry = cache.get(claimedNorm);
+    const cachedMatch = cachedEntry?.signerMatchBySigner?.get(signerNorm);
+    if (cachedMatch) {
+      return projectSignerMatch(cachedMatch, claimedNorm, signerNorm);
+    }
+    const inferredNetwork = network ?? (signerNorm.startsWith("0x") ? "evm" : "solana");
+    let assessResponse;
+    try {
+      assessResponse = await sdk.assess(claimedNorm, {
+        resolveSigner: { address: signerNorm, network: inferredNetwork }
+      });
+    } catch (err) {
+      console.warn("[gate] verifyWalletSignerMatch assess failed:", err instanceof Error ? err.message : err);
+      reportSignerEvent("api_error");
+      return { kind: "api_error", claimedWallet: claimedNorm };
+    }
+    const signerMatch = assessResponse.signer_match;
+    if (signerMatch && typeof signerMatch === "object") {
+      if (cachedEntry) {
+        const map = cachedEntry.signerMatchBySigner ?? /* @__PURE__ */ new Map();
+        map.set(signerNorm, signerMatch);
+        cachedEntry.signerMatchBySigner = map;
+      } else {
+        const entry = { allow: true, raw: assessResponse };
+        entry.signerMatchBySigner = /* @__PURE__ */ new Map([[signerNorm, signerMatch]]);
+        cache.set(claimedNorm, entry);
+      }
+      return projectSignerMatch(signerMatch, claimedNorm, signerNorm);
+    }
     const [claimedResolve, signerResolve] = await Promise.all([
       resolveWalletToOperator(claimedNorm),
       resolveWalletToOperator(signerNorm)
@@ -503,8 +585,6 @@ function createAgentScoreCore(options) {
       actualSignerOperator: signerOperator,
       expectedSigner: claimedNorm,
       actualSigner: signerNorm,
-      // Populated from /v1/assess.linked_wallets on the claimed wallet — the full set of
-      // wallets the agent CAN sign with to satisfy the claim (same-operator rule).
       linkedWallets: claimedResolve.linkedWallets,
       agentInstructions: WALLET_SIGNER_MISMATCH_INSTRUCTIONS
     };