Skip to main content

Documentation Index

Fetch the complete documentation index at: https://lava.so/docs/llms.txt

Use this file to discover all available pages before exploring further.

Lava bills paid providers from your account balance. Free providers run without funds; paid providers (most model APIs and many data services) charge per call. This guide covers funding, balance checks, usage history, and what to do when a call fails on insufficient balance. Your account balance is sometimes called your wallet balance — same number, different label. The dashboard uses “wallet” as the section name; the chat tools (get_balance, add_funds) operate on the same balance.

​
Prerequisites

  • A Lava account.
  • The Lava MCP installed in your AI chat. See the Quickstart if you haven’t done this yet.

​
Add Funds via the Dashboard

The dashboard is the simplest path for the first deposit, since it lets you save a payment method for later in-chat top-ups.
  1. Open https://www.lava.so/dashboard/wallet.
  2. Click “Add Funds”.
  3. Enter an amount between 10and10 and 10,000.
  4. Add a payment method or select a saved one.
  5. Confirm the charge.
Expected result. Your wallet balance increases by the amount you charged. The new balance shows in the dashboard header.

​
Add Funds from Your Chat

Once you have a saved payment method, you can top up without leaving the chat. Type: 
Add $25 to my Lava wallet.
The chat calls add_funds with the amount. There are three possible outcomes:
  • You have a saved payment method. Lava charges it directly and returns the new balance.
  • You have no saved payment method. Lava returns a hint suggesting use_checkout: true. Ask the chat to open the browser checkout: 
    Open the Lava checkout to add $25.
    Lava returns a checkout URL. Open it, complete payment in the browser, and return to your chat.
  • You called add_funds with no arguments. Lava returns your saved payment methods plus current wallet state, so you can pick a method.
The minimum charge is 10.Themaximumis10. The maximum is 10,000. Expected result. After a successful charge, asking the chat for your balance returns the new total.

​
Check Your Balance

From the chat: 
What's my Lava balance?
The chat calls get_balance and returns the current wallet balance: 
{
  "balance": "47.50"
}
The balance is in USD, expressed as a decimal string. The dashboard’s wallet page (https://www.lava.so/dashboard/wallet) shows the same balance, plus a chart of recent activity.

​
Review Usage

Lava tracks every call your chat makes. Two views:

​
Daily Summary (Default)

Ask the chat for a summary: 
Show me my Lava usage for the last 7 days.
The chat calls get_usage_history in summary mode. It returns daily aggregates: spend per day, request counts per day, broken out by provider. To widen the window, name a start date: 
Show me my Lava usage since April 1.
The chat passes an ISO 8601 start date. Optionally pass end to bound the window on both sides.

​
Per-Request List

Ask for individual calls: 
Show me my last 20 Lava requests with cost breakdown.
The chat calls get_usage_history with mode: "requests" and limit: 20. Each entry shows the provider, model (if applicable), cost, and status. Pagination uses the returned cursor.

​
Insufficient-Balance Behavior

When a paid call exceeds your wallet balance, Lava returns: 
{
  "error": "Insufficient wallet balance",
  "code": 402
}
Your chat surfaces this back to you. The call did not run; you weren’t charged.

​
How to Recover

  1. Top up the wallet — see Add Funds from Your Chat above. The minimum is $10.
  2. Retry the call.
If you hit insufficient-balance frequently and want a buffer, set a higher balance from the dashboard and check get_usage_history to size your top-ups against actual spend.

​
Spend Keys (Advanced)

Lava also supports Spend Keys — API keys with a wallet attached, useful for sharing budget with agents or other tools without sharing your account. Spend Keys are configured outside the MCP. See Spend Keys overview for setup.

​
Troubleshooting

​
”I funded but the chat still shows zero balance”

Some chat clients cache balance. Ask the chat for the balance again, or refresh the dashboard.

​
”Payment method failed”

Check the dashboard for the failure reason. Common causes: card declined by the issuer, expired card, billing address mismatch. Update the payment method in https://www.lava.so/dashboard/wallet and retry.

​
”I want to charge in a currency other than USD”

Lava bills in USD only. Currency conversion happens at the card issuer’s exchange rate.

​
Next Steps