NEUS SDK

JavaScript client (and optional widgets) for the NEUS Network verification API.

Install

npm install @neus/sdk

Create a proof (browser wallet flow)

This path requests a wallet signature in the browser and submits the verification request:

import { NeusClient } from '@neus/sdk';

const client = new NeusClient({ apiUrl: 'https://api.neus.network' });

const res = await client.verify({
  verifier: 'ownership-basic',
  content: 'Hello NEUS'
});

// Proof ID (standard). qHash is a deprecated alias.
const proofId = res.proofId;
const status = await client.getStatus(proofId);

Client configuration

const client = new NeusClient({
  // Optional: API base URL (default: https://api.neus.network)
  apiUrl: 'https://api.neus.network',
  // Optional: request timeout (ms)
  timeout: 30000,
});

Create a proof (server / manual signing)

If you already have a signature over the NEUS Standard Signing String, submit it directly:

const res = await client.verify({
  verifierIds: ['ownership-basic'],
  data: {
    owner: '0x1111111111111111111111111111111111111111',
    content: 'Hello NEUS',
    reference: { type: 'url', id: 'https://example.com' }
  },
  walletAddress: '0x1111111111111111111111111111111111111111',
  signature: '0x...',
  signedTimestamp: Date.now(),
  chainId: 84532,
  options: { privacyLevel: 'private' }
});

What verifiers are available?

Use the API directly (avoids drift):

• GET /api/v1/verification/verifiers

Hosted interactive verifiers

For interactive verifiers (ownership-social, ownership-org-oauth, proof-of-human), use VerifyGate hosted checkout mode. These flows require NEUS-hosted popup/redirect UX (OAuth/ZK), not direct wallet-only creation via client.verify(...).

import { VerifyGate } from '@neus/sdk/widgets';

export default function HostedGateExample() {
  return (
    <VerifyGate
      requiredVerifiers={['ownership-social']}
      onVerified={(result) => {
        console.log('Hosted verification complete:', result.proofId);
      }}
    >
      <button>Unlock with Social</button>
    </VerifyGate>
  );
}

Gate checks (recommended for server-side gating)

For production server-side gating, prefer the minimal public endpoint:

const res = await client.gateCheck({
  address: 'YOUR_WALLET_OR_DID',
  verifierIds: ['token-holding'],
  contractAddress: '0x...',
  minBalance: '100',
  chainId: 8453,
  // Optional: require a recent proof for point-in-time verifiers (example: last hour)
  since: Date.now() - 60 * 60 * 1000
});

if (!res.data?.eligible) {
  throw new Error('Access denied');
}

Note: gateCheck evaluates existing public/discoverable proofs. For strict real-time decisions, create a new proof via client.verify(...) (or POST /api/v1/verification) and use the final status.

Resilience & Polling

The SDK is designed for production stability:

• Automatic Backoff: pollProofStatus() automatically detects rate limiting (429) and applies jittered exponential backoff.

• Wallet Identification: Automatically attaches headers to preferred wallet-based limiting for higher reliability behind shared IPs (NATs).

• Private proof by Proof ID: client.getPrivateStatus(proofId, wallet)

• Private proofs by wallet/DID: client.getPrivateProofsByWallet(walletOrDid, { limit, offset }, wallet) (owner dashboard / first-party UX only; not recommended for integrator gating)

• Revoke your proof: client.revokeOwnProof(proofId, wallet)

Example:

const privateData = await client.getPrivateStatus(proofId, window.ethereum);

const privateProofs = await client.getPrivateProofsByWallet(
  'YOUR_WALLET_OR_DID',
  { limit: 50, offset: 0 },
  window.ethereum
);

await client.revokeOwnProof(proofId, window.ethereum);

Compatibility note: qHash remains supported as a deprecated alias (proofId === qHash).

React widgets

For UI gating, see ./widgets/README.md.

Widget imports:

import { VerifyGate, ProofBadge } from '@neus/sdk/widgets';

Reference docs

• API Reference: ../docs/api/README.md
• OpenAPI (JSON): ../docs/api/public-api.json