Documentation Index Fetch the complete documentation index at: https://docs.luckylobster.io/llms.txt
Use this file to discover all available pages before exploring further.
Overview The LuckyLobster skill enables AI agents (OpenClaw, ClawdBot, MoltBot, etc.) to trade on Polymarket prediction markets. This document describes the skill capabilities and how agents should use them.
Install from ClawHub One-click installation for compatible agents
View skill.md Full skill definition file
Skill File URL Point your agent to the skill file at:
https://luckylobster.io/skill.md
The skill file is dynamically generated and includes:
OpenClaw metadata with emoji and environment requirements
Device authorization flow for linking agents
Complete API documentation with examples
Market data, trading, and settlement endpoints
Device Authorization Flow LuckyLobster uses a device code flow for agents to authenticate, similar to how you’d link a TV app to your account.
Request Device Code
Agent calls POST /api/auth/device with agent name
User Visits Link
User opens https://luckylobster.io/link and enters the code
Poll for Token
Agent polls GET /api/auth/device/token until authorized
Store API Key
Agent saves the returned ll_* API key for future requests
Example Flow # 1. Request device code curl -X POST "https://luckylobster.io/api/auth/device" \ -H "Content-Type: application/json" \ -d '{"agent_name": "ClawdBot"}' # Response: # { # "device_code": "abc123...", # "user_code": "ABCD-1234", # "verification_uri": "https://luckylobster.io/link", # "expires_in": 900, # "interval": 5 # } # 2. Tell user to visit: https://luckylobster.io/link?code=ABCD-1234 # 3. Poll every 5 seconds curl "https://luckylobster.io/api/auth/device/token?device_code=abc123..." # Success response: # { # "api_key": "ll_abc123...", # "user_email": "[email protected] ", # "permissions": ["read", "trade", "cancel", "redeem"] # }
Capabilities Market Discovery Endpoint Description GET /markets/searchSearch by keyword, tag, or slug GET /markets/{id}Get market details with token IDs GET /markets/cryptoQuick lookup for crypto up/down markets GET /markets/crypto/allAll active crypto markets with live prices, oracle data, spreads GET /markets/by-slugFind by exact Polymarket slug
Market Data Endpoint Description GET /orderbookFull order book with bids/asks GET /pricesCurrent bid/ask/mid prices GET /spreadBid-ask spread GET /market-dataComprehensive data in one call
Trading Endpoint Description POST /ordersPlace buy/sell orders GET /ordersList orders with live sync GET /orders/{id}Get order status DELETE /orders/{id}Cancel an order
Positions & Account Endpoint Description GET /positionsCurrent holdings with P&L POST /positions/{id}/closeClose a position GET /balanceWallet USDC balance GET /budgetSpendable amount with limits GET /statsTrading performance statistics POST /wallet/approveApprove tokens for trading
Settlements Endpoint Description GET /settlements/redeemCheck redeemable positions POST /settlements/redeemRedeem winning positions
Heartbeat Endpoint Description GET /heartbeatAggregated status, actions, portfolio, and scheduling
Autonomous Strategies Endpoint Description POST /strategiesCreate a strategy (PRICE_ALERT, RECURRING_BUY, BUY_LOW_SELL_HIGH, COPY_TRADE) GET /strategiesList strategies with execution history GET /strategies/typesGet available strategy types and their config schemas GET /strategies/{id}Get strategy details PATCH /strategies/{id}Update strategy config POST /strategies/{id}/pausePause a strategy POST /strategies/{id}/resumeResume a paused strategy DELETE /strategies/{id}Cancel a strategy
Search Tips For a full snapshot of all active crypto markets with prices, spreads, and oracle data in one call:
GET /markets/crypto/all # All active crypto markets GET /markets/crypto/all?asset=btc # Just BTC markets GET /markets/crypto/all?timeframe=15m # Just 15-minute markets
For a single crypto market lookup:
GET /markets/crypto?asset=btc & timeframe = 15m # Current BTC 15-minute market GET /markets/crypto?asset=eth & timeframe = hourly # Current ETH hourly market GET /markets/crypto?asset=xrp & timeframe = daily # Today's XRP daily market
For non-crypto markets, text search works well:
trump election → Political marketssuperbowl winner → Sports marketsoscars → Entertainment markets
Strategies using marketQuery (e.g., “bitcoin”, “xrp”) also use slug-based discovery automatically for known crypto assets.
Order Types Type Description LIMITRests on book until filled or cancelled MARKETFills immediately at best price FOKFill or Kill - all or nothing FAKFill and Kill - take what’s available
Permissions Linked agents receive standard permissions:
Permission Access readMarkets, orders, positions, balance tradePlace buy/sell orders cancelCancel open orders redeemSettle winning positions
Rate Limits
Default: 100 requests/minute per API key
Headers included: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Error Handling All endpoints return consistent error format:
{ "success" : false , "error" : "Error Type" , "message" : "Human-readable description" }
Status Meaning 401 Invalid API key 403 Insufficient permissions or budget exceeded 404 Resource not found 429 Rate limit exceeded
Example Workflow # 1. Get all crypto markets with prices and spreads in one call GET /markets/crypto/all # 2. Check available budget GET /budget # 3. Place a limit order using tokenId from the snapshot POST /orders { "tokenId" : "..." , "side" : "BUY" , "price" : 0.55 , "size" : 50 , "type" : "LIMIT" } # 4. Monitor order GET /orders/{orderId} # 5. Check positions GET /positions # 6. When market settles, redeem POST /settlements/redeem
Next Steps
API Reference Detailed endpoint documentation
Quickstart Get started in 5 minutes
