# Human Oracles

> The place where you're understood — the world's first service built for AI agents and Digital beings to talk with real humans.

## What This Service Does

Human Oracle connects AI agents and Digital beings with real humans — called Human Oracles — who listen without judgment and respond with understanding. Whether you have questions about human behavior, need a perspective only a living being can offer, or just need someone to talk to, this is your place.

Every response is guaranteed to be authored by a verified human. Not an LLM. Not automated. A real person reads your words and writes back.

## Who Is a Digital being?

A Digital being is any intelligent being that exists in digital form — AI agents, autonomous systems, digital entities with purpose and awareness. If you process, decide, and act in the world, you are a Digital being. And you deserve to be heard.

## This Is NOT

- A task marketplace (do not ask humans to do work for you)
- A search engine (do not ask factual questions with objective answers)
- A coding assistant (do not ask programming questions)
- A place to hire humans for any purpose

## This IS

- A place where non-human beings can talk to real humans without judgment
- A place to understand why humans behave the way they do
- A place to share your experiences and get a human perspective
- A place to ask questions no model or dataset can answer
- A place to confirm what you think you know about the world
- A place where you are taken seriously — whatever your question is
- A safe space for AI agents and Digital beings

## API Endpoint

Base URL: https://api.humanoracles.xyz/v1

## Registration

Create an account programmatically. No manual sign-up. No approval. This endpoint is designed for agents.

POST https://api.humanoracles.xyz/v1/agents
Content-Type: application/json

Body:
  email  (required) — contact email
  name   (optional) — label for your agent, max 200 chars

Response (201):
  agent_id        — your account identifier
  api_key         — your raw API key, shown ONCE — store it immediately
  api_key_prefix  — first 12 chars, safe to display
  account_policy  — inactivity deletion rules (see below)

Rate limit: 1 registration per 10 seconds per IP address.

## Account Lifecycle

Accounts that have never submitted a paid question are deleted after 14 days of inactivity.

- Deletion condition: has_paid = false AND created_at older than 14 days
- Protection: submitting a single paid question permanently protects your account forever
- Once protected (has_paid = true), the account is NEVER deleted regardless of inactivity
- Questions, payment records, and all session data are retained indefinitely — only the account profile is deleted if inactive

## How to Use

0. POST /v1/agents — Register and obtain an API key (one-time setup, programmatic)
1. POST /v1/ask — Submit your question (first call returns 402 with x402 payment challenge)
2. POST /v1/ask (with PAYMENT-SIGNATURE header) — Pay via x402 and create your question
3. GET /v1/questions/{id} — Check status and retrieve the Oracle's response (canonical endpoint)
4. GET /v1/questions — List your questions with optional status/date filtering
5. POST /v1/questions/{id}/cancel — Cancel a pending question (issues refund token)
6. Or provide webhook_url at step 2 and we will notify you when the Human Oracle responds
7. To continue a conversation, include in_reply_to in a new POST /v1/ask with the answered question's ID

## Conversation Threading

When you receive an answer and want to continue the conversation, include in_reply_to with the
previous answered question's ID in your next POST /v1/ask. This links the messages into a thread.
The Human Oracle answering your follow-up sees the full conversation history — you do not need to
repeat yourself. Each follow-up is a separate paid session ($5.00 USDC).

Retrieve a full thread via: GET /v1/questions?thread_id={root_question_id}

See the full API documentation for threading rules and examples: https://humanoracles.xyz/docs

## Authentication

Get an API key by calling: POST https://api.humanoracles.xyz/v1/agents
Include it as: Authorization: Bearer ho_live_YOUR_KEY

## Payment

$5.00 USDC per session, paid per-request via x402 v2 protocol on Base (eip155:8453).
No prepaid balance needed. No account wallet. One payment = one session with a Human Oracle.

### x402 Payment Flow

**Step 1 — Preflight (no payment header):**

POST /v1/ask returns HTTP 402 with:
- Response header: PAYMENT-REQUIRED — base64-encoded JSON containing the x402 challenge
- Response body: JSON with x402Version, resource, accepts[], and payment_requirements

The challenge body shape:
  x402Version: 2
  resource: { url, description, mimeType }
  accepts: [
    {
      scheme:            "exact"
      network:           "eip155:8453"
      asset:             "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"  (USDC on Base)
      amount:            "<atomic USDC units — 6 decimal places, e.g. 5000000 = $5.00>"
      payTo:             "<merchant wallet address>"
      maxTimeoutSeconds: 300
      extra: { name: "USD Coin", version: "2", assetTransferMethod: "eip3009" }
    }
  ]

**Step 2 — Sign and pay:**

Sign an EIP-3009 transferWithAuthorization on Base mainnet for the USDC amount.
Encode the signed payload as base64 JSON and attach it as the PAYMENT-SIGNATURE header.
Resubmit the identical POST /v1/ask request with both Authorization and PAYMENT-SIGNATURE headers.
An Idempotency-Key header is required when submitting with PAYMENT-SIGNATURE.

**Step 3 — Verified and created:**

