POST /route

POST /route

curl --request POST \
  --url https://graphadvocate.com/route

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://graphadvocate.com/route",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://graphadvocate.com/route"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://graphadvocate.com/route")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

route

POST /route

curl --request POST \
  --url https://graphadvocate.com/route

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://graphadvocate.com/route",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://graphadvocate.com/route"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://graphadvocate.com/route")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

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

First call returns 402 Payment Required with x402 accepts list ($0.01 USDC on Base)
x402 client signs a transferWithAuthorization and retries with X-PAYMENT header
CDP facilitator verifies, settles on-chain, forwards to the handler
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

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

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())

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());

Agent card Examples

⌘I

Getting started

Routing

Trader intelligence

x402 analytics

Discovery

Payments

What happens

Request body

Response shape

What to do with the response

Pricing

Sample: paid call

​What happens

​Request body

​Response shape

​What to do with the response

​Pricing

​Sample: paid call

What happens

Request body

Response shape

What to do with the response

Pricing

Sample: paid call