Skip to content

Chat completions (OpenAI-compatible)

quoted per request from $0.02USDC via x402POST /v1/chat/completions

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

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

Try in playground →

Parameters

NameTypeRequiredDescription
modelstringnoModel 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.
messagesarrayyesOpenAI chat messages: [{role, content}] - text and image_url content blocks supported
max_tokensnumbernoOutput token cap (clamped to the tier maximum)
zdrbooleannoOptional - true routes only to zero-data-retention providers (OpenRouter provider.zdr); the only provider preference a caller may set.
model_fallbackbooleannoOptional, 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_controlanynoOptional - 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.
reasoningobjectnoOptional - {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_tokensintegernoOptional - alias of max_tokens (newer OpenAI SDKs send this).
toolsarraynoOptional - 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
  }
}
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

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

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)

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

Grounded chat (web search, OpenAI-compatible)

$0.03POST /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.

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.