API Reference
API Overview
Solvela REST API reference — OpenAI-compatible with x402 payment
The Solvela API is OpenAI-compatible. Any client that works with the OpenAI API works with Solvela with two changes: set the base URL and add x402 payment handling.
Base URL
https://api.solvela.aiFor local development (after cargo run -p gateway):
http://localhost:8402Authentication
Solvela does not use API keys. Authentication is payment — include a valid payment-signature header with every request that requires payment. See x402 Protocol for how to construct this header.
payment-signature: <base64-encoded PaymentPayload JSON>Request format
All endpoints accept and return application/json. Streaming responses use SSE (text/event-stream).
Common headers
| Header | Description |
|---|---|
Content-Type: application/json | Required for all POST requests |
payment-signature: <value> | Required for paid endpoints (chat completions) |
X-Request-Id: <uuid> | Optional — tracked in usage logs |
X-Session-Id: <string> | Optional — correlates requests in a session |
X-Solvela-Debug: true | Optional — attaches routing diagnostics (X-Solvela-Model, -Tier, -Score, -Provider, -Cache, -Payment-Status, etc.) to the response. Legacy X-RCR-Debug is also accepted. |
Endpoints
Other endpoints
| Method | Path | Description |
|---|---|---|
GET | /health | Gateway health and Solana RPC connectivity |
GET | /metrics | Prometheus metrics |
GET | /v1/supported | Supported payment networks and schemes |
GET | /v1/nonce | Fetch a durable nonce for replay-safe transactions |
POST | /v1/images/generations | Image generation (OpenAI-compatible) |
POST | /v1/messages | Anthropic-native relay — forwards a validated Anthropic request byte-for-byte to Anthropic-provider models, preserving thinking-block signatures, redacted_thinking, and native tool_use (only usage is parsed, for billing). Single-turn works today; multi-turn extended thinking is not yet supported. |
POST | /v1/search | x402-paid web search ($0.01/query + 5% platform fee). Returns normalized title/url/snippet. |
GET | /v1/services | Lists the x402 service-marketplace tools (e.g. web search) with per-call pricing |
POST | /v1/escrow/settle | Client-initiated early escrow claim after stream completion (see Escrow → F4 settle) |
GET | /.well-known/agent-card.json | A2A AgentCard for agent discovery (v0.3 canonical path; /.well-known/agent.json kept as alias) |
POST | /a2a | A2A protocol JSON-RPC endpoint |
Rate limiting
The gateway enforces a per-client rate limit, identifying the client as the payer wallet derived from the signed transaction first, then falling back to the TCP peer IP, then to a stricter shared "unknown" bucket. The default is 60 requests per 60-second fixed window per identified client (10 for the shared unknown bucket). Always read X-RateLimit-Limit and X-RateLimit-Reset from response headers rather than hardcoding expected values. Exceeding the limit returns 429 Too Many Requests. See Rate Limits.
Error format
Most errors use the OpenAI-style envelope with type and message:
{
"error": {
"type": "bad_request",
"message": "human-readable description"
}
}Exception: a 402 returned because no payment-signature header was supplied emits the PaymentRequired object at the top level of the response body — not wrapped in an envelope. See Error Reference for the full list of status codes and shapes.
Note
The gateway degrades gracefully when Redis or PostgreSQL are unavailable. Redis absence disables response caching and falls back to in-memory replay protection. PostgreSQL absence disables spend logging and budget enforcement.