Humanity Docs

Humanity Docs

• Build with Humanity: Choose between SDK/API integration (traditional web2) or on-chain smart contracts (web3) to add proof-of-humanity verification. Includes quickstart links for both paths.
• Start Here - Choose Your Integration Path: Choose between SDK/API integration (traditional web2) or on-chain smart contracts (web3) to add proof-of-humanity verification. Includes quickstart links for both paths.
• Build with the SDK / API: Build web applications with Humanity using OAuth 2.0 like Google or Stripe. Complete integration guide for web2 developers.
• SDK QuickStart: Add Sign in with Humanity to your React app in under 10 minutes — same OAuth pattern as Google or GitHub, with biometric human verification built in.
• SDK OAuth Scopes and Presets: Configure what user data your app can access using OAuth scopes. Complete list available presets including identity, KYC, financial, and social data.
• @humanity-org/react-sdk: React-first setup, core components and hooks, authentication flow, and essential usage patterns for the Humanity React SDK.
• Components: In-depth component reference: UI building blocks, required props, customization options, and composition patterns for the Humanity React SDK.
• Hooks: In-depth hooks reference: data fetching and mutations, cache behavior, auth/session hooks, and common usage patterns for the Humanity React SDK.
• Error handling: In-depth error handling: error types, retry strategies, user messaging, and recovery patterns for the Humanity React SDK.
• @humanity-org/connect-sdk: In-depth SDK reference: TypeScript interfaces, query engine documentation, error handling, and advanced usage patterns for the Humanity Connect SDK.
• SDK / API Integration Overview: Complete guide to Humanity's API surface, SDK capabilities, OAuth flows, and use cases for web2 authentication and verification.
• SDK Environments & Tooling: Sandbox vs production environments, API credentials, test data, debugging tools, and developer portal access for SDK integration.
• Build On-Chain: Build decentralized applications with Humanity's smart contracts. Deploy verification logic directly on-chain for web3 applications.
• On-Chain QuickStart: Get your first Humanity on-chain integration. Clone the scaffold, deploy a verification contract to Humanity testnet, and confirm a wallet is linked to a verified human.
• On-Chain Quick Start Guide
• Network Information - Testnet: Humanity testnet connection details: RPC endpoints, chain ID, block explorer, faucet links, and network configuration for development.
• Network Information - Mainnet: Humanity mainnet connection details: RPC endpoints, chain ID, block explorer, bridge information, and production network configuration.
• Credentials Verification Service: On-chain oracle interface for querying user credentials. Smart contracts can verify claims (presets) within categories (scopes) without exposing personal data.
• Canonical Contracts: Official open-source smart contract interfaces and implementations for on-chain development with Humanity verification.
• IFeeEscrow: Smart contract interface for FeeEscrow: handles verification fees, escrow deposits, and payment distribution for on-chain verification requests.
• IVerificationOracle: Verification Oracle interface: query user credentials on-chain, verify claims, and integrate proof-of-humanity into smart contract logic.
• Understanding Humanity: Introduction to Humanity's biometric identity verification system, architecture, and core concepts for developers.
• What Is Humanity: Biometric identity verification layer built on palm scanning and Web3 infrastructure. Enables proof-of-humanity without storing personal data.
• The Problem We Solve: Traditional identity systems lack privacy, uniqueness verification, and user sovereignty. Learn how Humanity solves bot prevention, KYC, and age verification challenges.
• How Biometric Proof-of-Humanity Works: This page describes the concept of SSI and how biometrics can empower humans to be fully autonomous when it comes to owing their own data.
• Core Concepts: Verifiable Credentials & SSI: Essential concepts for developers: Verifiable Credentials (VCs), claims, presets, scopes, and how they enable privacy-preserving identity verification.
• Overall System Architecture: Technical architecture overview showing decentralized infrastructure.
• Developer Guides & Tutorials: Step-by-step guides, tutorials, and reference implementations for both SDK/API and on-chain integration with Humanity.
• Generating Mock Credentials: Create test credentials for development and testing. Mock data generation for SDK flows and on-chain verification without real palm scans.
• SDK / API Guides: Practical guides and code examples for integrating Humanity SDK into web applications with common use cases.
• SDK Implementation Recipes & Patterns: Prerequisites, common integration patterns and best practices for SDK usage.
• Frontend OAuth with the Connect SDK: Build a React app that authenticates users with Humanity's OAuth flow and gates content based on biometric verification — using the Connect SDK directly without pre-built components.
• Personalized Newsletter App - Reference Implementation: Full-stack reference application demonstrating Humanity SDK integration with user authentication, email verification, and personalized content delivery.
• Personalized Newsletter App Overview: Complete architecture overview, repository links, high-level flow diagram, and prerequisites for the newsletter reference app.
• Installing the App: Step-by-step installation guide: clone repository, configure environment variables, install dependencies, set up OAuth credentials, and run locally.
• Understanding the SDK Usage: Code walkthrough explaining SDK initialization, authentication flow, callback handling, user data retrieval, and error handling in the newsletter app.
• On-Chain Guides: Practical guides for building decentralized applications with Humanity Protocol's on-chain verification infrastructure.
• Connect Wallets: Connect Web3 wallets to Humanity network for testnet and mainnet interactions.
• Add Humanity Testnet to Metamask: Configure MetaMask for Humanity testnet: network name, RPC URL, chain ID, currency symbol, and block explorer URL.
• Add Humanity Mainnet to Metamask: Configure MetaMask for Humanity mainnet: network name, RPC URL, chain ID, currency symbol, and block explorer URL.
• Fund Your Wallet: Get testnet tokens and mainnet funds for deploying contracts and paying gas fees on Humanity network.
• Fund Your Testnet Wallet: Request free testnet tokens from the faucet for development and testing. Includes faucet URL and usage instructions.
• Fund Your Mainnet Wallet: Acquire mainnet tokens via bridges, exchanges, or direct transfer for production smart contract deployment and gas fees.
• Deploy an ERC-20 Token on Humanity Testnet using Hardhat: Complete tutorial: write, compile, test, deploy, and verify an ERC-20 token smart contract on Humanity testnet using Hardhat framework.
• Verified Airdrop dApp - Reference Implementation: Reference dApp demonstrating on-chain credential verification for token airdrops. Only verified humans can claim tokens using proof-of-humanity.
• Verified Airdrop dApp Overview: Architecture overview, smart contract design, frontend integration, end-to-end verification flow, repository links, and setup prerequisites.
• Smart Contracts Set Up: Deploy and configure verification oracle, airdrop contract, and credential checking logic for the verified airdrop dApp on testnet.
• Front End Integration: Build React frontend that connects wallets, checks verification status, calls smart contract functions, and displays airdrop eligibility.
• Starter Templates & Examples: Production-ready starter templates and example repositories for rapid development with Humanity SDK and smart contracts.
• SDK Integration Templates: Framework-specific starter templates with Humanity SDK pre-configured: Next.js, React, Vue, Express, and full-stack examples.
• connect-sdk-examples: GitHub repository collection with working examples: authentication flows, preset usage, query patterns, and production-ready templates you can clone and deploy.
• react-sdk-examples: GitHub repository collection with working examples such as full sdk capabilities exploration or identity-gated access.
• On-Chain Templates: Smart contract templates and scaffold projects for building decentralized applications with Humanity verification.
• Scaffold Humanity: Full-stack application based on Scaffold-ETH to build on-chain dApps with Humanity.
• Developer Portal: Access the Humanity developer dashboard to create applications, generate API credentials, configure OAuth settings, and manage integrations. Available for sandbox and production.
• Working with LLMs: Optimize your development workflow using AI assistants with Humanity documentation. LLM integration guides for major AI coding tools.
• Cursor Integration Guide: Integrate Humanity docs with Cursor IDE using native documentation indexing. Enable AI autocomplete and chat with full context of our API reference.
• Claude Code Integration Guide: Use custom MCP server to give Claude Code (CLI and VS Code extension) real-time access to Humanity documentation and examples.
• Codex Integration Guide: Give Codex (VS Code) real-time access to Humanity documentation and examples using a custom MCP server.
• Glossary: Comprehensive glossary of Humanity terminology: VCs, presets, scopes, claims, SSI, biometric verification, and blockchain concepts.
• Community / Support: Join Humanity developer community on Discord, GitHub, and Twitter. Get technical support, report bugs, and request features.
• zkProofer Node: Complete guide to purchasing, running, and managing zkProofer nodes on Humanity network.
• What is the zkProofer Node: Learn what zkProofer nodes do, how they work, and why they matter for Humanity's decentralized trust network.
• Node Reward Distribution: Understand how node operators earn protocol rewards and verification fees, and the mechanics behind reward distribution.
• KYC & Eligibility: Check eligibility requirements and KYC process before purchasing or operating a zkProofer node.
• How to Purchase zkProofer Nodes: Step-by-step guide to buying node licenses, from wallet setup through completion of your purchase.
• Tiers and Pricing: Explore available license tiers, pricing options, and early-buyer rewards for the node sale.
• How to Run zkProofer Nodes: Activate your node and begin earning. Choose between delegating to a provider or running it yourself.
• Binding & Delegating: Bind your license NFT and delegate it to start verification work and accrual of rewards.
• Using a NaaS Provider: Run your node through a Node-as-a-Service provider for hands-off operation and automated management.
• EaseFlow: Deploy and manage your node using EaseFlow's hosted service with monitoring and support included.
• Running your own Node: Self-host your verification node using Docker. Full control and technical responsibility required
• Stopping Delegation & Unbinding: Deactivate your node and stop earning rewards when you no longer want to participate.
• How to Manage zkProofer Nodes: Monitor gas, track rewards, delegate licenses, and manage daily node operations from the Operator Portal.
• Managing Licenses: View, transfer, and re-delegate your license NFTs across nodes.
• Managing Rewards: Track earned rewards, understand claim cycles, and view distribution details in the Operator Portal.
• Operator Portal: Access the dashboard for delegating licenses, monitoring node health and tracking performance metrics.
• FAQ: Common questions about purchasing, running, managing, and earning rewards with zkProofer nodes.
• Support: Get help: contact support, find community resources, and escalation paths for technical issues.
• Release notes: Latest updates, version changes, and deprecation notices for node software and documentation.
• zkProofer Node - NaaS Provider Integration Guide: Instructions for Node-as-a-Service (NaaS) providers integrating Humanity Verification Nodes into their platform.
• Whitepaper: Technical whitepaper detailing Humanity's architecture, cryptographic foundations, economic model, and decentralized verification system.

API Reference

• Humanity Developer Platform API: Complete REST API reference for Humanity Protocol: authentication, OAuth endpoints, user data retrieval, presets, queries, and credential verification.
• Getting Started: API quickstart guide: obtain credentials, authenticate, make your first API request, and understand response formats.
• Resources: Links to main reference for the documentation of the SDK / API
• API Reference
• Models

Agent Instructions: Querying This Documentation

If you need additional information, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on a page URL with the ask query parameter:

GET https://docs.humanity.org/build-with-humanity.md?ask=<question>

The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.