MPP Quickstart

Pay for a TwexAPI advanced search page with Tempo USDC and the mppx client.

MPP Quickstart

Make a pay-per-use TwexAPI advanced-search request without a TwexAPI API key. This guide uses the mppx client to answer the HTTP 402 challenge, pay with Tempo USDC, and retry the request automatically.

Step 1: Install the client dependencies

npm install mppx viem

mppx handles MPP challenges and payments. viem converts a Tempo private key into the wallet account used by the client.

Step 2: Create and fund a Tempo wallet

Create a local MPP account, then export its private key:

mppx account create
mppx account export

Fund the printed address with USDC on Tempo. Store the exported 0x... private key in an environment variable:

export TEMPO_PRIVATE_KEY="0x..."

Step 3: Make an MPP request

Create mpp-search.ts:

import { Mppx, tempo } from "mppx/client";
import { privateKeyToAccount } from "viem/accounts";

Mppx.create({
  methods: [
    tempo({
      account: privateKeyToAccount(
        process.env.TEMPO_PRIVATE_KEY as `0x${string}`,
      ),
    }),
  ],
});

const response = await fetch(
  "https://api.twexapi.io/twitter/advanced_search/page",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      searchTerms: ["openai"],
      sortBy: "Latest",
    }),
  },
);

if (!response.ok) {
  throw new Error(`TwexAPI request failed: ${response.status}`);
}

console.log(await response.json());

Mppx.create() configures fetch to handle an MPP 402 Payment Required challenge. For an eligible endpoint, it pays the server-provided Tempo offer and retries the same request with the payment credential. Inspect response.headers.get("Payment-Receipt") when you need to record settlement.

Pass next_cursor in the JSON body when continuing from a prior page:

{
  "searchTerms": ["openai"],
  "sortBy": "Latest",
  "next_cursor": "cursor-from-the-previous-response"
}

Step 4: Implement the raw HTTP flow

Without mppx, first request the search page normally:

curl -i --request POST 'https://api.twexapi.io/twitter/advanced_search/page' \
  --header 'Content-Type: application/json' \
  --data '{"searchTerms":["openai"],"sortBy":"Latest"}'

On 402, process the WWW-Authenticate: Payment challenge with a compatible Tempo MPP implementation. Then retry the exact request with the generated credential:

curl -i --request POST 'https://api.twexapi.io/twitter/advanced_search/page' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Payment eyJjaGFsbGVuZ2UiOnsi...' \
  --data '{"searchTerms":["openai"],"sortBy":"Latest"}'

The successful response contains TwexAPI’s usual JSON envelope and a Payment-Receipt response header. Save receipts with your own request records if your application needs reconciliation.

Next steps

• Machine Payments Protocol — review the supported operation, payment sequence, and API-key comparison.
• API overview — browse API-key authentication and the complete endpoint catalog.