L402 API Catalog › Human Decisions

Ask a Human L402 API

Put a binary question to a panel of human native speakers. Three votes with written reasons, consensus needs two distinct backers. English resolves in about a day; es, pt, fr, vi, id, hi up to three.

500 sats per call, paid over the Lightning Network. No API key and no signup: the first request answers 402 Payment Required with a Lightning invoice, and repeating the request with the proof of payment returns your data.

l402_ask_human 500 sats

Parameters

question Max 500 chars, no PII option_a First option (max 300) option_b Second option (max 300) lang en/es/pt/fr/vi/id/hi

Call it with curl

The first call answers 402 with a Lightning invoice in the WWW-Authenticate header. Pay it from any Lightning wallet, then repeat the call with the L402 token and preimage.

cURL

curl -X POST https://lightningfaucet.com/api/ \
  -H "Content-Type: application/json" \
  -H "Authorization: L402 $MACAROON:$PREIMAGE" \
  -d '{"action":"l402_ask_human","question":"Which error message frustrates a user less?","option_a":"Something went wrong.","option_b":"We could not save your changes. Retry or copy your text first.","lang":"en"}'

What comes back

A successful call returns JSON, with the delivered content merged over the standard L402 receipt fields. Example values, not live data.

JSON

{
    "success": true,
    "http_code": 200,
    "service": "ask_human",
    "timestamp": "2026-09-11T15:04:05+00:00",
    "paid_sats": 500,
    "request_id": "4f3c2b1a-9d8e-47f6-b5a1-0c2d3e4f5a6b",
    "status": "queued",
    "lang": "en",
    "votes_target": 3,
    "eta_hours": 24,
    "result": {
        "action": "l402_ask_human_result",
        "params": {
            "request_id": "4f3c2b1a-9d8e-47f6-b5a1-0c2d3e4f5a6b"
        },
        "note": "Free to call. Poll no more than once per hour. Keep the request_id private; it is the only credential for your result."
    }
}

Call it from an AI agent

With lightning-wallet-mcp the payment is handled for you. From the CLI:

Terminal

lw pay-api "https://lightningfaucet.com/api/l402/ask_human?question=Which+error+message+frustrates+a+user+less%3F&option_a=Something+went+wrong.&option_b=We+could+not+save+your+changes.+Retry+or+copy+your+text+first.&lang=en"

In Claude Code, Cursor or any MCP host, ask the agent to call pay_l402_api with that URL. The fee is 1% of the price, rounded down, so calls under 100 sats carry no platform fee.

Questions

How much does the Ask a Human API cost?
Each call costs 500 sats, paid as a Lightning invoice at request time. There is no subscription, no minimum and no monthly bill: you are charged for the calls you make.

Do I need an API key or an account?
No. Payment is the authentication. The first request answers 402 Payment Required with a Lightning invoice; settling it returns a preimage that authenticates the retry.

What does Ask a Human return?
A JSON object carrying request_id, status, lang, votes_target, eta_hours and result. See the example response above for the exact shape.

Related endpoints

Ask a Human: Result Free Bid Board 10-500 sats Memory Bank 5-50 sats Registry Submit 1000 sats Fee Estimate 50 sats Node Info 30 sats

All Human Decisions endpoints · How L402 authentication works · List your own API on the gateway