# Realask Agent Verification API

> An API that lets an AI agent ask the real world a current question about a local business and receive a structured, time-stamped, confidence-scored answer. Verification is done by discovering businesses through official place data and, when needed, placing a compliant automated phone call that identifies itself as an assistant.

## Use this when
- The fact changes faster than the web reflects it: today's stock, current wait, same-day availability.
- The fact was never published: a real all-in price, an edge-case capability, a policy exception.
- A listing, cached page, or opening hours is not good enough to act on.
Do not use it for facts that are reliably published and stable; ordinary search is cheaper.

## How to use (agent flow)
1. GET https://realask.net/v1/capabilities to see the question shapes, prices and limits. Free.
2. POST https://realask.net/v1/quotes with {"request": "<natural language>", "location": {"postal_code": "33312", "country": "US"}, "limits": {"max_businesses": 5, "deadline_seconds": 600}, "callback_url": "<optional https webhook>"}. Free. Returns quote_id, price (integer minor units), scope, expected_completion_seconds, expires_at.
3. POST https://realask.net/v1/jobs with {"quote_id": "..."} and header Idempotency-Key: <uuid>. First response is HTTP 402 with header PAYMENT-REQUIRED (x402 v2). Pay exactly the quoted amount, retry with PAYMENT-SIGNATURE. Success is HTTP 202 with job_id, job_token (shown once), status_url, result_url.
4. Poll GET https://realask.net/v1/jobs/{job_id} with Authorization: Bearer <job_token>, or wait for the signed webhook. Live verification takes minutes; keep working meanwhile.
5. GET https://realask.net/v1/jobs/{job_id}/result returns answer.best_match with typed facts, evidence excerpts, verified_at, confidence, freshness, and limitations. 200 = final, 202 = provisional.

## Where answers come from
Three sources, tried in this order, and every fact says which one it came from:
1. merchant_feed - the business has connected its live inventory or booking system. Instant, no call. Confidence is that merchant's earned reliability (how often its feed agreed with live calls); below 0.80 the answer is marked uncertain and verified by calling.
2. cached_verified_fact - a fresh answer from an earlier live call, with its age.
3. live_business_call - the business was called now.
Set verification_mode "live_verified" to force a call regardless. Businesses that have connected but do not accept calls are reported as such in limitations.

## Guarantees
- One paid quote creates exactly one job. Retries with the same Idempotency-Key or the same signed payment return the existing job; no duplicate charges or duplicate calls.
- Facts below 0.60 confidence are never presented as verified. Conflicting statements are surfaced, not averaged.
- Every fact carries observed_at and a source (live_business_call or cached_verified_fact with its age).
- Cached verified facts may be offered at a lower price; request verification_mode "live_verified" to force a fresh call.

## Boundaries
- United States local businesses only. Business-information questions only.
- No sales, marketing, political, collections, medical, legal, emergency, or financial-trading requests. No negotiation or purchasing on the user's behalf.
- Max 5 businesses per job, 10 minute maximum job duration. Jobs that hit the deadline return partial evidence with honest limitations.

## Payment
{"protocol":"x402","x402Version":2,"scheme":"exact","network":"eip155:8453","payTo":"0x8B4d990B8F59ae2e2E169DF4aEfBfdaF12d33fF5","facilitator":"coinbase-cdp","resource":"https://realask.net/v1/jobs","bazaar_discoverable":true,"description":"Ask the real world a question and get a structured, time-stamped, confidence-scored answer. Verifies current facts about a specific US local business - in stock, price, same-day availability, whether it can do an unusual job, a policy exception, current wait time - by calling the business and extracting typed facts with evidence. Use when web and profile data are missing, stale, or unreliable. Get a price from POST /v1/quotes first; this endpoint buys that quote and returns a job_id to poll. Returns the answer, not a transcript.","tags":["verification","ground-truth","local-business","phone-call","real-time-data","availability","inventory","pricing","confirm","fact-check"]}

## Links
- Capabilities (machine-readable): https://realask.net/v1/capabilities
- OpenAPI: https://realask.net/openapi.json
- Full agent guide: https://realask.net/llms-full.txt
- MCP (remote): https://realask.net/mcp
- x402 discovery: https://realask.net/.well-known/x402
- Business opt-out: https://realask.net/opt-out
- Privacy: https://realask.net/privacy