MPP payments

Pay for API requests with crypto using the Machine Payments Protocol on the Tempo blockchain.

MPP payments

The Machine Payments Protocol (MPP) enables crypto-native, per-request payments on the Tempo blockchain. MPP is an additive payment method alongside Stripe — you choose which to use on each request.

How it works

MPP uses an HTTP 402 challenge/response flow:

1. You send a request to the gateway.
2. The server returns 402 Payment Required with a challenge containing the price, token, and recipient.
3. You sign a Tempo transaction matching the challenge.
4. You retry the request with the signed transaction as a credential in the Authorization header.
5. The server verifies the payment on-chain and returns the response with a Payment-Receipt header.

Supported networks

Network	Chain ID	RPC URL	Status
Tempo Mainnet	4217	https://rpc.tempo.xyz	Active
Tempo Testnet	42431	https://rpc.moderato.tempo.xyz	Active

Set TEMPO_TESTNET=true in your environment to use the testnet during development.

Plugin pricing

Each plugin has a fixed per-request price in USD, settled in pathUSD on Tempo.

Plugin	Price per request	Description
agent	$0.05	Agent orchestrator
generate-text	$0.01	LLM text generation
tts	$0.03	Text-to-speech synthesis
stt	$0.02	Speech-to-text transcription

Payment credential

After receiving a 402 challenge, build and sign a credential to send with your retry:

Authorization header format

Authorization: Payment <JSON credential>

Credential structure

{
  "scheme": "Payment",
  "transaction": "0x76...",
  "challengeNonce": "a1b2c3d4e5f6..."
}

Field	Type	Description
scheme	string	Always Payment
transaction	string	Hex-encoded signed Tempo transaction (prefixed with 0x76 type marker)
challengeNonce	string	The nonce value from the 402 challenge (replay protection)

402 challenge structure

When a payment is required, the server responds with:

{
  "error": "payment_required",
  "message": "Payment required for agent. Choose payment method: Stripe or Tempo MPP.",
  "mpp": {
    "scheme": "Payment",
    "amount": "0.05",
    "currency": "0x20c0000000000000000000000000000000000000",
    "recipient": "0xd8fd0e1dce89beaab924ac68098ddb17613db56f",
    "description": "Agent orchestrator request",
    "nonce": "a1b2c3d4e5f6...",
    "expiresAt": 1742472000000
  },
  "stripe": {
    "checkoutUrl": "/api/v1/payments/stripe/create?plugin=agent",
    "amount": "0.05",
    "currency": "usd"
  }
}

Challenge fields

Field	Type	Description
scheme	string	Always Payment
amount	string	Price in USD
currency	string	Token contract address (pathUSD)
recipient	string	Wallet address to pay
description	string	Human-readable description of the charge
nonce	string	Unique nonce for this challenge (used for replay protection)
expiresAt	number	Unix timestamp (ms) when the challenge expires. Challenges are valid for 5 minutes.

Verification

The server verifies your credential by checking:

1. The transaction is hex-encoded and starts with the 0x76 type marker.
2. The recipient address matches the expected recipient.
3. The token address matches the expected currency (pathUSD).
4. The amount matches the plugin price (within a 0.0001 tolerance).
5. The nonce matches the original challenge nonce.

If verification fails, the server returns an error with a description of the mismatch.

Receipt

On success, the server returns:

• A Payment-Receipt response header containing the transaction hash.
• The payment.receipt field in the JSON response body.

Client usage

Use mppFetch to handle the full 402 flow automatically:

import { mppFetch } from '@agentbot/sdk';

const result = await mppFetch({
  plugin: 'agent',
  body: { messages: [{ role: 'user', content: 'Hello' }] },
  privateKey: '0xYOUR_PRIVATE_KEY',
  baseUrl: 'https://agentbot.sh',
  testnet: false,
});

if (result.success) {
  console.log(result.data);
  console.log('Receipt:', result.receipt);
}

mppFetch options

