> ## Documentation Index
> Fetch the complete documentation index at: https://raveculture-mintlify-api-provision-docs-1774045983.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 and MPP 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.

## 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` or `mpp`. Defaults to `stripe`.                      |
| `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).                |

### 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        |

<Note>`generate-text` 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.

## Payment flow

The gateway supports two 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).

The server selects the payment method using the following priority:

1. `X-Payment-Method` header (`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"
```

## 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.

### 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) |

## Error responses

| Status | Error code         | Description                                                                           |
| ------ | ------------------ | ------------------------------------------------------------------------------------- |
| 401    | `Unauthorized`     | Authentication required for a protected plugin and no valid session or MPP credential |
| 402    | `payment_required` | MPP payment required. Response includes challenge and pricing.                        |
| 500    | `internal`         | Internal server error                                                                 |
| 502    | `no_plugin`        | No plugin registered for the given ID                                                 |

## 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.

## 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"}]}'
```