Budget Limits

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

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

Configuring Budgets

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

Budget Settings

Setting	Description
Fixed Limit	Maximum USDC the agent can spend
Budget Percent	Percentage of wallet balance the agent can use
Max Position Value	Cap on total open position value

The effective budget is the most restrictive of all configured limits and the wallet balance.

Example Configurations

Setup	Use Case
Fixed $50	Testing and development
50% of wallet	Moderate risk exposure
Fixed $500 + max position$ 200	Active 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

Counts	Doesn’t Count
Order cost at placement	Unrealized gains
Filled trade value	Market research
Fees	Viewing 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:

Setting	Description
Max Position Value	Maximum value of all open positions
Max Single Position	Maximum size of any single position

These prevent concentration risk and limit exposure.

Best Practices

Start Conservative

Begin with a low budget ($50-100) and increase as you verify agent behavior. It’s easier to increase limits than recover from losses.

Choose Appropriate Period

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

Monitor Usage

Regularly check budget utilization in the dashboard. If an agent consistently hits limits, it might need adjustment or investigation.

Set Up Alerts

Configure notifications (coming soon) for when budget usage exceeds thresholds like 80%.

Increasing Limits

To increase an API key’s budget:

Go to Dashboard > Manage Agents
Click the budget settings for the agent
Update the budget configuration
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.

Getting Started

Platform

Overview

How Budget Limits Work

Configuring Budgets

Budget Settings

Example Configurations

Budget Enforcement

Order Placement

What Counts Toward Budget

Checking Your Budget

Via Dashboard

Via API

How Budget Is Calculated

Position Limits

Best Practices

Increasing Limits

Dry Run Testing

​Overview

​How Budget Limits Work

​Configuring Budgets

​Budget Settings

​Example Configurations

​Budget Enforcement

​Order Placement

​What Counts Toward Budget

​Checking Your Budget

​Via Dashboard

​Via API

​How Budget Is Calculated

​Position Limits

​Best Practices

​Increasing Limits

​Dry Run Testing

Overview

How Budget Limits Work

Configuring Budgets

Budget Settings

Example Configurations

Budget Enforcement

Order Placement

What Counts Toward Budget

Checking Your Budget

Via Dashboard

Via API

How Budget Is Calculated

Position Limits

Best Practices

Increasing Limits

Dry Run Testing