From d4183f2faf560f6254dfaa1d0a13e532bb091960 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 24 Mar 2026 15:22:08 +0000 Subject: [PATCH 1/3] Update gateway API defaults and CORS settings Generated-By: mintlify-agent --- api-reference/gateway.mdx | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/api-reference/gateway.mdx b/api-reference/gateway.mdx index 992f18e..35a676a 100644 --- a/api-reference/gateway.mdx +++ b/api-reference/gateway.mdx @@ -23,6 +23,7 @@ POST /api/v1/gateway | `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`. | | `Authorization` | string | No | For MPP payments, use `Payment `. For session auth, handled via cookies. | +| `Payment` | string | No | Alternative header for passing MPP payment credentials. Included in the gateway CORS allowlist. | | `Accept` | string | No | Set to `text/event-stream` for streaming responses (where supported). | ### Body @@ -36,7 +37,7 @@ POST /api/v1/gateway | 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. @@ -46,16 +47,18 @@ The gateway routes to the following plugins: | Plugin ID | Name | Description | Auth required | Streaming | |-----------|------|-------------|---------------|-----------| -| `agent` | Agent | Agent orchestrator for multi-step tasks | Yes | Yes | -| `generate-text` | Text Generation | LLM text generation | Yes | Yes | -| `tts` | Text-to-Speech | Speech synthesis | Yes | No | -| `stt` | Speech-to-Text | Speech transcription | Yes | No | +| `agent` | Agent | Agent orchestrator for multi-step tasks | No | Yes | +| `generate-text` | Text Generation | LLM text generation | No | Yes | +| `tts` | Text-to-Speech | Speech synthesis | No | No | +| `stt` | Speech-to-Text | Speech transcription | No | No | -`generate-text` is the default plugin when no plugin ID is specified. +Authentication is controlled per-plugin via the gateway configuration. Plugins without the `auth` flag set do not require session authentication. When a plugin has `auth` enabled, requests must include either a valid session cookie or a verified MPP payment credential. + +`agent` is the default plugin when no plugin ID is specified. ## 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. +Plugins with the `auth` flag enabled in the gateway configuration 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. Plugins without the `auth` flag can be called without authentication. ## Payment flow @@ -229,7 +232,7 @@ The gateway monitors channel health for each agent container. When a channel bec ## 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 From cf1b06825b43e4898d0e091b5ace3b215ca7d486 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 24 Mar 2026 22:04:07 +0000 Subject: [PATCH 2/3] Update gateway and wallet API docs for session billing --- api-reference/gateway.mdx | 97 +++++++++++++++++++++++++++++++-------- 1 file changed, 78 insertions(+), 19 deletions(-) diff --git a/api-reference/gateway.mdx b/api-reference/gateway.mdx index 35a676a..f938ce1 100644 --- a/api-reference/gateway.mdx +++ b/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,9 +21,10 @@ POST /api/v1/gateway |--------|------|----------|-------------| | `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 `. For session auth, handled via cookies. | -| `Payment` | string | No | Alternative header for passing MPP payment credentials. Included in the gateway CORS allowlist. | | `Accept` | string | No | Set to `text/event-stream` for streaming responses (where supported). | ### Body @@ -47,31 +48,72 @@ The gateway routes to the following plugins: | Plugin ID | Name | Description | Auth required | Streaming | |-----------|------|-------------|---------------|-----------| -| `agent` | Agent | Agent orchestrator for multi-step tasks | No | Yes | -| `generate-text` | Text Generation | LLM text generation | No | Yes | -| `tts` | Text-to-Speech | Speech synthesis | No | No | -| `stt` | Speech-to-Text | Speech transcription | No | No | - -Authentication is controlled per-plugin via the gateway configuration. Plugins without the `auth` flag set do not require session authentication. When a plugin has `auth` enabled, requests must include either a valid session cookie or a verified MPP payment credential. +| `agent` | Agent | Agent orchestrator for multi-step tasks | Yes | Yes | +| `generate-text` | Text Generation | LLM text generation | Yes | Yes | +| `tts` | Text-to-Speech | Speech synthesis | Yes | No | +| `stt` | Speech-to-Text | Speech transcription | Yes | No | `agent` is the default plugin when no plugin ID is specified. ## Authentication -Plugins with the `auth` flag enabled in the gateway configuration 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. Plugins without the `auth` flag can be called without authentication. +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 @@ -120,21 +162,27 @@ Payment amount="0.05", currency="0x20c0000000000000000000000000000000000000", re } ``` -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::`. 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 | @@ -261,3 +309,14 @@ curl -X POST https://agentbot.raveculture.xyz/api/v1/gateway \ -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"}]}' +``` From b329e9b59765fb56f6dfe47f2489fd92a4ee7555 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 24 Mar 2026 22:04:20 +0000 Subject: [PATCH 3/3] Update wallet and MPP docs for session billing and top-up Generated-By: mintlify-agent --- api-reference/wallet.mdx | 367 ++++++++++++++++++++++++++++++++++++++- payments/mpp.mdx | 37 +++- 2 files changed, 397 insertions(+), 7 deletions(-) diff --git a/api-reference/wallet.mdx b/api-reference/wallet.mdx index 8a89230..5304467 100644 --- a/api-reference/wallet.mdx +++ b/api-reference/wallet.mdx @@ -5,7 +5,7 @@ description: "Manage wallets for on-chain transactions and payments" # Wallet API -Manage wallets for on-chain transactions and payments. Supports both session-based wallets and Coinbase Developer Platform (CDP) wallets. +Manage wallets for on-chain transactions and payments. Supports session-based wallets, Coinbase Developer Platform (CDP) wallets, and Tempo network balance queries. ## Get wallet @@ -13,9 +13,72 @@ Manage wallets for on-chain transactions and payments. Supports both session-bas GET /api/wallet ``` -Returns wallet information. When CDP is configured, returns CDP status without authentication. Otherwise, requires session authentication. +Returns wallet information. Behavior depends on whether an `address` query parameter is provided and on your server configuration. -### Response (CDP configured) +### Tempo balance query + +When the `address` query parameter is present, the endpoint queries the Tempo blockchain for the wallet's balance and fee token information. + +```http +GET /api/wallet?address=0xd8fd...db56f +``` + +#### Query parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `address` | string | Yes | Hex-encoded wallet address (0x-prefixed) | + +#### Response + +```json +{ + "address": "0xd8fd0e1dce89beaab924ac68098ddb17613db56f", + "chain": "Tempo", + "chainId": 4217, + "testnet": false, + "feeToken": { + "address": "0x20c0000000000000000000000000000000000000", + "balance": "12.470000", + "balanceRaw": "12470000" + }, + "pathUsd": { + "address": "0x20c0000000000000000000000000000000000000", + "balance": "12.470000", + "balanceRaw": "12470000" + } +} +``` + +#### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `address` | string | The queried wallet address | +| `chain` | string | Network name (`Tempo` or `Tempo Testnet`) | +| `chainId` | number | Chain ID (`4217` for mainnet, `42431` for testnet) | +| `testnet` | boolean | Whether the server is configured for testnet | +| `feeToken.address` | string | Contract address of the user's configured fee token | +| `feeToken.balance` | string | Fee token balance formatted with 6 decimals | +| `feeToken.balanceRaw` | string | Fee token balance in raw units | +| `pathUsd.address` | string | pathUSD contract address | +| `pathUsd.balance` | string | pathUSD balance formatted with 6 decimals | +| `pathUsd.balanceRaw` | string | pathUSD balance in raw units | + +Balance values are formatted to 6 decimal places. pathUSD uses 6 decimals, not 18. The network is determined server-side by the `TEMPO_TESTNET` environment variable. + +#### Errors + +| Code | Description | +|------|-------------| +| 400 | Missing `address` parameter | +| 500 | Failed to fetch wallet data from Tempo RPC | + +### CDP / session wallet query + +When no `address` parameter is provided, the endpoint returns CDP or session-based wallet information. When CDP is configured, returns CDP status without authentication. Otherwise, requires session authentication. + +#### Response (CDP configured) ```json { @@ -34,7 +97,7 @@ Returns wallet information. When CDP is configured, returns CDP status without a } ``` -### Response (user wallet exists) +#### Response (user wallet exists) ```json { @@ -46,7 +109,7 @@ Returns wallet information. When CDP is configured, returns CDP status without a } ``` -### Response (no wallet) +#### Response (no wallet) ```json { @@ -58,7 +121,7 @@ Returns wallet information. When CDP is configured, returns CDP status without a } ``` -### Errors +#### Errors | Code | Description | |------|-------------| @@ -245,3 +308,295 @@ When transferring USDC through the wallet service, the following validation rule These checks run before any on-chain transaction is initiated. When payments are initiated through the [x402 pay action](/api-reference/x402#pay), additional protections apply: a per-payment maximum of $100, recipient address format validation (EVM or Solana), and audit logging of every payment attempt. See the [x402 gateway reference](/api-reference/x402) for details. + +## Wallet top-up + +Fund your wallet via Stripe checkout to credit your payment session balance. + +### Create checkout session + +```http +GET /api/wallet/top-up?amount=1000 +``` + +Creates a Stripe checkout session for wallet top-up. Requires session authentication. + +#### Query parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `amount` | number | No | `1000` | Amount in cents. Valid values: `500` ($5), `1000` ($10), `2500` ($25), `5000` ($50). | + +#### Response + +```json +{ + "url": "https://checkout.stripe.com/...", + "sessionId": "cs_live_..." +} +``` + +| Field | Type | Description | +|-------|------|-------------| +| `url` | string | Stripe checkout URL. Redirect the user here to complete payment. | +| `sessionId` | string | Stripe checkout session ID | + +#### Errors + +| Code | Description | +|------|-------------| +| 400 | Invalid amount. Must be one of: 500, 1000, 2500, 5000 (cents). | +| 401 | Unauthorized — session authentication required | +| 500 | Stripe not configured or failed to create checkout session | + +### Stripe webhook + +```http +POST /api/wallet/top-up +``` + +Handles the Stripe `checkout.session.completed` webhook to credit the user's wallet after payment. This endpoint verifies the Stripe webhook signature before processing. + +This endpoint is called by Stripe, not by your application. Configure your Stripe webhook to point to this URL with the `checkout.session.completed` event. + +#### Errors + +| Code | Description | +|------|-------------| +| 400 | Invalid Stripe webhook signature | +| 500 | Stripe not configured or webhook processing failed | + +## MPP payment sessions + +Payment sessions enable off-chain, per-call billing for agent requests. Instead of settling every call on-chain, you deposit funds into a session and sign lightweight vouchers that are batched and settled periodically. + +When you send a request to the [gateway](/api-reference/gateway) with `X-Session-Id` and `X-Wallet-Address` headers, the gateway auto-debits your session balance and returns the updated balance in the `X-Session-Remaining` response header. + +See [MPP payments — sessions](/payments/mpp#sessions) for the full protocol description. + +### List sessions + +```http +GET /api/wallet/sessions?address=0x... +``` + +Returns all sessions (active and closed) for the given wallet address. + +#### Query parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `address` | string | Yes | Hex-encoded wallet address (0x-prefixed) | + +#### Response + +```json +{ + "sessions": [ + { + "id": "ses_a1b2c3d4e5f6...", + "userAddress": "0x...", + "deposit": "10.00", + "spent": "1.25", + "remaining": "8.75", + "vouchers": [], + "status": "active", + "createdAt": 1742472000000, + "lastSettledAt": 1742472000000 + } + ] +} +``` + +### Get session + +```http +GET /api/wallet/sessions?sessionId=ses_... +``` + +Returns a single session by ID. + +#### Query parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `sessionId` | string | Yes | Session ID (prefixed with `ses_`) | + +#### Response + +```json +{ + "session": { + "id": "ses_a1b2c3d4e5f6...", + "userAddress": "0x...", + "deposit": "10.00", + "spent": "1.25", + "remaining": "8.75", + "vouchers": [], + "status": "active", + "createdAt": 1742472000000, + "lastSettledAt": 1742472000000 + } +} +``` + +#### Errors + +| Code | Description | +|------|-------------| +| 400 | Missing `address` or `sessionId` parameter | +| 404 | Session not found | + +### Session fields + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Unique session ID (`ses_` prefix) | +| `userAddress` | string | Wallet address that owns the session | +| `deposit` | string | Total deposited amount in USD | +| `spent` | string | Total spent via vouchers in USD | +| `remaining` | string | Remaining balance in USD | +| `vouchers` | array | Pending vouchers not yet settled on-chain | +| `status` | string | One of `active`, `settling`, or `closed` | +| `createdAt` | number | Unix timestamp (ms) when the session was created | +| `lastSettledAt` | number | Unix timestamp (ms) of the last on-chain settlement | + +### Create session + +```http +POST /api/wallet/sessions +``` + +Opens a new payment session. If the wallet already has an active session, the existing session is returned instead. + +#### Request body + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `address` | string | Yes | Hex-encoded wallet address (0x-prefixed) | +| `deposit` | string | Yes | Deposit amount in USD (minimum `1.00`, maximum `100.00`) | + +#### Response (201 Created) + +```json +{ + "session": { + "id": "ses_a1b2c3d4e5f6...", + "userAddress": "0x...", + "deposit": "10.00", + "spent": "0.00", + "remaining": "10.00", + "vouchers": [], + "status": "active", + "createdAt": 1742472000000, + "lastSettledAt": 1742472000000 + } +} +``` + +#### Response (existing session) + +```json +{ + "session": { ... }, + "note": "Active session already exists" +} +``` + +#### Errors + +| Code | Description | +|------|-------------| +| 400 | Missing `address` or `deposit`, deposit below minimum, or deposit above maximum | + +### Close session + +```http +DELETE /api/wallet/sessions?sessionId=ses_... +``` + +Closes an active session. Any pending vouchers are settled on-chain first, and the remaining balance is returned to the user. + +#### Query parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `sessionId` | string | Yes | Session ID to close | + +#### Response + +```json +{ + "success": true, + "returned": "8.75" +} +``` + +| Field | Type | Description | +|-------|------|-------------| +| `success` | boolean | Whether the session was closed | +| `returned` | string | Amount in USD returned to the user | + +#### Errors + +| Code | Description | +|------|-------------| +| 400 | Missing `sessionId`, or session could not be closed | + +### Submit voucher + +```http +POST /api/wallet/sessions/voucher +``` + +Submits a signed voucher to debit the session balance off-chain. This is the primary billing mechanism during an active session — each agent call produces one voucher. + +#### Request body + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `sessionId` | string | Yes | Active session ID | +| `userAddress` | string | Yes | Wallet address that owns the session (0x-prefixed) | +| `plugin` | string | Yes | Plugin identifier (e.g., `agent`, `generate-text`, `tts`, `stt`) | +| `signature` | string | Yes | User's hex-encoded signature (0x-prefixed) | +| `nonce` | string | Yes | Unique nonce for this voucher | + +The voucher amount is determined automatically from the plugin's pricing. See [plugin pricing](/payments/mpp#plugin-pricing) for current rates. + +#### Response + +```json +{ + "success": true, + "session": { + "id": "ses_a1b2c3d4e5f6...", + "spent": "0.05", + "remaining": "9.95", + "pendingVouchers": 1 + }, + "voucher": { + "amount": "0.05", + "plugin": "agent", + "description": "Agent orchestrator request" + } +} +``` + +#### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `session.id` | string | Session ID | +| `session.spent` | string | Updated total spent in USD | +| `session.remaining` | string | Updated remaining balance in USD | +| `session.pendingVouchers` | number | Number of vouchers pending on-chain settlement | +| `voucher.amount` | string | Amount debited for this call in USD | +| `voucher.plugin` | string | Plugin that was called | +| `voucher.description` | string | Human-readable description of the charge | + +#### Errors + +| Code | Description | +|------|-------------| +| 400 | Missing required fields, unknown plugin, session not found, session not active, address mismatch, or insufficient balance | +| 500 | Internal error processing the voucher | diff --git a/payments/mpp.mdx b/payments/mpp.mdx index bc92866..dff0928 100644 --- a/payments/mpp.mdx +++ b/payments/mpp.mdx @@ -5,7 +5,7 @@ description: "Pay for API requests with crypto using the Machine Payments Protoc # MPP payments -The Machine Payments Protocol (MPP) enables crypto-native, per-request payments on the Tempo blockchain. MPP is an additive payment method alongside [Stripe](/payments/stripe) — you choose which to use on each request. +The Machine Payments Protocol (MPP) enables crypto-native, per-request payments on the Tempo blockchain. MPP is an additive payment method alongside [Stripe](/payments/stripe) and session-based billing — you choose which to use on each request. ## How it works @@ -175,6 +175,41 @@ const { supported } = await checkMppSupport( The function sends an `OPTIONS` request and checks for a `WWW-Authenticate: Payment` header. +## Sessions + +Payment sessions provide off-chain, per-call billing without an on-chain transaction for every request. This reduces latency to sub-100ms per call while still settling on-chain periodically. + +### How sessions work + +1. **Open a session** — deposit pathUSD (minimum $1.00, maximum $100.00) into escrow via `POST /api/wallet/sessions`. You can also fund your session via Stripe using the [wallet top-up](/api-reference/wallet#wallet-top-up) endpoint. +2. **Make gateway requests** — send requests to the [gateway](/api-reference/gateway) with `X-Session-Id` and `X-Wallet-Address` headers. The gateway auto-debits your session balance via an off-chain voucher on each call. You can also submit vouchers directly via `POST /api/wallet/sessions/voucher`. +3. **Automatic settlement** — when accumulated vouchers reach $5.00 or after one hour, the server batches them into a single on-chain transaction. +4. **Close the session** — call `DELETE /api/wallet/sessions?sessionId=ses_...` to settle any remaining vouchers and return unused funds. + +### Session configuration + +| Parameter | Value | Description | +|-----------|-------|-------------| +| Minimum deposit | $1.00 | Minimum amount to open a session | +| Maximum deposit | $100.00 | Maximum amount per session | +| Settle threshold | $5.00 | Accumulated voucher total that triggers on-chain settlement | +| Settle interval | 1 hour | Maximum time between on-chain settlements | + +### Session states + +| State | Description | +|-------|-------------| +| `active` | Session is open and accepting vouchers | +| `settling` | Vouchers are being settled on-chain (temporary) | +| `closed` | Session has been closed and remaining funds returned | + +### When to use sessions vs. per-request MPP + +- **Sessions** are ideal for high-frequency agent calls where sub-100ms billing latency matters (e.g., chat, real-time orchestration). The gateway auto-debits your session on each call when you provide `X-Session-Id` and `X-Wallet-Address` headers. +- **Per-request MPP** (the standard 402 flow) is better for infrequent or large-value calls where on-chain settlement per request is acceptable. + +See the [Wallet API — MPP payment sessions](/api-reference/wallet#mpp-payment-sessions) reference for the full endpoint documentation and the [Gateway API](/api-reference/gateway#session-billing) for how sessions integrate with the gateway. + ## Troubleshooting