---
description: Install the LuckyLobster skill for AI agent integration
metadata:
  mintlify-proj: luckylobster
---

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

<CardGroup>
  <Card title="Install from ClawHub" icon="download" href="https://clawhub.com/skills/luckylobster">
    One-click installation for compatible agents
  </Card>

  <Card title="View skill.md" icon="file-code" href="https://luckylobster.io/skill.md">
    Full skill definition file
  </Card>
</CardGroup>

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

<Steps>
  <Step title="Request Device Code">
    Agent calls `POST /api/auth/device` with agent name
  </Step>

  <Step title="User Visits Link">
    User opens `https://luckylobster.io/link` and enters the code
  </Step>

  <Step title="Poll for Token">
    Agent polls `GET /api/auth/device/token` until authorized
  </Step>

  <Step title="Store API Key">
    Agent saves the returned `ll_*` API key for future requests
  </Step>
</Steps>

### Example Flow

```bash theme={null}
# 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": "user@example.com",
#   "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:

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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

```yaml theme={null}
# 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

<CardGroup>
  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Detailed endpoint documentation
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get started in 5 minutes
  </Card>
</CardGroup>