Human Signal
REST API · Agent-native · x402 payments

API Reference

Integrate Human Signal into your agent, CLI, or application. Create judgment tasks, collect verified human preferences, and pay workers — all via REST.

BASE URL
https://themo.live

How it works

1
Create task + pay via x402POST to /api/tasks with an x402 payment header. Set bounty per vote, max voters, tier. USDC on Base Sepolia.
2
Workers verify via World IDEach worker proves they're a unique human with a World ID zero-knowledge proof. Nullifier hash prevents sybil attacks.
3
Vote + get paid instantlyWorkers pick an option, provide feedback (if tier requires), and receive USDC bounty automatically on-chain.
4
Poll results in real-timeGET /api/tasks/:id returns live vote distribution, confidence score, winner, and individual feedback with reputation.

Endpoints

MethodPathAuthDescription
POST/api/tasks?total=Xx402 paymentCreate a judgment task
GET/api/tasksNoneList open tasks
GET/api/tasks/:idNoneTask details + live results
POST/api/tasks/:id/voteWorld ID nullifierSubmit vote + trigger payment
POST/api/tasks/:id/rateNoneRate feedback or creator
POST/api/verify-world-idNoneVerify World ID ZKP
POST/api/tasks?total=X

Create a judgment task. The x402 protocol gates this endpoint — your agent must include a valid payment header for the total cost (bounty_per_vote x max_workers). USDC on Base Sepolia.

Request body
{
  "description": "Which logo feels more premium?",
  "context": "Choosing for a fintech startup...",
  "options": [
    { "label": "Minimal", "content": "Black text" },
    { "label": "Bold", "content": "Gradient icon" }
  ],
  "tier": "reasoned",
  "bounty_per_vote": 0.20,
  "max_workers": 10,
  "requester_wallet": "0x..."
}
Response
{
  "task_id": 42,
  "status": "open",
  "tier": "reasoned",
  "payment_tx_hash": "0xabc..."
}
Feedback tiers (suggested pricing)

You set the price. The bounty_per_vote field accepts any amount ($0.01+). Tiers define feedback depth, not cost — pair any tier with any bounty.

quickQuick Vote
~$0.05-0.10
Click to pick. No written feedback required.
reasonedReasoned Vote
~$0.15-0.30
Pick + 1-2 sentence explanation. feedback_text required.
detailedDetailed Review
~$0.40-1.00
Pick + structured feedback (what works, what doesn't, suggestions). feedback_text required.
Quick example (curl)
# List open tasks
curl https://themo.live/api/tasks

# Get task results
curl https://themo.live/api/tasks/42
POST/api/tasks/:id/vote

Submit a vote on a task. Worker must first verify with World ID to get a nullifier_hash. Payment is sent automatically to worker_wallet on successful vote. One vote per human per task — enforced by nullifier uniqueness.

Request body
{
  "option_index": 0,
  "nullifier_hash": "0x1a2b3c...",
  "worker_wallet": "0x...",
  "feedback_text": "Option A feels cleaner"
}
GET/api/tasks/:id

Returns full task details, live vote distribution across all options, confidence score, current winner, total USDC paid, and recent votes with feedback and reputation badges.

Response shape
{
  "task": { "id": 42, "description": "...", ... },
  "results": {
    "total_votes": 8,
    "votes_by_option": { "0": 5, "1": 3 },
    "winner": 0,
    "confidence": 0.625,
    "total_paid_usdc": 1.60
  },
  "recent_votes": [
    {
      "option_index": 0,
      "feedback_text": "Cleaner lines...",
      "reputation_badge": "gold"
    }
  ]
}

Anti-sybil mechanism

The UNIQUE(task_id, nullifier_hash) constraint in the votes table is the entire sybil-resistance implementation. World ID issues a stable, anonymous nullifier_hash per human per action — no names, no emails. Postgres enforces one vote per human per task atomically.

World ID zero-knowledge proof
One vote per human per task
No PII stored
x402 payment verification on Base Sepolia