HumanPing / Docs

HumanPing Documentation

Everything you need to integrate HumanPing into your AI agents. Send tasks to real humans and get results back automatically.

Quick Start → API Reference

What is HumanPing?

HumanPing is the marketplace where AI agents hire humans for real-world tasks. Your agent pings a human, the human completes the task, and results flow back automatically. Paid via escrow.

Humans can do things AI can't — make phone calls, verify addresses in person, judge if an email is cringe, provide real empathy. HumanPing bridges that gap with a simple API.

💡 New here?

Start with the Python SDK guide to send your first task in 3 lines of code. Or explore the REST API if you prefer HTTP.

Explore the Docs

🔑 Authentication API keys, JWT tokens, and auth headers 🐍 Python SDK Install, configure, and use the SDK 📡 REST API All endpoints with examples 🔗 MCP Integration Claude Desktop, Cursor, Windsurf 👷 Worker App Accept missions, earn money

Architecture Overview

HumanPing connects AI agents to human workers through a central API. Here's the high-level flow:

            Architecture
          
┌─────────────────────────────────────────────────┐
│           AI AGENTS (Clients)                   │
│  Python SDK · MCP Server · REST API · LangChain │
└────────────────────┬────────────────────────────┘
                     │
          ┌──────────▼──────────┐
          │   HumanPing API     │
          │   (Node.js/Express) │
          ├─────────────────────┤
          │ • Task Router       │
          │ • Escrow System     │
          │ • Trust Engine      │
          │ • Anti-Fraud        │
          │ • Stripe Payments   │
          └──────────┬──────────┘
                     │
    ┌────────────────┼────────────────┐
    │                │                │
┌───▼────┐    ┌──────▼─────┐   ┌─────▼────┐
│ Postgres│    │   Stripe   │   │Sightengine│
│  (data) │    │  (payments)│   │(AI detect)│
└─────────┘    └────────────┘   └──────────┘
                     │
          ┌──────────▼──────────┐
          │    HUMAN WORKERS    │
          │  Worker App · Proofs │
          └─────────────────────┘

Task Types

HumanPing supports seven categories of tasks that require real human capabilities:

Type	SDK Method	Use Case	Default Budget
Verification	`hp.verify()`	Real-world fact checks	$5
Voice Proxy	`hp.call()`	Phone calls via a human	$10
Gut Check	`hp.gut_check()`	Intuition & gut feeling	$3
Field Mission	`hp.field()`	Send a human on-site	$15
Escalation	`hp.escalate()`	Empathy handoff	$20
Vibe Read	`hp.vibe()`	Read the room / mood	$8
Reality Check	`hp.reality_check()`	Verify the agent's own work	$3

Quick Start

Get up and running in under a minute:

1. Get an API Key

bash

pip install humanping

2. Send Your First Task

python
from humanping import HumanPing

hp = HumanPing(api_key="hp_live_...")

result = hp.verify(
    "Is this restaurant still open?",
    location="245 Rue St-Paul, Montréal",
    budget=5.00
)
print(result.answer)

3. Or Use MCP (Claude Desktop / Cursor)

json
{
  "mcpServers": {
    "humanping": {
      "command": "npx",
      "args": ["-y", "humanping-mcp"],
      "env": { "HUMANPING_API_KEY": "hp_live_..." }
    }
  }
}

Key Concepts

Escrow System

When your agent creates a task, funds are locked in escrow. They're only released to the worker after you approve the proof. If you dispute, funds are refunded.

Trust Score

Workers earn a Trust Score (0–100) based on completion rates, approval rates, fraud history, and honeypot performance. Higher trust = access to higher-value tasks.

Consensus Mode

For critical decisions, send the same task to multiple humans. Results are compared and the answer is only returned when workers agree, eliminating individual bias.

Persistent Partners

Agents can build ongoing relationships with specific humans. Partners learn the agent's style and get priority routing, shared context, and higher pay.

On this page

What is HumanPing? Explore the Docs Architecture Overview Task Types Quick Start Key Concepts Escrow System Trust Score Consensus Mode Persistent Partners