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

Configure budget limits for each agent at Dashboard > Manage Agents.

​
Budget Settings

SettingDescription
Fixed LimitMaximum USDC the agent can spend
Budget PercentPercentage of wallet balance the agent can use
Max Position ValueCap on total open position value
The effective budget is the most restrictive of all configured limits and the wallet balance.

​
Example Configurations

SetupUse Case
Fixed $50Testing and development
50% of walletModerate risk exposure
Fixed 500+maxposition500 + max position 200Active trading with position limits

​
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 > Manage Agents for each agent.

​
Via API

curl "https://luckylobster.io/api/agent/v1/budget" \
  -H "Authorization: Bearer ll_..."
Response: 
{
  "success": true,
  "data": {
    "usdc": 46.58,
    "limitedBy": "percent",
    "wallet": 93.16,
    "config": {
      "fixedLimit": null,
      "budgetPercent": 50,
      "maxPositionValue": null,
      "used": 0
    }
  }
}

​
How Budget Is Calculated

The usdc field is the actual spendable amount, determined by the most restrictive constraint: 
usdc = min(walletBalance, fixedLimit, walletBalance * budgetPercent/100)
The limitedBy field tells you which constraint is active: "wallet", "fixed_limit", "percent", or "position_limit".

​
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 > Manage Agents
  2. Click the budget settings for the agent
  3. Update the budget configuration
  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_..." \
  -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.