# Session \[Low-cost high-throughput payments] The `session` intent enables high-frequency, pay-as-you-go payments over unidirectional payment channels. Clients deposit funds into an on-chain escrow and sign off-chain vouchers as they consume resources. The server verifies vouchers with fast signature checks—no RPC or blockchain calls—and settles periodically in batches. Payment sessions reduce payment verification to near constant time, making it possible to meter and bill at the granularity of individual LLM tokens, API calls, or bytes transferred. ## Why sessions matter in MPP Traditional payment rails target human purchase flows: a buyer decides, pays, and receives goods. Usage-based billing—the model that powers cloud infrastructure, LLM APIs, and metered services—requires something fundamentally different. It needs payment verification that can keep pace with the service itself. Consider an LLM API: a single inference request can generate hundreds of tokens over several seconds. Each token has a known cost, but the total cost isn't known when the request begins. Standard billing models handle this by accumulating usage and charging after the fact, introducing credit risk, reconciliation complexity, and billing disputes. Prepaid credit systems require the client to guess consumption upfront and lose unused funds. Sessions on Tempo solve this by making payment a continuous, inline part of the HTTP request. The client signs a cumulative voucher for each increment of service consumed, and the server verifies it in microseconds. The server delays on-chain settlement to whenever it chooses, batching hundreds or thousands of vouchers into a single on-chain transaction. This reduces both the latency and the cost of payment verification to near zero. ## How it works ### Overview >Tempo: (1) Deposit tokens Tempo-->>Client: Channel created Client->>Server: (2) Open credential Note over Server: Verify on-chain deposit Server-->>Client: 200 OK (session established) loop Per request Client->>Server: (3) Request + voucher Note over Server: recover signature (ecrecover) Server-->>Client: 200 OK + Receipt end Note over Server: (4) Periodic settlement Server->>Tempo: settle(channelId, voucher) Client->>Server: (5) Close Server->>Tempo: close(channelId, voucher) Tempo-->>Client: Refund remaining deposit `} /> A payment session has four phases: ::::steps ### Open The client deposits funds into an on-chain escrow contract, creating a payment channel between the client (payer) and server (payee). A unique `channelId` identifies the channel and holds the deposited TIP-20 tokens. ### Session The client signs EIP-712 vouchers with increasing cumulative amounts as service is consumed. Each voucher authorizes "I have now consumed up to X total." The server verifies the signature, checks that the cumulative amount is higher than the previous voucher, and grants access based on the delta. Voucher verification is CPU-bound: a single `ecrecover` call against the EIP-712 typed data. No RPC calls. No database lookups in the critical path. This is what enables per-token LLM billing without adding latency. ### Top up If the channel runs low on funds, the client deposits additional tokens without closing the channel. The session continues uninterrupted. ### Close Either party can close the channel. The server calls `close()` on the escrow contract with the highest voucher, settling the final balance on-chain and refunding any unused deposit to the client. :::: ## Session receipts Session Receipts differ from charge Receipts. The `reference` field contains the payment channel ID (a `bytes32` hash), not a transaction hash. The on-chain settlement transaction hash is only available after closing the channel. | Field | Charge receipt | Session receipt | |-------|---------------|-----------------| | `reference` | Transaction hash | Channel ID | | `status` | `"success"` | `"success"` | | `method` | `"tempo"` | `"tempo"` | To get the settlement transaction hash, close the channel via `session.close()` and read the `txHash` field from the returned receipt. ## High volume API billing Payment sessions match the billing model that high-volume APIs need: pay stablecoin tokens, receive API responses. The granularity of payment matches the granularity of consumption. A typical flow for a high-volume large language model API: 1. **Client:** opens a channel with a 10 USDC.e deposit 2. **Client:** sends a prompt to the API 3. **Server:** issues Challenges requesting payment for each chunk (for example, 0.000025 USDC.e per token) 4. **Client:** signs a voucher for each chunk—the cumulative amount increases by the cost of tokens received 5. **Server:** verifies the voucher signature (~microseconds) and sends the next chunk 6. **Server:** settles on-chain and the client gets the unused deposit back The server never touches the chain during inference. Payment verification adds microseconds of CPU overhead per chunk, not hundreds of milliseconds of network latency. :::info\[Why Tempo] Tempo handles payments at scale and has properties that make it a uniquely good fit for payment sessions: * **Channel management UX**—Opening, topping up, and closing channels are on-chain operations. Tempo's ~500ms finality and sub-cent fees keep channel lifecycle from becoming a UX bottleneck. * **Payment lane**—Tempo's 2D nonce system provides dedicated nonce lanes for payment transactions, so channel operations don't block other account activity. This matters for clients that use the same account for payments and other on-chain interactions. * **High throughput**—When a server settles thousands of channels, Tempo's throughput handles the settlement volume without congestion or fee spikes. * **Fee sponsorship**—Servers can pay channel management fees on behalf of clients, making the client-side integration purely off-chain after the initial deposit. * **Enshrined tokens**—TIP-20 tokens are precompile-based, not smart contracts. Token operations are cheaper and more predictable than ERC-20 interactions on other chains. ::: ## Integration
Use [`tempo`](/sdk/typescript/server/Method.tempo.session) to accept payment sessions. The server needs an RPC URL for on-chain verification during channel open/close, and a storage backend for channel state. ```ts twoslash import { Mppx, Store, tempo } from 'mppx/server' const mppx = Mppx.create({ methods: [ tempo({ recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', store: Store.memory(), }), ], }) ``` During a session, the server verifies each voucher with a single `ecrecover`—no RPC calls, no database writes in the hot path. On-chain interaction only happens during open, settlement, and close. Use `mppx.session` in your request handler to meter access: ```ts twoslash import { Mppx, tempo } from 'mppx/server' const mppx = Mppx.create({ methods: [ tempo.session({ currency: '0x20c0000000000000000000000000000000000000', recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', }), ], }) // ---cut--- export async function handler(request: Request) { const result = await mppx.session({ amount: '25', unitType: 'llm_token', })(request) if (result.status === 402) return result.challenge return result.withReceipt(Response.json({ data: '...' })) } ```
Use [`tempo`](/sdk/typescript/client/Method.tempo) with `Mppx.create` to sign vouchers automatically when the server requests payment sessions. ```ts twoslash import { Mppx, tempo } from 'mppx/client' import { privateKeyToAccount } from 'viem/accounts' const account = privateKeyToAccount('0xabc…123') Mppx.create({ methods: [tempo({ account })], }) const response = await fetch('https://api.example.com/v1/chat/completions') // Automatically opens channel, signs vouchers per chunk ``` ### Without polyfill If you don't want to patch `globalThis.fetch`, use `mppx.fetch` directly: ```ts twoslash import { Mppx, tempo } from 'mppx/client' import { privateKeyToAccount } from 'viem/accounts' const account = privateKeyToAccount('0xabc…123') const mppx = Mppx.create({ methods: [tempo.session({ account })], polyfill: false, }) const response = await mppx.fetch('https://api.example.com/v1/chat/completions') ``` ### With multiple methods Register multiple methods so the client can handle servers that offer multiple payment methods. For example, to accept both charge and payment sessions: ```ts twoslash import { Mppx, tempo } from 'mppx/client' import { privateKeyToAccount } from 'viem/accounts' const account = privateKeyToAccount('0xabc…123') Mppx.create({ methods: [ tempo.charge({ account }), tempo.session({ account }), ], }) ``` ### Closing the channel Channels remain open for reuse across requests. Call `session.close()` to settle on-chain and reclaim unspent deposit. :::warning Channels do not close automatically. If you don't call `close()`, the deposit stays locked in the escrow contract until the channel expires or is manually closed. ::: See [`tempo.session` manager](/sdk/typescript/client/Method.tempo.session-manager) for the full session lifecycle API.
## Escrow contract Sessions use the `TempoStreamChannel` escrow contract for on-chain deposits, settlement, and channel close. The [reference implementation](https://github.com/tempoxyz/tempo/blob/main/tips/ref-impls/src/TempoStreamChannel.sol) lives in the `tempoxyz/tempo` repository. | Network | Chain ID | Contract Address | |---|---|---| | [Mainnet](https://explore.mainnet.tempo.xyz/address/0x33b901018174DDabE4841042ab76ba85D4e24f25?tab=contract) | 4217 | `0x33b901018174DDabE4841042ab76ba85D4e24f25` | | [Testnet (Moderato)](https://explore.testnet.tempo.xyz/address/0xe1c4d3dce17bc111181ddf716f75bae49e61a336?tab=contract) | 42431 | `0xe1c4d3dce17bc111181ddf716f75bae49e61a336` | ## Specification