<!-- tempo-docs-context -->
> Source: [/docs/guide/machine-payments/x402-facilitator](https://tempo.com/developers/docs/guide/machine-payments/x402-facilitator.md)
> Section: [Machine Payments](https://tempo.com/developers/docs/agents.md). Pay for APIs, accept API payments over MPP or x402, find services, and use MPP (https://mpp.dev).
> [Documentation index](https://tempo.com/developers/llms.txt) · [Docs skill](https://tempo.com/developers/SKILL.md)

> Tempo MCP: Use `search`, `find_pages`, `read_page`, and `code` at `https://mcp.tempo.xyz` for Tempo and related documentation.
> If an indexed page is missing or reflects an older site, read this site’s [documentation index](https://tempo.com/developers/llms.txt) and Markdown pages directly.

# Tempo x402 facilitator

Keep selling over [x402](https://x402.org) and get paid in stablecoins on Tempo. Point your x402 middleware at Tempo's facilitator: buyers pay USDC on Base as usual, and each payment arrives as OUSD at your Tempo address.

* **No change for buyers.** Any x402 client pays, such as `@x402/fetch` or `mppx`.
* **No registration.** An API key and a payout address in `extra.tempoSettlement` are all you need.
* **No minimum.** Price routes at any amount above 0, up to the maximum per payment that Tempo sets.

```mermaid
sequenceDiagram
  participant Buyer
  participant Seller as Your server
  participant Tempo as Tempo facilitator
  Buyer->>Seller: Request resource
  Seller-->>Buyer: 402 Payment Required
  Buyer->>Seller: Retry with signed USDC
  Seller->>Tempo: Verify and settle
  Note over Tempo: Settle USDC on Base, send OUSD on Tempo
  Tempo-->>Seller: Base and Tempo hashes
  Seller-->>Buyer: Resource
```

## Supported payment networks

| Direction | Network | Chain ID | Token | Schemes |
| --- | --- | --- | --- | --- |
| Pay in | Base mainnet | `eip155:8453` | [USDC](https://basescan.org/token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) | `exact` (EIP-3009 or Permit2) |
| Pay out | Tempo mainnet | `eip155:4217` | [OUSD](https://explore.tempo.xyz/address/0x20c0000000000000000000006a37da5c996874be) | — |

Testnet: use `https://api.tempo-dev.workers.dev/v1/x402` with a sandbox key (Base Sepolia USDC in, Moderato OUSD out).

## Accept x402 payments on Tempo

:::steps
### Create an API key

Create an API key in [Tempo Console](https://tempo.com/console?to=/\:org/api-keys) with the `mpp:write` scope, and keep it on your server.

```bash [Terminal]
export TEMPO_API_KEY="tempo:sk:..."
export TEMPO_PAYOUT_ADDRESS="0x..." # any Tempo address you control
export MPP_SECRET_KEY=$(openssl rand -hex 32) # mppx and pympp only
```

### Point your middleware at Tempo

Use `tempoX402()` from `mppx` with the x402 SDK. It points the SDK at `https://api.tempo.xyz/v1/x402` with your API key, pays to Tempo's deposit address, and names your payout address in `extra.tempoSettlement`.

```bash [Terminal]
npm i mppx @x402/core @x402/evm @x402/hono hono
```

```ts [server.ts]
import { paymentMiddleware } from '@x402/hono'
import { Hono } from 'hono'
import { tempoX402 } from 'mppx/x402/tempo'

const tempo = tempoX402() // reads TEMPO_API_KEY and TEMPO_PAYOUT_ADDRESS // [!code hl]

const app = new Hono()

app.use(paymentMiddleware({ 'GET /weather': tempo.route({ price: '$0.01' }) }, tempo.server)) // [!code hl]

app.get('/weather', (c) => c.json({ forecast: 'sunny' }))

export default app
```

Using another framework or SDK:

### Next.js

```bash [Terminal]
npm i mppx @x402/core @x402/evm @x402/next
```

```ts [app/weather/route.ts]
import { withX402 } from '@x402/next'
import { tempoX402 } from 'mppx/x402/tempo'
import { NextResponse } from 'next/server'

const tempo = tempoX402()

export const GET = withX402(
  async () => NextResponse.json({ forecast: 'sunny' }),
  tempo.route({ price: '$0.01' }), // [!code hl]
  tempo.server,
)
```

### Express

```bash [Terminal]
npm i mppx @x402/core @x402/evm @x402/express express
```

```ts [server.ts]
import { paymentMiddleware } from '@x402/express'
import express from 'express'
import { tempoX402 } from 'mppx/x402/tempo'

const tempo = tempoX402()

const app = express()

app.use(paymentMiddleware({ 'GET /weather': tempo.route({ price: '$0.01' }) }, tempo.server)) // [!code hl]

app.get('/weather', (req, res) => {
  res.json({ forecast: 'sunny' })
})

app.listen(4021)
```

### mppx

```bash [Terminal]
npm i mppx hono
```

```ts [server.ts]
import { Hono } from 'hono'
import { Mppx, evm } from 'mppx/hono'

const facilitator = 'https://api.tempo.xyz/v1/x402'

const mppx = Mppx.create({
  methods: [
    evm.charge({
      currency: evm.assets.base.USDC,
      // [!code hl:start]
      // Tempo's deposit address on Base, read from GET /supported at startup
      recipient: await evm.facilitatorPayTo(facilitator, { network: 'eip155:8453' }),
      x402: {
        extra: { tempoSettlement: process.env.TEMPO_PAYOUT_ADDRESS! },
        facilitator,
        headers: { 'tempo-api-key': process.env.TEMPO_API_KEY! },
        routeBinding: 'resource', // accept any x402 client
      },
      // [!code hl:end]
    }),
  ],
})

const app = new Hono()

app.get('/weather', mppx.evm.charge({ amount: '0.01' }), (c) => c.json({ forecast: 'sunny' }))

export default app
```

### Python

```bash [Terminal]
pip install "pympp[x402]" uvicorn
```

```python [main.py]
import os

import httpx
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

from mpp import Credential, Receipt
from mpp.methods.evm import BASE_USDC
from mpp.methods.evm import server as evm
from mpp.server import Mpp, pay
from mpp.x402 import HttpFacilitator

FACILITATOR_URL = "https://api.tempo.xyz/v1/x402"

# [!code hl:start]
facilitator = HttpFacilitator(
    FACILITATOR_URL,
    headers={"tempo-api-key": os.environ["TEMPO_API_KEY"]},
)

# Tempo's deposit address on Base, read from GET /supported at startup
kinds = httpx.get(f"{FACILITATOR_URL}/supported").raise_for_status().json()["kinds"]
deposit_address = next(k["extra"]["payTo"] for k in kinds if k["network"] == "eip155:8453")
# [!code hl:end]

mpp = Mpp(
    methods=evm.charge(
        currency=BASE_USDC,
        # [!code hl:start]
        recipient=deposit_address,
        facilitator=facilitator,
        x402_extra={"tempoSettlement": os.environ["TEMPO_PAYOUT_ADDRESS"]},
        route_binding="resource",  # accept any x402 client
        # [!code hl:end]
    ),
)

app = FastAPI()


@app.get("/weather")
@pay(mpp.charge(amount="0.01"))
async def weather(request: Request, credential: Credential, receipt: Receipt) -> JSONResponse:
    return JSONResponse({"forecast": "sunny"})
```

* `payTo` is Tempo's deposit address on Base, from the public `GET /v1/x402/supported`. `tempoX402()` and `evm.facilitatorPayTo()` read it for you when the server starts (`facilitator_pay_to()` does the same from async code in Python), so there's no address to copy into your environment.
* A route can send its payout to its own address, such as a platform's seller: `tempo.route({ price: '$0.10', payoutAddress: seller.tempoAddress })`.
* `mppx` and `pympp` need `routeBinding: 'resource'` (`route_binding="resource"`) to accept buyers that use the x402 SDK.
:::

## Check the payout

Settle waits for the Base receipt, then returns the Base hash in `transaction` and the Tempo payout in `extensions.tempoSettlement`:

```json
{
  "success": true,
  "transaction": "0x<BASE_HASH>",
  "network": "eip155:8453",
  "extensions": {
    "tempoSettlement": {
      "status": "pending",
      "amount": "10000",
      "to": "<TEMPO_PAYOUT_ADDRESS>",
      "payoutId": "x402pay_..."
    }
  }
}
```

The OUSD arrives a few minutes later, once Base is final: poll `GET /v1/x402/payouts/{payoutId}` until `status` is `confirmed`.

## Tempo x402 facilitator API

Base URL: `https://api.tempo.xyz/v1/x402`. Send the API key in the `tempo-api-key` header.

| Route | Auth | Description |
| --- | --- | --- |
| `GET /supported` | Public | Networks and the deposit address (`extra.payTo`) |
| `POST /verify` | `mpp:write` | Checks a payment without settling it |
| `POST /settle` | `mpp:write` | Settles on Base and sends the Tempo payout |
| `GET /payouts/{id}` | `mpp:write` | A payout: `pending`, `submitted`, `confirmed`, or `failed` |
| `GET /settlements/{transaction}` | `mpp:write` | The same payout, by its Base hash |

## Errors you can fix

Verify and settle answer HTTP `200` with `isValid: false` or `success: false` and a reason:

| Reason | Fix |
| --- | --- |
| `payto_not_deposit_address` | Pay to `extra.payTo` from `GET /supported`. |
| `missing_tempo_settlement` | Set `extra.tempoSettlement` to a valid Tempo address. |
| `amount_above_maximum` | Lower the route's price. |
| `settlement_pending` | Retry settle with the same payload. Buyers resend the same signed payment. It never pays twice. |
| HTTP `429` | Settle is rate-limited per API key. Retry after `Retry-After`. |
