# Accept pay-as-you-go payments \[Session-based billing with payment channels]
Build a payment-gated photo gallery API that charges $0.01 per photo using `mppx` sessions.
The server returns random photos from [Picsum](https://picsum.photos) behind a paywall,
but you could imagine generating images with an AI model instead like [OpenAI Image Generation](https://developers.openai.com/api/reference/resources/images).
:::info
Unlike [one-time payments](/guides/one-time-payments), sessions open a payment channel once and
use offchain vouchers for each subsequent request—vouchers are **not bottlenecked by blockchain throughput**, they are processed in pure CPU-bound signature checks.
:::
## Demo
Try the live payment-gated photo gallery API running in this command line interface.
## Prompt mode
Paste this into your coding agent to build the entire guide in one shot:
{`Use https://mpp.dev/guides/pay-as-you-go.md as reference.
Add mppx to my app with a payment-gated gallery endpoint
that charges $0.01 per photo using the Tempo session payment method with
PathUSD. When payment is verified, fetch a random photo from
https://picsum.photos/200/200 and return the URL as JSON.`}
## Manual mode
Select your framework to follow a step-by-step guide. If your framework isn't listed, choose **Other** for a generic [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) approach compatible with most TypeScript server frameworks.
::::steps
#### Install `mppx`
:::code-group
```bash [npm]
npm install mppx viem
```
```bash [pnpm]
pnpm add mppx viem
```
```bash [bun]
bun add mppx viem
```
:::
#### Set up `Mppx` instance
Set up an `Mppx` instance with the `tempo` method.
* `recipient` is the address where you receive payments.
* `currency` is the token address for payments (in this case, `pathUSD`).
```ts [app/api/sessions/photo/route.ts]
import { Mppx, tempo } from 'mppx/nextjs'
export const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
})],
})
```
#### Create the `/api/sessions/photo` route
Create the gallery route. This route is **currently unpaid**.
```ts [app/api/sessions/photo/route.ts]
import { Mppx, tempo } from 'mppx/nextjs'
export const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
})],
})
// [!code focus:start]
export const GET = async () => {
const res = await fetch('https://picsum.photos/200/200')
return Response.json({ url: res.url })
}
// [!code focus:end]
```
#### Add `.session` to the route handler
Add payment verification using `mppx.session` as route middleware.
The handler runs only after payment is verified.
```ts [app/api/sessions/photo/route.ts]
import { Mppx, tempo } from 'mppx/nextjs'
export const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
})],
})
// [!code focus:start]
export const GET =
mppx.session({ amount: '0.01', unitType: 'photo' }) // [!code ++]
(async () => {
const res = await fetch('https://picsum.photos/200/200')
return Response.json({ url: res.url })
})
// [!code focus:end]
```
#### Test via the `mppx` CLI
```bash
# Create account funded with testnet tokens
$ npx mppx account create
# Make a paid request
$ npx mppx http://localhost:3000/api/sessions/photo
```
::::
::::steps
#### Install `mppx` and `hono`
:::code-group
```bash [npm]
npm install mppx hono viem
```
```bash [pnpm]
pnpm add mppx hono viem
```
```bash [bun]
bun add mppx hono viem
```
:::
#### Set up `Mppx` instance
Set up an `Mppx` instance with the `tempo` method.
* `recipient` is the address where you receive payments.
* `currency` is the token address for payments (in this case, `pathUSD`).
```ts [server.ts]
import { Hono } from 'hono'
import { Mppx, tempo } from 'mppx/hono'
const app = new Hono()
const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
})],
})
```
#### Create the `/api/sessions/photo` route
Create the gallery route. This route is **currently unpaid**.
```ts [server.ts]
import { Hono } from 'hono'
import { Mppx, tempo } from 'mppx/hono'
const app = new Hono()
const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
})],
})
// [!code focus:start]
app.get('/api/sessions/photo', async (c) => {
const res = await fetch('https://picsum.photos/200/200')
return c.json({ url: res.url })
})
// [!code focus:end]
```
#### Add `.session` to the route handler
Add payment verification using `mppx.session` as route middleware.
The handler runs only after payment is verified.
```ts [server.ts]
import { Hono } from 'hono'
import { Mppx, tempo } from 'mppx/hono'
const app = new Hono()
const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
})],
})
// [!code focus:start]
app.get(
'/api/sessions/photo',
mppx.session({ amount: '0.01', unitType: 'photo' }), // [!code ++]
async (c) => {
const res = await fetch('https://picsum.photos/200/200')
return c.json({ url: res.url })
},
)
// [!code focus:end]
```
#### Test via the `mppx` CLI
```bash
# Create account funded with testnet tokens
$ npx mppx account create
# Make a paid request
$ npx mppx http://localhost:3000/api/sessions/photo
```
::::
::::steps
#### Install `mppx`
:::code-group
```bash [npm]
npm install mppx viem
```
```bash [pnpm]
pnpm add mppx viem
```
```bash [bun]
bun add mppx viem
```
:::
#### Set up `Mppx` instance
Set up an `Mppx` instance with the `tempo` method.
* `recipient` is the address where you receive payments.
* `currency` is the token address for payments (in this case, `pathUSD`).
```ts [src/index.ts]
import { Mppx, tempo } from 'mppx/server'
const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
})],
})
```
#### Create the gallery route
Create the gallery route. This route is **currently unpaid**.
```ts [src/index.ts]
import { Mppx, tempo } from 'mppx/server'
const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
})],
})
// [!code focus:start]
export default {
async fetch(request: Request) {
const res = await fetch('https://picsum.photos/200/200')
return Response.json({ url: res.url })
},
}
// [!code focus:end]
```
#### Add `.session` to the route handler
Add payment verification using `mppx.session`. If the status is `402`, return the Challenge. Otherwise, fetch the photo and attach a Receipt to the response.
```ts [src/index.ts]
import { Mppx, tempo } from 'mppx/server'
const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
})],
})
// [!code focus:start]
export default {
async fetch(request: Request) {
const result = await mppx.session({ // [!code ++]
amount: '0.01', // [!code ++]
unitType: 'photo', // [!code ++]
})(request) // [!code ++]
if (result.status === 402) return result.challenge // [!code ++]
const res = await fetch('https://picsum.photos/200/200')
return result.withReceipt(Response.json({ url: res.url })) // [!code ++]
},
}
// [!code focus:end]
```
#### Test via the `mppx` CLI
```bash
# Create account funded with testnet tokens
$ npx mppx account create
# Make a paid request
$ npx mppx http://localhost:8787
```
::::
::::steps
#### Install `mppx` and `express`
:::code-group
```bash [npm]
npm install mppx express viem
```
```bash [pnpm]
pnpm add mppx express viem
```
```bash [bun]
bun add mppx express viem
```
:::
#### Set up `Mppx` instance
Set up an `Mppx` instance with the `tempo` method.
* `recipient` is the address where you receive payments.
* `currency` is the token address for payments (in this case, `pathUSD`).
```ts [server.ts]
import express from 'express'
import { Mppx, tempo } from 'mppx/express'
const app = express()
const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
})],
})
```
#### Create the `/api/sessions/photo` route
Create the gallery route. This route is **currently unpaid**.
```ts [server.ts]
import express from 'express'
import { Mppx, tempo } from 'mppx/express'
const app = express()
const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
})],
})
// [!code focus:start]
app.get('/api/sessions/photo', async (req, res) => {
const response = await fetch('https://picsum.photos/200/200')
res.json({ url: response.url })
})
// [!code focus:end]
```
#### Add `.session` to the route handler
Add payment verification using `mppx.session` as route middleware.
The handler runs only after payment is verified.
```ts [server.ts]
import express from 'express'
import { Mppx, tempo } from 'mppx/express'
const app = express()
const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
})],
})
// [!code focus:start]
app.get(
'/api/sessions/photo',
mppx.session({ amount: '0.01', unitType: 'photo' }), // [!code ++]
async (req, res) => {
const response = await fetch('https://picsum.photos/200/200')
res.json({ url: response.url })
},
)
// [!code focus:end]
```
#### Test via the `mppx` CLI
```bash
# Create account funded with testnet tokens
$ npx mppx account create
# Make a paid request
$ npx mppx http://localhost:3000/api/sessions/photo
```
::::
This guide walks through using `mppx/server` directly with any [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)-compatible framework: [Bun](https://bun.sh), [Deno](https://deno.com), [Cloudflare Workers](https://workers.dev), and others.
::::steps
#### Install `mppx`
:::code-group
```bash [npm]
npm install mppx viem
```
```bash [pnpm]
pnpm add mppx viem
```
```bash [bun]
bun add mppx viem
```
:::
#### Set up `Mppx` instance
Set up an `Mppx` instance with the `tempo` method.
* `recipient` is the address where you receive payments.
* `currency` is the token address for payments (in this case, `pathUSD`).
```ts [server.ts]
import { Mppx, tempo } from 'mppx/server'
const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
})],
})
```
#### Create the `/api/sessions/photo` route
Create the gallery route. This route is **currently unpaid**.
```ts [server.ts]
import { Mppx, tempo } from 'mppx/server'
const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
})],
})
// [!code focus:start]
Bun.serve({
async fetch(request) {
const res = await fetch('https://picsum.photos/200/200')
return Response.json({ url: res.url })
},
})
// [!code focus:end]
```
#### Add `.session` to the route handler
Add payment verification using `mppx.session`. If the status is `402`, return the Challenge. Otherwise, fetch the photo and attach a Receipt to the response.
```ts [server.ts]
import { Mppx, tempo } from 'mppx/server'
const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
})],
})
// [!code focus:start]
Bun.serve({
async fetch(request) {
const result = await mppx.session({ // [!code ++]
amount: '0.01', // [!code ++]
unitType: 'photo', // [!code ++]
})(request) // [!code ++]
if (result.status === 402) return result.challenge // [!code ++]
const res = await fetch('https://picsum.photos/200/200')
return result.withReceipt(Response.json({ url: res.url })) // [!code ++]
},
})
// [!code focus:end]
```
#### Test via the `mppx` CLI
```bash
# Create account funded with testnet tokens
$ npx mppx account create
# Make a paid request
$ npx mppx http://localhost:3000
```
::::
## Client setup
When using sessions from a client, set `maxDeposit` to enable automatic channel management. This is the maximum amount of tokens the client locks into the payment channel's escrow contract. Any unspent deposit is refunded when the channel closes.
```ts [client.ts]
import { Mppx, tempo } from 'mppx/client'
import { privateKeyToAccount } from 'viem/accounts'
const mppx = Mppx.create({
methods: [tempo({
account: privateKeyToAccount('0x...'),
maxDeposit: '1', // Lock up to 1 pathUSD per channel
})],
})
// Each fetch automatically manages the session lifecycle:
// 1st request: opens channel on-chain, sends initial voucher
// 2nd+ requests: sends off-chain vouchers (no on-chain tx)
const res = await fetch('http://localhost:3000/api/sessions/photo')
```
* **`maxDeposit: '1'`** — Locks up to 1 pathUSD into the payment channel. At $0.01/photo, this covers up to 100 requests before the channel runs out.
* The client handles the full session lifecycle automatically: channel open, voucher signing, and retry after `402` responses.
* If the server sets `suggestedDeposit`, the client uses `min(suggestedDeposit, maxDeposit)`.
## Next steps