Machine Payments Protocol (MPP)

Make pay-per-use TwexAPI requests with HTTP 402, Tempo USDC, and payment receipts.

Machine Payments Protocol (MPP)

TwexAPI supports the Machine Payments Protocol (MPP) for selected pay-per-use requests. An MPP client can pay for an eligible request with Tempo USDC instead of sending a TwexAPI API key.

MPP is useful for agents, scripts, and services that need to pay only for the requests they make. It does not replace API-key authentication on endpoints that are not listed below.

Supported operation

The server remains the authority for the current payment offer. Read the WWW-Authenticate: Payment challenge returned for a request instead of hard-coding an amount, recipient, or payment credential format.

How payment works

1. Send a normal request to an MPP-enabled endpoint without an API key.
2. The server responds with 402 Payment Required and a WWW-Authenticate: Payment challenge.
3. Your MPP client pays the Tempo USDC request described by that challenge and retries with an Authorization: Payment credential.
4. A settled response includes a Payment-Receipt header. Check both the HTTP status and response body; a receipt only confirms the payment was settled.

Payment challenge

HTTP/2 402 Payment Required
WWW-Authenticate: Payment id="abc...", realm="api.twexapi.io", method="tempo", intent="charge", request="eyJhbW91bnQiOi..."

The challenge’s request value contains the current payment instruction. Treat it as opaque data for the MPP client; do not parse or construct a payment from a cached example.

Paid retry and receipt

POST /twitter/advanced_search/page HTTP/2
Host: api.twexapi.io
Authorization: Payment eyJjaGFsbGVuZ2UiOnsi...
Content-Type: application/json

{"searchTerms":["openai"],"sortBy":"Latest"}

HTTP/2 200 OK
Payment-Receipt: eyJzdGF0dXMiOiJzdWNjZXNzIiwi...
Content-Type: application/json

MPP and API keys

MPP payments use a Tempo wallet funded with USDC. Keep the wallet private key in an environment variable and never commit it to source control, logs, or chat transcripts.

Next steps

• MPP quickstart — install the client, configure a Tempo wallet, and make a paid search request.
• API overview — use API-key authentication and browse the wider TwexAPI endpoint catalog.