Skip to main content

​
Overview

Budget limits are a critical safety feature that cap how much an API key can spend. This protects against bugs, unexpected behavior, and compromised keys.

​
How Budget Limits Work

  1. Agent submits an order
  2. LuckyLobster calculates order cost: price × size
  3. Compares against remaining budget
  4. If sufficient, executes and updates usage
  5. If exceeded, rejects with budget details

​
Configuring Budgets

​
Budget Limit

The maximum amount (in USDC) the API key can spend.
ExampleUse Case
$50Testing and development
$500Small trading agent
$5,000Active trading strategy
UnlimitedAdvanced users (not recommended)

​
Budget Period

When the spent amount resets to zero.
PeriodResets
dailyEvery day at midnight UTC
weeklyEvery Monday at midnight UTC
monthlyFirst of each month at midnight UTC
neverNever resets (lifetime limit)

​
Budget Enforcement

​
Order Placement

When placing an order, budget is checked: 
{
  "success": false,
  "error": "Budget Exceeded",
  "message": "Order cost ($55.00) would exceed budget limit",
  "budget": {
    "limit": 100,
    "used": 80,
    "remaining": 20,
    "activePositionValue": 150,
    "maxPositionValue": 500
  }
}

​
What Counts Toward Budget

CountsDoesn’t Count
Order cost at placementUnrealized gains
Filled trade valueMarket research
FeesViewing positions

​
Checking Your Budget

​
Via Dashboard

View budget usage at Dashboard > API Keys for each key.

​
Via API

curl "https://luckylobster.io/api/agent/v1/budget" \
  -H "Authorization: Bearer ll_live_..."
Response: 
{
  "success": true,
  "data": {
    "limit": 1000,
    "used": 250.50,
    "remaining": 749.50,
    "period": "monthly",
    "resetsAt": "2024-02-01T00:00:00Z",
    "walletBalance": 1250.00,
    "effectiveLimit": 749.50
  }
}

​
Effective Limit

The effectiveLimit is the actual spendable amount: 
effectiveLimit = min(budgetRemaining, walletBalance)
If your wallet has 500butbudgetremainingis500 but budget remaining is 200, you can only spend $200.

​
Position Limits

In addition to spending budgets, you can configure position limits:
SettingDescription
Max Position ValueMaximum value of all open positions
Max Single PositionMaximum size of any single position
These prevent concentration risk and limit exposure.

​
Best Practices

Begin with a low budget ($50-100) and increase as you verify agent behavior. It’s easier to increase limits than recover from losses.
  • Use daily for high-frequency strategies that need fresh limits each day
  • Use monthly for steady strategies with predictable spending
  • Use never for fixed-allocation strategies
Regularly check budget utilization in the dashboard. If an agent consistently hits limits, it might need adjustment or investigation.
Configure notifications (coming soon) for when budget usage exceeds thresholds like 80%.

​
Increasing Limits

To increase an API key’s budget:
  1. Go to Dashboard > API Keys
  2. Click on the key to edit
  3. Update the Budget Limit field
  4. Save changes
Changes take effect immediately. Be sure you want to increase spending capacity before confirming.

​
Dry Run Testing

Use dryRun: true in orders to test budget validation without spending: 
curl -X POST "https://luckylobster.io/api/agent/v1/orders" \
  -H "Authorization: Bearer ll_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tokenId": "...",
    "side": "BUY",
    "price": 0.55,
    "size": 100,
    "dryRun": true
  }'
This validates all budget constraints without placing a real order.