API Overview | Solvela

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

For local development (after cargo run -p gateway):

http://localhost:8402

Authentication

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-Debug-Payment: true`	Optional — returns cost breakdown in response headers

Endpoints

POST /v1/chat/completions→

GET /v1/models→

GET /pricing→

Error Reference→

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/escrow/settle`	Client-initiated early escrow claim after stream completion (see Escrow → F4 settle)
`GET`	`/.well-known/agent.json`	A2A AgentCard for agent discovery
`POST`	`/a2a`	A2A protocol JSON-RPC endpoint

The gateway enforces per-IP and per-wallet rate limits. The default is 60 requests per 60-second sliding window per wallet (and the same per IP, before wallet identity is established). 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. Enterprise API keys can override these limits — see Rate Limits.

Error format

All errors use the OpenAI error envelope:

{
  "error": {
    "message": "human-readable description"
  }
}

For 402 responses, error.message contains a JSON-encoded PaymentRequired object. See Error Reference for the full list of status codes.

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.