Last updated: 2026-04-20
How the Proxy Works
Understanding SpendLil's transparent proxy architecture.
SpendLil operates as a transparent proxy between your application and your AI provider. It observes and logs every request without modifying, storing, or blocking anything.
Provider Gateways
Each AI provider has its own gateway subdomain. You swap your provider's base URL for the corresponding gateway — the path stays identical.
| Provider | Gateway | Upstream |
|---|---|---|
| OpenAI | openai.gateway.spendlil.ai | api.openai.com |
| Anthropic | anthropic.gateway.spendlil.ai | api.anthropic.com |
| google.gateway.spendlil.ai | generativelanguage.googleapis.com | |
| Mistral | mistral.gateway.spendlil.ai | api.mistral.ai |
| Groq | groq.gateway.spendlil.ai | api.groq.com |
| DeepSeek | deepseek.gateway.spendlil.ai | api.deepseek.com |
| xAI (Grok) | xai.gateway.spendlil.ai | api.x.ai |
| Together | together.gateway.spendlil.ai | api.together.xyz |
| Fireworks | fireworks.gateway.spendlil.ai | api.fireworks.ai |
| Perplexity | perplexity.gateway.spendlil.ai | api.perplexity.ai |
| OpenRouter | openrouter.gateway.spendlil.ai | openrouter.ai/api |
| Cohere | cohere.gateway.spendlil.ai | api.cohere.com |
The Request Flow
- Your request hits the provider-specific gateway (e.g., openai.gateway.spendlil.ai/v1/chat/completions)
- The X-SpendLil-Key header is validated against DynamoDB to identify your account
- The provider is determined from the gateway subdomain
- Your provider API key (extracted from Authorization / x-api-key / x-goog-api-key) is hashed with SHA-256 — the key itself is never stored
- If this is a new key hash, a record is created automatically (auto-discovery)
- The request is forwarded to the upstream provider with your original auth header intact
- The provider processes the request and returns a response
- SpendLil extracts token usage counts from the response body
- Cost is calculated using the model pricing table and your account's currency
- A usage record is written to DynamoDB (fire-and-forget)
- Your daily spend counter is atomically incremented
- The provider's response is returned to your app with X-SpendLil-Route and X-SpendLil-Request-Id headers
Fire-and-forget logging
Usage logging is non-blocking. If the DynamoDB write fails, you still get your AI response.
Headers
| Header | Direction | Description |
|---|---|---|
| X-SpendLil-Key | Request | Your SpendLil account key (sl_...). Required. |
| Authorization | Request | Your provider API key for OpenAI, Mistral, Cohere, Groq, DeepSeek, xAI, Together, Fireworks, Perplexity, OpenRouter. Passed through unchanged. |
| x-api-key | Request | Anthropic native auth. Passed through unchanged. |
| x-goog-api-key | Request | Google Gemini auth. Passed through unchanged. |
| X-SpendLil-Tag | Request | Optional label for filtering spend by workload (max 64 chars) |
| X-SpendLil-Route | Response | governed (tracked) or bypassed (tracking failed) |
| X-SpendLil-Request-Id | Response | Unique ID for this proxied request |
What SpendLil Does NOT Do
- Does not store your API keys — passthrough only
- Does not modify your request body
- Does not modify the provider's response body
- Does not block or rate-limit any requests
- Does not read or store the content of your prompts or completions
Infrastructure
The proxy runs on AWS Lambda behind API Gateway in eu-west-2 (London). Each provider subdomain has its own API Gateway custom domain with Route 53 health checks and UptimeRobot monitoring. All gateways report to status.spendlil.ai.