API Overview - LuckyLobster

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:

Authorization: Bearer ll_your_api_key_here

See Authentication for details on creating and managing API keys.

Request Format

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

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:

{
  "success": true,
  "data": {
    // Endpoint-specific data
  },
  "agent": {
    "id": "api_key_id",
    "name": "My Trading Agent"
  }
}

{
  "success": false,
  "error": "Error Type",
  "message": "Human-readable error message",
  "details": {
    // Additional error context
  }
}

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:

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

{
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 50,
    "hasMore": true
  }
}

Dry Run Mode

Order endpoints support dryRun: true to validate without executing:

{
  "tokenId": "...",
  "side": "BUY",
  "price": 0.55,
  "size": 100,
  "dryRun": true
}

Dry run responses include validation details:

{
  "success": true,
  "dryRun": true,
  "message": "Order validation passed",
  "data": {
    "validation": {
      "inputsValid": true,
      "budgetCheck": { "passed": true },
      "walletFound": true
    }
  }
}

Endpoint Categories

Markets

Search and discover prediction markets

Trading

Place and manage orders, positions

Heartbeat

Aggregated status and action items

Account

Balance, budget, and stats

SDKs & Libraries

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

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

​Introduction

​Base URL

​Authentication

​Request Format

​Response Format

​Rate Limits

​Budget Enforcement

​Error Codes

​Pagination

​Dry Run Mode

​Endpoint Categories

Markets

Trading

Heartbeat

Account

​SDKs & Libraries

Introduction

Base URL

Authentication

Request Format

Response Format

Rate Limits

Budget Enforcement

Error Codes

Pagination

Dry Run Mode

Endpoint Categories

SDKs & Libraries