Messages premium (Anthropic-compatible)
POST /v1/premium/messagesAnthropic Messages API over x402 - point the Anthropic SDK (or Claude Code / the Agent SDK) at base_url https://agent402.tools/v1/premium and pay $0.50 per call in USDC, no API key, no signup. Send POST /v1/premium/messages with the required fields max_tokens and messages and pay $0.50 per call over x402 or MPP (there is no free tier). It returns a JSON object with id, type, role, model, content and 2 more.
Same models, caps and price as this tier's /chat/completions route; any model here is served through the Messages wire (Claude natively, others translated). Depth: `effort` (low..max) on Claude 4.7+ and Haiku 5.5, thinking.budget_tokens on older Claude. Up to 200,000 input chars and 8192 output tokens; streaming supported. Omit "model" and the tier serves anthropic/claude-opus-5.5 (named back in agent402_default_model); the price does not change.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
model | string | no | Model id (OpenRouter naming, e.g. anthropic/claude-sonnet-5) - allowlisted per tier; omit (or "auto") on the auto tier |
max_tokens | integer | yes | Required by the Messages API; clamped to the tier's output cap |
messages | array | yes | Anthropic messages: {role: user|assistant, content: string | [text|image|tool_use|tool_result blocks]} |
system | string | no | Optional system prompt (string or text blocks) |
tools | array | no | Optional client tools {name, description, input_schema}; server/built-in tools are not served |
thinking | object | no | Optional {type:"enabled", budget_tokens} | {type:"adaptive"} | {type:"disabled"} - thinking tokens are output tokens; a budget is clamped along with max_tokens to fit the tier output cap. On Claude 4.7+ (Opus 5, Sonnet 5, Fable 5.1) thinking is adaptive and `effort` is the depth control; a budget_tokens value is advisory there. Claude Haiku 5.5 refuses {type:"enabled", budget_tokens} with a 400 (send effort instead). A budget above three quarters of max_tokens is lowered to leave a quarter for the answer (not under 1024), and an answer that still comes back empty is retried once with thinking off where the model runs without it, when the call's price and time allow; either change is named in agent402_reasoning_adjusted |
effort | string | no | Optional depth control for Claude 4.7+ (Opus 5, Sonnet 5, Fable 5.1) and Claude Haiku 5.5: low | medium | high | xhigh | max, validated against the model's own list (GET /v1/models). Not accepted on Haiku 4.5 and older, which take thinking.budget_tokens instead. An effort above low that leaves no room for an answer inside a small max_tokens is sent as low, and an answer that still comes back empty is retried once at the model's lowest effort when the call's price and time allow; either change is named in agent402_reasoning_adjusted {field, requested, used, reason} (the X-Agent402-Reasoning-Adjusted header on a stream) |
stream | boolean | no | Anthropic SSE (message_start … message_stop) |
zdr | boolean | no | Optional - zero-data-retention providers only |
Example request
curl -i -X POST https://agent402.tools/v1/premium/messages \
-H "Content-Type: application/json" \
-d '{"model":"anthropic/claude-opus-5.5","max_tokens":1024,"messages":[{"role":"user","content":"Summarize x402 in one sentence."}]}'Without payment this returns HTTP 402 Payment Required with the exact price for v1-chat-premium-messages; any x402 v2 or MPP client pays it and retries.
Example response
{
"id": "msg_…",
"type": "message",
"role": "assistant",
"model": "anthropic/claude-sonnet-5",
"content": [
{
"type": "text",
"text": "x402 is an HTTP-native way for agents to pay per request with USDC."
}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 14,
"output_tokens": 18
}
}| Field | Type | Always present | In the example |
|---|---|---|---|
id | string | yes | msg_… |
type | string | yes | message |
role | string | yes | assistant |
model | string | yes | anthropic/claude-sonnet-5 |
content | array of objects | yes | 1 item in the example |
stop_reason | string | yes | end_turn |
usage | object | yes | 2 fields: input_tokens, output_tokens |
From an MCP client
catalog.call {
"slug": "v1-chat-premium-messages",
"params": {
"model": "anthropic/claude-opus-5.5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "Summarize x402 in one sentence."
}
]
}
}The hosted connector at https://agent402.tools/mcp needs a payment for v1-chat-premium-messages; 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
max_tokensandmessagesare 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.50 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/premium/messages 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/premium/messages", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
"model": "anthropic/claude-opus-5.5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "Summarize x402 in one sentence."
}
]
}),
});Related tools
Messages auto (Anthropic-compatible)
Anthropic Messages API over x402 - point the Anthropic SDK (or Claude Code / the Agent SDK) at base_url.
Messages base (Anthropic-compatible)
Anthropic Messages API over x402 - point the Anthropic SDK (or Claude Code / the Agent SDK) at base_url.
Messages metered (Anthropic-compatible)
Anthropic Messages API priced per request from the request itself.
Messages nano (Anthropic-compatible)
Anthropic Messages API over x402 - point the Anthropic SDK (or Claude Code / the Agent SDK) at base_url.
Messages pro (Anthropic-compatible)
Anthropic Messages API over x402 - point the Anthropic SDK (or Claude Code / the Agent SDK) at base_url.
Text-to-speech (OpenAI-compatible)
OpenAI-compatible text-to-speech over x402 - point any OpenAI SDK's audio.speech.create() at base_url.