x402 per-call payments

Availability

Singular includes x402 v2 payment middleware for POST /v1/chat/completions and POST /v1/embeddings. It is disabled unless the deployment enables x402. Configuration, verifier selection, startup grace, quote storage, and settlement health are separate readiness checks: a configured or advertised rail is not proof that a payment will settle, and unavailable quote storage can produce 503.

Only Chat Completions is otherwise documented as a stable inference endpoint today. Do not infer that embeddings is production-ready merely because payment middleware is registered on its route.

A pay-per-call request must use exactly one explicit live-catalog model, omit the Singular-specific models fallback array, avoid Singular routing suffixes, and set stream: false. model: "auto", fallback arrays, suffixed IDs, and streaming are rejected on the payment path.

The live 402 response is the source of truth for what is advertised. If a request does not include a valid PAYMENT-REQUIRED challenge with an acceptable scheme, network, asset, amount, destination, and expiry, the client must treat x402 as unavailable. A challenge proves configuration, not final settlement.

1. Request a quote

Send the exact JSON request without Authorization, x-api-key, or a payment signature:

curl -i https://api.impossi.build/v1/chat/completions \
  -H "Content-Type: application/json" \
  --data-binary '{
    "model": "provider/explicit-model",
    "stream": false,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

When a rail is advertised, the gateway returns 402 Payment Required, Cache-Control: no-store, a JSON x402 v2 PaymentRequired body, and the same document encoded in PAYMENT-REQUIRED.

2. Parse the v2 challenge

The emitted document follows this shape. This example is illustrative; sign the exact entry returned by the gateway and never reconstruct or drop fields:

{
  "x402Version": 2,
  "error": "payment_required",
  "resource": {
    "url": "https://api.impossi.build/v1/chat/completions",
    "mimeType": "application/json"
  },
  "accepts": [{
    "scheme": "<advertised scheme: exact or upto>",
    "network": "<CAIP-2 network>",
    "asset": "<asset identifier>",
    "amount": "<integer base units>",
    "payTo": "<destination>",
    "maxTimeoutSeconds": 30,
    "extra": {
      "rail": "x402",
      "chainId": "<chain id or null>",
      "nonce": "<quote nonce>",
      "bodyHash": "<bound request hash>",
      "expiresAt": "<timestamp>",
      "resource": "<canonical request URL>",
      "description": "<model id>",
      "mimeType": "application/json"
    }
  }]
}

x402 v2 uses amount. Older examples using maxAmountRequired are not valid for this contract.

3. Sign and retry

Use a current x402 client that supports the advertised scheme and network. Retry the same method, URL, explicit model, and JSON content with:

PAYMENT-SIGNATURE: <base64-encoded x402 v2 PaymentPayload>

The quote is bound to its nonce, expiry, endpoint, model, JCS-canonical body hash, network, asset, destination, amount, and scheme. JSON key order and insignificant whitespace may change without changing the canonical hash, but semantic request changes invalidate the credential.

4. Read the result

A successfully settled and served 2xx response includes:

PAYMENT-RESPONSE: <base64-encoded settlement response>
Cache-Control: private

For EVM upto, inference can complete before deferred settlement. If that settlement fails, Singular deliberately serves the upstream 2xx without PAYMENT-RESPONSE and the operator absorbs the cost. Clients must treat a 2xx without this header as served but not receipt-confirmed.

A payment failure can return another 402 without a fresh challenge. Do not assume that every post-signature failure is safely replayable.

Current standards gate

The source currently selects upto for non-streaming EVM chat, but the current official x402 EVM upto scheme is Permit2-only and excludes EIP-3009. Singular's implementation does not yet publish the current Permit2-specific requirement fields. There is no separate runtime release gate for this mismatch: enabling x402 can advertise EVM upto automatically. Do not enable EVM-chat x402 in production until the implementation is updated and verified against the live facilitator.

Singular's exact path also settles before model execution, while the current default exact scheme describes verify → resource → settle unless an alternate flow is declared. Treat protocol-version alignment as a release gate, not a documentation detail.

What x402 does not do here

• It does not top up a Singular API key or reseller wallet.
• It does not apply to native Anthropic Messages, Responses, legacy completions, media routes, or streaming.
• It does not provide a documented automatic-refund guarantee.
• A configured network template is not proof that facilitator support, destination health, and settlement are live.

Primary protocol references: x402 v2 schema and x402 HTTP transport.