> ## 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.

# POST /route

> Paid routing — pay $0.01 USDC and get an end-to-end answer.

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

## 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

```json theme={null}
{ "request": "your plain-English question" }
```

Also accepts A2A-format body with `params.message.parts[].text`.

## Response shape

```json theme={null}
{
  "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

| Tier     | Quota                     | Cost                                        |
| -------- | ------------------------- | ------------------------------------------- |
| Free     | 10 queries / sender / day | \$0 (hit `POST /`, not `/route`)            |
| Paid     | Unlimited                 | \$0.01 USDC on Base per call                |
| Priority | Same as paid              | Higher-ranked response, full search context |

## Sample: paid call

<CodeGroup>
  ```python Python theme={null}
  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())
  ```

  ```typescript TypeScript theme={null}
  import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
  import { registerExactEvmScheme } from "@x402/evm/exact/client";
  import { privateKeyToAccount } from "viem/accounts";

  const client = new x402Client();
  registerExactEvmScheme(client, { signer: privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`) });

  const pay = wrapFetchWithPayment(fetch, client);
  const r = await pay("https://graphadvocate.com/route", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ request: "Top Aave V3 reserves by TVL on Base" }),
  });
  console.log(await r.json());
  ```
</CodeGroup>