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/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/MATIC balance
`GET /budget`	Spendable amount with limits
`POST /wallet/approve`	Approve tokens for trading

Settlements

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

Search Tips

The skill supports smart search with shorthand:

btc 15m → Bitcoin 15-minute markets
eth daily → Ethereum daily markets
trump election → Political markets
superbowl winner → Sports markets

Search auto-expands common crypto tickers (btc, eth, sol, doge) and time periods.

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. Search for Bitcoin market
GET /markets/crypto?asset=btc&timeframe=daily

# 2. Check the spread
GET /spread?token_id={tokenId from step 1}

# 3. Check available budget
GET /budget

# 4. Place a limit order
POST /orders
{
  "tokenId": "...",
  "side": "BUY",
  "price": 0.55,
  "size": 50,
  "type": "LIMIT"
}

# 5. Monitor order
GET /orders/{orderId}

# 6. Check positions
GET /positions

# 7. 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

Search Tips

Order Types

Permissions

Rate Limits

Error Handling

Example Workflow

Next Steps

API Reference

Quickstart

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

​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

Search Tips

Order Types

Permissions

Rate Limits

Error Handling

Example Workflow

Next Steps