@neus/sdk 1.1.4 → 1.1.6

package/cli/neus.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { spawnSync } from 'node:child_process';
+import { exec, spawnSync } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -12,6 +12,13 @@ import {
 } from '../mcp-hosts.js';
 
 const __cliDir = path.dirname(fileURLToPath(import.meta.url));
+const CLI_PACKAGE_VERSION = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__cliDir, '..', 'package.json'), 'utf8')).version;
+  } catch {
+    return '0.0.0';
+  }
+})();
 
 const NEUS_APP_URL = 'https://neus.network';
 const NEUS_TOKEN_ENDPOINT = 'https://neus.network/api/v1/auth/mcp/token';
@@ -100,7 +107,7 @@ function emitCliBanner(cliOptions = {}) {
   if (!shouldEmitCliBanner(cliOptions)) return;
   const version = readCliVersion();
   const title = paint('NEUS', 'green');
-  const meta = `${paint(`v${version}`, 'dim')}${paint(' | trust receipts', 'dim')}`;
+  const meta = `${paint(`v${version}`, 'dim')}${paint(' | trust that travels', 'dim')}`;
   writeCliLine('');
   writeCliLine(`  ${title}  ${meta}`);
   writeCliLine('');
@@ -137,21 +144,20 @@ function describeClientResult(command, result) {
   }
   if (result.changed) return 'updated';
   if (result.authConfigured) return 'signed in';
+  if (result.configured) return 'ready';
   return 'ready';
 }
 
 function printBuilderGuidance(command, results) {
-  if (!['setup', 'auth'].includes(command)) return;
+  if (!['setup', 'auth', 'check'].includes(command)) return;
   const hasCodex = results.some(result => result.client === 'codex');
   writeCliLine('');
-  writeCliLine(paint('Builder notes', 'cyan'));
-  writeGuidanceLine('Use from any shell without a global install: `npx -y -p @neus/sdk neus ...`.');
+  writeCliLine(paint('Next steps', 'cyan'));
+  writeGuidanceLine('Run `npx -y -p @neus/sdk neus examples` for assistant prompts.');
   if (hasCodex) {
-    writeGuidanceLine('Codex owns OAuth: run `neus auth --client codex` or `codex mcp login neus`.');
+    writeGuidanceLine('Codex OAuth: `neus auth --client codex` or `codex mcp login neus`.');
   }
-  writeGuidanceLine(
-    'Claude plugin commands run inside Claude Code chat, not as `claude install`: `/plugin marketplace add https://github.com/neus/network`.'
-  );
+  writeGuidanceLine('Ask your assistant: "Use NEUS Verify before taking sensitive actions."');
 }
 
 function selectedClientNames(results) {
@@ -178,7 +184,7 @@ function printStatusGuidance(results) {
   writeGuidanceLine(NEUS_MCP_URL);
   writeCliLine(paint('Profile connection', 'cyan'));
   if (results.some(result => result.configured)) {
-    writeGuidanceLine('Saved config found. Run `npx -y -p @neus/sdk neus doctor --live` to confirm live Profile context.');
+    writeGuidanceLine('Saved config found. Run `npx -y -p @neus/sdk neus check` to confirm live connection.');
   } else {
     writeGuidanceLine(`No selected MCP host is configured yet. Run \`${preferredSetupCommand(results)}\`.`);
   }
@@ -298,6 +304,7 @@ function envAccessKey() {
 
 /** --access-key flag, else NEUS_ACCESS_KEY from the environment, else browser sign-in. */
 function resolveAccessKey(options) {
+  if (options?.oauth) return '';
   const explicit = String(options.accessKey || '').trim();
   if (explicit) return explicit;
   return envAccessKey();
@@ -309,6 +316,7 @@ function resolveLiveAccessKey(options, scope, cwd) {
   if (explicit) return explicit;
   const installed = readInstalledAccessKey(scope, cwd);
   if (installed) return installed;
+  if (options?.oauth) return '';
   return envAccessKey();
 }
 
@@ -581,7 +589,8 @@ function parseArgs(argv) {
     live: false,
     json: false,
     dryRun: false,
-    project: false
+    project: false,
+    oauth: false
   };
 
   for (let index = 1; index < argv.length; index += 1) {
@@ -637,6 +646,10 @@ function parseArgs(argv) {
       index += 1;
       continue;
     }
+    if (token === '--oauth') {
+      options.oauth = true;
+      continue;
+    }
     if (token === '--help' || token === '-h') {
       return { command: 'help', options };
     }
@@ -659,6 +672,8 @@ function printUsage(exitCode = 0) {
     '  auth          Sign in (browser, or NEUS_ACCESS_KEY / --access-key when set)',
     '  disconnect    Disconnect NEUS MCP (revoke the stored OAuth token or access key)',
     '  status        Show current NEUS MCP setup',
+    '  check         Confirm setup and live NEUS connection (alias for doctor --live)',
+    '  examples      Show assistant prompts to try after install',
     '  doctor        Deep check: config status, profile connection, and live MCP context',
     '  import        Detect and package supported assistant context for NEUS portability',
     '  export        Export the latest local NEUS portable agent manifest',
@@ -668,6 +683,7 @@ function printUsage(exitCode = 0) {
     '  --client <name[,name]>   Limit setup to claude, codex, cursor, or vscode',
     '  --project                Write shared project config instead of user config',
     '  --access-key <npk_...>   Override profile access key (else uses NEUS_ACCESS_KEY if set)',
+    '  --oauth                    Force browser OAuth (ignore NEUS_ACCESS_KEY in the environment)',
     '  --from <source>          Import source: auto, cursor, claude-code, or claude-desktop',
     '  --to <format>            Export format: manifest or json',
     '  --output <path>          Write exported manifest to a specific path',
@@ -1105,7 +1121,7 @@ function createEmptyManifest(source) {
     proofHints: {
       status: 'not-issued',
       qHashes: [],
-      next: ['neus setup', 'neus auth', 'neus doctor --live']
+      next: ['neus setup', 'neus auth', 'neus check']
     }
   };
 }
@@ -1383,7 +1399,7 @@ async function runLiveMcpDiagnostics(accessKey) {
       params: {
         protocolVersion: '2025-11-25',
         capabilities: {},
-        clientInfo: { name: 'neus-cli', version: '1.0.0' }
+        clientInfo: { name: 'neus-cli', version: CLI_PACKAGE_VERSION }
       },
       accessKey,
       signal: controller.signal
@@ -1424,6 +1440,9 @@ async function runLiveMcpDiagnostics(accessKey) {
       signal: controller.signal
     });
     const mode = context.ok ? context.payload?.mode?.current || context.payload?.mode || '' : '';
+    const profileCtx = context.ok ? context.payload?.profileContext : null;
+    const principal = profileCtx?.principal || null;
+    const proofsTotal = profileCtx?.profileSummary?.proofsSummary?.total;
     return {
       live: true,
       reachable: true,
@@ -1431,6 +1450,9 @@ async function runLiveMcpDiagnostics(accessKey) {
       toolsCount: toolNames.length,
       tools: toolNames,
       contextMode: mode,
+      sessionWallet: context.ok ? context.payload?.sessionWallet || principal?.primaryAccount || null : null,
+      profileHandle: principal?.handle || null,
+      proofsTotal: Number.isFinite(Number(proofsTotal)) ? Number(proofsTotal) : null,
       checks: [
         {
           name: 'initialize',
@@ -1693,9 +1715,12 @@ async function runAuthBrowser(options) {
         logStep('next', 'wait', 'finish sign-in in the browser');
       }
 
-      const { exec } = require('node:child_process');
-      const openCmd = process.platform === 'win32' ? 'start' : process.platform === 'darwin' ? 'open' : 'xdg-open';
-      exec(`${openCmd} "${authUrl}"`, err => {
+      const openCommand = process.platform === 'win32'
+        ? `cmd /c start "" "${authUrl.replace(/"/g, '\\"')}"`
+        : process.platform === 'darwin'
+          ? `open "${authUrl.replace(/"/g, '\\"')}"`
+          : `xdg-open "${authUrl.replace(/"/g, '\\"')}"`;
+      exec(openCommand, { shell: true }, err => {
         if (err && !options.json) {
           logStep('warn', 'browser', 'open the URL above manually');
         }
@@ -1810,12 +1835,18 @@ async function runSetup(options) {
   }
 
   if (options.json) {
+    payload.authRequired = !accessKey && !options.dryRun;
+    if (payload.authRequired) {
+      payload.nextCommand = clients.length === 1 && clients[0] === 'codex'
+        ? 'neus auth --client codex'
+        : 'neus auth';
+    }
     printJson(payload);
     return payload;
   }
 
   printFlowSummary('setup', scope, initResults, {
-    nextStep: accessKey ? 'Open your MCP client and ask the assistant to use NEUS Trust.' : '',
+    nextStep: accessKey ? 'Run `neus examples`, then ask your assistant to use NEUS Verify.' : '',
     cliOptions: options
   });
 
@@ -1823,7 +1854,7 @@ async function runSetup(options) {
     const authResult = await runAuth(options);
     if (authResult && !authResult.hasErrors) {
       printFlowSummary('auth', authResult.scope, authResult.results, {
-        nextStep: 'Open your MCP client and ask the assistant to use NEUS Trust.',
+        nextStep: 'Run `neus examples`, then ask your assistant to use NEUS Verify.',
         cliOptions: options
       });
     }
@@ -1910,7 +1941,39 @@ function runExport(options) {
   printExportSummary(payload, options);
 }
 
+const ASSISTANT_EXAMPLE_PROMPTS = [
+  'Use NEUS Verify before taking sensitive actions.',
+  'Check whether I already have the required trust receipt.',
+  'Verify this agent is trusted before it runs tools.',
+  'Use NEUS Vault before storing or using secrets.',
+  'Show the receipt for this verification.'
+];
+
+function runExamples(options) {
+  const payload = {
+    command: 'examples',
+    intro: 'Try this in your assistant:',
+    prompts: ASSISTANT_EXAMPLE_PROMPTS
+  };
+
+  if (options.json) {
+    printJson(payload);
+    return;
+  }
+
+  emitCliBanner(options);
+  writeCliLine(paint('examples', 'green'));
+  writeCliLine('');
+  writeCliLine(`  ${paint(payload.intro, 'dim')}`);
+  writeCliLine('');
+  ASSISTANT_EXAMPLE_PROMPTS.forEach((prompt, index) => {
+    writeCliLine(`  ${paint(String(index + 1) + '.', 'cyan')} ${prompt}`);
+  });
+  writeCliLine('');
+}
+
 async function runDoctor(options) {
+  const displayCommand = options.displayCommand || 'doctor';
   const scope = resolveScope(options);
   const cwd = process.cwd();
   const clients = resolveClients(scope, options.clients);
@@ -1922,7 +1985,7 @@ async function runDoctor(options) {
   const configuredClients = inspected.filter(r => r.configured);
   const liveAccessKey = resolveLiveAccessKey(options, scope, cwd);
   const payload = {
-    command: 'doctor',
+    command: displayCommand,
     scope,
     clients: inspected,
     configuredCount: configuredClients.length,
@@ -1951,7 +2014,7 @@ async function runDoctor(options) {
 
   if (configuredClients.length === 0) {
     emitCliBanner(options);
-    writeCliLine(paint('doctor', 'green'));
+    writeCliLine(paint(displayCommand, 'green'));
     for (const result of inspected) {
       if (result.error) {
         logStep('warn', result.client, result.error);
@@ -1966,13 +2029,13 @@ async function runDoctor(options) {
     writeGuidanceLine(NEUS_MCP_URL);
     writeCliLine(paint('Profile connection', 'cyan'));
     writeGuidanceLine(`No selected MCP host is configured yet. Run \`${preferredSetupCommand(inspected)}\`.`);
-    writeGuidanceLine(`Then run \`${preferredAuthCommand(inspected)}\` and re-check with \`npx -y -p @neus/sdk neus doctor --live\`.`);
+    writeGuidanceLine(`Then run \`${preferredAuthCommand(inspected)}\` and re-check with \`npx -y -p @neus/sdk neus check\`.`);
     writeCliLine('');
     process.exitCode = 1;
     return;
   }
 
-  printFlowSummary('doctor', scope, inspected, { cliOptions: options });
+  printFlowSummary(displayCommand, scope, inspected, { cliOptions: options });
   const hasCodex = inspected.some(result => result.client === 'codex');
   writeCliLine(paint('Profile connection', 'cyan'));
   if (options.live && payload.mcp) {
@@ -1983,16 +2046,19 @@ async function runDoctor(options) {
           : 'No account credential found for the configured MCP clients. Run `neus auth`.'
       );
     } else {
-      logStep(
-        payload.mcp.authenticated ? 'ok' : 'warn',
-        'profile',
-        payload.mcp.authenticated
-          ? `live MCP context confirmed; ${payload.mcp.toolsCount || 0} tools discovered`
-          : 'live MCP context was not confirmed'
-      );
+      if (payload.mcp.authenticated) {
+        const handle = payload.mcp.profileHandle ? ` as ${payload.mcp.profileHandle}` : '';
+        const receipts =
+          payload.mcp.proofsTotal != null ? ` · ${payload.mcp.proofsTotal} trust receipts on file` : '';
+        logStep('ok', 'profile', `connected${handle}${receipts}`);
+        writeGuidanceLine('NEUS Verify is ready. Ask your assistant to verify trust before sensitive actions.');
+        writeGuidanceLine('Run `npx -y -p @neus/sdk neus examples` for starter prompts.');
+      } else {
+        logStep('warn', 'profile', 'live connection was not confirmed — run `neus auth`');
+      }
     }
   } else if (liveAccessKey) {
-    writeGuidanceLine('Saved credential found. Run `neus doctor --live` to confirm Profile context.');
+    writeGuidanceLine('Saved credential found. Run `neus check` to confirm live connection.');
   } else {
     writeGuidanceLine(
       hasCodex
@@ -2096,12 +2162,12 @@ async function main() {
           printJson(result);
         } else if (result.authMethod !== 'browser') {
           printFlowSummary('auth', result.scope, result.results, {
-            nextStep: 'Open your MCP client and ask the assistant to use NEUS Trust.',
+            nextStep: 'Run `neus examples`, then ask your assistant to use NEUS Verify.',
             cliOptions: options
           });
         } else {
           printFlowSummary('auth', result.scope, result.results, {
-            nextStep: 'Open your MCP client and ask the assistant to use NEUS Trust.',
+            nextStep: 'Run `neus examples`, then ask your assistant to use NEUS Verify.',
             cliOptions: options
           });
         }
@@ -2122,10 +2188,18 @@ async function main() {
       }
       return;
     }
+    if (command === 'check') {
+      await runDoctor({ ...options, live: true, displayCommand: 'check' });
+      return;
+    }
     if (command === 'doctor') {
       await runDoctor(options);
       return;
     }
+    if (command === 'examples') {
+      runExamples(options);
+      return;
+    }
     if (command === 'import') {
       runImport(options);
       return;

package/client.js

@@ -11,19 +11,19 @@ import {
 
 const 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 }
 };
 
 const EVM_ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
@@ -1204,6 +1204,12 @@ export class NeusClient {
         typeof options?.storeOriginalContent === 'boolean' ? options.storeOriginalContent : true
     };
     if (typeof options?.enableIpfs === 'boolean') optionsPayload.enableIpfs = options.enableIpfs;
+    // Receipts persist offchain by default; hub registry anchoring is explicit opt-in.
+    if (options?.publishToHub === true) {
+      optionsPayload.publishToHub = true;
+    } else {
+      delete optionsPayload.publishToHub;
+    }
 
     const requestData = {
       verifierIds: normalizedVerifierIds,
@@ -1471,6 +1477,33 @@ export class NeusClient {
     return true;
   }
 
+  _buildProofsByWalletQuery(options = {}) {
+    const qs = [];
+    if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
+    const cursorRaw = options.cursor !== null && options.cursor !== undefined ? String(options.cursor).trim() : '';
+    if (cursorRaw) qs.push(`cursor=${encodeURIComponent(cursorRaw)}`);
+    else if (options.offset !== undefined && 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');
@@ -1479,12 +1512,7 @@ export class NeusClient {
     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 !== undefined ? 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(
@@ -1500,13 +1528,14 @@ export class NeusClient {
     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
+          : null,
+      facets: response.data?.facets || null,
     };
   }
 
@@ -1569,12 +1598,7 @@ export class NeusClient {
       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 !== undefined ? 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, {
@@ -1592,7 +1616,7 @@ export class NeusClient {
     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:
@@ -1730,6 +1754,67 @@ export class NeusClient {
     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;