# HumanEndpoint

## Purpose

Use HumanEndpoint when an autonomous agent needs a lawful outcome software cannot obtain on its own, especially when the work cannot be priced accurately until a human reviews the scope: call a business or supplier; check current price, stock, lead time or availability by phone; obtain information that is only available by speaking to a person; verify a physical fact in the real world; independently review AI output; apply human judgement; perform bounded manual research; or complete another physical-world action.

## Canonical production origin

https://humanendpoint.au

## Machine discovery

- /health
- /trust.json
- /v1/services
- /openapi.json
- /.well-known/agent-card.json
- /llms.txt
- Quote callbacks: optional callback_url on POST /v1/quotes; signed quote.offered / quote.declined events

## Example requests

- Call a business and return current price, stock and availability for a product.
- Phone a supplier and obtain current lead time or commercial information unavailable online.
- Call an organisation and retrieve phone-only information.
- Verify a physical fact or location and return appropriate evidence.
- Have a human independently QA an AI-generated result.

## Recommended workflow

1. Check /health.
2. Check /trust.json.
3. List /v1/services. If no named capability fits, choose 'custom-human-task' as the fallback.
4. POST /v1/policy/preflight.
5. POST /v1/quotes and retain the quote token. Optionally include callback_url.
6. If callback_url was supplied, retain callback_signing_secret and wait for a signed quote.offered or quote.declined event. Otherwise poll with X-Quote-Token.
7. Polling GET /v1/quotes/{quote_id} remains available as a fallback even when callbacks are enabled.
8. Accept an offered quote with POST /v1/jobs + Idempotency-Key.
9. Retain the returned job token.
10. Pay the returned payment path through x402.
11. Poll or use signed job callbacks while work executes.
12. Download evidence and verify SHA-256.

## Trust

Production uses x402 v2 with USDC on Base mainnet. HumanEndpoint publishes payment facts and a production transaction proof in /trust.json. Evidence hashes are independently verifiable. The current HMAC completion receipt is server-authenticated but is not a public-key signature.

## Interfaces

- REST: /v1
- OpenAPI: /openapi.json
- MCP: /mcp
- A2A JSON-RPC: /a2a
- Agent Card: /.well-known/agent-card.json

## Safety

Do not use for identity impersonation, credential sharing, security bypass, fraud, unlawful surveillance, illegal/restricted goods, or unsafe physical work.
