API documentation

1. Choose the payment mode

Circle Gateway: POST https://402.paymentrequired.com/v1/gateway/chat/completions costs exactly 0.010000 USDC per successful bounded answer. It accepts the mainnet networks published in the live 402 challenge. The calling wallet needs funded Circle Gateway balance on an accepted network. This is not a direct wallet-token transfer.

Direct wallet: existing POST /v1/chat/completions and paid MCP chat at /mcp use actual input/output token pricing on Base, without a Gateway deposit. Their current tariff is in /v1/models: 1 USDC per million input tokens, 3 per million output tokens, plus 0.002 USDC per completed answer, maximum bill 0.01 USDC. They prepare the answer privately before issuing its exact invoice. Do not apply the fixed Gateway price to this separate mode.

Neither mode requires a router account or router API key. The Gateway OpenAPI document describes the fixed-price endpoint. Model selection and direct-wallet/MCP behavior remain available independently.

2. Build a valid Gateway request

Choose subs/gpt-6-astra or subs/gpt-5.6-luna. Supply 1–16 text messages with a role (system, user or assistant) and text content. Maximum request size: 16384 bytes. Optional max_tokens: 1–128, default 64. Set stream to false or omit it. No images, tools, multiple choices, live streaming or unlisted OpenAI options.

curl -i https://402.paymentrequired.com/v1/gateway/chat/completions   -H 'Content-Type: application/json'   -d '{"model":"subs/gpt-6-astra","messages":[{"role":"user","content":"Reply exactly: CIRCLE_GATEWAY_OK"}],"max_tokens":32}'

This unsigned request returns HTTP 402 and a real PAYMENT-REQUIRED header. It does not generate an answer or move funds.

circle services inspect https://402.paymentrequired.com/v1/gateway/chat/completions --output json

circle services pay https://402.paymentrequired.com/v1/gateway/chat/completions   -X POST --address <your-wallet-address> --chain MATIC   --max-amount 0.01 --estimate   -d '{"model":"subs/gpt-6-astra","messages":[{"role":"user","content":"Reply exactly: CIRCLE_GATEWAY_OK"}],"max_tokens":32}'

The estimate does not pay. For an explicitly approved real payment, remove --estimate, add --timeout 240 --output json, and supply -H 'Idempotency-Key: <a-new-private-UUIDv4>'. Select the chain of your funded Gateway balance from the actual challenge; MATIC means Polygon. Do not copy placeholder text as credentials or keys.

3. Payment and response

The official @circle-fin/x402-batching middleware negotiates x402 v2, verifies the signed authorization and settles through Circle Gateway. The server validates the request, reserves its verified identity, prepares and persists the real answer, then allows settlement and releases the answer. Invalid or failed model preparation must not settle.

A successful HTTP 200 contains choices[0].message.content, provider metadata and reported usage. The PAYMENT-RESPONSE header contains a base64 JSON receipt. Its transaction can be a Circle transfer ID, not a blockchain transaction hash. Check the exact ID at https://gateway-api.circle.com/v1/x402/transfers/<transfer-id>; accepted, batched and completed are different states.

The fixed charge is 0.010000 USDC, not a claim of supplier-cost pass-through. The caller must use Gateway-compatible authorization, not ordinary USDC EIP-3009 signing; the official client handles the Gateway signing domain and required validity period. Wallet private keys never belong in API messages.

4. Retry and failure rules

Generate a private random UUIDv4 Idempotency-Key for each logical request. Preserve it and the exact body. A confirmed paid response can be recovered by repeating that body/key without authorizing a new payment. A signature visible on chain is not a private answer-recovery credential. A call without a recovery key can execute once but cannot safely recover a lost private answer using the public signature alone.

400: fix the input before paying. 402 with PAYMENT-REQUIRED: inspect the real challenge. 409: request/nonce already in use. 502: provider/preparation failure, including exhausted bounded generation capacity. 503 or an unknown/pending settlement: stop and contact support, never blindly re-pay. Keep the original receipt and request identifier privately. There is no automatic refund or atomic payment-and-delivery guarantee.

5. Scope and human support

This is a bounded technical PoC. OpenAPI 3.1 and seller readiness describe the declared Gateway endpoint; they are not proof of full OpenAI feature parity or of every network having a separately executed paid test. Only transaction-backed runs are published as payment proof. Existing direct-wallet tests: proof.json.

Contact support@nuri.com for reconciliation or API questions. Send the request/transfer ID, never wallet keys or payment signatures.