Skill Reference

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/search`	Search by keyword, tag, or slug
`GET /markets/{id}`	Get market details with token IDs
`GET /markets/crypto`	Quick lookup for crypto up/down markets
`GET /markets/crypto/all`	All active crypto markets with live prices, oracle data, spreads
`GET /markets/by-slug`	Find by exact Polymarket slug

Market Data

Endpoint	Description
`GET /orderbook`	Full order book with bids/asks
`GET /prices`	Current bid/ask/mid prices
`GET /spread`	Bid-ask spread
`GET /market-data`	Comprehensive data in one call

Trading

Endpoint	Description
`POST /orders`	Place buy/sell orders
`GET /orders`	List orders with live sync
`GET /orders/{id}`	Get order status
`DELETE /orders/{id}`	Cancel an order

Positions & Account

Endpoint	Description
`GET /positions`	Current holdings with P&L
`POST /positions/{id}/close`	Close a position
`GET /balance`	Wallet USDC balance
`GET /budget`	Spendable amount with limits
`GET /stats`	Trading performance statistics
`POST /wallet/approve`	Approve tokens for trading

Settlements

Endpoint	Description
`GET /settlements/redeem`	Check redeemable positions
`POST /settlements/redeem`	Redeem winning positions

Heartbeat

Endpoint	Description
`GET /heartbeat`	Aggregated status, actions, portfolio, and scheduling

Autonomous Strategies

Endpoint	Description
`POST /strategies`	Create a strategy (PRICE_ALERT, RECURRING_BUY, BUY_LOW_SELL_HIGH, COPY_TRADE)
`GET /strategies`	List strategies with execution history
`GET /strategies/types`	Get available strategy types and their config schemas
`GET /strategies/{id}`	Get strategy details
`PATCH /strategies/{id}`	Update strategy config
`POST /strategies/{id}/pause`	Pause a strategy
`POST /strategies/{id}/resume`	Resume 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

Type	Description
`LIMIT`	Rests on book until filled or cancelled
`MARKET`	Fills immediately at best price
`FOK`	Fill or Kill - all or nothing
`FAK`	Fill and Kill - take what’s available

Permissions

Linked agents receive standard permissions:

Permission	Access
`read`	Markets, orders, positions, balance
`trade`	Place buy/sell orders
`cancel`	Cancel open orders
`redeem`	Settle 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

Getting Started

Platform

Overview

Install from ClawHub

View skill.md

Skill File URL

Device Authorization Flow

Example Flow

Capabilities

Market Discovery

Market Data

Trading

Positions & Account

Settlements

Heartbeat

Autonomous Strategies

Search Tips

Order Types

Permissions

Rate Limits

Error Handling

Example Workflow

Next Steps

API Reference

Quickstart

​Overview

Install from ClawHub

View skill.md

​Skill File URL

​Device Authorization Flow

​Example Flow

​Capabilities

​Market Discovery

​Market Data

​Trading

​Positions & Account

​Settlements

​Heartbeat

​Autonomous Strategies

​Search Tips

​Order Types

​Permissions

​Rate Limits

​Error Handling

​Example Workflow

​Next Steps

API Reference

Quickstart

Overview

Skill File URL

Device Authorization Flow

Example Flow

Capabilities

Market Discovery

Market Data

Trading

Positions & Account

Settlements

Heartbeat

Autonomous Strategies

Search Tips

Order Types

Permissions

Rate Limits

Error Handling

Example Workflow

Next Steps