Skip to content

Grounded chat (web search, OpenAI-compatible)

$0.03 per callUSDC via x402POST /v1/grounded/chat/completions

OpenAI-compatible chat completions GROUNDED in a live web search on every call: the gateway runs a live web search (up to 5 results) for the prompt, hands the results to the model, and returns the answer with url_citation annotations - $0.03 per call in USDC, no API key, no signup. Send POST /v1/grounded/chat/completions with the required field messages and pay $0.03 per call over x402 or MPP (there is no free tier). It returns a JSON object with id, object, created, model, choices and 2 more.

Model is chosen server-side like the auto tier (omit "model" or send "auto"; explicit ranked models accepted); the response adds agent402_router {category, quality, served}. The sanctioned way to get live-web answers from the gateway (":online" model variants are refused elsewhere). Caps 16k chars in / 1024 tokens out. Streaming supported. Never cached - the web moves.

Category: LLM gatewayTags: llm ai inference chat gateway openai-compatible router grounded

Try in playground →

Parameters

NameTypeRequiredDescription
messagesarrayyesOpenAI chat messages: [{role, content}] - text and image_url content blocks supported
modelstringnoOptional - omit (or send "auto") for eval-ranked server-side routing. An explicit model from the auto ranking is honored at the auto caps.
qualitystringnoOptional routing band when the gateway picks the model: "fast" (cheapest/snappiest), "balanced" (default), "best" (strongest under the flat price). Never changes the price.
service_tierstringnoOptional. "priority" (alias "fast") asks for the model's priority endpoint on /v1/pro and /v1/premium at the same flat price; max_tokens may be sized down. Refused with the reason on the other tiers; "flex" is applied by the gateway automatically and not accepted as a request.
max_tokensnumbernoOutput token cap (clamped to the tier maximum)

Example request

curl -i -X POST https://agent402.tools/v1/grounded/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"What is the current Node.js LTS version? One line, cite the source."}],"max_tokens":120}'

Without payment this returns HTTP 402 Payment Required with the exact price for v1-chat-grounded; any x402 v2 or MPP client pays it and retries.

Example response

{
  "id": "gen-…",
  "object": "chat.completion",
  "created": 1750000000,
  "model": "openai/gpt-6-luna",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "OK"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 1,
    "total_tokens": 13
  },
  "agent402_router": {
    "category": "general",
    "quality": "balanced",
    "served": "openai/gpt-5.6-luna"
  }
}
FieldTypeAlways presentIn the example
idstringyesgen-…
objectstringyeschat.completion
creatednumberyes1750000000
modelstringyesopenai/gpt-6-luna
choicesarray of objectsyes1 item in the example
usageobjectyes3 fields: prompt_tokens, completion_tokens, total_tokens
agent402_routerobjectyes3 fields: category, quality, served

From an MCP client

catalog.call {
  "slug": "v1-chat-grounded",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": "What is the current Node.js LTS version? One line, cite the source."
      }
    ],
    "max_tokens": 120
  }
}

The hosted connector at https://agent402.tools/mcp needs a payment for v1-chat-grounded; the stdio package pays it from a wallet or from an AGENT402_CREDITS_KEY issued earlier. Local install: npx -y agent402-mcp@0.13.32.

Errors and behavior

Paid call (JavaScript agent)

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
client.setSpendControls?.({ maxAmountPerPayment: "$0.03" }); // refuse any quote above this tool's price
registerExactEvmScheme(client, { signer: privateKeyToAccount(KEY) });
const payFetch = wrapFetchWithPayment(fetch, client);

const res = await payFetch("https://agent402.tools/v1/grounded/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "messages": [
      {
        "role": "user",
        "content": "What is the current Node.js LTS version? One line, cite the source."
      }
    ],
    "max_tokens": 120
  }),
});

Related tools

Chat completions - auto tier (eval-ranked routing)

$0.01POST /v1/auto/chat/completions

OpenAI-compatible chat completions with server-side model choice: omit "model" (or send "auto") and the gateway routes.

Text-to-speech (OpenAI-compatible)

$0.06POST /v1/audio/speech

OpenAI-compatible text-to-speech over x402 - point any OpenAI SDK's audio.speech.create() at base_url.

Chat completions (OpenAI-compatible)

from $0.02POST /v1/chat/completions

OpenAI-compatible chat completions, base tier: point any OpenAI SDK at base_url https://agent402.tools/v1 and pay per.

Chat completions - metered (pay what the call costs)

from $0.001POST /v1/metered/chat/completions

OpenAI-compatible chat completions priced per request from the request itself.

Chat completions - nano tier

from $0.003POST /v1/nano/chat/completions

OpenAI-compatible chat completions, nano tier: gpt-6-luna (the default), gpt-5.6-luna, claude haiku 5.5, gemini.

Chat completions - premium tier

$0.50POST /v1/premium/chat/completions

OpenAI-compatible chat completions, premium tier: claude opus 5.5 (the default), gpt-5.6 sol and terra, gpt-6 astra.