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

# API Keys

> How API keys work and how to manage agent access

## Overview

API keys allow AI agents to access your LuckyLobster account programmatically. Each key is tied to a linked agent and has configurable budget limits.

## How API Keys Are Created

API keys are generated automatically through the **device authorization flow** when an AI agent links to your account. There is no manual key creation - the process is:

<Steps>
  <Step title="Agent Requests a Code">
    Your agent calls `POST /api/auth/device` and receives a user code
  </Step>

  <Step title="You Approve the Link">
    Visit the link page shown by your agent and enter the code to approve
  </Step>

  <Step title="Agent Receives Key">
    After approval, the agent receives an `ll_*` API key automatically

    ```
    ll_abc123xyz789defghi456...
    ```
  </Step>
</Steps>

<Tip>
  See the [Skill Reference](/skill) for the complete device authorization flow with code examples.
</Tip>

## Permission Scopes

All linked agents receive the standard set of permissions:

| Scope    | Allows                                   | Use Case             |
| -------- | ---------------------------------------- | -------------------- |
| `read`   | View markets, balance, positions, orders | All agents need this |
| `trade`  | Place orders                             | Trading agents       |
| `cancel` | Cancel open orders                       | Trading agents       |
| `redeem` | Redeem settled market winnings           | Automated redemption |

## Budget Configuration

### Budget Limits

Configure spending limits for each agent at **Dashboard > Manage Agents** to protect against:

* Bugs in agent logic
* Unexpected market conditions
* Compromised keys

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

### Checking Budget

Agents can check their remaining budget:

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

## Rate Limits

Default rate limit: **100 requests/minute**

Rate limit headers are included in every response:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200
```

## Managing Agents

### Viewing Agents

All your linked agents are listed at **Dashboard > Manage Agents** with:

* Name and link date
* API key prefix
* Budget usage
* Strategy count
* Status (active/paused/revoked)

### Pausing Agents

To temporarily disable an agent without revoking its key:

1. Find the agent in your list
2. Click the pause button
3. Select a duration (15 minutes, 30 minutes, 1 hour, 4 hours, or indefinitely)

Paused agents can be resumed at any time.

### Revoking Keys

To permanently revoke an agent's access:

1. Find the agent in your list
2. Click **Revoke**
3. Confirm the action

<Warning>
  Revoking is immediate and irreversible. The agent will lose access instantly.
</Warning>

## Best Practices

<AccordionGroup>
  <Accordion icon="key" title="Link separate agents per use case">
    Each agent gets its own API key through the device flow. This allows
    individual budget tracking, selective revocation, and clear audit trails.
  </Accordion>

  <Accordion icon="dollar-sign" title="Start with conservative budgets">
    Begin with low budget limits and increase as you verify agent behavior.
  </Accordion>

  <Accordion icon="pause" title="Pause agents when not in use">
    Use the pause feature to temporarily disable agents without revoking access.
    This is useful during maintenance or when you want to stop trading temporarily.
  </Accordion>

  <Accordion icon="shield" title="Never expose keys in code">
    Use environment variables or secure vaults. Never commit keys to repositories.
  </Accordion>
</AccordionGroup>

## API Key Format

```
ll_<64_character_hash>
```

* Prefix: `ll_`
* Hash: 64-character secure random string