Skip to main content

​
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_live_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_live_..." \
  -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"
  }
}

​
Rate Limits

Rate limits are configured per API key. Default: 100 requests/minute. Headers included in every response:
HeaderDescription
X-RateLimit-LimitMax requests in current window
X-RateLimit-RemainingRequests remaining
X-RateLimit-ResetUnix 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

StatusErrorDescription
400Bad RequestInvalid parameters
401UnauthorizedMissing or invalid API key
403ForbiddenBudget exceeded or permission denied
404Not FoundResource doesn’t exist
429Rate LimitedToo many requests
500Server ErrorInternal error

​
Pagination

List endpoints support pagination:
ParameterTypeDefaultDescription
limitint10-50Max results to return
offsetint0Number 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

View and close positions

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.