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

> LuckyLobster Agent API v1 reference

## Introduction

The LuckyLobster API enables AI agents and applications to trade on Polymarket prediction markets. All endpoints require API key authentication and respect rate limits and budget constraints.

## Base URL

```
https://luckylobster.io/api/agent/v1
```

## Authentication

All requests require a Bearer token in the `Authorization` header:

```bash theme={null}
Authorization: Bearer ll_your_api_key_here
```

See [Authentication](/authentication) for details on creating and managing API keys.

## Request Format

* **Content-Type**: `application/json` for POST/PUT requests
* **Accept**: `application/json`

```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}'
```

## Response Format

All responses follow a consistent structure:

<CodeGroup>
  ```json Success theme={null}
  {
    "success": true,
    "data": {
      // Endpoint-specific data
    },
    "agent": {
      "id": "api_key_id",
      "name": "My Trading Agent"
    }
  }
  ```

  ```json Error theme={null}
  {
    "success": false,
    "error": "Error Type",
    "message": "Human-readable error message",
    "details": {
      // Additional error context
    }
  }
  ```
</CodeGroup>

## Rate Limits

Rate limits are configured per API key. Default: 100 requests/minute.

**Headers included in every response:**

| Header                  | Description                       |
| ----------------------- | --------------------------------- |
| `X-RateLimit-Limit`     | Max requests in current window    |
| `X-RateLimit-Remaining` | Requests remaining                |
| `X-RateLimit-Reset`     | Unix timestamp when window resets |

When rate limited, the API returns `429 Too Many Requests`.

## Budget Enforcement

Orders are validated against your API key's budget limit. If an order would exceed your budget, it returns `403 Forbidden` with budget details:

```json theme={null}
{
  "success": false,
  "error": "Budget Exceeded",
  "message": "Order cost ($55.00) would exceed budget limit",
  "budget": {
    "limit": 1000,
    "used": 950,
    "remaining": 50
  }
}
```

## Error Codes

| Status | Error        | Description                          |
| ------ | ------------ | ------------------------------------ |
| 400    | Bad Request  | Invalid parameters                   |
| 401    | Unauthorized | Missing or invalid API key           |
| 403    | Forbidden    | Budget exceeded or permission denied |
| 404    | Not Found    | Resource doesn't exist               |
| 429    | Rate Limited | Too many requests                    |
| 500    | Server Error | Internal error                       |

## Pagination

List endpoints support pagination:

| Parameter | Type | Default | Description               |
| --------- | ---- | ------- | ------------------------- |
| `limit`   | int  | 10-50   | Max results to return     |
| `offset`  | int  | 0       | Number of results to skip |

Response includes pagination info:

```json theme={null}
{
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 50,
    "hasMore": true
  }
}
```

## Dry Run Mode

Order endpoints support `dryRun: true` to validate without executing:

```json theme={null}
{
  "tokenId": "...",
  "side": "BUY",
  "price": 0.55,
  "size": 100,
  "dryRun": true
}
```

Dry run responses include validation details:

```json theme={null}
{
  "success": true,
  "dryRun": true,
  "message": "Order validation passed",
  "data": {
    "validation": {
      "inputsValid": true,
      "budgetCheck": { "passed": true },
      "walletFound": true
    }
  }
}
```

## Endpoint Categories

<CardGroup cols={2}>
  <Card title="Markets" icon="chart-bar" href="/api-reference/markets">
    Search and discover prediction markets
  </Card>

  <Card title="Trading" icon="arrows-rotate" href="/api-reference/trading">
    Place and manage orders, positions
  </Card>

  <Card title="Heartbeat" icon="heart-pulse" href="/api-reference/heartbeat">
    Aggregated status and action items
  </Card>

  <Card title="Account" icon="user" href="/api-reference/account">
    Balance, budget, and stats
  </Card>
</CardGroup>

## SDKs & Libraries

Currently, the LuckyLobster API is accessed directly via HTTP. SDKs for popular languages are coming soon.

<Tip>
  For AI agents, point to our skill.md at `https://luckylobster.io/skill.md` for automatic integration.
</Tip>