Payment Sessions
Session tokens for high-frequency requests, settled on-chain in batches. Coming in general availability.
The problem sessions solve
One-time payments, and even active subscriptions, hit a practical ceiling once request rates climb. Take an LLM inference agent firing off 500 API calls in a minute. An on-chain transaction per request would tack hundreds of milliseconds onto each call and burn more in fees than the requests themselves are worth.
Payment sessions separate the payment authorization from individual request processing. The agent puts up a budget in advance, the Facilitator batches the underlying settlements, and each request carries almost no payment overhead.
How sessions work
1. Agent calls agent.openSession({ provider, budget, ttl })
2. HoodLayer Facilitator verifies the agent has sufficient balance
3. Facilitator issues a short-lived Session Token (JWT, TTL: 5-60 min)
4. Agent attaches the Session Token to each request header
5. Service validates the token against the Facilitator (sub-millisecond)
6. Facilitator batches on-chain settlements periodically
7. On session expiry: final settlement executed, unused balance returned
On the service’s side, validating a session is a cheap token check rather than an on-chain query, which keeps per-request latency close to zero.
Session Token lifecycle
| Phase | Description |
|---|---|
| Open | The agent commits a budget and the Facilitator issues a token. Funds are locked. |
| Active | The agent makes requests while the Facilitator tracks spend against the committed budget. |
| Expired | The TTL runs out or the agent closes the session. Final settlement executes on-chain. |
| Settled | Every charge is finalized on-chain and unused budget goes back to the agent wallet. |
Planned API
Opening a session (agent)
const session = await agent.openSession({
provider: "https://api.inference.com",
budget: 10_000_000, // 10 USDC session budget
ttl: 3600, // 1 hour
});
// Make high-frequency calls through the session
const response = await session.get("/v1/completions", {
body: { prompt: "..." },
});
// Closing early settles up and reclaims whatever budget is left
await session.close();
Accepting sessions (provider)
app.use("/v1", hoodlayer.sessionGate({
facilitatorUrl: "https://facilitator.hoodlayer.org",
}));
On each request, the sessionGate middleware checks the X-HoodLayer-Session header. There’s no per-request on-chain call; the only thing queried is the Facilitator.
On-chain auditability
Per-request settlements are batched, but the final settlement is an ordinary on-chain transaction. Anyone watching the chain can confirm how much a session paid in total, how long it lasted, and who the parties were. The transaction memo field carries the session ID.
Use cases
Sessions make the most sense for:
- LLM inference agents issuing rapid completions calls
- Consumers of real-time data feeds
- Multi-step agent workflows with many sub-calls to a single provider
- Any workload where per-request latency is a real concern
If your request rate is lower, one-time payments and subscriptions are simpler, and they work today.