# 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 payment-gated poetry API. Click **Run demo** to create a wallet, fund it, and stream a paid poem.
## Prompt mode
Paste this into your coding agent to build the entire guide in one prompt:
{`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: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
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: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
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 [terminal]
# 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: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
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: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
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 [terminal]
# 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: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
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: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
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 [terminal]
# 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: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
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: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
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 [terminal]
# 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: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
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: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
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 [terminal]
# 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.
### Closing the channel
After streaming completes, close the channel to settle and reclaim unspent deposit:
```ts twoslash [client.ts]
import { tempo } from 'mppx/client'
import { privateKeyToAccount } from 'viem/accounts'
const session = tempo.session({
account: privateKeyToAccount('0x...'),
maxDeposit: '1',
})
const stream = await session.sse('http://localhost:3000/api/sessions/poem')
for await (const word of stream) {
process.stdout.write(word + ' ')
}
// Settle on-chain and reclaim unspent deposit
const receipt = await session.close()
```
## Next steps