# Accept streamed payments \[Per-token billing over Server-Sent Events]
Build a payment-gated poetry API that streams poems word-by-word and charges $0.001 per word using `mppx` sessions with Server-Sent Events (SSE).
:::info
Streamed payments extend [pay-as-you-go sessions](/guides/pay-as-you-go) with SSE. The server charges per token as content streams—if the channel balance runs out mid-stream, the client automatically sends a new voucher and the stream resumes.
:::
## Demo
Try the live payment-gated poetry 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/streamed-payments.md as reference.
Add mppx to my app with a payment-gated SSE endpoint
that streams text word-by-word and charges $0.001 per word using the
Tempo session payment method with PathUSD and sse: true.`}
## 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 with streaming
Set up an `Mppx` instance with `sse: true` to enable SSE support on the session method.
```ts [app/api/sessions/poem/route.ts]
import { Mppx, tempo } from 'mppx/nextjs'
export const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
sse: true,
})],
})
```
#### Create the `/api/sessions/poem` route
Create the poem route. The `withReceipt` method accepts an async generator—each yielded value is one SSE event and one charged word.
```ts [app/api/sessions/poem/route.ts]
import { Mppx, tempo } from 'mppx/nextjs'
export const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
sse: true,
})],
})
// [!code focus:start]
const poem = {
title: 'The Road Not Taken',
author: 'Robert Frost',
lines: [
'Two roads diverged in a yellow wood,',
'And sorry I could not travel both',
'And be one traveler, long I stood',
'And looked down one as far as I could',
'To where it bent in the undergrowth;',
],
}
export const GET =
mppx.session({ amount: '0.001', unitType: 'word' })
(async () => {
const words = poem.lines.flatMap(line => [...line.split(' '), '\\n'])
return async function* (stream) {
yield JSON.stringify({ title: poem.title, author: poem.author })
for (const word of words) {
await stream.charge()
yield word
}
}
})
// [!code focus:end]
```
#### Test via the `mppx` CLI
```bash
# Create account funded with testnet tokens
$ npx mppx account create
# Stream a paid poem
$ npx mppx http://localhost:3000/api/sessions/poem
```
::::
::::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 with streaming
Set up an `Mppx` instance with `sse: true` to enable SSE support on the session method.
```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',
sse: true,
})],
})
```
#### Create the `/api/sessions/poem` route
Create the poem route with the session middleware. The handler returns an async generator—each yielded value is one SSE event and one charged word.
```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',
sse: true,
})],
})
// [!code focus:start]
const poem = {
title: 'The Road Not Taken',
author: 'Robert Frost',
lines: [
'Two roads diverged in a yellow wood,',
'And sorry I could not travel both',
'And be one traveler, long I stood',
'And looked down one as far as I could',
'To where it bent in the undergrowth;',
],
}
app.get(
'/api/sessions/poem',
mppx.session({ amount: '0.001', unitType: 'word' }),
async (c) => {
const words = poem.lines.flatMap(line => [...line.split(' '), '\\n'])
return async function* (stream) {
yield JSON.stringify({ title: poem.title, author: poem.author })
for (const word of words) {
await stream.charge()
yield word
}
}
},
)
// [!code focus:end]
```
#### Test via the `mppx` CLI
```bash
# Create account funded with testnet tokens
$ npx mppx account create
# Stream a paid poem
$ npx mppx http://localhost:3000/api/sessions/poem
```
::::
::::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 with streaming
Set up an `Mppx` instance with `sse: true` to enable SSE support on the session method.
```ts [src/index.ts]
import { Mppx, tempo } from 'mppx/server'
const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
sse: true,
})],
})
```
#### Create the `/api/sessions/poem` route
Create the poem route. The `withReceipt` method accepts an async generator—each yielded value is one SSE event and one charged word.
```ts [src/index.ts]
import { Mppx, tempo } from 'mppx/server'
const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
sse: true,
})],
})
// [!code focus:start]
const poem = {
title: 'The Road Not Taken',
author: 'Robert Frost',
lines: [
'Two roads diverged in a yellow wood,',
'And sorry I could not travel both',
'And be one traveler, long I stood',
'And looked down one as far as I could',
'To where it bent in the undergrowth;',
],
}
export default {
async fetch(request: Request) {
const result = await mppx.session({
amount: '0.001',
unitType: 'word',
})(request)
if (result.status === 402) return result.challenge
const words = poem.lines.flatMap(line => [...line.split(' '), '\\n'])
return result.withReceipt(async function* (stream) {
yield JSON.stringify({ title: poem.title, author: poem.author })
for (const word of words) {
await stream.charge()
yield word
}
})
},
}
// [!code focus:end]
```
#### Test via the `mppx` CLI
```bash
# Create account funded with testnet tokens
$ npx mppx account create
# Stream a paid poem
$ 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 with streaming
Set up an `Mppx` instance with `sse: true` to enable SSE support on the session method.
```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',
sse: true,
})],
})
```
#### Create the `/api/sessions/poem` route
Create the poem route with the session middleware. The handler returns an async generator—each yielded value is one SSE event and one charged word.
```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',
sse: true,
})],
})
// [!code focus:start]
const poem = {
title: 'The Road Not Taken',
author: 'Robert Frost',
lines: [
'Two roads diverged in a yellow wood,',
'And sorry I could not travel both',
'And be one traveler, long I stood',
'And looked down one as far as I could',
'To where it bent in the undergrowth;',
],
}
app.get(
'/api/sessions/poem',
mppx.session({ amount: '0.001', unitType: 'word' }),
async (req, res) => {
const words = poem.lines.flatMap(line => [...line.split(' '), '\\n'])
return async function* (stream) {
yield JSON.stringify({ title: poem.title, author: poem.author })
for (const word of words) {
await stream.charge()
yield word
}
}
},
)
// [!code focus:end]
```
#### Test via the `mppx` CLI
```bash
# Create account funded with testnet tokens
$ npx mppx account create
# Stream a paid poem
$ npx mppx http://localhost:3000/api/sessions/poem
```
::::
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 with streaming
Set up an `Mppx` instance with `sse: true` to enable SSE support on the session method.
```ts [server.ts]
import { Mppx, tempo } from 'mppx/server'
const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
sse: true,
})],
})
```
#### Create the streaming poem route
Create the route handler. `withReceipt` accepts an async generator—each yielded value becomes one SSE `event: message` and is charged one tick (`$0.001`). If the channel balance runs out mid-stream, the server emits `event: payment-need-voucher` and pauses until the client sends a new voucher.
```ts [server.ts]
import { Mppx, tempo } from 'mppx/server'
const mppx = Mppx.create({
methods: [tempo({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0xa726a1CD723409074DF9108A2187cfA19899aCF8',
sse: true,
})],
})
// [!code focus:start]
const poem = {
title: 'The Road Not Taken',
author: 'Robert Frost',
lines: [
'Two roads diverged in a yellow wood,',
'And sorry I could not travel both',
'And be one traveler, long I stood',
'And looked down one as far as I could',
'To where it bent in the undergrowth;',
],
}
Bun.serve({
async fetch(request) {
const result = await mppx.session({
amount: '0.001',
unitType: 'word',
})(request)
if (result.status === 402) return result.challenge
const words = poem.lines.flatMap(line => [...line.split(' '), '\\n'])
return result.withReceipt(async function* (stream) {
yield JSON.stringify({ title: poem.title, author: poem.author })
for (const word of words) {
await stream.charge()
yield word
}
})
},
})
// [!code focus:end]
```
#### Test via the `mppx` CLI
```bash
# Create account funded with testnet tokens
$ npx mppx account create
# Stream a paid poem
$ npx mppx http://localhost:3000
```
::::
## Client setup
Use `tempo.session()` from `mppx/client` to create a session manager. The `.sse()` method connects to the SSE endpoint and handles voucher renewal automatically—if the server requests a new voucher mid-stream, the client signs and sends one without interrupting the stream.
```ts [client.ts]
import { tempo } from 'mppx/client'
import { privateKeyToAccount } from 'viem/accounts'
const session = tempo.session({
account: privateKeyToAccount('0x...'),
maxDeposit: '1', // Lock up to 1 pathUSD per channel
})
// .sse() returns an async iterable of SSE data payloads
const stream = await session.sse('http://localhost:3000/api/sessions/poem')
for await (const word of stream) {
process.stdout.write(word + ' ')
}
```
* **`tempo.session()`** — Creates a session manager that handles the full channel lifecycle: open, voucher signing, and close.
* **`.sse()`** — Connects to an SSE endpoint. Automatically sends new vouchers when the server emits `payment-need-voucher` events.
* **`maxDeposit: '1'`** — Locks up to 1 pathUSD. At $0.001/word, this covers ~1,000 words before the channel needs a top-up.
## Next steps