Skip to main content

​
Request Lifecycle

When your application makes an AI API request through Lava, here’s the complete flow:

​
1. Authentication

Your application sends a request with a forward token in the Authorization header. This token contains:
  • Your merchant secret key
  • The connection identifier (links to a specific wallet)
  • Optional product configuration (for custom pricing)
Authorization: Bearer <base64_encoded_token>
Lava validates this token against a Redis cache for low-latency authentication (under 5ms).

​
2. Balance Check

Before forwarding the request, Lava checks:
  • Does the wallet have sufficient credits?
  • Is the connection active and not deleted?
  • Are there any spending limits or quotas?
If funds are insufficient, Lava can either block the request or allow overdraft based on your product configuration.

​
3. Request Forwarding

Lava forwards your request to the AI provider with:
  • Transparent proxying: The request body remains unchanged
  • Provider authentication: Lava adds the appropriate API key for the provider
  • Streaming support: Server-sent events (SSE) work seamlessly
The target URL is specified via the ?u= query parameter: 
https://api.lavapayments.com/v1/forward?u=https://api.openai.com/v1/chat/completions

​
4. Response & Metering

When the AI provider responds:
  • Lava parses the response to extract usage data (tokens, characters, duration)
  • Calculates costs based on the provider’s pricing and your configured fees
  • Records the request in the database with full metadata
  • Returns the response to your application with usage headers
Response Headers: 
x-lava-request-id: req_01234567890abcdef
The x-lava-request-id header is added for request tracking. Usage and cost data come from the response body (data.usage), not headers.

​
5. Billing & Settlement

After the request completes:
  • Creates transfer records in the internal ledger
    • Base cost transfer (to AI provider)
    • Fee transfer (to merchant)
    • Service charge transfer (to Lava)
  • Deducts amounts from the wallet’s active balance
  • Updates connection status if balance falls below threshold

​
Streaming Support

Lava fully supports Server-Sent Events (SSE) for real-time streaming responses:
All major LLM providers support streaming:
  • OpenAI (GPT models)
  • Anthropic (Claude models)
  • Google (Gemini models)
  • Mistral, xAI, DeepSeek
  • Groq, Fireworks, together.ai
  • And all other LLM platforms
  1. Your request includes "stream": true in the body
  2. Lava detects streaming and forwards the request
  3. Lava streams the response back to you in real-time
  4. Usage data is extracted from the final SSE message
  5. Billing happens after the stream completes
Lava adds the request tracking header:
x-lava-request-id: req_01234567890abcdef
Usage data comes from the response body’s final SSE message, not headers.

​
Next Steps

Authentication Model

Learn about forward tokens and authentication validation

Forward Proxy Guide

Integrate Lava’s proxy into your application