Spend keys are scoped API keys that work as drop-in replacements for provider API keys. Use them to give agents, team members, or developer tools access to AI models with built-in spend limits, model restrictions, and rate controls.
How Spend Keys Work
A spend key is an OpenAI-compatible API key that routes through Lava’s gateway. Any tool that accepts an OpenAI API key can use a Lava spend key instead. You control which models are allowed, how much can be spent, and how fast requests can be made.
Create a Spend Key
Spend keys are wallet-scoped, so use your wallet key:
import { Lava } from '@lavapayments/nodejs';
const wallet = new Lava(process.env.LAVA_WALLET_KEY);
const spendKey = await wallet.spendKeys.create({
name: 'Agent - Production',
allowed_providers: ['openai', 'anthropic'],
allowed_models: ['gpt-4o-mini', 'claude-sonnet-4-20250514'],
spend_limit: {
amount: '50.00',
cycle: 'monthly'
},
rate_limit: {
rpm: 60
}
});
// Save this immediately - the full key is only shown once
console.log('Spend key:', spendKey.key);
console.log('Key ID:', spendKey.spend_key_id);
The full key value is only returned when you create or rotate a spend key. Store it securely right away.
Spend key options
| Parameter | Options | Description |
|---|
allowed_providers | Array of provider names, or null for all | Restrict which providers can be used |
allowed_models | Array of model IDs, or null for all | Restrict which models can be used |
request_shape | openai, anthropic | Request format (default: openai) |
spend_limit | { amount, cycle } | Max spend per cycle (daily, weekly, monthly, total) |
request_limit | { count, cycle } | Max requests per cycle |
rate_limit | { rpm, burst? } | Requests per minute, with optional burst allowance |
expires_at | ISO 8601 date, or null | Auto-expire the key after a date |
status | active, paused | Pause a key without revoking it |
Use a Spend Key
Spend keys work anywhere an OpenAI API key is accepted. Point the tool at Lava’s base URL and use the spend key as the API key.
With the OpenAI SDK
import OpenAI from 'openai';
const openai = new OpenAI({
apiKey: spendKey.key,
baseURL: 'https://api.lava.so/v1'
});
const completion = await openai.chat.completions.create({
model: 'gpt-4o-mini',
messages: [{ role: 'user', content: 'Hello!' }]
});
With the Anthropic SDK
For Anthropic-shaped requests, create the key with request_shape: 'anthropic':
const anthropicKey = await wallet.spendKeys.create({
name: 'Agent - Anthropic',
request_shape: 'anthropic',
allowed_providers: ['anthropic'],
spend_limit: { amount: '100.00', cycle: 'monthly' }
});
import Anthropic from '@anthropic-ai/sdk';
const anthropic = new Anthropic({
apiKey: anthropicKey.key,
baseURL: 'https://api.lava.so' // No /v1 — Anthropic SDK appends it
});
const message = await anthropic.messages.create({
model: 'claude-sonnet-4-20250514',
max_tokens: 1024,
messages: [{ role: 'user', content: 'Hello!' }]
});
Update a Spend Key
Change restrictions on an existing key without rotating the key itself:
await wallet.spendKeys.update(spendKey.spend_key_id, {
allowed_models: ['gpt-4o-mini'], // Restrict to a cheaper model
spend_limit: { amount: '100.00', cycle: 'monthly' } // Increase limit
});
Rotate a Key
Generate a new key value for the same spend key. The old key stops working immediately:
const rotated = await wallet.spendKeys.rotate(spendKey.spend_key_id);
console.log('New key:', rotated.key); // Full key, shown once
Monitor Spend
Check current spend and usage for a key:
const keys = await wallet.spendKeys.list();
for (const key of keys.data) {
console.log(`${key.name}: $${key.current_spend} spent (limit: $${key.spend_limit?.amount ?? 'none'})`);
console.log(` ${key.current_requests} requests, last used: ${key.last_used_at ?? 'never'}`);
}
Revoke a Key
Permanently disable a spend key:
await wallet.spendKeys.revoke(spendKey.spend_key_id);
What’s Next?
