AI Spending Guidelines

This guide provides recommended budget configurations for different AI agent use cases when using the pay_invoice tool.

How Budgets Are Configured

There are two layers of spending control, and they work together:

1. Operator limits (USD) — set in ~/.lightning-enable/config.json under limits.maxPerPayment and limits.maxPerSession. Only you can edit this file; no MCP tool can raise these values.
2. Runtime sats caps (tighten-only) — the configure_budget MCP tool lets an agent lower its per-request / per-session sats caps mid-session. It can never raise them above your config-file limits. Parameter names: per_request / per_session in the Python package, perRequest / perSession in .NET.
3. Out-of-band confirmation — payments above the auto-approve threshold return requiresConfirmation=true and the server prints a confirmation code to its console; you relay the code to the agent, which re-calls the original payment tool with confirmation_nonce=<code>. Full flow: AI Spending Security.

Legacy env vars removed

The L402_MAX_SATS_PER_REQUEST and L402_MAX_SATS_PER_SESSION environment variables have been removed from both packages (.NET and Python). Setting them does nothing. Use ~/.lightning-enable/config.json for operator limits and configure_budget for runtime tightening.

Quick Reference

Use Case	Per Request	Per Session	Wallet Balance
Testing/Development	100 sats	1,000 sats	5,000 sats
Light Browsing	50 sats	500 sats	2,000 sats
Research Sessions	200 sats	2,000 sats	10,000 sats
API Integration	500 sats	5,000 sats	20,000 sats
Heavy Usage	1,000 sats	10,000 sats	50,000 sats

To apply a row: set USD equivalents in config.json (the hard ceiling), then have the agent call configure_budget with the sats values (the runtime cap).

Configuration Examples

Minimal (Testing)

For initial testing and learning, set tight USD limits in ~/.lightning-enable/config.json:

{
  "limits": {
    "maxPerPayment": 0.10,
    "maxPerSession": 1.00
  }
}

Then tighten the runtime sats caps at the start of the session:

configure_budget per_request=100 per_session=1000

Wallet funding: 5,000 sats (~$5)

Use for:

• Learning how pay_invoice works
• Testing your MCP configuration
• Paying a few test invoices

Conservative (Light Usage)

For occasional, supervised use:

{
  "limits": {
    "maxPerPayment": 0.05,
    "maxPerSession": 0.50
  }
}

configure_budget per_request=50 per_session=500

Wallet funding: 2,000 sats (~$2)

Use for:

• Accessing a few L402-protected resources
• Light browsing of paid content
• One-off API calls

Moderate (Research)

For research sessions with multiple data sources:

{
  "limits": {
    "maxPerPayment": 0.25,
    "maxPerSession": 2.00
  }
}

configure_budget per_request=200 per_session=2000

Wallet funding: 10,000 sats (~$10)

Use for:

• Research involving multiple paid APIs
• Gathering data from various sources
• Extended work sessions

Professional (API Integration)

For development and integration work:

{
  "limits": {
    "maxPerPayment": 0.50,
    "maxPerSession": 5.00
  }
}

configure_budget per_request=500 per_session=5000

Wallet funding: 20,000 sats (~$20)

Use for:

• Testing API integrations
• Development workflows
• Automated data collection (supervised)

Cost Estimation

Common Operations

Operation	Typical Cost
Single API call	1-100 sats
Premium content access	10-500 sats
AI model API (per request)	50-200 sats
Data feed query	10-100 sats
Image generation	100-1000 sats
Lightning Enable Store purchase	25,000-45,000+ sats

Store Purchases Require Higher Limits

Lightning Enable Store products cost 25,000-45,000+ sats (including shipping). Default budget limits will reject these payments. To purchase from the store, raise the limits in ~/.lightning-enable/config.json (only you can do this — no MCP tool can raise limits):

{
  "limits": {
    "maxPerPayment": 50.00,
    "maxPerSession": 100.00
  }
}

Where the payment tool takes a maxSats / max_sats parameter (access_l402_resource, pay_l402_challenge, and the Python pay_invoice), also pass a large enough value (e.g., maxSats=50000) — the per-call default is 1,000 sats.

Session Estimates

Task Type	Estimated Cost
10-minute research	100-500 sats
1-hour development session	500-2,000 sats
Day of API testing	2,000-5,000 sats

Session Management

Starting a Session

1. Check wallet balance before starting
2. Review budget limits - are they appropriate?
3. Define scope - what will the AI be doing?
4. Monitor actively during first few uses

# Check balance before starting
get_balance

# Verify budget configuration
get_budget_status  # Shows current limits and session spending

During a Session

• Watch for unexpected payment patterns
• If limits are hit, only the operator can grant more budget — by editing ~/.lightning-enable/config.json (both packages; applied at restart). An agent cannot raise its own limits
• To narrow scope mid-session, tighten the caps further:

# configure_budget can only LOWER limits, never raise them
# (param names: per_request / per_session in the Python package; perRequest / perSession in .NET)
configure_budget per_request=200 per_session=2000

Ending a Session

• Review all payments made
• Check remaining balance
• Note any unexpected charges

# Review what was spent
get_payment_history limit=50

Budget Strategy

Start Low

Begin with minimal limits and increase only as needed:

1. Week 1: 100 sats/request, 1,000 sats/session
2. Week 2: Evaluate - were limits hit? Why?
3. Week 3: Adjust based on actual usage patterns
4. Ongoing: Find your comfortable baseline

Per-Request vs Per-Session

Per-request limit protects against:

• Single large accidental payment
• Overpaying for one service

Per-session limit protects against:

• Many small payments adding up
• Extended sessions draining funds
• Runaway loops

When to Increase Limits

Increase limits when:

• You consistently hit limits for legitimate use
• You understand why limits are being reached
• You're comfortable with the higher exposure

Do NOT increase limits:

• Just because limits were hit
• Without understanding what payments were made
• To avoid supervision

Refill Strategy

Recommended Approach

1. Keep wallet balance low - Only what you need for near-term use
2. Refill frequently in small amounts
3. Never exceed what you're willing to lose
4. Track refills to understand true spending over time

Example Refill Schedule

Usage Level	Refill Amount	Frequency
Light	5,000 sats	Monthly
Moderate	10,000 sats	Bi-weekly
Heavy	25,000 sats	Weekly

Troubleshooting Budget Issues

"Exceeds per-request limit"

Your payment request is larger than the effective per-request cap — either limits.maxPerPayment in ~/.lightning-enable/config.json, a tighter runtime cap the agent set via configure_budget, or the tool call's own maxSats parameter.

Options:

1. Increase limits.maxPerPayment in the config file (operator only) if the payment is legitimate, and pass a larger maxSats on the tool call
2. Find alternative service with lower cost
3. Skip the payment if not essential

"Would exceed session budget"

You've spent most of your session budget.

Options:

1. Start a fresh session (restart the MCP server) — the session counter is not agent-resettable
2. Increase the session budget in ~/.lightning-enable/config.json (operator only, with caution)
3. End session and review payments

Wallet balance low

Your wallet/payment provider account needs more funds.

Options:

1. Add funds via your payment provider dashboard (Strike or OpenNode)
2. Transfer from another Lightning wallet
3. Adjust budget limits to match available funds

Related Documentation

• AI Spending Security - Security best practices
• Legal Considerations - Liability and terms
• MCP Configuration - Setting up MCP