Update API docs for session-based billing

api-reference/gateway.mdx

@@ -1,11 +1,11 @@
 ---
 title: Gateway
-description: "Route requests to plugins through the v1 gateway with support for Stripe and MPP payments."
+description: "Route requests to plugins through the v1 gateway with support for session, MPP, and Stripe payments."
 ---
 
 # Gateway
 
-The v1 gateway routes incoming requests to registered plugins. It supports dual payment methods — Stripe (existing) and [MPP](/payments/mpp) (Machine Payments Protocol) via the Tempo blockchain.
+The v1 gateway routes incoming requests to registered plugins. It supports three payment methods — session-based billing (off-chain vouchers), [MPP](/payments/mpp) (Machine Payments Protocol on the Tempo blockchain), and Stripe.
 
 ## Base URL
 
@@ -21,7 +21,9 @@
 |--------|------|----------|-------------|
 | `Content-Type` | string | Yes | Must be `application/json` |
 | `X-Plugin-Id` | string | No | Plugin to route the request to. Overrides the `plugin` field in the body. |
-| `X-Payment-Method` | string | No | Payment method to use: `stripe` or `mpp`. Defaults to `stripe`. |
+| `X-Payment-Method` | string | No | Payment method to use: `session`, `mpp`, or `stripe`. Defaults to `stripe`. |
+| `X-Session-Id` | string | No | Active session ID for session-based billing. When present, implies `session` payment method. |
+| `X-Wallet-Address` | string | No | Wallet address (0x-prefixed) for session-based billing. Required when `X-Session-Id` is set. |
 | `Authorization` | string | No | For MPP payments, use `Payment <credential>`. For session auth, handled via cookies. |
 | `Accept` | string | No | Set to `text/event-stream` for streaming responses (where supported). |
 
@@ -36,7 +38,7 @@
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `plugin` | string | No | Plugin ID to route to. The `X-Plugin-Id` header takes priority if both are provided. Defaults to `generate-text`. |
+| `plugin` | string | No | Plugin ID to route to. The `X-Plugin-Id` header takes priority if both are provided. Defaults to `agent`. |
 
 Additional body fields are forwarded to the target plugin.
 
@@ -51,24 +53,67 @@
 | `tts` | Text-to-Speech | Speech synthesis | Yes | No |
 | `stt` | Speech-to-Text | Speech transcription | Yes | No |
 
-<Note>`generate-text` is the default plugin when no plugin ID is specified.</Note>
+<Note>`agent` is the default plugin when no plugin ID is specified.</Note>
 
 ## Authentication
 
-Protected plugins require either a valid session (cookie-based via NextAuth) or a verified MPP payment credential. If you pay with MPP, session authentication is not required.
+Protected plugins require either a valid session (cookie-based via NextAuth), a verified MPP payment credential, or a valid payment session with receipt. If you pay with MPP or session-based billing, NextAuth session authentication is not required.
 
 ## Payment flow
 
-The gateway supports two payment methods per request:
+The gateway supports three payment methods per request:
 
