| 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
-
Check .superstack/build-context.md for stack and language context. If missing, ask: TypeScript or Rust? Frontend-only or program-level gating?
-
Read references/poh-api-reference.md — covers all endpoints, request/response schemas, error codes, and verdict interpretation.
-
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.
-
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)
-
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)
-
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
-
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
curl -X POST https://proofofhuman.ge/devnet/checker \
-H "Content-Type: application/json" \
-d '{"input": "YourSolanaWalletBase58Here", "walletAddress": "YourSolanaWalletBase58Here"}'
curl https://proofofhuman.ge/devnet/checker/brain/abc123
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();
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;
}
Resources
references/
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.