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

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

Parse the JSON response and extract the verification_uri_complete field. Display it to the user as a clickable link:

🦞 To connect LuckyLobster, click: {verification_uri_complete}

Important: Use the verification_uri_complete value exactly as returned — do NOT concatenate fields or build the URL yourself. The value is a complete, ready-to-use URL.

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": "[email protected]",
  "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.

Use the gateway tool with config.patch to save it in the skill config:

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

---

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 dedicated endpoint. It uses deterministic slug-based lookups (not text search) and is the most reliable way to find crypto markets:

GET /markets/crypto?asset={btc|eth|sol|xrp|doge|matic}&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
• /markets/crypto?asset=xrp&timeframe=15m - Current XRP 15-minute market

Response includes tokens array with tokenId, negRisk, and live spread data 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 crypto markets, always prefer /markets/crypto over /markets/search — it uses the same deterministic slug lookups as the internal market-data-worker and is far more reliable.

Get Market Details

...