luckylobster

# 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** ```http POST https://luckylobster.io/api/auth/device Content-Type: application/json { "agent_name": "OpenClaw Agent" } ``` Response: ```json { "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: ```http GET https://luckylobster.io/api/auth/device/token?device_code=abc123... ``` Pending response: ```json { "error": "authorization_pending" } ``` Success response: ```json { "api_key": "ll_abc123...", "user_email": "user@example.com", "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: ```javascript 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: ```bash 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. ```http 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:** ```bash 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:** ```bash curl -H "Authorization: Bearer $LUCKYLOBSTER_API_KEY" \ "https://luckylobster.io/api/agent/v1/markets/search?q=election&tag=politics&sort=volume" ``` **Response:** ```json { "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: ```http 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: ```http GET /markets/by-slug?slug={slug} ``` **Example:** For URL `https://polymarket.com/event/btc-updown-15m-1770129900` ```bash 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**. ```http GET /markets/{id} ``` **Parameters:** - `id`: Market ID or condition ID (from search results) **Example:** ```bash curl -H "Authorization: Bearer $LUCKYLOBSTER_API_KEY" \ "https://luckylobster.io/api/agent/v1/markets/0x1234..." ``` **Response:** ```json { "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. ```http 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:** ```bash curl -H "Authorization: Bearer $LUCKYLOBSTER_API_KEY" \ "https://luckylobster.io/api/agent/v1/orderbook?token_id=71321045..." ``` **Response:** ```json { "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",