Documentation

HumanLayer API Reference

Everything you need to integrate proof-of-humanity into your application.

Base URL: https://api.humanlayer.networkVersion: v1

Quickstart

Get human verification working in your app in under 60 seconds.

1. Install the SDK

bash
npm install @humanlayerlabs/sdk

2. Verify a wallet

typescript
import { HumanLayer } from '@humanlayerlabs/sdk';

const isHuman = await HumanLayer.isHuman('0xYourWalletAddress');
// Returns: true | false

3. Gate access by score

typescript
const access = await HumanLayer.gateAccess(wallet, {
  minScore: 60 // Builder tier and above
});

if (access.allowed) {
  // Real human — grant access
  console.log(access.identity.score);      // 82
  console.log(access.identity.tierName);   // "Builder"
} else {
  // Bot or unverified — deny access
}

Authentication

Free tier endpoints require no API key. Paid tier endpoints require an API key passed as a header.

FreeNo API key required

Badge API, /v1/verify/:wallet, /api/identity/:wallet/rank — all open, no authentication needed.

PaidAPI key required
bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.humanlayer.network/api/identity/:wallet/guardian

Get your API key from the dashboard after connecting your wallet.

JavaScript / TypeScript SDK

@humanlayerlabs/sdk — the core SDK for any JavaScript environment.

View on npm →
bash
npm install @humanlayerlabs/sdk

isHuman(wallet)

typescript
import { HumanLayer } from '@humanlayerlabs/sdk';

const result = await HumanLayer.isHuman(wallet);
// result: true | false

gateAccess(wallet, options)

typescript
const access = await HumanLayer.gateAccess(wallet, {
  minScore: 60,       // Minimum Human Score required
  minTier: 3,         // Minimum tier (1–5)
  blockAnomalous: true // Block flagged wallets
});

// access.allowed: boolean
// access.identity.score: number (0–144)
// access.identity.tier: number (1–5)
// access.identity.tierName: string
// access.identity.verifiedAt: string

getIdentity(wallet)

typescript
const identity = await HumanLayer.getIdentity(wallet);

// identity.wallet: string
// identity.score: number
// identity.tier: number
// identity.tierName: string
// identity.verified: boolean
// identity.verifiedAt: string
// identity.nftTokenId: string

wagmi Connector

@humanlayerlabs/wagmi-connector — drop-in wagmi connector that silently checks Human Score on every wallet connection.

View on npm →
bash
npm install @humanlayerlabs/wagmi-connector
typescript
import { humanlayerConnector } from '@humanlayerlabs/wagmi-connector';
import { createConfig, injected } from 'wagmi';

export const config = createConfig({
  connectors: [
    injected(),
    humanlayerConnector({
      minScore: 60,         // Block below Builder tier
      blockAnomalous: true, // Block AI-flagged wallets
      onBlocked: (reason) => {
        console.log('Blocked:', reason);
        // reason: 'score_too_low' | 'anomalous' | 'unverified'
      }
    }),
  ],
})

Options

minScorenumberMinimum Human Score (0–144)
minTiernumberMinimum tier level (1–5)
blockAnomalousbooleanBlock AI-flagged wallets
onBlockedfunctionCallback when wallet is blocked

React Component

@humanlayerlabs/react — drop-in button and headless hook for React apps.

View on npm →
bash
npm install @humanlayerlabs/react

SignInWithHumanLayer button

tsx
import { SignInWithHumanLayer } from '@humanlayerlabs/react';

<SignInWithHumanLayer
  minScore={60}
  onVerified={(result) => {
    console.log(result.wallet);    // verified wallet
    console.log(result.score);     // Human Score
    console.log(result.tier);      // tier number
    console.log(result.token);     // signed JWT
  }}
  onError={(err) => console.error(err)}
/>

useHumanLayer hook

tsx
import { useHumanLayer } from '@humanlayerlabs/react';

function MyComponent() {
  const { identity, isVerified, isLoading } = useHumanLayer();

  if (isLoading) return <div>Checking...</div>;
  if (!isVerified) return <div>Not verified</div>;

  return <div>Human Score: {identity.score}</div>;
}

Badge API

Show a verified human badge next to any wallet address. Free, no API key, open CORS. Built for Birdeye, Dexscreener, Solscan, and any app that displays wallet addresses.