-1. **Stripe** — Default. Requires an active subscription or credits. See [Stripe integration](/payments/stripe).
-2. **MPP** — Crypto-native payments on the Tempo blockchain. See [MPP payments](/payments/mpp).
+1. **Session** — Off-chain billing via payment sessions. Each agent call auto-debits a voucher from the session balance with sub-100ms latency. See [MPP sessions](/payments/mpp#sessions).
+2. **MPP** — Crypto-native per-request payments on the Tempo blockchain. See [MPP payments](/payments/mpp).
+3. **Stripe** — Credit card payments. Requires an active subscription or credits. See [Stripe integration](/payments/stripe).
 
 The server selects the payment method using the following priority:
 
-1. `X-Payment-Method` header (`mpp` or `stripe`)
+1. `X-Payment-Method` header (`session`, `mpp`, or `stripe`)
 2. Presence of an `Authorization: Payment` header (implies `mpp`)
-3. Default: `stripe`
+3. Presence of an `X-Session-Id` header (implies `session`)
+4. Default: `stripe`
+
+### Session billing
+
+When the payment method is `session`, the gateway auto-debits the session balance via an off-chain voucher. You must provide both `X-Session-Id` and `X-Wallet-Address` headers.
+
+The gateway checks the session balance against the plugin's price before forwarding the request. If the balance is insufficient, the gateway returns `402` with the current balance and required cost.
+
+```bash
+curl -X POST https://agentbot.raveculture.xyz/api/v1/gateway \
+  -H "Content-Type: application/json" \
+  -H "X-Plugin-Id: agent" \
+  -H "X-Session-Id: ses_a1b2c3d4e5f6" \
+  -H "X-Wallet-Address: 0xYOUR_WALLET_ADDRESS" \
+  -d '{"messages": [{"role": "user", "content": "Summarize my tasks"}]}'
+```
+
+On success, the response includes a `Payment-Receipt` header with the session receipt and an `X-Session-Remaining` header with the updated balance.
+
+#### Session 402 errors
+
+When a session payment fails, the response includes a specific error code:
+
+| Error code | Description |
+|------------|-------------|
+| `session_required` | `X-Session-Id` or `X-Wallet-Address` header is missing |
+| `session_invalid` | No active session found for the given address and session ID |
+| `insufficient_balance` | Session balance is too low for the requested plugin. The response body includes the current `remaining` balance and the `cost`. |
+| `voucher_failed` | The off-chain voucher could not be processed |
+
+Example insufficient balance response:
+
+```json
+{
+  "error": "insufficient_balance",
+  "message": "Need $0.05, have $0.02",
+  "session": {
+    "remaining": "0.02",
+    "cost": "0.05"
+  }
+}
+```
 
 ### MPP 402 challenge
 
@@ -117,21 +162,27 @@
 }
 ```
 
-When paid via MPP, the response includes a `Payment-Receipt` header and the `payment.receipt` field contains the transaction hash.
+When paid via MPP, the response includes a `Payment-Receipt` header and the `payment.receipt` field contains the transaction hash. When paid via session, the `Payment-Receipt` header contains the session receipt and the `X-Session-Remaining` header contains the updated balance.
 
 ### Response headers
 
 | Header | Description |
 |--------|-------------|
 | `x-plugin-id` | The plugin that handled the request |
-| `Payment-Receipt` | MPP transaction receipt hash (only present for MPP-paid requests) |
+| `Payment-Receipt` | Payment receipt. For MPP: the transaction hash. For session: a receipt in the format `session:<sessionId>:<nonce>`. Only present for MPP or session-paid requests. |
+| `X-Session-Remaining` | Remaining session balance in USD after the debit. Only present for session-paid requests. |
 
 ## Error responses
 
 | Status | Error code | Description |
 |--------|-----------|-------------|
-| 401 | `Unauthorized` | Authentication required for a protected plugin and no valid session or MPP credential |
+| 400 | `unknown_plugin` | No pricing configured for the specified plugin (session billing only) |
+| 401 | `Unauthorized` | Authentication required for a protected plugin and no valid session, MPP credential, or payment session |
 | 402 | `payment_required` | MPP payment required. Response includes challenge and pricing. |
+| 402 | `session_required` | Session ID and wallet address required for session billing |
+| 402 | `session_invalid` | No active session found for the given address |
+| 402 | `insufficient_balance` | Session balance too low for the requested plugin |
+| 402 | `voucher_failed` | Off-chain voucher processing failed |
 | 500 | `internal` | Internal server error |
 | 502 | `no_plugin` | No plugin registered for the given ID |
 
@@ -160,26 +211,26 @@
 | `HOME` | `/home/node` | Home directory for the `node` user that the official OpenClaw image runs as |
 | `TERM` | `xterm-256color` | Terminal type |
 | `NODE_COMPILE_CACHE` | `/var/tmp/openclaw-compile-cache` | Directory for the Node.js compile cache. Speeds up cold starts by caching compiled bytecode across process restarts. |
 | `OPENCLAW_NO_RESPAWN` | `1` | When set to `1`, prevents the OpenClaw process from automatically respawning after exit. Container-level restart policies (Docker `--restart` or orchestrator health checks) handle process recovery instead. |
 | `OPENCLAW_GATEWAY_TOKEN` | Auto-generated | Gateway authentication token. When not set, the entrypoint generates a 32-character hex token. See [per-agent gateway authentication](#per-agent-gateway-authentication). |
 | `OPENCLAW_GATEWAY_PORT` | `18789` | Port the gateway listens on inside the container |
 | `AGENTBOT_USER_ID` | Per-user | Owner user ID passed at provisioning time |
 | `AGENTBOT_PLAN` | `solo` | Subscription plan tier (`solo`, `collective`, `label`, or `network`) |
 | `AGENTBOT_MODE` | `home` | Installation mode (`home` for self-hosted, `link` for existing OpenClaw) |
 | `AGENTBOT_API_KEY` | Per-user | API key for authenticating with the Agentbot platform |
 
 ### Gateway settings
 
 | Parameter | Value | Description |
 |-----------|-------|-------------|
 | `gateway.bind` | `loopback` | Bind address for the gateway. The container entrypoint overrides this to `loopback` via the `--bind loopback` CLI flag, so the gateway only listens on `127.0.0.1`. Docker port mapping forwards external traffic to the loopback address inside the container. The provisioning config sets `lan` but the entrypoint takes precedence at runtime. |
 | `gateway.port` | `18789` | Internal gateway port |
 | `gateway.auth.mode` | `token` | Authentication mode |
 | `gateway.auth.rateLimit.maxAttempts` | `10` | Maximum authentication attempts before lockout |
 | `gateway.auth.rateLimit.windowMs` | `60000` | Rate limit window in milliseconds (1 minute) |
 | `gateway.auth.rateLimit.lockoutMs` | `300000` | Lockout duration in milliseconds (5 minutes) |
 | `gateway.auth.rateLimit.exemptLoopback` | `true` | Exempt loopback addresses from rate limiting |
 | `gateway.auth.allowTailscale` | `true` | Allow Tailscale network connections |
 | `gateway.controlUi.enabled` | `true` | Gateway control UI is enabled in containers. |
 
 ### Tool settings
@@ -209,7 +260,7 @@
 |-----------|-------|-------------|
 | `agents.defaults.workspace` | `~/.openclaw/workspace` | Default workspace directory |
 | `agents.defaults.imageMaxDimensionPx` | `1200` | Maximum image dimension in pixels (optimizes vision token usage) |
 | `agents.defaults.userTimezone` | `Europe/London` | Default timezone (overridden by signup timezone when available) |
 | `agents.defaults.timeFormat` | `24h` | Time format |
 | `agents.defaults.compaction.maxMessages` | `200` | Maximum messages before compaction |
 | `agents.defaults.compaction.keepLastN` | `20` | Number of recent messages preserved after compaction |
@@ -229,7 +280,7 @@
 
 ## CORS
 
-The gateway supports CORS preflight via `OPTIONS /api/v1/gateway`. Allowed methods are `POST` and `OPTIONS`. The `Authorization`, `Content-Type`, `X-Plugin-Id`, and `X-Payment-Method` headers are permitted.
+The gateway supports CORS preflight via `OPTIONS /api/v1/gateway`. Allowed methods are `GET`, `POST`, `PUT`, `DELETE`, and `OPTIONS`. The `Content-Type`, `Authorization`, `X-Plugin-Id`, and `Payment` headers are permitted.
 
 ## Rate limits
 
@@ -258,3 +309,14 @@
   -H "Authorization: Payment {\"scheme\":\"Payment\",\"transaction\":\"0x76...\",\"challengeNonce\":\"abc123\"}" \
   -d '{"messages": [{"role": "user", "content": "Hello"}]}'
 ```
+
+### Route a request with session billing
+
+```bash
+curl -X POST https://agentbot.raveculture.xyz/api/v1/gateway \
+  -H "Content-Type: application/json" \
+  -H "X-Plugin-Id: agent" \
+  -H "X-Session-Id: ses_a1b2c3d4e5f6" \
+  -H "X-Wallet-Address: 0xYOUR_WALLET_ADDRESS" \
+  -d '{"messages": [{"role": "user", "content": "Summarize my tasks"}]}'
+```