MPP charge payments

Status and scope

Singular implements MPP-style per-call charge challenges on POST /v1/chat/completions and POST /v1/embeddings when enabled. A paid request must contain exactly one explicit live-catalog model, omit models, and avoid Singular routing suffixes. Streaming, model: "auto", fallback arrays, suffixed IDs, native Anthropic Messages, legacy completions, Responses, and media routes are excluded.

MPP is a separate HTTP authentication protocol from x402. MPP offers are sent as WWW-Authenticate: Payment ... challenges and do not appear inside x402's accepts array.

The HTTP Payment specification is still a working draft, and Singular's imr* method names and payloads are private extensions. A generic MPP client will not automatically know how to fulfill them.

1. Receive a Payment challenge

Send the same unsigned, non-streaming, single-model request used for the x402 discovery step. A ready MPP deployment appends one challenge per usable method/network:

HTTP/1.1 402 Payment Required
Cache-Control: no-store
WWW-Authenticate: Payment realm="impossi-router", id="<quote-id>", method="imrevmusdc", intent="charge", ...

The challenge binds the quote ID, method, expiry, digest, and request metadata. The digest is SHA-256 over the raw request body. Preserve the exact body bytes for the retry.

2. Fulfill the advertised method

The shipped methods are:

All shipped Singular payment methods are exact-charge methods. Network, asset, destination, amount, memo/nonce, and expiry must match the challenge.

3. Retry with the credential

Encode the method-specific credential as unpadded base64url JSON and retry the exact request:

Authorization: Payment <base64url-without-padding JSON>
Content-Type: application/json

Singular verifies the quote and request binding before promoting the settled payment into the data-plane authorization context. Payment headers are stripped before the model request reaches an upstream provider.

4. Read the receipt

A successfully served 2xx response includes an unpadded base64url receipt:

Payment-Receipt: <base64url-without-padding JSON>
Cache-Control: private

Singular never emits Payment-Receipt on a non-2xx model response. A quote can still be consumed after settlement even when upstream inference fails, so clients must not equate 'no receipt' with 'no funds moved.'

Deployment requirements

MPP defaults off. A working deployment needs MPP enabled, complete chain rows, a durable quote/nonce store, and chain-specific verifier health. EVM methods also require a funded hot relayer. Solana and Stellar use payer-broadcast transactions and enforce their memo bindings.

The default source registry contains network templates, not a promise of live service. Always use the methods and networks actually advertised in the current response.

Known protocol deviations

The initial challenge and successful receipt broadly follow the current HTTP Payment draft. Ordinary protocol or payment rejections currently use a bare JSON 402 without the fresh Payment challenge and Problem Details described by the draft. Missing verifiers can return 503, and unexpected verifier failures can surface as 5xx. Clients should treat failure recovery as Singular-specific and avoid automatic replay.

No first-party @impossi/router-sdk is published in this repository. Implementations must use the wire contract and method-specific signing logic; copied placeholder SDK examples are not supported.

Primary references: HTTP Payment authentication draft and USDC charge method draft.