> ## Documentation Index
> Fetch the complete documentation index at: https://docs.luckylobster.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Budget Limits

> Control agent spending with 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

```mermaid theme={null}
flowchart LR
    A[Agent Places Order] --> B{Check Budget}
    B -->|Order Cost <= Remaining| C[Execute Order]
    B -->|Order Cost > Remaining| D[Reject Order]
    C --> E[Update Budget Used]
    D --> F[Return 403 Error]
```

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

| 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:

```json theme={null}
{
  "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

```bash theme={null}
curl "https://luckylobster.io/api/agent/v1/budget" \
  -H "Authorization: Bearer ll_..."
```

Response:

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion icon="scale-balanced" title="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.
  </Accordion>

  <Accordion icon="calendar" title="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
  </Accordion>

  <Accordion icon="chart-line" title="Monitor Usage">
    Regularly check budget utilization in the dashboard. If an agent consistently hits limits, it might need adjustment or investigation.
  </Accordion>

  <Accordion icon="bell" title="Set Up Alerts">
    Configure notifications (coming soon) for when budget usage exceeds thresholds like 80%.
  </Accordion>
</AccordionGroup>

## 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

<Warning>
  Changes take effect immediately. Be sure you want to increase spending capacity before confirming.
</Warning>

## Dry Run Testing

Use `dryRun: true` in orders to test budget validation without spending:

```bash theme={null}
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.