Option	Type	Required	Default	Description
plugin	string	Yes	—	Plugin ID to call
body	object	Yes	—	Request body forwarded to the plugin
privateKey	string	Yes	—	Hex-encoded private key for signing Tempo transactions
baseUrl	string	No	https://agentbot.sh	Agentbot instance URL
stream	boolean	No	false	Request a streaming response
testnet	boolean	No	false	Use Tempo testnet instead of mainnet

mppFetch result

Field	Type	Description
success	boolean	Whether the request succeeded
data	object	Response body (non-streaming)
stream	ReadableStream	Response stream (streaming)
receipt	string	Payment receipt hash
error	string	Error message on failure

Check MPP support

You can check whether an endpoint supports MPP payments:

import { checkMppSupport } from '@agentbot/sdk';

const { supported } = await checkMppSupport(
  'https://agentbot.sh/api/v1/gateway'
);

The function sends an OPTIONS request and checks for a WWW-Authenticate: Payment header.

Sessions

Payment sessions provide off-chain, per-call billing without an on-chain transaction for every request. This reduces latency to sub-100ms per call while still settling on-chain periodically.

How sessions work

1. Open a session — deposit pathUSD (minimum $1.00, maximum$100.00) into escrow via POST /api/wallet/sessions.
2. Make gateway calls — include X-Session-Id and X-Wallet-Address headers on your gateway requests with X-Payment-Method: session. The gateway auto-debits your session balance using off-chain vouchers — no 402 round-trip needed.
3. Automatic settlement — when accumulated vouchers reach $5.00 or after one hour, the server batches them into a single on-chain transaction.
4. Close the session — call DELETE /api/wallet/sessions?sessionId=ses_... to settle any remaining vouchers and return unused funds.

You can also submit vouchers manually via POST /api/wallet/sessions/voucher if you need fine-grained control. When using the gateway with X-Payment-Method: session, voucher creation is handled automatically.

Session configuration

Parameter	Value	Description
Minimum deposit	$1.00	Minimum amount to open a session
Maximum deposit	$100.00	Maximum amount per session
Settle threshold	$5.00	Accumulated voucher total that triggers on-chain settlement
Settle interval	1 hour	Maximum time between on-chain settlements

Session states

State	Description
active	Session is open and accepting vouchers
settling	Vouchers are being settled on-chain (temporary)
closed	Session has been closed and remaining funds returned

Session initialization

When opening a session, you must provide a viem Account to the tempo.session() call. If no account is provided, the SDK throws immediately with a descriptive error message and an example fix. This prevents cryptic errors during channel close.

import { tempo } from 'mppx';
import { privateKeyToAccount } from 'viem/accounts';

// Correct — pass an Account object
const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY');
const session = tempo.session({ account });

// Incorrect — throws immediately with a helpful error
const session = tempo.session({}); // Error: No Account provided. Pass { account: privateKeyToAccount('0x...') }

Redis store for session state

By default, session state is stored in memory. For production deployments where you need persistence across restarts or across multiple server instances, use the Store.redis() adapter. It works with standard Redis clients including ioredis, node-redis, and Valkey.

import { Store } from 'mppx';
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);
const store = Store.redis(redis);

The Redis adapter handles BigInt serialization automatically, so session voucher amounts are stored and retrieved without data loss.

Use the Redis store in any environment where your server may restart or where you run multiple instances behind a load balancer. Without persistent storage, active sessions are lost on restart.

When to use sessions vs. per-request MPP

• Sessions are ideal for high-frequency agent calls where sub-100ms billing latency matters (e.g., chat, real-time orchestration).
• Per-request MPP (the standard 402 flow) is better for infrequent or large-value calls where on-chain settlement per request is acceptable.

See the Wallet API — MPP payment sessions reference for the full endpoint documentation.

Troubleshooting

402 response with no MPP challenge

The plugin may not have a configured price. Only plugins listed in the pricing table above support MPP payments.

Credential verification failed

• Ensure the challengeNonce matches the nonce from the 402 response.
• Verify the transaction amount matches the challenge amount exactly.
• Check that you are using the correct network (mainnet vs. testnet).

Transaction type error

The transaction hex must begin with 0x76 (the Tempo transaction type marker). Ensure your signing implementation includes this prefix.