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

{
  "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) 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.
2. MPP — Crypto-native payments on the Tempo blockchain. See MPP payments.

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:

{
  "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)

{
  "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 GET, 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)

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

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