Skip to main content
Recommended end-to-end path for a production NEUS integration.

​
Standard Flow

1

Check gate eligibility

Use GET /api/v1/proofs/check (or client.gateCheck(...)).Optionally include X-Neus-App: <appId> for attribution (non-secret).
2

Run verification (if not eligible)

  • Instant / lookup verifiers: submit verification request.
  • Interactive verifiers: use hosted checkout via VerifyGate.
3

Poll status

For async verifiers, poll until terminal state.
4

Unlock access

When eligible, persist the returned receipt identifier (proofId in SDK responses, {qHash} on HTTP paths).

​
Verification Modes

ModeStrategyUse When
Reuse-first gatingstrategy="reuse-or-create"Standard UX
Fresh proof requiredstrategy="fresh"High-stakes actions
Read-only checkstrategy="reuse"Don’t want to create new proofs

​
Session-First Integration

For lowest friction: use hosted verify + auth code exchange.
  1. Redirect users to https://neus.network/verify?intent=login&returnUrl=...
  2. After sign-in, the page returns an auth code
  3. If NEUS has enabled partner code exchange for your deployment, your server calls POST https://api.neus.network/api/v1/auth/code/exchange with the code and your NEUS-issued partner credential
  4. Subsequent API calls use cookie/Bearer without per-request signing
Use this only for the hosted session-first path. For the full routing and popup contract, see Auth + Hosted Verify.

​
Hosted Checkout Requirements

Interactive verifiers (ownership-social, ownership-org-oauth, proof-of-human) require hosted checkout.
  • Default checkout URL: https://neus.network/verify (or use SDK getHostedCheckoutUrl())
  • Sponsored flows: include X-Neus-App (public appId) and X-Sponsor-Grant when your backend is covering verification costs.

​
Policy-Based Gate Checks

For backend policy enforcement, use gateCheck with explicit recency:
ParameterUse For
sinceExact timestamp windows
sinceDaysCoarse policy windows
Tight windows are recommended for point-in-time state verifiers.

​
Privacy and Access Model

  • Private-by-default proofs are recommended.
  • Public + discoverable proofs support broad reuse and discovery.
  • Private proof reads require owner-authenticated access or explicit grant-based sharing.

​
Verify Widget (Script Tag)

The easiest integration path for non-React or non-framework sites. One script tag, one HTML attribute, no build step: 
<script src="https://verify.neus.network/widget.js"></script>
<div data-neus-proof="0xYOUR_PROOF_RECEIPT_ID"></div>
The badge auto-renders on page load. Clicking it links to the proof on neus.network.
CORS: The widget calls GET https://api.neus.network/api/v1/verification/status/:qHash using your proof identifier value. This endpoint responds with Access-Control-Allow-Origin: *. No configuration needed.

​
Optional Attributes

AttributeDescription
data-neus-proofProof receipt identifier (required). Use the SDK proofId value.
data-neus-api-urlCustom API base (default: https://api.neus.network)
data-neus-ui-baseCustom viewer base (default: https://neus.network)
data-neus-sizesm (default) or md
data-neus-show-chainstrue to show chain count

​
Manual JS API

NeusWidget.mount(el, opts);
NeusWidget.mountAll(root?);
NeusWidget.unmount(el);

Hub Integrator Setup

Domain and org setup.

Auth + Hosted Verify

Hosted login flows.

API Overview

HTTP endpoints.