Chat completions (OpenAI-compatible)
POST /v1/chat/completionsOpenAI-compatible chat completions, base tier: point any OpenAI SDK at base_url https://agent402.tools/v1 and pay per call over x402 or MPP (the 402 lists every accepted rail), no API key, no signup. Send POST /v1/chat/completions with the required field messages and pay quoted per request from $0.02 over x402 or MPP (there is no free tier). It returns a JSON object with id, object, created, model, choices and 1 more.
Returns the standard chat.completion object (choices[].message.content, usage). Budget/mid models: gpt-6-luna (the default when model is omitted), claude haiku, gemini flash, deepseek, llama, mistral, qwen. Full wire compatibility incl. tools/function-calling and response_format. GET /v1/models lists every model. Streaming supported (stream: true). One flat price per call up to the tier caps; /v1/metered/chat/completions quotes each call from its own size instead. Model-backed. The default is openai/gpt-6-luna; a call that names no model and carries a parameter openai/gpt-6-luna does not take (temperature, top_p or top_k) is served by google/gemini-3.5-flash-lite.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
model | string | no | Model id - OpenRouter form (openai/gpt-6-luna) or bare OpenAI form (gpt-6-luna). GET /v1/models lists the allowlist per tier. Optional: omit it and the tier serves its documented default (x402.defaultModel on /v1/models), named back in agent402_default_model; the price does not change. On /v1/metered/chat/completions: The default is anthropic/claude-haiku-5.5; a call that names no model and carries a parameter anthropic/claude-haiku-5.5 does not take (temperature, top_p, top_k, an assistant prefill or a fixed reasoning budget) is served by anthropic/claude-haiku-4.5. |
messages | array | yes | OpenAI chat messages: [{role, content}] - text and image_url content blocks supported |
max_tokens | number | no | Output token cap (clamped to the tier maximum) |
zdr | boolean | no | Optional - true routes only to zero-data-retention providers (OpenRouter provider.zdr); the only provider preference a caller may set. |
model_fallback | boolean | no | Optional, default true - when the requested model has no available upstream host, a same-family successor costing no more (or the tier's own fallback model) serves instead, and the reply names a successor in agent402_model_substituted. false: serve only the requested model, never a fallback, and return the error. |
cache_control | any | no | Optional - prompt caching preference. Default ON ({type:"ephemeral"}, 5-minute TTL): repeated prefixes across your turns are served from the provider cache (same price to you). Send false to disable. ttl:"1h" is not offered. |
reasoning | object | no | Optional - {effort: "none"|"minimal"|"low"|"medium"|"high"|"xhigh"|"max", max_tokens?, exclude?, enabled?}. Reasoning tokens count against max_tokens. Omitted: low effort on the budget tiers, the model default on premium. reasoning_effort (string) is accepted as an alias. An effort above "low", or a reasoning.max_tokens budget, that leaves no room for an answer inside a small max_tokens is lowered before the call (the cap and the price stay as they are), and an answer that still comes back empty for length is retried once on the same model at its lowest supported effort when the call's price and time allow. Either change is named in agent402_reasoning_adjusted {field, requested, used, reason}, sent as the X-Agent402-Reasoning-Adjusted header on a stream. |
max_completion_tokens | integer | no | Optional - alias of max_tokens (newer OpenAI SDKs send this). |
tools | array | no | Optional - OpenAI function tools {type:"function", function:{...}}, or a tool namespace {type:"namespace", name, tools:[...]} (flattened into its functions). The pro and premium routes also accept the bounded server tools openrouter:web_search, openrouter:web_fetch and openrouter:datetime with server-owned limits (GET /v1/models lists them); stop_server_tools_when and max_tool_calls are refused. A request with a server tool is never served from the prompt cache. |
Example request
curl -i -X POST https://agent402.tools/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"Reply with exactly: OK"}],"max_tokens":5}'Without payment this returns HTTP 402 Payment Required with the exact price for v1-chat; 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
}
}| Field | Type | Always present | In the example |
|---|---|---|---|
id | string | yes | gen-… |
object | string | yes | chat.completion |
created | number | yes | 1750000000 |
model | string | yes | openai/gpt-6-luna |
choices | array of objects | yes | 1 item in the example |
usage | object | yes | 3 fields: prompt_tokens, completion_tokens, total_tokens |
From an MCP client
catalog.call {
"slug": "v1-chat",
"params": {
"messages": [
{
"role": "user",
"content": "Reply with exactly: OK"
}
],
"max_tokens": 5
}
}The hosted connector at https://agent402.tools/mcp needs a payment for v1-chat; 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
messagesis required. An input the tool rejects returns an HTTP 4xx whose body carrieserror,tool,expected,requiredandexample, so the caller can correct it.- A paid call that ends in any status of 400 or above is not charged over x402, MPP or a prepaid credits key: settlement runs after the tool and only on a successful response. The exception is a Tempo push credential, a transfer the buyer sent before the call: it settles before the tool runs, so if the tool then fails the payment is recorded as a refund owed to the paying wallet.
- Wallet-only: this tool runs a model, so it has no proof-of-work tier. A prepaid card-credits key issued earlier (
Authorization: Bearer a402_...) also pays it. - Model-backed: the answer is generated by a model, so the same input can produce a different result.
- Priced per request: the 402 quotes this body, between $0.02 and $0.5.
- Flat per call for the models this tier serves. A body naming another flat tier's model (nano, base, pro, premium) is quoted at that tier's price in the 402 and served under that tier; model "auto" is quoted and served as the auto tier. The answer names the tier in agent402_tier. The live 402 is always the price.
- A
GETorHEADto /v1/chat/completions returns the same 402 quote, so the price can be read without a body. - An
Idempotency-Keyheader makes a retried paid call replay the first 200 instead of charging again (an answer larger than 1 MB and a streamed response are not replayed).
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.50" }); // 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/chat/completions", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
"messages": [
{
"role": "user",
"content": "Reply with exactly: OK"
}
],
"max_tokens": 5
}),
});Related tools
Text-to-speech (OpenAI-compatible)
OpenAI-compatible text-to-speech over x402 - point any OpenAI SDK's audio.speech.create() at base_url.
Chat completions - auto tier (eval-ranked routing)
OpenAI-compatible chat completions with server-side model choice: omit "model" (or send "auto") and the gateway routes.
Grounded chat (web search, OpenAI-compatible)
OpenAI-compatible chat completions GROUNDED in a live web search on every call: the gateway runs a live web search (up.
Chat completions - metered (pay what the call costs)
OpenAI-compatible chat completions priced per request from the request itself.
Chat completions - nano tier
OpenAI-compatible chat completions, nano tier: gpt-6-luna (the default), gpt-5.6-luna, claude haiku 5.5, gemini.
Chat completions - premium tier
OpenAI-compatible chat completions, premium tier: claude opus 5.5 (the default), gpt-5.6 sol and terra, gpt-6 astra.