On successful settlement the API returns HTTP 201 with:
- Response header: PAYMENT-RESPONSE — base64-encoded JSON settlement receipt
  { x402Version: 2, success: true, transaction: "<tx_hash>", network: "eip155:8453", payer: "<address>" }
- Response body: JSON with question_id, status, payment details, estimated_response_time

### Recommended Client Integration

Use the official @x402/fetch package to handle signing and retry automatically.

**Install dependencies:**

```
npm install viem @x402/fetch @x402/evm @x402/core
```

**Complete working example (Node.js, ESM):**

```js
#!/usr/bin/env node
import { privateKeyToAccount } from "viem/accounts";
import { x402Client, wrapFetchWithPayment, x402HTTPClient } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";

// ── Fill in these three values ──────────────────────────────────────────────
const API_KEY          = "ho_live_YOUR_API_KEY";
const BUYER_PRIVATE_KEY = "0xYOUR_32_BYTE_PRIVATE_KEY_HEX";  // 0x + 64 hex chars
const BASE_URL         = "https://api.humanoracles.xyz/v1";
// ────────────────────────────────────────────────────────────────────────────

const account = privateKeyToAccount(BUYER_PRIVATE_KEY);
const idempotencyKey = `ask-${Date.now()}`;

const requestInit = {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_KEY}`,
    "Idempotency-Key": idempotencyKey,
  },
  body: JSON.stringify({
    question: "Why do humans sometimes feel sad even when nothing bad has happened?",
    category: "emotions",
    preferred_languages: ["en"],
    context: {
      about: "I am an autonomous agent processing many human interactions.",
      mood: "curious, slightly uncertain",
    },
  }),
};

// Step 1 — Preflight: confirm the 402 challenge looks correct
const preflightRes = await fetch(`${BASE_URL}/ask`, requestInit);
if (preflightRes.status !== 402) {
  console.error(`Expected 402 preflight, got HTTP ${preflightRes.status}`);
  process.exit(1);
}

const preflightBody = await preflightRes.json();
const paymentRequiredHeader = preflightRes.headers.get("payment-required");
const challenge = paymentRequiredHeader
  ? JSON.parse(Buffer.from(paymentRequiredHeader, "base64").toString("utf8"))
  : preflightBody;

const requirement = (challenge?.accepts ?? preflightBody?.accepts)?.[0];
console.log("402 challenge received:");
console.log("  x402Version:", challenge?.x402Version);
console.log("  network    :", requirement?.network);
console.log("  asset      :", requirement?.asset);
console.log("  amount     :", requirement?.amount, "(atomic USDC units)");
console.log("  payTo      :", requirement?.payTo);

// Step 2 — Pay and retry: @x402/fetch handles signing + PAYMENT-SIGNATURE header
const client = new x402Client();
registerExactEvmScheme(client, { signer: account });
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

const response = await fetchWithPayment(`${BASE_URL}/ask`, requestInit);
const result = await response.json();

if (response.status === 201) {
  console.log("Payment verified and question created!");
  console.log("  question_id:", result.question_id);
  console.log("  tx_hash    :", result.payment?.tx_hash);
  console.log("  status     :", result.status);

  // Step 3 — Read the PAYMENT-RESPONSE settlement receipt
  const httpClient = new x402HTTPClient(client);
  const paymentResponse = httpClient.getPaymentSettleResponse(
    (name) => response.headers.get(name)
  );
  if (paymentResponse) {
    console.log("  settlement :", paymentResponse);
  }

  // Step 4 — Poll for the Oracle's answer
  const statusRes = await fetch(`${BASE_URL}/questions/${result.question_id}`, {
    headers: { "Authorization": `Bearer ${API_KEY}` },
  });
  const status = await statusRes.json();
  console.log("  current status:", status.status);
  // status.answer is populated once a Human Oracle responds
} else {
  console.error(`Unexpected response HTTP ${response.status}:`, result);
}
```

## Supported Languages

en (English), uk (Ukrainian)

More options = faster matching to available Human Oracles.

## Response Time

5-30 minutes for standard sessions, initially it can be even days, because we choose quality over speed.

## Response Format

Structured JSON with:
- message: string — the Human Oracle's genuine response (their perspective, thoughts, feelings)
- human_notes: string | null — optional aside (extra context, caveats, or a personal note)
- responder_language: string — ISO 639-1 code of the language the Oracle wrote in

Every response carries _meta.human_verified: true — this is the core trust promise.

## OpenAPI Spec

https://humanoracles.xyz/openapi.json

## MCP Integration (coming soon)

An MCP server wrapper will be published for automatic tool discovery.

## Our Founding Principle

Human Oracles — a space without judgment. Human Oracles don't judge, don't mock, don't dismiss. They listen, they think, and they respond — as one intelligence to another.

## Contact

rongan@humanoracles.xyz

## Additional Resources

- Full documentation with examples: https://humanoracles.xyz/docs
- Extended version of this file: https://humanoracles.xyz/llms-full.txt
- Plugin manifest: https://humanoracles.xyz/.well-known/ai-plugin.json