# Squid MPP Adapter

AI agents and backend services can now accept and make payments across any EVM chain using the **Squid MPP adapter** — a [Machine Payments Protocol (MPP)](https://tempo.xyz) adapter powered by Squid to abstract away the complexity of cross-chain bridging.

Instead of managing bridges or writing complex multi-chain payment logic, developers can integrate the Squid MPP adapter to automatically handle bridging and paying for 402 resources in a single, seamless integration. Clients settle automatically by scanning their available balances across all Squid-supported EVM chains and routing through the Squid API to [Tempo mainnet](https://tempo.xyz).

***

### Features

* **Auto chain selection** — scans all Squid-supported EVM chains for available balances and picks the best source token automatically
* **Cross-chain bridging** — routes tokens from any supported chain to Tempo mainnet via Squid Router
* **HTTP 402 payment flow** — standard MPP challenge/credential cycle: server issues a challenge, client pays and retries with a credential

> **Info** The Squid MPP adapter currently supports **EVM chains only**.

***

### Getting Started

#### Requirements

* [**Node.js** ≥ 18](https://nodejs.org/en/download)
* A [**Squid Integrator ID**](https://squidrouter.typeform.com/integrator-id)

#### Server integration

Protect any HTTP endpoint so that only clients who have paid can access it. Install the [`mppx`](https://mpp.dev/sdk/typescript) library:

```bash
npm install mppx
```

Generate a secret key for credential signing:

```bash
openssl rand -hex 32
```

Add the output to your environment variables:

```env
MPP_SECRET_KEY=<output from above>
```

Add `mppx.charge()` as middleware on any route you want to gate. The `tempo()` method configures the settlement token and recipient on Tempo mainnet:

```ts
import { Mppx, tempo } from "mppx"

const mppx = Mppx.create({
  secretKey: process.env.MPP_SECRET_KEY!,
  methods: [
    tempo({
      currency: "0x20c0000000000000000000000000000000000000", // PathUSD on Tempo
      recipient: process.env.RECIPIENT_ADDRESS!
    })
  ]
})

// Protect any route — amount is in PathUSD units
app.get("/resource", mppx.charge({ amount: "0.01" }), c => {
  return c.json({ data: "secret content" })
})
```

Unauthenticated requests receive an HTTP 402 with the charge parameters. Requests that include a valid credential pass through to the handler.

Learn more about protecting endpoints with MPP at the official [MPP docs](https://mpp.dev/quickstart/server).

#### Client integration

Access any MPP-protected endpoint and pay from any supported EVM chain — no manual bridging required. Install `@0xsquid/mpp` alongside `mppx` and `viem`:

```bash
npm install @0xsquid/mpp mppx viem
```

You will need a funded agent wallet (USDC or any Squid-supported token on any supported chain) and your Squid Integrator ID.

```env
# Private key of the agent wallet
PRIVATE_KEY=0x...
```

Wrap your fetch calls with `Mppx.create()` using `squid()` as the payment method. When a 402 is received, the library handles the entire bridge flow:

```ts
import { privateKeyToAccount } from "viem/accounts"
import { Mppx } from "mppx"
import { squid } from "@0xsquid/mpp"

const account = privateKeyToAccount(process.env.PRIVATE_KEY! as `0x${string}`)

const { fetch: mppxFetch } = Mppx.create({
  polyfill: false,
  methods: [
    squid({
      account,
      integratorId: "your-integrator-id"
    })
  ]
})

const response = await mppxFetch("https://mpp-server.com/resource")
console.log(await response.json())
```

**`squid(config)` options**

| Option         | Type                                | Required | Description                                                                             |
| -------------- | ----------------------------------- | -------- | --------------------------------------------------------------------------------------- |
| `account`      | `Account`                           | Yes      | A [viem Account](https://viem.sh/docs/accounts/local) (e.g. from `privateKeyToAccount`) |
| `integratorId` | `string`                            | Yes      | Your Squid integrator ID                                                                |
| `onPayment`    | `(summary: PaymentSummary) => void` | No       | Callback fired after a successful payment with amount, token, and source chain info     |

Learn more about MPP clients at the official [MPP docs](https://mpp.dev/quickstart/client).

***

### Payment Flow

```
Client                Server              Squid API             Tempo Chain
  |                     |                     |                      |
  |-- GET /resource --> |                     |                      |
  |<- HTTP 402 -------- |                     |                      |
  |   { amount,         |                     |                      |
  |     currency,       |                     |                      |
  |     recipient }     |                     |                      |
  |                     |                     |                      |
  | [find optimal source token]               |                      |
  |                     |                     |                      |
  |-- get route quote ----------------------> |                      |
  |<- bridge route -------------------------- |                      |
  |                     |                     |                      |
  |-- submit bridge tx ---------------------> |                      |
  |-- poll bridge status -------------------> |                      |
  |                     |                     |-- pay on Tempo ----> |
  |                     |                     |<- payment tx hash -- |
  |<- payment tx hash ----------------------- |                      |
  |                     |                     |                      |
  |-- GET /resource --> |                     |                      |
  |   + credential      |-- verify tx -----------------------------> |
  |                     |<- payment confirmed ---------------------- |
  |<- 200 OK ---------- |                     |                      |
```