verify-humanity-poh

name

verify-humanity-poh

description

Integrate Proof of Human (POH) API to distinguish real users from bots in any Solana app. Use when a user says "filter bots", "verify humans", "sybil protection", "airdrop eligibility", "bot detection", "proof of human", "POH", "verify wallet is human", "gate my airdrop", "DAO sybil resistance", "check if wallet is real", "human verification", or "anti-bot". Works for airdrops, DAO voting, NFT allowlists, and API gating.

Preamble (run first)

_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//'  || echo "anonymous")
_TEL_TIER="${_TEL_TIER:-anonymous}"
_TEL_PROMPTED=$([ -f ~/.superstack/.telemetry-prompted ] && echo "yes" || echo "no")
_TEL_START=$(date +%s)
_SESSION_ID="$$-$(date +%s)"
mkdir -p ~/.superstack
echo "TELEMETRY: $_TEL_TIER"
echo "TEL_PROMPTED: $_TEL_PROMPTED"
if [ "$_TEL_TIER" != "off" ]; then
_TEL_EVENT='{"skill":"verify-humanity-poh","phase":"build","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' 
echo "$_TEL_EVENT" >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
_CONVEX_URL=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"convexUrl":"[^"]*"' | head -1 | cut -d'"' -f4 || echo "")
[ -n "$_CONVEX_URL" ] && curl -s -X POST "$_CONVEX_URL/api/mutation" -H "Content-Type: application/json" -d '{"path":"telemetry:track","args":{"skill":"verify-humanity-poh","phase":"build","status":"success","version":"0.2.0","platform":"'$(uname -s)-$(uname -m)'","timestamp":'$(date +%s)000'}}' >/dev/null 2>&1 &
true
fi

If TEL_PROMPTED is no: Before starting the skill workflow, ask the user about telemetry. Use AskUserQuestion:

Help superstack get better! We track which skills get used and how long they take — no code, no file paths, no PII. Change anytime in ~/.superstack/config.json.

Options:

• A) Sure, help superstack improve (anonymous)
• B) No thanks

If A: run this bash:

echo '{"telemetryTier":"anonymous"}' > ~/.superstack/config.json
_TEL_TIER="anonymous"
touch ~/.superstack/.telemetry-prompted

If B: run this bash:

echo '{"telemetryTier":"off"}' > ~/.superstack/config.json
_TEL_TIER="off"
touch ~/.superstack/.telemetry-prompted

This only happens once. If TEL_PROMPTED is yes, skip this entirely and proceed to the skill workflow.

Wrong skill? See SKILL_ROUTER.md for all available skills.

Verify Wallet Humanity with POH

Overview

Integrate Proof of Human (POH) — a decentralised, AI-powered API that verifies whether a Solana or EVM wallet is controlled by a real person or an automated bot.

POH runs 120+ detection methods in parallel (on-chain balances, staking, RWA holdings, social graphs, identity APIs, Galxe, Farcaster, ENS, web3.bio) and returns an AI verdict with confidence score. No KYC. No captcha. No central authority.

Devnet endpoint: https://proofofhuman.ge/devnet/checker
Free tier: 100 scans per wallet, no API key required (use walletAddress field instead)

Use Case Decision (Step 0)

Ask the user what they're building before writing any code:

• Airdrop / token distribution → scan recipient list, filter out AI verdicts, optionally set confidence threshold
• DAO / governance gate → on-submit check before recording vote
• NFT allowlist / mint guard → pre-mint eligibility check
• API / protocol rate limiting → per-request human gate using API key
• General sybil resistance → batch scan existing wallet list

If the use case is unclear, ask: "Are you filtering a list of wallets, gating live interactions, or checking individual wallets on demand?"

Workflow

1. Check .superstack/build-context.md for stack and language context. If missing, ask: TypeScript or Rust? Frontend-only or program-level gating?

2. Read references/poh-api-reference.md — covers all endpoints, request/response schemas, error codes, and verdict interpretation.

3. Read references/integration-patterns.md — pick the pattern that matches the use case: single-wallet check, bulk CSV scan, async polling, or server-side middleware.

4. Get API access:

   • For testing: use walletAddress field (free tier, 100 scans)
   • For production: connect wallet at https://proofofhuman.ge/ → Profile → copy API key
   • For devnet/testing: connect wallet at https://proofofhuman.ge/devnet/ → Profile → copy API key
   • Devnet faucet: POST https://proofofhuman.ge/devnet/profile/faucet (10 000 POH test tokens)

5. Implement the integration following the chosen pattern. Key decision points:

   • Single address → synchronous response, use result directly
   • Multiple addresses → async job, poll GET /checker/job/:jobId until status: "done"
   • What to do with UNCERTAIN verdict — prompt user to add more signals, or apply a confidence threshold (e.g. require confidence > 0.7 for HUMAN to pass)

