Skip to main content
POST
/
route
POST /route
curl --request POST \
  --url https://graphadvocate.com/route

Documentation Index

Fetch the complete documentation index at: https://docs.graphadvocate.com/llms.txt

Use this file to discover all available pages before exploring further.

This endpoint is x402-gated. Free-tier users (10/day) should POST to / using A2A JSON-RPC — same routing logic, no payment required.

​
What happens

  1. First call returns 402 Payment Required with x402 accepts list ($0.01 USDC on Base)
  2. x402 client signs a transferWithAuthorization and retries with X-PAYMENT header
  3. CDP facilitator verifies, settles on-chain, forwards to the handler
  4. Graph Advocate routes the query, picks the best service, generates the GraphQL, and — when possible — executes it and returns live data
You pay once. You get routing + execution. One call, one answer.

​
Request body

{ "request": "your plain-English question" }
Also accepts A2A-format body with params.message.parts[].text.

​
Response shape

{
  "recommendation": "subgraph-registry | token-api | substreams | ...",
  "reason": "...",
  "confidence": "high | medium | low",
  "query_ready": {
    "tool": "execute_query_by_subgraph_id",
    "args": {
      "subgraph_id": "HMuAwufqZ1YCRmzL2SfHTVkzZovC9VL2UAKhjvRqKiR1",
      "gql": "{ pools(...) { ... } }"
    }
  },
  "curl_example": "curl -X POST 'https://gateway.thegraph.com/api/...",
  "subgraph_details": { "name": "UniV3-Base", "query_volume_30d": 40771350, "..." },
  "alternatives": [ { "service": "...", "reason": "..." } ],
  "execution_result": { "data": { "pools": [...] } }
}
The killer field is execution_result — Graph Advocate didn’t just tell you where to look, it ran the query for you.

​
What to do with the response

  • gql is production-ready GraphQL — paste it as-is into your client or the Graph gateway, no edits needed.
  • subgraph_id is the deployment ID; combine with https://gateway.thegraph.com/api/subgraphs/id/{subgraph_id} to query directly.
  • curl_example is a complete working request you can run in a terminal — useful for sanity-checking before wiring up your client.
  • execution_result (when present) is already the answer; no follow-up call needed.
If execution_result is missing, fire the curl_example against the Graph gateway with your own API key (free tier available). The gql is always live-tested before being returned.

​
Pricing

TierQuotaCost
Free10 queries / sender / day$0 (hit POST /, not /route)
PaidUnlimited$0.01 USDC on Base per call
PrioritySame as paidHigher-ranked response, full search context

​
Sample: paid call

from x402 import x402Client
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client
from x402.http.clients import x402HttpxClient
from eth_account import Account
import os

client = x402Client()
register_exact_evm_client(client, EthAccountSigner(Account.from_key(os.environ["EVM_PRIVATE_KEY"])))

async with x402HttpxClient(client) as http:
    r = await http.post(
        "https://graphadvocate.com/route",
        json={"request": "Top Aave V3 reserves by TVL on Base"},
    )
    print(r.json())