NEUS Docs

A published gate is a reusable checkout: visitors pass the checks you configured, optionally pay, and receive the reward you attached. This page documents the full server contract behind hosted checkout so you can mirror it from your own app or backend. The simplest integrations do not need any of this directly — use the VerifyGate widget or the hosted checkout link. Read on when you want to drive the flow yourself.

Which API host?

Caller	Gate snapshot	Fulfill
SDK (`NeusClient`)	`client.getGate(gateId)`	`client.fulfillGate(...)`
`api.neus.network`	`GET /api/v1/profile/gates/{gateId}`	`POST /api/v1/profile/gates/{gateId}/fulfill`
`neus.network` (browser)	`GET /api/v1/gates/{gateId}`	`POST /api/v1/gates/{gateId}/fulfill`

Prefer the SDK on your server. The neus.network paths are the same contract, proxied for same-origin browser calls.

Lifecycle

Snapshot — load the public gate: requirements, price, schedule, and reward presence (not the secret reward value). Use client.getGate(gateId) or GET /api/v1/profile/gates/{gateId} on api.neus.network.
Eligibility — GET /api/v1/proofs/check?gateId=...&address=...&includePrivate=true&includeQHashes=true evaluates the visitor’s existing proofs against every requirement.
Verify — if checks are missing, the visitor completes them (hosted verify link, VerifyGate, or POST /api/v1/verification for signature-based verifiers). Pass gateId and reuse satisfied checks via options.reusedVerifierProofs.
Pay — for paid gates, payment happens after verification by default (executionOrder: "verifyThenCharge"). Gates with a connected payout account settle through one Stripe checkout session — the visitor picks card or crypto there. Gates with a custom wallet settle by direct USDC on Base.
Fulfill — deliver the reward with the verified qHash (plus payment evidence for paid gates) via client.fulfillGate(...) or POST /api/v1/gates/{gateId}/fulfill.

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

const client = new NeusClient();

// 1. Snapshot
const gate = await client.getGate('gate_your-listing');

// 2. Eligibility
const check = await client.gateCheck({
  gateId: 'gate_your-listing',
  address: visitorWallet,
  includePrivate: true,
  includeQHashes: true,
});

// 5. Fulfill (after verify + pay)
const reward = await client.fulfillGate({
  gateId: 'gate_your-listing',
  qHash: verifiedQHash,
  walletAddress: visitorWallet,
});

Reading the gate check

When gateId is passed, the response carries a per-requirement data.gate block. gate.allRequiredSatisfied === true is the only signal that checkout is ready. Top-level eligible and matchedCount exist for criteria-only checks and must not be used as gate readiness on their own.

{
  "success": true,
  "data": {
    "eligible": true,
    "gate": {
      "gateId": "gate_your-listing",
      "allRequiredSatisfied": true,
      "satisfiedVerifierIds": ["proof-of-human", "wallet-risk"],
      "missingVerifierIds": [],
      "reusedVerifierProofs": {
        "proof-of-human": "0xabc…",
        "wallet-risk": "0xdef…"
      }
    }
  }
}

satisfiedVerifierIds / missingVerifierIds — which requirements existing receipts cover.
reusedVerifierProofs — verifierId → qHash map (requires includeQHashes=true). Pass it as options.reusedVerifierProofs on POST /api/v1/verification so satisfied checks are not re-run.
Re-run the gate check after every interactive step (OAuth grant, personhood session) before treating checkout as complete. Interactive completions only count once the protocol confirms them here.

Request-time vs receipt-based rules

Each requirement carries match rows ({ path, op, value }). They are enforced at two different moments:

Rule type	Examples	Enforced
Request-time (`eq` on input fields)	`domain`, `contractAddress`, `chainId`, `minBalance`, `provider`	When the verification request is submitted — the locked value must match exactly
Receipt-based (`traits.`, `claims.`, risk fields, `gte`/`lte`)	`claims.age_min`, `claims.liveness_verified`, `riskLevel`, `overallRisk`	After verification, against the check result

Receipt-based rows mean an existing receipt may not satisfy a stricter gate. For example, a personhood receipt created for a basic gate will not satisfy another gate that also requires claims.age_min ≥ 21. The visitor must complete the additional check. For wallet-risk gates, any receipt-based row also requires policyVerified to be true. A failed risk check never satisfies a gate.

Verification links

In the gate builder, choose Verification link. The visitor pastes their own HTTPS URL; NEUS reads JSON from that URL or its conventional .json form and checks whether verified is true. Builders do not configure fetch targets, callbacks, or provider-specific connectors. The saved gate contains the portable match rows reference.type = url and resolved.verified = true. API clients can use other resolved.* output matches when a source exposes a different public JSON contract. Resolved-link receipts default to five-minute freshness so checkout does not silently reuse old source status. See Content ownership for the wire shape and resolver safeguards.

Paid gates

The snapshot’s monetization.charge describes pricing:

amountUsd, label, methods (usdc, stripe), cardPayoutReady
executionOrder — verifyThenCharge (default): verification completes first, then payment, then fulfill.

Method semantics:

stripe — hosted Stripe checkout. One session covers card and crypto; the visitor chooses at checkout. Available when the gate has a connected payout account.
usdc — direct on-chain USDC transfer on Base. The only method for custom-wallet payout gates.

Fulfill payment evidence:

Stripe (card or crypto) — paymentCheckoutSessionId from the checkout return.
USDC — paymentTxHash of the on-chain transfer.

Payments are bound to one gateId + qHash pair and cannot be reused for another checkout (409 PAYMENT_ALREADY_USED).

Fulfillment result

{
  "success": true,
  "data": {
    "gateId": "gate_your-listing",
    "qHash": "0xabc…",
    "fulfillment": {
      "delivery": "redirect",
      "type": "redirect_url",
      "value": "https://yourapp.com/members"
    }
  }
}

fulfillment.delivery is one of access_granted, redirect, download, or reveal. The secret value appears only here — after verification (and payment) succeeded for the caller’s wallet.

Campaign windows

Gates may carry a schedule (startsAt / endsAt). Outside the window, gate checks report the closed state and verification/fulfillment are refused server-side (GATE_NOT_STARTED, GATE_ENDED). Treat the window as enforced — it is not a UI-only hint.

VerifyGate widget

Drop-in checkout for published gates

Pricing

Plans and credits

Billing

How verification and checkout charges work

API overview

Full HTTP API surface

Verifier catalog

Every check a gate can require

Overview

Checks

Platform

SDK

Widgets

API

Gate checkout

Which API host?

Lifecycle

Reading the gate check

Request-time vs receipt-based rules

Verification links

Paid gates

Fulfillment result

Campaign windows

Next

VerifyGate widget

Pricing

Billing

API overview

Verifier catalog

​Which API host?

​Lifecycle

​Reading the gate check

​Request-time vs receipt-based rules

​Verification links

​Paid gates

​Fulfillment result

​Campaign windows

​Next

VerifyGate widget

Pricing

Billing

API overview

Verifier catalog

Which API host?

Lifecycle

Reading the gate check

Request-time vs receipt-based rules

Verification links

Paid gates

Fulfillment result

Campaign windows

Next