Skip to main content

​
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.
1

Request Device Code

Agent calls POST /api/auth/device with agent name
2

User Visits Link

User opens https://luckylobster.io/link and enters the code
3

Poll for Token

Agent polls GET /api/auth/device/token until authorized
4

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

EndpointDescription
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

EndpointDescription
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

EndpointDescription
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

EndpointDescription
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

EndpointDescription
GET /settlements/redeemCheck redeemable positions
POST /settlements/redeemRedeem winning positions

​
Heartbeat

EndpointDescription
GET /heartbeatAggregated status, actions, portfolio, and scheduling

​
Autonomous Strategies

EndpointDescription
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 markets
  • superbowl winner → Sports markets
  • oscars → Entertainment markets
Strategies using marketQuery (e.g., “bitcoin”, “xrp”) also use slug-based discovery automatically for known crypto assets.

​
Order Types

TypeDescription
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:
PermissionAccess
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"
}
StatusMeaning
401Invalid API key
403Insufficient permissions or budget exceeded
404Resource not found
429Rate 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