luckylobster

name	luckylobster
description	Trade prediction markets on Polymarket. Search markets, place orders, and manage positions.
homepage	https://luckylobster.io
user-invocable	true
metadata	{"openclaw":{"primaryEnv":"LUCKYLOBSTER_API_KEY","emoji":"🦞","homepage":"https://luckylobster.io","requires":{"env":"[Truncated]"}}}

LuckyLobster - Polymarket Trading API

Trade prediction markets on Polymarket through a secure API designed for AI agents.

How Polymarket Works

Polymarket is a prediction market where you trade on the outcomes of real-world events.

Buying Contracts:

• In active markets, you can buy outcome contracts priced from $0.01 to $0.99
• Each contract entitles you to 1 share at your purchase price
• Lower prices = higher potential return, but less likely outcome (market's view)

Selling Contracts:

• You can sell your shares at any time before the market closes
• Sell price depends on current market conditions

Market Resolution:

• When a market resolves, the winning outcome pays $1.00 USDC per share
• Losing outcomes pay $0 (or a negligible amount in rare cases)

Example: You buy 100 "Yes" shares at $0.35 each (cost: $35). If "Yes" wins, you receive $100 (profit: $65). If "No" wins, you lose your $35.

Setup

If you don't have an API key configured, use the device authorization flow to link your account.

Device Authorization Flow

Step 1: Request a Device Code

POST https://luckylobster.io/api/auth/device
Content-Type: application/json

{
  "agent_name": "OpenClaw Agent"
}

Response:

{
  "device_code": "abc123...",
  "user_code": "ABCD-1234",
  "verification_uri": "https://luckylobster.io/link",
  "verification_uri_complete": "https://luckylobster.io/link?code=ABCD-1234",
  "expires_in": 900,
  "interval": 5
}

Step 2: Direct the User

Display this message to the user:

🦞 To connect LuckyLobster, visit: https://luckylobster.io/link
   Enter code: ABCD-1234

Step 3: Poll for Authorization

Poll every 5 seconds until authorized:

GET https://luckylobster.io/api/auth/device/token?device_code=abc123...

Pending response:

{ "error": "authorization_pending" }

Success response:

{
  "api_key": "ll_abc123...",
  "user_email": "[e-mail]",
  "permissions": ["read", "trade", "cancel", "redeem"]
}

All linked agents receive standard permissions: read (view markets/orders/positions), trade (buy/sell), cancel (cancel orders), and redeem (settle positions).

Step 4: Store the API Key

Save the API key persistently so it survives restarts. It is only returned once.

Option A: OpenClaw Config (Recommended) Use the gateway tool with config.patch to save it in the skill entry:

gateway.config.patch({
  patch: {
    skills: {
      entries: {
        luckylobster: {
          env: {
            LUCKYLOBSTER_API_KEY: "ll_abc123..."
          }
        }
      }
    }
  }
})

Option B: Environment File Append it to ~/.openclaw/.env or the workspace .env file if one exists:

echo "LUCKYLOBSTER_API_KEY=ll_abc123..." >> ~/.openclaw/.env

---

Authentication

All API requests require an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Base URL

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

Rate Limits

• Default: 100 requests per minute
• Rate limit headers included in responses:
  • X-RateLimit-Limit: Max requests allowed
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Reset time (ISO 8601)

Endpoints

Search Markets

Find prediction markets on Polymarket. The search uses smart relevance scoring to return the best matches first.

GET /markets/search?q={query}

Parameters:

• q (required for search): Natural language query - "bitcoin 15m", "trump election", "superbowl winner"
• limit (optional): Max results (default: 10, max: 100)
• offset (optional): Pagination offset
• sort (optional): "relevance" (default), "volume", "liquidity", "end_date", "recent"
• ending_soon (optional): Prioritize markets ending within 24h (default: false)
• min_volume (optional): Minimum volume in USD (default: 100)
• min_liquidity (optional): Minimum liquidity in USD
• tag (optional): Filter by category: "crypto", "politics", "sports", "entertainment"
• accepting_orders (optional): Only tradeable markets (default: true)

Search Tips:

• Shorthand supported: "btc 15m" → "Bitcoin Up or Down", "eth daily" → "Ethereum Up or Down on"
• The search auto-expands: btc→Bitcoin, eth→Ethereum, sol→Solana, etc.
• Time keywords (15m, hourly, daily) auto-expand to "Up or Down" queries
• Results are ranked by relevance: query match + liquidity + volume + accepting orders
• For time-sensitive markets, add ending_soon=true to prioritize markets expiring within 24h
• First result is usually the best match - check context.topMatch

Example - Find Current BTC Market:

curl -H "Authorization: Bearer $LUCKYLOBSTER_API_KEY" \
  "https://luckylobster.io/api/agent/v1/markets/search?q=bitcoin%20up%20down&ending_soon=true&limit=5"

Example - High-Volume Politics Markets:

curl -H "Authorization: Bearer $LUCKYLOBSTER_API_KEY" \
  "https://luckylobster.io/api/agent/v1/markets/search?q=election&tag=politics&sort=volume"

Response:

{
  "success": true,
  "data": [
    {
      "id": "1314069",
      "slug": "bitcoin-up-or-down-on-february-3",
      "question": "Bitcoin Up or Down on February 3?",
      "outcomes": ["Up", "Down"],
      "outcomePrices": ["0.65", "0.35"],
      "volume": "409100.65",
      "liquidity": "39255.13",
      "endDate": "2026-02-03T17:00:00Z",
      "active": true,
      "acceptingOrders": true
    }
  ],
  "pagination": { "limit": 5, "offset": 0, "count": 1, "hasMore": false },
  "context": {
    "hasResults": true,
    "topMatch": { "id": "1314069", "question": "Bitcoin Up or Down on February 3?", "acceptingOrders": true },
    "endingSoonCount": 1
  },
  "options": {
    "sortBy": ["relevance", "volume", "liquidity", "end_date", "recent"],
    "tags": ["crypto", "politics", "sports", "entertainment"]
  }
}

Workflow for Trading:

1. Search: GET /markets/search?q=bitcoin up down
2. Use the id from the top result to get full details: GET /markets/{id}
3. Response includes clobTokenIds - use these with trading endpoints

---

Quick Crypto Market Lookup

For crypto up/down markets, use this simplified endpoint:

GET /markets/crypto?asset={btc|eth|sol}&timeframe={daily|hourly|15m}

Examples:

• /markets/crypto?asset=btc - Today's Bitcoin daily market
• /markets/crypto?asset=btc&timeframe=15m - Current Bitcoin 15-minute market
• /markets/crypto?asset=eth&timeframe=hourly - Current Ethereum hourly market

Response includes tokens array with tokenId ready for trading.

---

Find Market by Slug

If you know the exact market slug (from a Polymarket URL), use this for direct lookup:

GET /markets/by-slug?slug={slug}

Example: For URL https://polymarket.com/event/btc-updown-15m-1770129900

curl -H "Authorization: Bearer $LUCKYLOBSTER_API_KEY" \
  "https://luckylobster.io/api/agent/v1/markets/by-slug?slug=btc-updown-15m-1770129900"

Response includes clobTokenIds and tokens ready for trading.

Note: For most use cases, /markets/search or /markets/crypto is easier than constructing slugs.

Get Market Details

Get detailed information about a specific market, including token IDs required for market data and trading.

GET /markets/{id}

Parameters:

• id: Market ID or condition ID (from search results)

Example:

curl -H "Authorization: Bearer $LUCKYLOBSTER_API_KEY" \
  "https://luckylobster.io/api/agent/v1/markets/0x1234..."

Response:

{
  "success": true,
  "data": {
    "id": "1314069",
    "conditionId": "0xf46bf33576e8341821161316705ab2357312f58d58b7d157cb8dca73b656b326",
    "question": "Bitcoin Up or Down on February 3?",
    "outcomes": ["Up", "Down"],
    "outcomePrices": ["0.345", "0.655"],
    "tokens": [
      {"tokenId": "36656454529662513...", "outcome": "Up", "price": "0.345"},
      {"tokenId": "10609233133841503...", "outcome": "Down", "price": "0.655"}
    ],
    "clobTokenIds": ["36656454529662513...", "10609233133841503..."],
    "volume": "409100.65",
    "liquidity": "39255.13",
    "active": true,
    "acceptingOrders": true,
    "spreads": [
      {"outcome": "Up", "tokenId": "36656454...", "bid": "0.34", "ask": "0.35", "spread": "0.01"}
    ]
  }
}

Important: Use the tokenId from the tokens array or clobTokenIds for the market data endpoints below.

---

Market Data Endpoints

These endpoints provide real-time order book and pricing data from the Polymarket CLOB (Central Limit Order Book).

Workflow for getting market data:

1. Search markets: GET /markets/search?q=Bitcoin
2. Get market details: GET /markets/{id} → This returns tokens[].tokenId
3. Get market data: GET /orderbook?token_id={tokenId} or GET /market-data?token_id={tokenId}

Get Order Book

Get the order book summary for a token, including all bids and asks.

GET /orderbook?token_id={tokenId}

Parameters:

• token_id (required): The outcome token address
• token_ids (optional): Comma-separated list for batch request (max 20)

Example:

curl -H "Authorization: Bearer $LUCKYLOBSTER_API_KEY" \
  "https://luckylobster.io/api/agent/v1/orderbook?token_id=71321045..."

Response:

{
  "success": true,
  "data": {
    "tokenId": "71321045...",
    "market": "0xabc...",
    "timestamp": "2025-01-15T12:00:00Z",
    "bids": [
      {"price": "0.65", "size": "1000"},
      {"price": "0.64", "size": "500"}
    ],
    "asks": [
      {"price": "0.66", "size": "800"},
      {"price": "0.67", "size": "1200"}
    ],
    "tickSize": "0.01",
    "minOrderSize": "1",