@neus/sdk 1.1.4 → 1.1.6

package/README.md

@@ -1,8 +1,8 @@
 # @neus/sdk
 
-Create, check, and reuse NEUS trust receipts from apps and backends. The same package ships the **`neus`** CLI for hosted MCP setup.
+Create, check, and reuse NEUS trust receipts from apps and backends. The same package ships the **`neus`** CLI for assistant setup.
 
-NEUS makes trust portable across apps, agents, and ecosystems before access, payment, or action.
+NEUS is trust infrastructure for apps, agents, and ecosystems.
 
 Roadmap: [docs.neus.network/platform/status](https://docs.neus.network/platform/status)
 
@@ -18,25 +18,26 @@ One command detects your environment and configures hosted MCP for Claude Code,
 
 ```bash
 npx -y -p @neus/sdk neus setup
-npx -y -p @neus/sdk neus doctor --live
+npx -y -p @neus/sdk neus check
+npx -y -p @neus/sdk neus examples
 ```
 
-Open your MCP client and ask the assistant to use NEUS Trust.
+Ask your assistant: **"Use NEUS Verify before taking sensitive actions."**
 
 ## MCP docs
 
 | Topic                             | Link                                                                          |
 | --------------------------------- | ----------------------------------------------------------------------------- |
 | Setup, JSON snippets, and headers | [MCP setup](https://docs.neus.network/mcp/setup)                              |
-| Tools and session order           | [MCP overview](https://docs.neus.network/mcp/overview)                        |
+| Reuse-first MCP flow              | [MCP overview](https://docs.neus.network/mcp/overview)                        |
 | Discovery URLs                    | [Discovery and endpoints](https://docs.neus.network/mcp/endpoints)            |
-| Install NEUS Trust                | [Install NEUS Trust](https://docs.neus.network/install)                         |
+| Install NEUS                      | [Install NEUS](https://docs.neus.network/install)                               |
 
 Prefer `neus setup` over hand-editing config files so every host stays on **`https://mcp.neus.network/mcp`**.
 
 ## What you can ship
 
-- Hosted verification flows that return a reusable receipt
+- Hosted verification flows that return reusable receipts
 - Server checks before access, rewards, payments, or actions
 - React gates with `VerifyGate`
 - Agent identity and scoped delegation
@@ -163,14 +164,14 @@ const client = new NeusClient({
 
 ```bash
 npx -y -p @neus/sdk neus setup
-npx -y -p @neus/sdk neus doctor --live
+npx -y -p @neus/sdk neus check
 ```
 
 `neus setup` configures MCP and signs you in: `NEUS_ACCESS_KEY` from the environment when set, otherwise the selected host starts OAuth. Cursor, VS Code, and Claude Code use browser sign-in on NEUS. Pass `--access-key <npk_...>` only to override.
 
 Codex owns its local MCP OAuth session. Use `npx -y -p @neus/sdk neus setup --client codex`, then `npx -y -p @neus/sdk neus auth --client codex`.
 
-Integrators embedding install UX in apps should import **`@neus/sdk/mcp-hosts`** (setup commands, deeplinks, host labels) instead of duplicating strings.
+Embed install UX with **`@neus/sdk/mcp-hosts`** (setup commands, deeplinks, host labels).
 
 Claude Code users can install **`neus-trust@neus`** for the bundled session workflow:
 
@@ -179,7 +180,7 @@ Claude Code users can install **`neus-trust@neus`** for the bundled session work
 /plugin install neus-trust@neus
 ```
 
-Other hosts: [Install NEUS Trust](https://docs.neus.network/install).
+Other hosts: [Install NEUS](https://docs.neus.network/install).
 
 ## Docs
 

package/cjs/client.cjs

@@ -468,19 +468,19 @@ var NEUS_CONSTANTS = {
 // client.js
 var FALLBACK_PUBLIC_VERIFIER_CATALOG = {
   "ownership-basic": { supportsDirectApi: true },
+  "ownership-social": { supportsDirectApi: false },
   "ownership-pseudonym": { supportsDirectApi: true },
   "ownership-dns-txt": { supportsDirectApi: true },
-  "ownership-social": { supportsDirectApi: false },
   "ownership-org-oauth": { supportsDirectApi: false },
   "contract-ownership": { supportsDirectApi: true },
+  "proof-of-human": { supportsDirectApi: false },
   "nft-ownership": { supportsDirectApi: true },
   "token-holding": { supportsDirectApi: true },
-  "wallet-link": { supportsDirectApi: true },
   "wallet-risk": { supportsDirectApi: true },
-  "proof-of-human": { supportsDirectApi: false },
+  "wallet-link": { supportsDirectApi: true },
+  "ai-content-moderation": { supportsDirectApi: true },
   "agent-identity": { supportsDirectApi: true },
-  "agent-delegation": { supportsDirectApi: true },
-  "ai-content-moderation": { supportsDirectApi: true }
+  "agent-delegation": { supportsDirectApi: true }
 };
 var EVM_ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
 var WALLET_LINK_RELATIONSHIP_TYPES = /* @__PURE__ */ new Set(["primary", "personal", "org", "affiliate", "agent", "linked"]);
@@ -1530,6 +1530,11 @@ ${bytes.length}`;
       storeOriginalContent: typeof options?.storeOriginalContent === "boolean" ? options.storeOriginalContent : true
     };
     if (typeof options?.enableIpfs === "boolean") optionsPayload.enableIpfs = options.enableIpfs;
+    if (options?.publishToHub === true) {
+      optionsPayload.publishToHub = true;
+    } else {
+      delete optionsPayload.publishToHub;
+    }
     const requestData = {
       verifierIds: normalizedVerifierIds,
       data,
@@ -1750,18 +1755,39 @@ ${bytes.length}`;
     }
     return true;
   }
+  _buildProofsByWalletQuery(options = {}) {
+    const qs = [];
+    if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
+    const cursorRaw = options.cursor !== null && options.cursor !== void 0 ? String(options.cursor).trim() : "";
+    if (cursorRaw) qs.push(`cursor=${encodeURIComponent(cursorRaw)}`);
+    else if (options.offset !== void 0 && options.offset !== null) {
+      qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
+    }
+    if (options.q) qs.push(`q=${encodeURIComponent(String(options.q))}`);
+    if (options.qHash) qs.push(`qHash=${encodeURIComponent(String(options.qHash).toLowerCase())}`);
+    if (options.verifierId) qs.push(`verifierId=${encodeURIComponent(String(options.verifierId))}`);
+    if (options.verifierIds) qs.push(`verifierIds=${encodeURIComponent(String(options.verifierIds))}`);
+    if (options.tags) qs.push(`tags=${encodeURIComponent(String(options.tags))}`);
+    if (options.tagPrefix) qs.push(`tagPrefix=${encodeURIComponent(String(options.tagPrefix))}`);
+    if (options.tagContains) qs.push(`tagContains=${encodeURIComponent(String(options.tagContains))}`);
+    if (options.tagPrefixesAll) qs.push(`tagPrefixesAll=${encodeURIComponent(String(options.tagPrefixesAll))}`);
+    if (options.status) qs.push(`status=${encodeURIComponent(String(options.status))}`);
+    if (options.appId) qs.push(`appId=${encodeURIComponent(String(options.appId))}`);
+    if (options.chainCoverage) qs.push(`chainCoverage=${encodeURIComponent(String(options.chainCoverage))}`);
+    if (options.privacyLevel) qs.push(`privacyLevel=${encodeURIComponent(String(options.privacyLevel))}`);
+    if (options.includeHistory) qs.push("includeHistory=1");
+    if (options.includeFacets) qs.push(`includeFacets=${encodeURIComponent(String(options.includeFacets))}`);
+    if (options.visibility) qs.push(`visibility=${encodeURIComponent(String(options.visibility))}`);
+    if (options.isPublicRead) qs.push("isPublicRead=1");
+    return qs;
+  }
   async getProofsByWallet(walletAddress, options = {}) {
     if (!walletAddress || typeof walletAddress !== "string") {
       throw new ValidationError("walletAddress is required");
     }
     const id = walletAddress.trim();
     const pathId = /^0x[a-fA-F0-9]{40}$/i.test(id) ? id.toLowerCase() : id;
-    const qs = [];
-    if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
-    const cursorRaw = options.cursor !== null && options.cursor !== void 0 ? String(options.cursor).trim() : "";
-    if (cursorRaw) qs.push(`cursor=${encodeURIComponent(cursorRaw)}`);
-    else if (options.offset) qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
-    if (options.qHash) qs.push(`qHash=${encodeURIComponent(options.qHash.toLowerCase())}`);
+    const qs = this._buildProofsByWalletQuery(options);
     const query = qs.length ? `?${qs.join("&")}` : "";
     const response = await this._makeRequest(
       "GET",
@@ -1774,10 +1800,11 @@ ${bytes.length}`;
     return {
       success: true,
       proofs: Array.isArray(proofs) ? proofs : [],
-      totalCount: response.data?.totalCount ?? proofs.length,
+      totalCount: typeof response.data?.totalCount === "number" ? response.data.totalCount : null,
       hasMore: Boolean(response.data?.hasMore),
       nextOffset: response.data?.nextOffset ?? null,
-      nextCursor: typeof response.data?.nextCursor === "string" && response.data.nextCursor.trim() ? response.data.nextCursor.trim() : null
+      nextCursor: typeof response.data?.nextCursor === "string" && response.data.nextCursor.trim() ? response.data.nextCursor.trim() : null,
+      facets: response.data?.facets || null
     };
   }
   async getPrivateProofsByWallet(walletAddress, options = {}, wallet = null) {
@@ -1827,12 +1854,7 @@ ${bytes.length}`;
       }
       throw new ValidationError(`Failed to sign message: ${error.message}`);
     }
-    const qs = [];
-    if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
-    const cursorRaw = options.cursor !== null && options.cursor !== void 0 ? String(options.cursor).trim() : "";
-    if (cursorRaw) qs.push(`cursor=${encodeURIComponent(cursorRaw)}`);
-    else if (options.offset) qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
-    if (options.qHash) qs.push(`qHash=${encodeURIComponent(options.qHash.toLowerCase())}`);
+    const qs = this._buildProofsByWalletQuery(options);
     const query = qs.length ? `?${qs.join("&")}` : "";
     const response = await this._makeRequest("GET", `/api/v1/proofs/by-wallet/${encodeURIComponent(pathId)}${query}`, null, {
       "x-wallet-address": signerWalletAddress,
@@ -1847,7 +1869,7 @@ ${bytes.length}`;
     return {
       success: true,
       proofs: Array.isArray(proofs) ? proofs : [],
-      totalCount: response.data?.totalCount ?? proofs.length,
+      totalCount: typeof response.data?.totalCount === "number" ? response.data.totalCount : null,
       hasMore: Boolean(response.data?.hasMore),
       nextOffset: response.data?.nextOffset ?? null,
       nextCursor: typeof response.data?.nextCursor === "string" && response.data.nextCursor.trim() ? response.data.nextCursor.trim() : null
@@ -1964,6 +1986,64 @@ ${bytes.length}`;
     }
     return response;
   }
+  /**
+   * Get the public snapshot of a published gate: requirements, charge, schedule,
+   * checkout plan, and reward presence. Never returns the secret reward value —
+   * that is delivered post-verify via fulfillGate().
+   *
+   * @param {string} gateId Published gate handle
+   * @returns {Promise<object>} Public gate snapshot
+   */
+  async getGate(gateId) {
+    const id = String(gateId || "").trim();
+    if (!id || id.length > 80 || !/^[a-zA-Z0-9:_-]+$/.test(id)) {
+      throw new ValidationError("Valid gateId is required");
+    }
+    const response = await this._makeRequest("GET", `/api/v1/gates/${encodeURIComponent(id)}`);
+    if (!response.success || !response.data?.gate) {
+      throw new ApiError(`Gate lookup failed: ${response.error?.message || "Gate not found"}`, response.error);
+    }
+    return response.data.gate;
+  }
+  /**
+   * Post-verify reward delivery for hosted gate checkout. Requires a verified
+   * proof (qHash) for the gate; paid gates also require payment evidence
+   * (paymentCheckoutSessionId for card, or paymentTxHash for USDC).
+   *
+   * @param {object} params
+   * @param {string} params.gateId Published gate handle
+   * @param {string} params.qHash Verified proof receipt id
+   * @param {string} [params.walletAddress] Wallet bound to the proof (required without a session cookie)
+   * @param {string} [params.paymentCheckoutSessionId] Stripe checkout session id (card rail)
+   * @param {string} [params.paymentTxHash] USDC payment transaction hash (wallet rail)
+   * @returns {Promise<object>} `{ success, data: { gateId, qHash, fulfillment, successReturnUrl? } }`
+   */
+  async fulfillGate(params = {}) {
+    const gateId = String(params.gateId || "").trim();
+    if (!gateId || gateId.length > 80 || !/^[a-zA-Z0-9:_-]+$/.test(gateId)) {
+      throw new ValidationError("Valid gateId is required");
+    }
+    const qHash = String(params.qHash || "").trim();
+    if (!/^0x[a-fA-F0-9]{64}$/.test(qHash)) {
+      throw new ValidationError("Valid qHash is required");
+    }
+    const body = { qHash };
+    const walletAddress = String(params.walletAddress || "").trim();
+    if (walletAddress) body.walletAddress = walletAddress;
+    const paymentCheckoutSessionId = String(params.paymentCheckoutSessionId || "").trim();
+    if (paymentCheckoutSessionId) body.paymentCheckoutSessionId = paymentCheckoutSessionId;
+    const paymentTxHash = String(params.paymentTxHash || "").trim();
+    if (paymentTxHash) body.paymentTxHash = paymentTxHash;
+    const response = await this._makeRequest(
+      "POST",
+      `/api/v1/gates/${encodeURIComponent(gateId)}/fulfill`,
+      body
+    );
+    if (!response.success) {
+      throw new ApiError(`Gate fulfillment failed: ${response.error?.message || "Unknown error"}`, response.error);
+    }
+    return response;
+  }
   async checkGate(params) {
     const { walletAddress, requirements, proofs: preloadedProofs } = params;
     if (!validateUniversalAddress(walletAddress)) {

package/cjs/index.cjs

@@ -1180,19 +1180,19 @@ var init_client = __esm({
     init_utils();
     FALLBACK_PUBLIC_VERIFIER_CATALOG = {
       "ownership-basic": { supportsDirectApi: true },
+      "ownership-social": { supportsDirectApi: false },
       "ownership-pseudonym": { supportsDirectApi: true },
       "ownership-dns-txt": { supportsDirectApi: true },
-      "ownership-social": { supportsDirectApi: false },
       "ownership-org-oauth": { supportsDirectApi: false },
       "contract-ownership": { supportsDirectApi: true },
+      "proof-of-human": { supportsDirectApi: false },
       "nft-ownership": { supportsDirectApi: true },
       "token-holding": { supportsDirectApi: true },
-      "wallet-link": { supportsDirectApi: true },
       "wallet-risk": { supportsDirectApi: true },
-      "proof-of-human": { supportsDirectApi: false },
+      "wallet-link": { supportsDirectApi: true },
+      "ai-content-moderation": { supportsDirectApi: true },
       "agent-identity": { supportsDirectApi: true },
-      "agent-delegation": { supportsDirectApi: true },
-      "ai-content-moderation": { supportsDirectApi: true }
+      "agent-delegation": { supportsDirectApi: true }
     };
     EVM_ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
     WALLET_LINK_RELATIONSHIP_TYPES = /* @__PURE__ */ new Set(["primary", "personal", "org", "affiliate", "agent", "linked"]);
@@ -2223,6 +2223,11 @@ ${bytes.length}`;
           storeOriginalContent: typeof options?.storeOriginalContent === "boolean" ? options.storeOriginalContent : true
         };
         if (typeof options?.enableIpfs === "boolean") optionsPayload.enableIpfs = options.enableIpfs;
+        if (options?.publishToHub === true) {
+          optionsPayload.publishToHub = true;
+        } else {
+          delete optionsPayload.publishToHub;
+        }
         const requestData = {
           verifierIds: normalizedVerifierIds,
           data,
@@ -2443,18 +2448,39 @@ ${bytes.length}`;
         }
         return true;
       }
+      _buildProofsByWalletQuery(options = {}) {
+        const qs = [];
+        if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
+        const cursorRaw = options.cursor !== null && options.cursor !== void 0 ? String(options.cursor).trim() : "";
+        if (cursorRaw) qs.push(`cursor=${encodeURIComponent(cursorRaw)}`);
+        else if (options.offset !== void 0 && options.offset !== null) {
+          qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
+        }
+        if (options.q) qs.push(`q=${encodeURIComponent(String(options.q))}`);
+        if (options.qHash) qs.push(`qHash=${encodeURIComponent(String(options.qHash).toLowerCase())}`);
+        if (options.verifierId) qs.push(`verifierId=${encodeURIComponent(String(options.verifierId))}`);
+        if (options.verifierIds) qs.push(`verifierIds=${encodeURIComponent(String(options.verifierIds))}`);
+        if (options.tags) qs.push(`tags=${encodeURIComponent(String(options.tags))}`);
+        if (options.tagPrefix) qs.push(`tagPrefix=${encodeURIComponent(String(options.tagPrefix))}`);
+        if (options.tagContains) qs.push(`tagContains=${encodeURIComponent(String(options.tagContains))}`);
+        if (options.tagPrefixesAll) qs.push(`tagPrefixesAll=${encodeURIComponent(String(options.tagPrefixesAll))}`);
+        if (options.status) qs.push(`status=${encodeURIComponent(String(options.status))}`);
+        if (options.appId) qs.push(`appId=${encodeURIComponent(String(options.appId))}`);
+        if (options.chainCoverage) qs.push(`chainCoverage=${encodeURIComponent(String(options.chainCoverage))}`);
+        if (options.privacyLevel) qs.push(`privacyLevel=${encodeURIComponent(String(options.privacyLevel))}`);
+        if (options.includeHistory) qs.push("includeHistory=1");
+        if (options.includeFacets) qs.push(`includeFacets=${encodeURIComponent(String(options.includeFacets))}`);
+        if (options.visibility) qs.push(`visibility=${encodeURIComponent(String(options.visibility))}`);
+        if (options.isPublicRead) qs.push("isPublicRead=1");
+        return qs;
+      }
       async getProofsByWallet(walletAddress, options = {}) {
         if (!walletAddress || typeof walletAddress !== "string") {
           throw new ValidationError("walletAddress is required");
         }
         const id = walletAddress.trim();
         const pathId = /^0x[a-fA-F0-9]{40}$/i.test(id) ? id.toLowerCase() : id;
-        const qs = [];
-        if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
-        const cursorRaw = options.cursor !== null && options.cursor !== void 0 ? String(options.cursor).trim() : "";
-        if (cursorRaw) qs.push(`cursor=${encodeURIComponent(cursorRaw)}`);
-        else if (options.offset) qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
-        if (options.qHash) qs.push(`qHash=${encodeURIComponent(options.qHash.toLowerCase())}`);
+        const qs = this._buildProofsByWalletQuery(options);
         const query = qs.length ? `?${qs.join("&")}` : "";
         const response = await this._makeRequest(
           "GET",
@@ -2467,10 +2493,11 @@ ${bytes.length}`;
         return {
           success: true,
           proofs: Array.isArray(proofs) ? proofs : [],
-          totalCount: response.data?.totalCount ?? proofs.length,
+          totalCount: typeof response.data?.totalCount === "number" ? response.data.totalCount : null,
           hasMore: Boolean(response.data?.hasMore),
           nextOffset: response.data?.nextOffset ?? null,
-          nextCursor: typeof response.data?.nextCursor === "string" && response.data.nextCursor.trim() ? response.data.nextCursor.trim() : null
+          nextCursor: typeof response.data?.nextCursor === "string" && response.data.nextCursor.trim() ? response.data.nextCursor.trim() : null,
+          facets: response.data?.facets || null
         };
       }
       async getPrivateProofsByWallet(walletAddress, options = {}, wallet = null) {
@@ -2520,12 +2547,7 @@ ${bytes.length}`;
           }
           throw new ValidationError(`Failed to sign message: ${error.message}`);
         }
-        const qs = [];
-        if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
-        const cursorRaw = options.cursor !== null && options.cursor !== void 0 ? String(options.cursor).trim() : "";
-        if (cursorRaw) qs.push(`cursor=${encodeURIComponent(cursorRaw)}`);
-        else if (options.offset) qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
-        if (options.qHash) qs.push(`qHash=${encodeURIComponent(options.qHash.toLowerCase())}`);
+        const qs = this._buildProofsByWalletQuery(options);
         const query = qs.length ? `?${qs.join("&")}` : "";
         const response = await this._makeRequest("GET", `/api/v1/proofs/by-wallet/${encodeURIComponent(pathId)}${query}`, null, {
           "x-wallet-address": signerWalletAddress,
@@ -2540,7 +2562,7 @@ ${bytes.length}`;
         return {
           success: true,
           proofs: Array.isArray(proofs) ? proofs : [],
-          totalCount: response.data?.totalCount ?? proofs.length,
+          totalCount: typeof response.data?.totalCount === "number" ? response.data.totalCount : null,
           hasMore: Boolean(response.data?.hasMore),
           nextOffset: response.data?.nextOffset ?? null,
           nextCursor: typeof response.data?.nextCursor === "string" && response.data.nextCursor.trim() ? response.data.nextCursor.trim() : null
@@ -2657,6 +2679,64 @@ ${bytes.length}`;
         }
         return response;
       }
+      /**
+       * Get the public snapshot of a published gate: requirements, charge, schedule,
+       * checkout plan, and reward presence. Never returns the secret reward value —
+       * that is delivered post-verify via fulfillGate().
+       *
+       * @param {string} gateId Published gate handle
+       * @returns {Promise<object>} Public gate snapshot
+       */
+      async getGate(gateId) {
+        const id = String(gateId || "").trim();
+        if (!id || id.length > 80 || !/^[a-zA-Z0-9:_-]+$/.test(id)) {
+          throw new ValidationError("Valid gateId is required");
+        }
+        const response = await this._makeRequest("GET", `/api/v1/gates/${encodeURIComponent(id)}`);
+        if (!response.success || !response.data?.gate) {
+          throw new ApiError(`Gate lookup failed: ${response.error?.message || "Gate not found"}`, response.error);
+        }
+        return response.data.gate;
+      }
+      /**
+       * Post-verify reward delivery for hosted gate checkout. Requires a verified
+       * proof (qHash) for the gate; paid gates also require payment evidence
+       * (paymentCheckoutSessionId for card, or paymentTxHash for USDC).
+       *
+       * @param {object} params
+       * @param {string} params.gateId Published gate handle
+       * @param {string} params.qHash Verified proof receipt id
+       * @param {string} [params.walletAddress] Wallet bound to the proof (required without a session cookie)
+       * @param {string} [params.paymentCheckoutSessionId] Stripe checkout session id (card rail)
+       * @param {string} [params.paymentTxHash] USDC payment transaction hash (wallet rail)
+       * @returns {Promise<object>} `{ success, data: { gateId, qHash, fulfillment, successReturnUrl? } }`
+       */
+      async fulfillGate(params = {}) {
+        const gateId = String(params.gateId || "").trim();
+        if (!gateId || gateId.length > 80 || !/^[a-zA-Z0-9:_-]+$/.test(gateId)) {
+          throw new ValidationError("Valid gateId is required");
+        }
+        const qHash = String(params.qHash || "").trim();
+        if (!/^0x[a-fA-F0-9]{64}$/.test(qHash)) {
+          throw new ValidationError("Valid qHash is required");
+        }
+        const body = { qHash };
+        const walletAddress = String(params.walletAddress || "").trim();
+        if (walletAddress) body.walletAddress = walletAddress;
+        const paymentCheckoutSessionId = String(params.paymentCheckoutSessionId || "").trim();
+        if (paymentCheckoutSessionId) body.paymentCheckoutSessionId = paymentCheckoutSessionId;
+        const paymentTxHash = String(params.paymentTxHash || "").trim();
+        if (paymentTxHash) body.paymentTxHash = paymentTxHash;
+        const response = await this._makeRequest(
+          "POST",
+          `/api/v1/gates/${encodeURIComponent(gateId)}/fulfill`,
+          body
+        );
+        if (!response.success) {
+          throw new ApiError(`Gate fulfillment failed: ${response.error?.message || "Unknown error"}`, response.error);
+        }
+        return response;
+      }
       async checkGate(params) {
         const { walletAddress, requirements, proofs: preloadedProofs } = params;
         if (!validateUniversalAddress(walletAddress)) {