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 |
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 (from X-Provider-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)
- X-Provider-Key is reconstructed as the standard Authorization header
- The request is forwarded to the upstream provider with the original path 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
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_...) |
| X-Provider-Key | Request | Your provider API key (Bearer sk-...). Reconstructed as Authorization before forwarding. |
| X-SpendLil-Route | Response | governed (tracked) or bypassed (tracking failed) |
| X-SpendLil-Request-Id | Response | Unique ID for this proxied request |
AWS API Gateway intercepts the standard Authorization header. SpendLil uses X-Provider-Key to pass your provider key through without interference, then reconstructs it as Authorization before forwarding upstream.
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.