Create an OpenAI-compatible LLM response

POST /v1/chat/completions

Operation ID: createChatCompletion. The canonical machine-readable schema is OpenAPI.

Request body

Choose an available model value from GET /v1/models. The max_tokens value limits the model's output and helps calculate the highest possible charge; it is not the final amount charged. Streaming must remain false.

{
  "model": "gemini-3.6-flash",
  "messages": [
    {
      "role": "user",
      "content": "Explain in two short sentences why the sky appears blue."
    }
  ],
  "max_tokens": 1024,
  "stream": false
}

Payment lifecycle

The first request returns Hypertext Transfer Protocol (HTTP) status 402 without calling the model provider. Check the Base network, United States Dollar Coin (USDC) contract, payment recipient, expiry time, payment scheme, and maximum amount. Sign locally with an official x402 client, then retry the identical effective request with the same idempotency key.

After success, read the PAYMENT-RESPONSE, X-Request-ID, X-Receipt-ID, and X-Catalog-Version headers together with the receipt link. The response is released only after the result, payment, and receipt are safely stored.

Read the response

Visible text is in choices[0].message.content. A finish_reason value of "stop" means the answer completed normally. A value of "length" means the answer is valid but ended at the output limit. Usage includes input, output, total, and provider-supported reasoning-token counts. Ignore large provider-specific fields unless the raw response was explicitly requested.

Responses

• 200: Durably settled response with X-Receipt-ID and PAYMENT-RESPONSE headers
• 400: Invalid or unsupported request
• 402: Payment required. The PAYMENT-REQUIRED header is authoritative and contains the official x402 challenge.
• 409: Idempotency key reused with a different effective request
• 503: Provider, payment, or safety dependency unavailable