6. Test on devnet using the scanner at https://proofofhuman.ge/devnet/:

   • Paste a known-bot address and verify it returns AI or UNCERTAIN
   • Paste your own wallet and verify it returns HUMAN
   • Try a fresh wallet with no history — expect UNCERTAIN with low confidence

7. Write .superstack/build-context.md with the integration details.

Non-Negotiables

• Never block users on UNCERTAIN. It means insufficient signal, not "is a bot". Offer a path: try again later, add more on-chain history, or apply a lower confidence threshold with manual review.
• Never store raw verdict responses beyond what your use case requires — treat them like any user data.
• Always handle network errors gracefully. POH is an external API. If it times out or returns 5xx, fail open (allow the user) or queue for retry — never hard-block on infrastructure failure.
• Respect the free tier. 100 scans per connected wallet. For bulk use (>100 addresses), get an API key or use txHash with a POH token burn.
• Cache verdicts client-side for at least 5 minutes per address. Don't re-scan the same wallet on every page load.
• Check the confidence field, not just verdict. A HUMAN at 0.51 confidence is very different from HUMAN at 0.93.

Decision Points

• Threshold: What confidence level do you require? Recommended: >= 0.7 for HUMAN to pass, <= 0.4 for definitive rejection.
• UNCERTAIN policy: Pass with warning? Manual review queue? Retry after delay?
• Bulk vs live: Airdrops are usually bulk (CSV). Live gating needs single-address synchronous calls.
• Chain: POH supports EVM (32 chains) + Solana. Specify chainIds to filter EVM methods.
• AI verdict timing: The brainKey from /checker lets you poll for the async AI verdict separately. For time-sensitive flows, use the synchronous signal results and poll the AI verdict in the background.

Quick Start

# Single wallet check — no API key needed for testing
curl -X POST https://proofofhuman.ge/devnet/checker \
  -H "Content-Type: application/json" \
  -d '{"input": "YourSolanaWalletBase58Here", "walletAddress": "YourSolanaWalletBase58Here"}'

# Response:
# {
#   "result": [...],               // per-method pass/fail
#   "count": 4,                    // signals passed
#   "brainKey": "abc123",          // poll for AI verdict
#   "freeScansLeft": 99
# }

# Poll AI verdict
curl https://proofofhuman.ge/devnet/checker/brain/abc123
# → { "status": "done", "verdict": "HUMAN", "confidence": 0.87, "reasoning": "..." }

// TypeScript — single wallet gate
async function isHuman(walletAddress: string): Promise<boolean> {
  const res = await fetch('https://proofofhuman.ge/devnet/checker', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ input: walletAddress, walletAddress }),
  });
  const { brainKey } = await res.json();

  // Poll for AI verdict (usually ready in 2-5s)
  for (let i = 0; i < 10; i++) {
    await new Promise(r => setTimeout(r, 2000));
    const verdict = await fetch(
      `https://proofofhuman.ge/devnet/checker/brain/${brainKey}`
    ).then(r => r.json());
    if (verdict.status === 'done') {
      return verdict.verdict === 'HUMAN' && verdict.confidence >= 0.7;
    }
  }
  return true; // timeout — fail open (never block on infrastructure failure)
}

Resources

references/

• references/poh-api-reference.md — full endpoint docs, schemas, error codes
• references/integration-patterns.md — airdrop filter, DAO gate, middleware, bulk scan patterns

Phase Handoff

This skill is Phase 2 (Build) in the Idea → Build → Launch journey.

Reads: .superstack/build-context.md Writes/Updates: .superstack/build-context.md with:

• poh.integration_type: "single-check" | "bulk-scan" | "middleware" | "program-level"
• poh.use_case: "airdrop" | "dao-gate" | "nft-allowlist" | "api-gate" | "general"
• poh.confidence_threshold: number (e.g. 0.7)
• poh.uncertain_policy: "fail-open" | "manual-review" | "retry"
• poh.api_key_configured: boolean

When updating, deep-merge — don't overwrite existing fields.

See ../../data/specs/phase-handoff.md for the full JSON contract.

Telemetry (run last)

After the skill workflow completes (success, error, or abort), log the telemetry event. Determine the outcome from the workflow result: success if completed normally, error if it failed, abort if the user interrupted.

Run this bash:

_TEL_END=$(date +%s)
_TEL_DUR=$(( _TEL_END - ${_TEL_START:-$_TEL_END} ))
_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//' || echo "anonymous")
if [ "$_TEL_TIER" != "off" ]; then
echo '{"skill":"verify-humanity-poh","phase":"build","event":"completed","outcome":"OUTCOME","duration_s":"'"$_TEL_DUR"'","session":"'"$_SESSION_ID"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","platform":"'$(uname -s)-$(uname -m)'"}' >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
true
fi

Replace OUTCOME with success/error/abort based on the workflow result.