MPP Session Flow (Streaming Payments)
Before writing code
Fetch live docs:
- Fetch
https://www.npmjs.com/package/mppx for the session middleware API and payment channel configuration
- Fetch
https://paymentauth.org/ for the canonical session intent specification
- Web-search
mpp session streaming micropayments payment channel for session implementation patterns
- Web-search
site:mpp.dev session for session-specific documentation
Conceptual Architecture
What Session Intent Is
The session intent implements streaming micropayments — often described as "OAuth for money". The agent authorizes a spending limit upfront, then streams micropayments continuously as it consumes resources:
1. Client opens session with spending cap
2. Server creates payment channel
3. Client makes requests — each deducts from the spending cap
4. Micropayments stream at sub-cent costs, sub-millisecond latency
5. Session closes — final settlement on-chain (single transaction)
When to Use Session
- Per-token billing — LLM inference charged per token generated
- Continuous data feeds — Real-time market data, sensor streams
- Compute metering — Pay for actual CPU/GPU seconds used
- Bandwidth metering — Pay per KB transferred
- Any high-frequency, low-value access pattern
Session vs Charge Comparison
| Dimension |
Charge |
Session |
| Settlement |
Per-request on-chain/card |
Aggregated at session close |
| Latency |
Includes payment settlement per call |
Sub-millisecond after session open |
| Cost |
One tx per request |
One tx for entire session |
| Pricing |
Fixed per request |
Variable, metered |
| Use case |
Infrequent, high-value calls |
Frequent, low-value calls |
Server-Side Implementation
// Protect a route with a session payment gate
app.get('/api/stream', mppx.session({ maxAmount: '10000' }), async (c) => {
// Deducts from the session's spending cap
return c.json({ data: 'streaming content' });
});
Session Lifecycle
- Open — Client sends initial request; server returns 402 with session challenge
- Authorize — Client authorizes spending cap (e.g., 10,000 units)
- Active — Client makes requests; each deducts from the cap
- Refill — Client can extend the cap before it runs out
- Close — Either party closes; final settlement happens on-chain
- Settled — Single on-chain transaction for the total consumed amount
Payment Channel
Session payments use a payment channel — an off-chain mechanism where:
- Funds are locked upfront in a channel
- Each micropayment updates the channel state without on-chain transactions
- Only the opening and closing transactions go on-chain
- This enables thousands of sub-cent payments at sub-millisecond latency
Spending Cap Management
- Agent sets the maximum they're willing to spend in the session
- Server deducts from this cap per request/unit consumed
- Agent can monitor remaining balance
- If cap is exhausted, server returns 402 for a new session
- Agent can proactively extend the cap
Metering Patterns
| Pattern |
Description |
| Fixed per request |
Each request costs a fixed amount |
| Per-unit |
Cost varies by units consumed (tokens, bytes, seconds) |
| Time-based |
Cost accrues per time interval |
| Tiered |
Rate decreases with volume (first 100 at $X, next 1000 at $Y) |
Best Practices
- Set reasonable default spending caps (not too high for safety, not too low for UX)
- Implement cap exhaustion warnings before the cap runs out
- Log metering data for billing reconciliation
- Handle session interruptions gracefully (network drops, server restarts)
- Implement session resumption where possible
- Monitor session durations and spending patterns for pricing optimization
Fetch the latest mppx SDK documentation and MPP specification for exact session API, payment channel mechanics, and configuration options before implementing.
1---2name: mpp-session-flow3description: Implement MPP session-based streaming payment flows — authorize-once pay-as-you-go patterns for continuous data feeds, per-token billing, and micropayment aggregation. Use when building streaming APIs or services that charge incrementally.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/mpp-session-flow7---89# MPP Session Flow (Streaming Payments)1011## Before writing code1213**Fetch live docs**:141. Fetch `https://www.npmjs.com/package/mppx` for the session middleware API and payment channel configuration152. Fetch `https://paymentauth.org/` for the canonical session intent specification163. Web-search `mpp session streaming micropayments payment channel` for session implementation patterns174. Web-search `site:mpp.dev session` for session-specific documentation1819## Conceptual Architecture2021### What Session Intent Is2223The session intent implements **streaming micropayments** — often described as **"OAuth for money"**. The agent authorizes a spending limit upfront, then streams micropayments continuously as it consumes resources:2425```261. Client opens session with spending cap272. Server creates payment channel283. Client makes requests — each deducts from the spending cap294. Micropayments stream at sub-cent costs, sub-millisecond latency305. Session closes — final settlement on-chain (single transaction)31```3233### When to Use Session3435- **Per-token billing** — LLM inference charged per token generated36- **Continuous data feeds** — Real-time market data, sensor streams37- **Compute metering** — Pay for actual CPU/GPU seconds used38- **Bandwidth metering** — Pay per KB transferred39- **Any high-frequency, low-value access pattern**4041### Session vs Charge Comparison4243| Dimension | Charge | Session |44|-----------|--------|---------|45| Settlement | Per-request on-chain/card | Aggregated at session close |46| Latency | Includes payment settlement per call | Sub-millisecond after session open |47| Cost | One tx per request | One tx for entire session |48| Pricing | Fixed per request | Variable, metered |49| Use case | Infrequent, high-value calls | Frequent, low-value calls |5051### Server-Side Implementation5253```typescript54// Protect a route with a session payment gate55app.get('/api/stream', mppx.session({ maxAmount: '10000' }), async (c) => {56 // Deducts from the session's spending cap57 return c.json({ data: 'streaming content' });58});59```6061### Session Lifecycle62631. **Open** — Client sends initial request; server returns 402 with session challenge642. **Authorize** — Client authorizes spending cap (e.g., 10,000 units)653. **Active** — Client makes requests; each deducts from the cap664. **Refill** — Client can extend the cap before it runs out675. **Close** — Either party closes; final settlement happens on-chain686. **Settled** — Single on-chain transaction for the total consumed amount6970### Payment Channel7172Session payments use a **payment channel** — an off-chain mechanism where:73- Funds are locked upfront in a channel74- Each micropayment updates the channel state without on-chain transactions75- Only the opening and closing transactions go on-chain76- This enables thousands of sub-cent payments at sub-millisecond latency7778### Spending Cap Management7980- Agent sets the maximum they're willing to spend in the session81- Server deducts from this cap per request/unit consumed82- Agent can monitor remaining balance83- If cap is exhausted, server returns 402 for a new session84- Agent can proactively extend the cap8586### Metering Patterns8788| Pattern | Description |89|---------|-------------|90| Fixed per request | Each request costs a fixed amount |91| Per-unit | Cost varies by units consumed (tokens, bytes, seconds) |92| Time-based | Cost accrues per time interval |93| Tiered | Rate decreases with volume (first 100 at $X, next 1000 at $Y) |9495### Best Practices9697- Set reasonable default spending caps (not too high for safety, not too low for UX)98- Implement cap exhaustion warnings before the cap runs out99- Log metering data for billing reconciliation100- Handle session interruptions gracefully (network drops, server restarts)101- Implement session resumption where possible102- Monitor session durations and spending patterns for pricing optimization103104Fetch the latest mppx SDK documentation and MPP specification for exact session API, payment channel mechanics, and configuration options before implementing.