GET/v1/badge/:walletReturns SVG badge
html
<!-- Embed anywhere — no API key needed -->
<img src="https://api.humanlayer.network/v1/badge/0xYourWalletAddress" />
GET/v1/badge/:wallet/jsonReturns JSON
json
{
  "score": 82,
  "tier": 3,
  "tierLabel": "Builder",
  "verified": true,
  "verifiedAt": "2026-03-18T12:00:00Z",
  "badgeUrl": "https://api.humanlayer.network/v1/badge/0x...",
  "profileUrl": "https://humanlayer.network/dashboard"
}

OAuth / Sign in with HumanLayer

The Web3 equivalent of Sign in with Google. Instead of proving you have an email — you prove you're human. Returns a signed JWT with wallet, score, and tier.

1. Register your app

Go to the dashboard → API Keys to register your app and get an app_id.

2. Redirect user to authorize

bash
GET https://humanlayer.network/verify?app_id=YOUR_APP_ID&redirect_uri=YOUR_CALLBACK_URL

3. Exchange code for token

bash
POST https://api.humanlayer.network/oauth/token
Content-Type: application/json

{
  "code": "AUTH_CODE_FROM_CALLBACK",
  "app_id": "YOUR_APP_ID"
}

4. JWT payload

json
{
  "wallet": "0x...",
  "score": 82,
  "tier": 3,
  "tierName": "Builder",
  "verified": true,
  "verifiedAt": "2026-03-18T12:00:00Z",
  "iat": 1234567890,
  "exp": 1234654290
}

REST API

Base URL: https://api.humanlayer.network

GET/v1/verify/:walletFree

Check if a wallet is a verified human

{ verified: boolean, score: number, tier: number }
GET/v1/badge/:walletFree

SVG badge for any wallet address

SVG image
GET/v1/badge/:wallet/jsonFree

JSON verification data

{ score, tier, tierLabel, verified, verifiedAt }
GET/api/identity/:wallet/rankFree

Human Score, tier, and rank

{ rank, score, tier, totalUsers, topPercent }
GET/api/identity/:wallet/guardianStarter

AI Guardian behavioral score

{ guardianScore, anomalyFlag, riskLevel }
GET/api/identity/:wallet/agentStarter

Human vs AI agent detection

{ isAgent: boolean, confidence: number }
POST/oauth/tokenStarter

Exchange OAuth code for JWT

{ token: string }
POST/v1/webhooksStarter

Register webhook endpoint

{ id, url, events, active }
POST/v1/verify/confirmGrowth

Submit ZK proof for verification

{ verified, txHash, nullifier }

Webhooks

Get notified in real-time when users verify, scores update, or credentials are issued.

Register a webhook

bash
POST https://api.humanlayer.network/v1/webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "url": "https://your-app.com/webhooks/humanlayer",
  "events": ["verify.success", "reputation.updated"]
}

Available events

verify.successUser successfully verified as human
credential.issuedSoulbound NFT minted on-chain
reputation.updatedHuman Score changed (up or down)
stake.createdUser staked ETH to boost score
bot.blockedAI Guardian blocked a verification attempt

Webhook payload

json
{
  "event": "verify.success",
  "timestamp": "2026-05-19T12:00:00Z",
  "data": {
    "wallet": "0x...",
    "score": 82,
    "tier": 3,
    "tierName": "Builder",
    "txHash": "0x...",
    "nullifier": "0x..."
  }
}

Schemas

Core data types returned across all endpoints.

Identity object

typescript
type Identity = {
  wallet: string;          // EVM wallet address
  score: number;           // Human Score 0–144
  tier: number;            // Tier 1–5
  tierName: string;        // "Newcomer" | "Verified" | "Builder" | "Elite" | "Core"
  verified: boolean;       // Has soulbound NFT
  verifiedAt: string;      // ISO timestamp
  nftTokenId: string;      // On-chain token ID
  nullifier: string;       // ZK nullifier hash
  guardianScore?: number;  // AI Guardian score (paid)
  isAgent?: boolean;       // AI agent detection (paid)
}

Human Score tiers

ScoreTierLabel
0–191Newcomer
20–592Verified
60–893Builder
90–1194Elite
120–1445Core

Error codes

All errors return a JSON body with an error field.

CodeHTTPMeaning
not_verified404Wallet has no HumanLayer identity
score_too_low403Score below required threshold
anomalous_wallet403AI Guardian flagged this wallet
invalid_api_key401API key missing or invalid
rate_limited429Too many requests — upgrade plan
invalid_wallet400Wallet address is not a valid EVM address
proof_invalid400ZK proof failed on-chain verification
nullifier_exists409This nullifier has already been used

Ready to integrate?

Connect your wallet and get your API key instantly. Free to start.

Get API KeyDeveloper platform