> ## Documentation Index > Fetch the complete documentation index at: https://raveculture-mintlify-api-spec-sync-1774445910.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Gateway > Route requests to plugins through the v1 gateway with support for Stripe, MPP, and session-based payments. # Gateway The v1 gateway routes incoming requests to registered plugins. It supports three payment methods — Stripe (existing), [MPP](/payments/mpp) (Machine Payments Protocol) via the Tempo blockchain, and session-based billing for low-latency, off-chain per-call payments. ## Base URL ``` POST /api/v1/gateway ``` ## Request ### Headers | Header | Type | Required | Description | | ------------------ | ------ | -------- | -------------------------------------------------------------------------------------------------- | | `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`, `mpp`, or `session`. Defaults to `stripe`. | | `Authorization` | string | No | For MPP payments, use `Payment `. For session auth, handled via cookies. | | `X-Session-Id` | string | No | Active session ID for session-based billing. Required when `X-Payment-Method` is `session`. | | `X-Wallet-Address` | string | No | Wallet address that owns the session (0x-prefixed). Required when `X-Payment-Method` is `session`. | | `Accept` | string | No | Set to `text/event-stream` for streaming responses (where supported). | ### Body ```json theme={null} { "plugin": "generate-text", "messages": [{ "role": "user", "content": "Hello" }] } ``` | 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`. | Additional body fields are forwarded to the target plugin. ## Plugins 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 | `generate-text` is the default plugin when no plugin ID is specified. ## Authentication Protected plugins require either a valid session (cookie-based via NextAuth), a verified MPP payment credential, or an active payment session. If you pay with MPP or use session-based billing, cookie-based authentication is not required. ## Payment flow 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). 3. **Session** — Off-chain, per-call billing using a pre-funded payment session. See [MPP payments — sessions](/payments/mpp#sessions) and the [wallet sessions API](/api-reference/wallet#mpp-payment-sessions). The server selects the payment method using the following priority: 1. `X-Payment-Method` header (`session`, `mpp`, or `stripe`) 2. Presence of an `Authorization: Payment` header (implies `mpp`) 3. Default: `stripe` ### MPP 402 challenge When an MPP request has no valid credential, the gateway returns `402 Payment Required` with pricing information for both payment methods: ```json theme={null} { "error": "payment_required", "message": "Payment required for agent. Choose payment method: Stripe or Tempo MPP.", "mpp": { "scheme": "Payment", "amount": "0.05", "currency": "0x20c0000000000000000000000000000000000000", "recipient": "0xd8fd0e1dce89beaab924ac68098ddb17613db56f", "description": "Agent orchestrator request", "nonce": "a1b2c3d4e5f6...", "expiresAt": 1742472000000 }, "stripe": { "checkoutUrl": "/api/v1/payments/stripe/create?plugin=agent", "amount": "0.05", "currency": "usd" } } ``` The `WWW-Authenticate` header is also set: ``` Payment amount="0.05", currency="0x20c0000000000000000000000000000000000000", recipient="0xd8fd0e1dce89beaab924ac68098ddb17613db56f" ``` ### Session-based billing When `X-Payment-Method` is `session`, the gateway auto-debits the caller's payment session using an off-chain voucher. This avoids the 402 challenge/response round-trip and settles each call in sub-100ms. To use session-based billing: 1. Open a payment session via `POST /api/wallet/sessions`. See [wallet sessions](/api-reference/wallet#mpp-payment-sessions). 2. Include `X-Session-Id` and `X-Wallet-Address` headers on every gateway request. 3. The gateway looks up the session, verifies the balance covers the plugin price, and debits the session automatically. 4. The response includes a `Payment-Receipt` header with the voucher reference and an `X-Session-Remaining` header with the updated balance. If the session is missing, expired, or has insufficient balance, the gateway returns `402` with a descriptive error. See [error responses](#error-responses) for the full list of session-related error codes. ## Response ### Success (200) ```json theme={null} { "plugin": "generate-text", "message": "Request processed by generate-text plugin", "timestamp": "2026-03-20T03:33:15.000Z", "payment": { "method": "stripe", "receipt": null } } ``` When paid via MPP, the response includes a `Payment-Receipt` header and the `payment.receipt` field contains the transaction hash. When paid via a session, the `payment.receipt` field contains the voucher reference (formatted as `session::`). ### Response headers | Header | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `x-plugin-id` | The plugin that handled the request | | `Payment-Receipt` | Payment receipt. For MPP: transaction hash. For sessions: voucher reference (`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 | | ------ | ---------------------- | --------------------------------------------------------------------------------------------------------------- | | 400 | `unknown_plugin` | No pricing configured for the requested 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 billing was requested but `X-Session-Id` or `X-Wallet-Address` header is missing | | 402 | `session_invalid` | No active session found for the provided session ID and wallet address | | 402 | `insufficient_balance` | Session balance is too low to cover the plugin price. Response includes `session.remaining` and `session.cost`. | | 402 | `voucher_failed` | The off-chain voucher could not be processed (e.g., concurrent debit race) | | 500 | `internal` | Internal server error | | 502 | `no_plugin` | No plugin registered for the given ID | ## Per-agent gateway authentication Each agent container receives a unique gateway auth token at provisioning time. The internal gateway authenticates requests using token-based auth on port `18789`. | Field | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `gateway.auth.mode` | `token` | | `gateway.auth.token` | Unique hex token auto-generated per container. Provisioning generates a 48-character token (24 bytes of entropy). The container entrypoint generates a 32-character token (16 bytes) if no token is passed via the `OPENCLAW_GATEWAY_TOKEN` environment variable. | | `gateway.port` | `18789` | The container entrypoint writes its own minimal configuration to `$HOME/.openclaw/openclaw.json` using a slightly different schema (`auth.method` at the top level instead of `gateway.auth.mode`). The provisioning config written by the backend uses the `gateway.auth.mode` path. When the entrypoint runs, it overwrites the provisioning config with its own minimal skeleton. To preserve the full provisioning config, pass the gateway token via the `OPENCLAW_GATEWAY_TOKEN` environment variable so the entrypoint uses the same token. ## Agent container configuration When an agent is provisioned, the backend generates an OpenClaw configuration with the following parameters. These values are set automatically and cannot be overridden by the caller. ### Container environment variables The following environment variables are set on every agent container at launch: | Variable | Default | Description | | ------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 | Parameter | Value | Description | | ----------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tools.profile` | `messaging` or `coding` | `messaging` for solo plan, `coding` for all other plans | | `tools.deny` | `["browser", "canvas"]` | Tools disabled in container environments | | `tools.exec.allowedCommands` | Array of whitelisted commands | Commands the agent is permitted to execute (includes `git`, `node`, `npm`, `python3`, `curl`, `ls`, `cat`, `grep`, `find`, `wget`, `mkdir`, `cp`, `mv`, `rm`, `echo`, `date`, `whoami`, `chmod`, `chown`, `touch`, `head`, `tail`, `wc`, `sort`, `uniq`, `awk`, `sed`, `tar`, `zip`, `unzip`, `docker`, `ps`, `df`, `du`) | | `tools.exec.allowedPaths` | `["~/.openclaw/workspace", "/tmp", "/home/node"]` | Filesystem paths the agent can access. The official OpenClaw image runs as the `node` user (`/home/node`). Configuration is stored at `/home/node/.openclaw/openclaw.json`. | | `tools.exec.denyPaths` | `["/etc/shadow", "/etc/passwd", "/proc", "/sys"]` | Filesystem paths the agent is blocked from accessing | | `tools.web.maxChars` | `50000` | Maximum characters returned from web tool requests | | `tools.loopDetection.maxIterations` | `20` | Maximum loop iterations before the agent is interrupted | | `tools.loopDetection.windowMinutes` | `5` | Time window for loop detection | ### Session settings | Parameter | Value | Description | | ------------------------------------- | -------- | ------------------------------------------------------------ | | `session.maxTokens` | `100000` | Maximum tokens per session | | `session.compaction.strategy` | `auto` | Automatic context compaction strategy | | `session.compaction.triggerAtPercent` | `80` | Compaction triggers when token usage reaches this percentage | ### Agent defaults | Parameter | Value | Description | | ---------------------------------------- | ----------------------- | ---------------------------------------------------------------- | | `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 | | `agents.defaults.heartbeat.every` | `30m` | Self-monitoring heartbeat interval | | `agents.defaults.skipBootstrap` | `false` | Whether to skip the bootstrap phase | | `agents.defaults.bootstrapMaxChars` | `4000` | Maximum characters for bootstrap content | ## Health monitoring The gateway monitors channel health for each agent container. When a channel becomes unresponsive, the gateway can automatically restart it. | Parameter | Value | Description | | ----------------------------------- | ----- | ------------------------------------------------------------------------ | | `channelHealthCheckMinutes` | `5` | Interval between health checks for each channel | | `channelStaleEventThresholdMinutes` | `30` | Channel is considered stale if no events are received within this window | | `channelMaxRestartsPerHour` | `10` | Maximum number of automatic channel restarts per hour | ## CORS The gateway supports CORS preflight via `OPTIONS /api/v1/gateway`. Allowed methods are `POST` and `OPTIONS`. The `Authorization`, `Content-Type`, `X-Plugin-Id`, `X-Payment-Method`, `X-Session-Id`, and `X-Wallet-Address` headers are permitted. ## Rate limits | Endpoint | Limit | | ----------------- | ------- | | `/api/v1/gateway` | 100/min | ## Examples ### Route a request to the agent plugin (Stripe) ```bash theme={null} curl -X POST https://agentbot.raveculture.xyz/api/v1/gateway \ -H "Content-Type: application/json" \ -H "X-Plugin-Id: agent" \ -H "Cookie: next-auth.session-token=YOUR_SESSION" \ -d '{"messages": [{"role": "user", "content": "Summarize my tasks"}]}' ``` ### Route a request with MPP payment ```bash theme={null} curl -X POST https://agentbot.raveculture.xyz/api/v1/gateway \ -H "Content-Type: application/json" \ -H "X-Plugin-Id: generate-text" \ -H "Authorization: Payment {\"scheme\":\"Payment\",\"transaction\":\"0x76...\",\"challengeNonce\":\"abc123\"}" \ -d '{"messages": [{"role": "user", "content": "Hello"}]}' ``` ### Route a request with session-based billing ```bash theme={null} curl -X POST https://agentbot.raveculture.xyz/api/v1/gateway \ -H "Content-Type: application/json" \ -H "X-Plugin-Id: agent" \ -H "X-Payment-Method: session" \ -H "X-Session-Id: ses_a1b2c3d4e5f6..." \ -H "X-Wallet-Address: 0xd8fd0e1dce89beaab924ac68098ddb17613db56f" \ -d '{"messages": [{"role": "user", "content": "Summarize my tasks"}]}' ``` The response includes the remaining session balance: ``` Payment-Receipt: session:ses_a1b2c3d4e5f6...:v_abc123def456 X-Session-Remaining: 9.95 ```