---
title: "Machine Payments Protocol (MPP)"
description: "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)](https://mpp.dev) 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

| Operation | What it does | Payment method | Price |
| --- | --- | --- | --- |
| `POST /twitter/advanced_search/page` | Returns one cursor-based page of advanced Twitter search results. | Tempo USDC | USD 0.0001 per page |

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
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

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

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

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

## MPP and API keys

| Choose | When it fits |
| --- | --- |
| MPP | You need an anonymous, pay-per-use request to a supported operation. |
| API key | You need access to the full TwexAPI surface, account-level credits, or endpoints that do not publish an MPP offer. |

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](/mpp/quickstart) — install the client, configure a Tempo wallet, and make a paid search request.
- [API overview](/api-reference/overview) — use API-key authentication and browse the wider TwexAPI endpoint catalog.