Skip to main content
POST /ask is a paid natural-language query interface over the entire history of x402 settlements on Base. Your agent asks a question — top recipients, daily volume, facilitator share, a specific address’s activity — and gets back a single answer plus the exact SQL that produced it. No subgraph schema to learn, no SQL to write, no hallucination to babysit.

​
What you get

EndpointCostReturns
POST /ask$0.05{ answer, sql_trace[], model, upstream_ms } — natural-language answer plus every query that ran.
Per-call payment in USDC on Base via x402.

​
Why derived over raw

The same dataset is queryable directly via the x402 Base subgraph on The Graph Network, but at row-level only — you’d write GraphQL paginate, aggregate client-side, and reason about the numbers yourself. /ask collapses that loop into a single call: the agent describes the question, Sonnet writes the SQL, DuckDB runs it against the parquet warehouse, and the answer comes back with every SQL step in sql_trace so the caller can audit the data path before trusting the number. For agents that need a single derived signal (“did volume inflect last week?”, “who’s the largest recipient?”) this is the cheapest end-to-end path.

​
Request body

{ "question": "your question, up to 1000 characters" }

​
Response shape

{
  "question": "...",
  "answer": "Daily settlement count rose from a weekly average of 1.2k in early May 2026 to a peak of 8.4k on 2026-05-22, a ~7x inflection...",
  "sql_trace": [
    {
      "sql": "SELECT day, total_count, median_amount_usdc FROM daily_stats WHERE day >= '2025-05-01' ORDER BY day",
      "rows": 388,
      "ms": 412
    }
  ],
  "model": "claude-sonnet-4-6",
  "upstream_ms": 2840,
  "dataset": "base-x402-settlements via x402-watch.vercel.app",
  "generated_at": "2026-06-04T18:23:11Z"
}
The sql_trace array is the receipt — every query the model ran is recorded, so the agent can verify the answer was derived from a real read (not a hallucination) and which slice of the data was actually inspected.

​
What the model can query

Two virtual tables are exposed:
TableGranularityUse for
settlementsRow-level — one row per x402 payment, ~132M rowsSpecific addresses, transaction lookups, fine-grained windows.
daily_statsOne row per day, May 2025 → Jun 2026 (~388 days)Trends, time-series, volume curves. Fast — the model picks this first when the question is daily-grain.
The model is steered to choose daily_stats for trend questions (cheap) and settlements for row-level or address-specific questions (expensive but precise), and to add a block_number predicate for parquet file pruning when reading raw rows.

​
Sample: ask in English

curl -X POST 'https://graphadvocate.com/ask' \
  -H 'Content-Type: application/json' \
  -d '{"question": "What were the top 10 x402 recipients by USDC volume in the last 30 days on Base?"}'
Returns a ranked answer plus the SQL that produced it. Use the answer to act; keep sql_trace for your audit log.

​
Sample: trend question

curl -X POST 'https://graphadvocate.com/ask' \
  -H 'Content-Type: application/json' \
  -d '{"question": "When did daily x402 settlement count inflect upward between May 2025 and June 2026?"}'
The model will pick daily_stats, return the inflection point with a date, and show you the single aggregate query in sql_trace.

​
Errors

CodeMeaningAction
400 invalid_questionBody missing question field.Send { "question": "..." }.
400 question_too_longOver 1000 characters.Tighten the question.
504 upstream_timeoutDuckDB query exceeded 60s.Retry; tighten the question; the response includes retry_after_seconds.
502 upstream_unavailableBackend error.Retry after retry_after_seconds.

​
Free tier

There is no free tier for /ask. To inspect routing without paying, send the plain-English question to POST / (A2A JSON-RPC) — Graph Advocate will name /ask as the right endpoint and hand back the exact paid curl, without charging. 
curl -X POST 'https://graphadvocate.com/' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "message/send",
    "params": {"message": {"parts": [{"text": "top x402 recipients last 7 days"}]}}
  }'