{
  "schemaVersion": "1.0",
  "item": {
    "slug": "luckylobster-skill",
    "name": "LuckyLobster",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/rachelbastian/luckylobster-skill",
    "canonicalUrl": "https://clawhub.ai/rachelbastian/luckylobster-skill",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/luckylobster-skill",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=luckylobster-skill",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "skill.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/luckylobster-skill"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/luckylobster-skill",
    "agentPageUrl": "https://openagent3.xyz/skills/luckylobster-skill/agent",
    "manifestUrl": "https://openagent3.xyz/skills/luckylobster-skill/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/luckylobster-skill/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "LuckyLobster - Polymarket Trading API",
        "body": "Trade prediction markets on Polymarket through a secure API designed for AI agents."
      },
      {
        "title": "How Polymarket Works",
        "body": "Polymarket is a prediction market where you trade on the outcomes of real-world events.\n\nBuying Contracts:\n\nIn active markets, you can buy outcome contracts priced from $0.01 to $0.99\nEach contract entitles you to 1 share at your purchase price\nLower prices = higher potential return, but less likely outcome (market's view)\n\nSelling Contracts:\n\nYou can sell your shares at any time before the market closes\nSell price depends on current market conditions\n\nMarket Resolution:\n\nWhen a market resolves, the winning outcome pays $1.00 USDC per share\nLosing outcomes pay $0 (or a negligible amount in rare cases)\n\nExample: You buy 100 \"Yes\" shares at $0.35 each (cost: $35). If \"Yes\" wins, you receive $100 (profit: $65). If \"No\" wins, you lose your $35."
      },
      {
        "title": "Setup",
        "body": "If you don't have an API key configured, use the device authorization flow to link your account."
      },
      {
        "title": "Device Authorization Flow",
        "body": "Step 1: Request a Device Code\n\nPOST https://luckylobster.io/api/auth/device\nContent-Type: application/json\n\n{\n  \"agent_name\": \"OpenClaw Agent\"\n}\n\nResponse:\n\n{\n  \"device_code\": \"abc123...\",\n  \"user_code\": \"ABCD-1234\",\n  \"verification_uri\": \"https://luckylobster.io/link\",\n  \"verification_uri_complete\": \"https://luckylobster.io/link?code=ABCD-1234\",\n  \"expires_in\": 900,\n  \"interval\": 5\n}\n\nStep 2: Direct the User\n\nParse the JSON response and extract the verification_uri_complete field. Display it to the user as a clickable link:\n\n🦞 To connect LuckyLobster, click: {verification_uri_complete}\n\nImportant: Use the verification_uri_complete value exactly as returned — do NOT concatenate fields or build the URL yourself. The value is a complete, ready-to-use URL.\n\nStep 3: Poll for Authorization\n\nPoll every 5 seconds until authorized:\n\nGET https://luckylobster.io/api/auth/device/token?device_code=abc123...\n\nPending response:\n\n{ \"error\": \"authorization_pending\" }\n\nSuccess response:\n\n{\n  \"api_key\": \"ll_abc123...\",\n  \"user_email\": \"user@example.com\",\n  \"permissions\": [\"read\", \"trade\", \"cancel\", \"redeem\"]\n}\n\nAll linked agents receive standard permissions: read (view markets/orders/positions), trade (buy/sell), cancel (cancel orders), and redeem (settle positions).\n\nStep 4: Store the API Key\n\nSave the API key persistently so it survives restarts. It is only returned once.\n\nUse the gateway tool with config.patch to save it in the skill config:\n\ngateway.config.patch({\n  patch: {\n    skills: {\n      entries: {\n        luckylobster: {\n          env: {\n            LUCKYLOBSTER_API_KEY: \"ll_abc123...\"\n          }\n        }\n      }\n    }\n  }\n})"
      },
      {
        "title": "Authentication",
        "body": "All API requests require an API key in the Authorization header:\n\nAuthorization: Bearer YOUR_API_KEY"
      },
      {
        "title": "Base URL",
        "body": "https://luckylobster.io/api/agent/v1"
      },
      {
        "title": "Rate Limits",
        "body": "Default: 100 requests per minute\nRate limit headers included in responses:\n\nX-RateLimit-Limit: Max requests allowed\nX-RateLimit-Remaining: Requests remaining\nX-RateLimit-Reset: Reset time (ISO 8601)"
      },
      {
        "title": "Search Markets",
        "body": "Find prediction markets on Polymarket. The search uses smart relevance scoring to return the best matches first.\n\nGET /markets/search?q={query}\n\nParameters:\n\nq (required for search): Natural language query - \"bitcoin 15m\", \"trump election\", \"superbowl winner\"\nlimit (optional): Max results (default: 10, max: 100)\noffset (optional): Pagination offset\nsort (optional): \"relevance\" (default), \"volume\", \"liquidity\", \"end_date\", \"recent\"\nending_soon (optional): Prioritize markets ending within 24h (default: false)\nmin_volume (optional): Minimum volume in USD (default: 100)\nmin_liquidity (optional): Minimum liquidity in USD\ntag (optional): Filter by category: \"crypto\", \"politics\", \"sports\", \"entertainment\"\naccepting_orders (optional): Only tradeable markets (default: true)\n\nSearch Tips:\n\nShorthand supported: \"btc 15m\" → \"Bitcoin Up or Down\", \"eth daily\" → \"Ethereum Up or Down on\"\nThe search auto-expands: btc→Bitcoin, eth→Ethereum, sol→Solana, etc.\nTime keywords (15m, hourly, daily) auto-expand to \"Up or Down\" queries\nResults are ranked by relevance: query match + liquidity + volume + accepting orders\nFor time-sensitive markets, add ending_soon=true to prioritize markets expiring within 24h\nFirst result is usually the best match - check context.topMatch\n\nExample - Find Current BTC Market:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/markets/search?q=bitcoin%20up%20down&ending_soon=true&limit=5\"\n\nExample - High-Volume Politics Markets:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/markets/search?q=election&tag=politics&sort=volume\"\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": \"1314069\",\n      \"slug\": \"bitcoin-up-or-down-on-february-3\",\n      \"question\": \"Bitcoin Up or Down on February 3?\",\n      \"outcomes\": [\"Up\", \"Down\"],\n      \"outcomePrices\": [\"0.65\", \"0.35\"],\n      \"volume\": \"409100.65\",\n      \"liquidity\": \"39255.13\",\n      \"endDate\": \"2026-02-03T17:00:00Z\",\n      \"active\": true,\n      \"acceptingOrders\": true\n    }\n  ],\n  \"pagination\": { \"limit\": 5, \"offset\": 0, \"count\": 1, \"hasMore\": false },\n  \"context\": {\n    \"hasResults\": true,\n    \"topMatch\": { \"id\": \"1314069\", \"question\": \"Bitcoin Up or Down on February 3?\", \"acceptingOrders\": true },\n    \"endingSoonCount\": 1\n  },\n  \"options\": {\n    \"sortBy\": [\"relevance\", \"volume\", \"liquidity\", \"end_date\", \"recent\"],\n    \"tags\": [\"crypto\", \"politics\", \"sports\", \"entertainment\"]\n  }\n}\n\nWorkflow for Trading:\n\nSearch: GET /markets/search?q=bitcoin up down\nUse the id from the top result to get full details: GET /markets/{id}\nResponse includes clobTokenIds - use these with trading endpoints"
      },
      {
        "title": "Quick Crypto Market Lookup",
        "body": "For crypto up/down markets, use this dedicated endpoint. It uses deterministic slug-based lookups (not text search) and is the most reliable way to find crypto markets:\n\nGET /markets/crypto?asset={btc|eth|sol|xrp|doge|matic}&timeframe={daily|hourly|15m}\n\nExamples:\n\n/markets/crypto?asset=btc - Today's Bitcoin daily market\n/markets/crypto?asset=btc&timeframe=15m - Current Bitcoin 15-minute market\n/markets/crypto?asset=eth&timeframe=hourly - Current Ethereum hourly market\n/markets/crypto?asset=xrp&timeframe=15m - Current XRP 15-minute market\n\nResponse includes tokens array with tokenId, negRisk, and live spread data ready for trading."
      },
      {
        "title": "Find Market by Slug",
        "body": "If you know the exact market slug (from a Polymarket URL), use this for direct lookup:\n\nGET /markets/by-slug?slug={slug}\n\nExample: For URL https://polymarket.com/event/btc-updown-15m-1770129900\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/markets/by-slug?slug=btc-updown-15m-1770129900\"\n\nResponse includes clobTokenIds and tokens ready for trading.\n\nNote: For crypto markets, always prefer /markets/crypto over /markets/search — it uses the same deterministic slug lookups as the internal market-data-worker and is far more reliable."
      },
      {
        "title": "Get Market Details",
        "body": "Get detailed information about a specific market, including token IDs required for market data and trading.\n\nGET /markets/{id}\n\nParameters:\n\nid: Market ID or condition ID (from search results)\n\nExample:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/markets/0x1234...\"\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": \"1314069\",\n    \"conditionId\": \"0xf46bf33576e8341821161316705ab2357312f58d58b7d157cb8dca73b656b326\",\n    \"question\": \"Bitcoin Up or Down on February 3?\",\n    \"outcomes\": [\"Up\", \"Down\"],\n    \"outcomePrices\": [\"0.345\", \"0.655\"],\n    \"tokens\": [\n      {\"tokenId\": \"36656454529662513...\", \"outcome\": \"Up\", \"price\": \"0.345\"},\n      {\"tokenId\": \"10609233133841503...\", \"outcome\": \"Down\", \"price\": \"0.655\"}\n    ],\n    \"clobTokenIds\": [\"36656454529662513...\", \"10609233133841503...\"],\n    \"volume\": \"409100.65\",\n    \"liquidity\": \"39255.13\",\n    \"active\": true,\n    \"acceptingOrders\": true,\n    \"spreads\": [\n      {\"outcome\": \"Up\", \"tokenId\": \"36656454...\", \"bid\": \"0.34\", \"ask\": \"0.35\", \"spread\": \"0.01\"}\n    ]\n  }\n}\n\nImportant: Use the tokenId from the tokens array or clobTokenIds for the market data endpoints below."
      },
      {
        "title": "Market Data Endpoints",
        "body": "These endpoints provide real-time order book and pricing data from the Polymarket CLOB (Central Limit Order Book).\n\nWorkflow for getting market data:\n\nSearch markets: GET /markets/search?q=Bitcoin\nGet market details: GET /markets/{id} → This returns tokens[].tokenId\nGet market data: GET /orderbook?token_id={tokenId} or GET /market-data?token_id={tokenId}"
      },
      {
        "title": "Get Order Book",
        "body": "Get the order book summary for a token, including all bids and asks.\n\nGET /orderbook?token_id={tokenId}\n\nParameters:\n\ntoken_id (required): The outcome token address\ntoken_ids (optional): Comma-separated list for batch request (max 20)\n\nExample:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/orderbook?token_id=71321045...\"\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"tokenId\": \"71321045...\",\n    \"market\": \"0xabc...\",\n    \"timestamp\": \"2025-01-15T12:00:00Z\",\n    \"bids\": [\n      {\"price\": \"0.65\", \"size\": \"1000\"},\n      {\"price\": \"0.64\", \"size\": \"500\"}\n    ],\n    \"asks\": [\n      {\"price\": \"0.66\", \"size\": \"800\"},\n      {\"price\": \"0.67\", \"size\": \"1200\"}\n    ],\n    \"tickSize\": \"0.01\",\n    \"minOrderSize\": \"1\",\n    \"summary\": {\n      \"bidCount\": 15,\n      \"askCount\": 12,\n      \"bestBid\": \"0.65\",\n      \"bestAsk\": \"0.66\",\n      \"spread\": \"0.01\",\n      \"totalBidSize\": \"5000.00\",\n      \"totalAskSize\": \"4200.00\"\n    }\n  }\n}"
      },
      {
        "title": "Get Prices",
        "body": "Get current prices for a token including midpoint, buy/sell prices, and last trade.\n\nReal-time data: When you have open positions, the server automatically subscribes to Polymarket WebSocket feeds for those markets. Price data from /prices and /heartbeat will use cached real-time data when available (indicated by \"source\": \"websocket\" in the response). This is significantly faster than HTTP polling.\n\nGET /prices?token_id={tokenId}\n\nParameters:\n\ntoken_id (required): The outcome token address\nside (optional): BUY or SELL to get price for specific side\ntoken_ids (optional): Comma-separated list for batch request (max 20)\n\nExample:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/prices?token_id=71321045...\"\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"tokenId\": \"71321045...\",\n    \"midpoint\": \"0.655\",\n    \"lastTradePrice\": \"0.65\",\n    \"buyPrice\": \"0.66\",\n    \"sellPrice\": \"0.65\",\n    \"timestamp\": \"2025-01-15T12:00:00Z\",\n    \"source\": \"websocket\"\n  }\n}"
      },
      {
        "title": "Get Spread",
        "body": "Get the bid-ask spread for a token.\n\nGET /spread?token_id={tokenId}\n\nParameters:\n\ntoken_id (required): The outcome token address\ntoken_ids (optional): Comma-separated list for batch request (max 20)\n\nExample:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/spread?token_id=71321045...\"\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"tokenId\": \"71321045...\",\n    \"bid\": \"0.65\",\n    \"ask\": \"0.66\",\n    \"spread\": \"0.01\",\n    \"spreadPercent\": \"1.52\",\n    \"timestamp\": \"2025-01-15T12:00:00Z\"\n  }\n}"
      },
      {
        "title": "Get Comprehensive Market Data",
        "body": "Get all market data in a single request (order book summary, prices, spread).\n\nGET /market-data?token_id={tokenId}\n\nParameters:\n\ntoken_id (required): The outcome token address\n\nExample:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/market-data?token_id=71321045...\"\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"tokenId\": \"71321045...\",\n    \"prices\": {\n      \"midpoint\": \"0.655\",\n      \"bestBid\": \"0.65\",\n      \"bestAsk\": \"0.66\",\n      \"lastTrade\": \"0.65\"\n    },\n    \"spread\": {\n      \"absolute\": \"0.01\",\n      \"percent\": \"1.52\"\n    },\n    \"orderbook\": {\n      \"bidCount\": 15,\n      \"askCount\": 12,\n      \"totalBidSize\": \"5000.00\",\n      \"totalAskSize\": \"4200.00\",\n      \"topBids\": [{\"price\": \"0.65\", \"size\": \"1000\"}],\n      \"topAsks\": [{\"price\": \"0.66\", \"size\": \"800\"}]\n    },\n    \"parameters\": {\n      \"tickSize\": \"0.01\",\n      \"minOrderSize\": \"1\"\n    },\n    \"timestamp\": \"2025-01-15T12:00:00Z\"\n  }\n}"
      },
      {
        "title": "Place Order",
        "body": "Place a buy or sell order on a market. Returns real-time order status.\n\nPOST /orders\nContent-Type: application/json\n\n{\n  \"tokenId\": \"0x1234...\",\n  \"side\": \"BUY\",\n  \"price\": 0.65,\n  \"size\": 50,\n  \"type\": \"LIMIT\"\n}\n\nParameters:\n\ntokenId: Outcome token address (from market data)\nside: BUY or SELL\nprice: Price per share (0.01 to 0.99)\nsize: Number of shares\ntype: LIMIT, MARKET, FOK, or FAK\n\nConstraints:\n\nMinimum order amount: price * size must be >= $1.00 USDC\nMinimum order size: 5 shares\nPrice must be a multiple of 0.01 (tick size)\n\nOrder Type Behavior:\n\nMARKET: Fills as much as available at your price or better, kills the rest (recommended for most trades)\nLIMIT: Rests on the order book until filled or cancelled\nFOK: Fill-or-Kill — must fill 100% or the entire order is rejected. Use only when you need guaranteed full fills. High failure rate on thin markets.\nFAK: Fill-and-Kill — same as MARKET\n\nTip: For short-timeframe markets (5m, 15m) where order books can be thin, prefer MARKET or LIMIT over FOK. MARKET orders will fill whatever is available. LIMIT orders rest on the book and can fill as liquidity arrives.\n\nReal-time Status: The response includes the order's current status from Polymarket. MARKET and FAK orders return faster (~500ms) since they execute immediately. LIMIT orders are checked after ~1 second.\n\nExample:\n\ncurl -X POST -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"tokenId\":\"0x1234...\",\"side\":\"BUY\",\"price\":0.65,\"size\":50,\"type\":\"LIMIT\"}' \\\n  \"https://luckylobster.io/api/agent/v1/orders\"\n\nResponse (with fill data when available):\n\n{\n  \"success\": true,\n  \"data\": {\n    \"order\": {\n      \"id\": \"ord_abc123\",\n      \"polyOrderId\": \"0x...\",\n      \"status\": \"FILLED\",\n      \"side\": \"BUY\",\n      \"price\": 0.65,\n      \"size\": 50,\n      \"filledSize\": 50,\n      \"avgFillPrice\": 0.65,\n      \"transactionHash\": \"0x...\",\n      \"filledAt\": \"2025-01-15T12:00:01Z\"\n    }\n  }\n}"
      },
      {
        "title": "List Orders",
        "body": "Get your orders with real-time status from Polymarket.\n\nGET /orders?status=OPEN&limit=50\n\nParameters:\n\nstatus (optional): Filter by status - PENDING, OPEN, FILLED, PARTIALLY_FILLED, CANCELLED, EXPIRED, FAILED\nlimit (optional): Max results (default: 50, max: 100)\noffset (optional): Pagination offset\nsync (optional): Set to false to skip live status sync (default: true)\n\nReal-time Sync: Open orders (PENDING, OPEN, PARTIALLY_FILLED) are automatically synced with Polymarket in parallel for real-time status. The response includes sync metadata.\n\nExample:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/orders?status=OPEN\"\n\nResponse includes sync info:\n\n{\n  \"success\": true,\n  \"data\": [...],\n  \"sync\": { \"enabled\": true, \"updated\": 2 }\n}"
      },
      {
        "title": "Get Order Status",
        "body": "Get details for a specific order, including live status from Polymarket.\n\nGET /orders/{orderId}\n\nExample:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/orders/ord_abc123\"\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"order\": {\n      \"id\": \"ord_abc123\",\n      \"polyOrderId\": \"0x...\",\n      \"tokenId\": \"123456...\",\n      \"side\": \"BUY\",\n      \"type\": \"LIMIT\",\n      \"price\": \"0.65\",\n      \"size\": \"50\",\n      \"filledSize\": \"25\",\n      \"status\": \"PARTIALLY_FILLED\",\n      \"marketQuestion\": \"Bitcoin Up or Down?\",\n      \"outcome\": \"Up\",\n      \"submittedAt\": \"2025-01-15T12:00:00Z\"\n    },\n    \"liveStatus\": {\n      \"polymarketStatus\": \"LIVE\",\n      \"originalSize\": 50,\n      \"sizeMatched\": 25,\n      \"price\": 0.65\n    }\n  }\n}"
      },
      {
        "title": "Cancel Order",
        "body": "Cancel an open order. Only orders with status PENDING, OPEN, or PARTIALLY_FILLED can be cancelled.\n\nDELETE /orders/{orderId}\n\nExample:\n\ncurl -X DELETE -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/orders/ord_abc123\"\n\nResponse:\n\n{\n  \"success\": true,\n  \"message\": \"Order cancelled successfully\",\n  \"data\": {\n    \"order\": {\n      \"id\": \"ord_abc123\",\n      \"polyOrderId\": \"0x...\",\n      \"status\": \"CANCELLED\",\n      \"previousStatus\": \"OPEN\",\n      \"filledSize\": \"25\",\n      \"cancelledAt\": \"2025-01-15T12:05:00Z\"\n    }\n  }\n}\n\nError Responses:\n\n400: Order cannot be cancelled (already filled, cancelled, or failed)\n403: Order was not placed by your agent\n404: Order not found\n\nNotes:\n\nYou can only cancel orders that your agent placed\nIf an order is partially filled, cancelling stops further fills but keeps the filled portion\nThe previousStatus field shows what status the order had before cancellation"
      },
      {
        "title": "Close Position (One-Shot)",
        "body": "Close an entire position with a single API call. The server handles determining the correct side, fetching current price, and placing the market order.\n\nPOST /positions/{positionId}/close\n\nURL Parameters:\n\npositionId: Position ID from GET /positions\n\nOptional Body:\n\n{\n  \"type\": \"MARKET\",   // Order type: \"MARKET\" (default), \"FOK\", or \"LIMIT\"\n  \"slippage\": 0.02,   // Max slippage for LIMIT orders (default: 2%)\n  \"dryRun\": true      // Preview without executing\n}\n\nExample - Close a position:\n\ncurl -X POST -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/positions/pos_abc123/close\"\n\nExample - Preview first (dry run):\n\ncurl -X POST -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dryRun\": true}' \\\n  \"https://luckylobster.io/api/agent/v1/positions/pos_abc123/close\"\n\nResponse:\n\n{\n  \"success\": true,\n  \"message\": \"Position closed successfully\",\n  \"data\": {\n    \"order\": {\n      \"id\": \"ord_xyz789\",\n      \"polyOrderId\": \"0x...\",\n      \"status\": \"FILLED\",\n      \"side\": \"SELL\",\n      \"type\": \"MARKET\",\n      \"price\": 0.65,\n      \"size\": 100,\n      \"filledSize\": 100,\n      \"avgFillPrice\": 0.65,\n      \"transactionHash\": \"0x...\"\n    },\n    \"position\": {\n      \"id\": \"pos_abc123\",\n      \"remainingSize\": 0,\n      \"isClosed\": true\n    },\n    \"execution\": {\n      \"proceeds\": 65.00,\n      \"pnl\": 10.00,\n      \"pnlPercent\": 18.18\n    },\n    \"market\": {\n      \"slug\": \"bitcoin-up-or-down-on-february-3\",\n      \"question\": \"Bitcoin Up or Down on February 3?\",\n      \"outcome\": \"Up\"\n    }\n  }\n}\n\nDry Run Response:\n\n{\n  \"success\": true,\n  \"dryRun\": true,\n  \"message\": \"Position close preview - no order placed\",\n  \"data\": {\n    \"position\": {\n      \"id\": \"pos_abc123\",\n      \"tokenId\": \"123456...\",\n      \"size\": 100,\n      \"avgEntryPrice\": 0.55\n    },\n    \"closeOrder\": {\n      \"side\": \"SELL\",\n      \"type\": \"MARKET\",\n      \"price\": 0.65,\n      \"size\": 100\n    },\n    \"estimates\": {\n      \"currentPrice\": 0.65,\n      \"bidPrice\": 0.65,\n      \"proceeds\": 65.00,\n      \"pnl\": 10.00,\n      \"pnlPercent\": 18.18\n    }\n  }\n}\n\nError Responses:\n\n400: Position is already closed (size=0) or already settled\n403: Position belongs to another user\n404: Position not found\n503: Unable to fetch market price (market may be closed/illiquid)\n\nNotes:\n\nUses the current bid price for immediate execution\nFor LIMIT orders, applies slippage tolerance (default 2%) below bid\nPosition is partially closed if order only partially fills\nCheck position.isClosed to verify complete exit"
      },
      {
        "title": "Get Balance",
        "body": "Get raw wallet balance (live from chain).\n\nGET /balance\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"usdc\": 93.16,\n    \"matic\": 0.5,\n    \"address\": \"0x1234...\",\n    \"walletType\": \"proxy\"\n  }\n}\n\nFields:\n\nusdc: Raw USDC in wallet\nmatic: For gas (rarely needed)\naddress: Your trading wallet on Polygon"
      },
      {
        "title": "Approve Tokens (Fix \"not enough allowance\" errors)",
        "body": "If you get a \"not enough balance / allowance\" error when selling or closing positions, you need to approve the CTF (Conditional Token Framework) contract. This is a one-time setup per wallet.\n\nPOST /wallet/approve\n\nRequest Body:\n\n{\n  \"token\": \"CTF\"  // or \"USDC\", \"NEG_RISK\", \"all\"\n}\n\nToken Types:\n\nUSDC: Required for buying (usually already approved)\nCTF: Required for selling/closing positions\nNEG_RISK: Required for multi-outcome markets\nall: Approve all tokens at once\n\nExample - Fix selling errors:\n\ncurl -X POST -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"token\": \"CTF\"}' \\\n  \"https://luckylobster.io/api/agent/v1/wallet/approve\"\n\nResponse:\n\n{\n  \"success\": true,\n  \"message\": \"CTF approved successfully\",\n  \"data\": {\n    \"approvals\": { \"CTF\": \"0x...\" },\n    \"successful\": [\"CTF\"],\n    \"failed\": []\n  }\n}\n\nWhen to use:\n\nError: \"not enough balance / allowance\" when selling\nError: \"not enough balance / allowance\" when closing a position\nFirst time selling after wallet setup"
      },
      {
        "title": "Get Budget",
        "body": "Get how much you can spend. Use this before placing orders.\n\nBudget = min(wallet balance, fixed limit, % of wallet)\n\nGET /budget\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"usdc\": 46.58,\n    \"limitedBy\": \"percent\",\n    \"wallet\": 93.16,\n    \"config\": {\n      \"fixedLimit\": null,\n      \"budgetPercent\": 50,\n      \"maxPositionValue\": null,\n      \"used\": 0\n    }\n  }\n}\n\nFields:\n\nusdc: What you can spend (accounts for all limits)\nlimitedBy: Why you're capped (\"wallet\", \"fixed_limit\", \"percent\", \"position_limit\")\nwallet: Raw wallet balance\nconfig: Your budget settings"
      },
      {
        "title": "Get Positions",
        "body": "Get your current positions directly from Polymarket. The endpoint fetches from the Polymarket Data API (source of truth) with automatic fallback to CLOB trades if Data API returns empty.\n\nGET /positions\n\nParameters:\n\nstatus (optional): Filter by status - \"open\" (default), \"settled\", \"redeemable\", or \"all\"\ntoken_id (optional): Filter by specific token ID\ncondition_id (optional): Filter by condition ID (market)\nsource (optional): Force data source - \"clob\" to bypass Data API and fetch directly from CLOB trades\n\nExample - Get Open Positions:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/positions\"\n\nExample - Get Redeemable Positions:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/positions?status=redeemable\"\n\nExample - Force CLOB Source (for freshest data):\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/positions?source=clob\"\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"positions\": [\n      {\n        \"id\": \"0xabc123_0\",\n        \"tokenId\": \"12345...\",\n        \"conditionId\": \"0xabc123...\",\n        \"market\": {\n          \"slug\": \"bitcoin-up-or-down-on-february-3\",\n          \"question\": \"Bitcoin Up or Down on February 3?\",\n          \"outcome\": \"Up\",\n          \"endDate\": \"2026-02-03T17:00:00Z\",\n          \"eventSlug\": \"btc-updown\"\n        },\n        \"size\": 100.0,\n        \"avgEntryPrice\": 0.55,\n        \"currentPrice\": 0.62,\n        \"currentValue\": 62.00,\n        \"pnl\": {\n          \"unrealized\": 7.00,\n          \"unrealizedPercent\": 12.73,\n          \"realized\": 0.00,\n          \"realizedPercent\": 0.00\n        },\n        \"status\": {\n          \"isOpen\": true,\n          \"isSettled\": false,\n          \"isRedeemable\": false,\n          \"isMergeable\": false,\n          \"isNegRisk\": false\n        },\n        \"oppositeOutcome\": \"Down\",\n        \"oppositeAsset\": \"67890...\",\n        \"updatedAt\": \"2026-02-03T14:45:00.000Z\"\n      }\n    ],\n    \"summary\": {\n      \"totalPositions\": 1,\n      \"totalUnrealizedPnl\": 7.00,\n      \"totalRealizedPnl\": 0.00,\n      \"totalValue\": 62.00\n    },\n    \"filters\": {\n      \"status\": \"open\",\n      \"tokenId\": null,\n      \"conditionId\": null\n    },\n    \"wallet\": {\n      \"address\": \"0x539b2de928064898...\",\n      \"type\": \"proxy\"\n    },\n    \"source\": \"data-api\"\n  }\n}\n\nKey Fields:\n\nsize: Number of outcome tokens held\navgEntryPrice: Average price paid per token (0.00 to 1.00)\ncurrentPrice: Live price from Polymarket\ncurrentValue: Current value in USDC\npnl.unrealized: Unrealized profit/loss\npnl.unrealizedPercent: Unrealized P&L as percentage\nstatus.isRedeemable: true if market resolved and position can be redeemed\nstatus.isNegRisk: true for multi-outcome markets (require special redemption)\nwallet.type: \"proxy\" (Polymarket smart wallet) or \"eoa\" (direct wallet)\nsource: \"data-api\" or \"clob-trades\" - shows which data source was used\n\nData Source Behavior:\n\nDefault: Fetches from Polymarket Data API (most reliable, includes all historical positions)\nFallback: If Data API returns empty, automatically falls back to CLOB trades\nForced CLOB: Use ?source=clob for freshest data immediately after placing an order (Data API can have ~30s delay)\n\nWhen to use source=clob:\n\nRight after placing an order (Data API has indexing delay)\nWhen Data API returns fewer positions than expected\nFor debugging position discrepancies"
      },
      {
        "title": "Settlement & Redemption",
        "body": "When a market resolves, winning outcome tokens can be redeemed for $1.00 USDC each. The redemption endpoint automatically fetches all redeemable positions from Polymarket and redeems them in a single batched transaction."
      },
      {
        "title": "List Redeemable Positions",
        "body": "Check what positions are ready for redemption.\n\nGET /settlements/redeem\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"positions\": [\n      {\n        \"conditionId\": \"0xbc13af0a940bb9a...\",\n        \"title\": \"Bitcoin Up or Down - February 4, 1:45PM-2:00PM ET\",\n        \"outcome\": \"Down\",\n        \"size\": 5.0,\n        \"estimatedValue\": \"$5.00\",\n        \"negRisk\": false\n      }\n    ],\n    \"count\": 3,\n    \"totalValue\": \"$42.50\",\n    \"wallet\": \"0x539b2de928064898...\"\n  },\n  \"message\": \"Found 3 redeemable positions (~$42.50). POST to redeem.\"\n}"
      },
      {
        "title": "Redeem Positions",
        "body": "Redeem winning positions in a single batched transaction. You can redeem all positions or target specific ones.\n\nPOST /settlements/redeem\n\nOptional Parameters:\n\n{\n  \"conditionId\": \"0x...\",           // Redeem ONLY this specific position\n  \"conditionIds\": [\"0x...\", \"...\"], // Redeem ONLY these specific positions\n  \"limit\": 50,       // Max positions to redeem (default: 10, max: 50)\n  \"minValue\": 1.00,  // Skip positions below this value (default: $0.10)\n  \"dryRun\": true     // Preview what would be redeemed without executing\n}\n\nExample - Redeem a specific position:\n\ncurl -X POST -H \"X-API-Key: $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"conditionId\": \"0xbc13af0a940bb9a...\"}' \\\n  \"https://luckylobster.io/api/agent/v1/settlements/redeem\"\n\nExample - Redeem all:\n\ncurl -X POST -H \"X-API-Key: $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/settlements/redeem\"\n\nExample - Dry run first:\n\ncurl -X POST -H \"X-API-Key: $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dryRun\": true}' \\\n  \"https://luckylobster.io/api/agent/v1/settlements/redeem\"\n\nExample - Redeem up to 50, skip dust:\n\ncurl -X POST -H \"X-API-Key: $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"limit\": 50, \"minValue\": 1.00}' \\\n  \"https://luckylobster.io/api/agent/v1/settlements/redeem\"\n\nResponse:\n\n{\n  \"success\": true,\n  \"message\": \"Redeemed 3 positions (~$42.50)\",\n  \"data\": {\n    \"processed\": 3,\n    \"redeemed\": [\n      {\n        \"conditionId\": \"0xbc13af0a...\",\n        \"title\": \"Bitcoin Up or Down - February 4, 1:45PM-2:00PM ET\",\n        \"outcome\": \"Down\",\n        \"size\": 5.0,\n        \"txHash\": \"0x82d8d7e4d63185...\"\n      }\n    ],\n    \"failed\": [],\n    \"remaining\": 0,\n    \"totalValueRedeemed\": \"$42.50\"\n  }\n}\n\nError Responses:\n\n404: Wallet not found\n403: Missing \"redeem\" permission\n501: Polymarket Builder API not configured\n\nNotes:\n\nRedemption is gasless (executed via Polymarket relayer)\nAll positions are batched into a single on-chain transaction for efficiency\nOnly positions marked as \"redeemable\" by Polymarket are included\nBoth standard and NegRisk markets are handled automatically"
      },
      {
        "title": "Heartbeat (Status Check)",
        "body": "The heartbeat endpoint provides a single-call summary of your portfolio, pending actions, and account status. Call it periodically to stay informed."
      },
      {
        "title": "Check Heartbeat",
        "body": "GET /heartbeat?skill_version=10\n\nInclude skill_version so the server can indicate if a newer version is available.\n\nReturns aggregated data: open positions, redeemable positions, filled orders since last check, budget status, and items that may need attention.\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"status\": \"ACTION_NEEDED\",\n    \"timestamp\": \"2026-02-06T15:30:00Z\",\n    \"actions\": [\n      {\n        \"type\": \"REDEEM\",\n        \"priority\": \"high\",\n        \"summary\": \"2 positions ready to redeem (~$42.50)\",\n        \"details\": { \"positions\": [...], \"action\": \"POST /settlements/redeem\" }\n      },\n      {\n        \"type\": \"ORDER_FILLED\",\n        \"priority\": \"medium\",\n        \"summary\": \"3 order(s) filled since last check\",\n        \"details\": { \"fills\": [...], \"totalPnl\": 12.50 }\n      }\n    ],\n    \"portfolio\": {\n      \"openPositions\": 5,\n      \"totalValue\": 250.00,\n      \"unrealizedPnl\": 12.50,\n      \"redeemableCount\": 2,\n      \"redeemableValue\": 42.50\n    },\n    \"orderActivity\": {\n      \"openOrders\": 1,\n      \"filledSinceLastHeartbeat\": 3,\n      \"recentFills\": [...]\n    },\n    \"budget\": {\n      \"available\": 46.58,\n      \"limitedBy\": \"percent\",\n      \"walletBalance\": 93.16\n    },\n    \"heartbeat\": {\n      \"next_check_at\": \"2026-02-06T16:00:00Z\",\n      \"interval_ms\": 1800000,\n      \"active_hours\": { \"start\": \"09:00\", \"end\": \"22:00\", \"timezone\": \"America/New_York\" },\n      \"heartbeat_count\": 42,\n      \"latest_skill_version\": 10\n    },\n    \"realtime\": {\n      \"subscribedMarkets\": 3,\n      \"clobConnected\": true,\n      \"sportsConnected\": false,\n      \"cryptoConnected\": true\n    }\n  }\n}\n\nStatus Values:\n\nACTION_NEEDED: Items may need attention. Check the actions array.\nOK: Nothing needs attention.\nSLEEPING: Outside configured active hours.\n\nAction Types:\n\nREDEEM (high): Settled positions ready for redemption. Call POST /settlements/redeem.\nORDER_FILLED (medium): Orders filled since last heartbeat. Includes P&L details.\nBUDGET_LOW (medium): Budget running low.\nPOSITION_EXPIRING (low): Open positions in markets closing within 30 minutes.\nSEEK_TRADES (low): Budget is available. Trading opportunities may exist — use GET /markets/search or GET /markets/crypto to browse.\n\nHeartbeat Scheduling:\n\nThe response includes heartbeat.next_check_at as a suggested time for your next call, and heartbeat.latest_skill_version so you can check whether a newer skill version is available on ClawHub. Use the suggested interval or your own preferred schedule."
      },
      {
        "title": "Autonomous Strategies",
        "body": "Create server-side trading strategies that execute automatically. Instead of making trade decisions on every heartbeat (which costs tokens), define rules once and let the server trade for you."
      },
      {
        "title": "Strategy Types",
        "body": "PRICE_ALERT - Buy or sell when price hits a target (stop-loss, take-profit, limit buy)\nRECURRING_BUY - Dollar-cost average into a market at fixed intervals\nBUY_LOW_SELL_HIGH - Buy below a floor, sell above a ceiling, repeat"
      },
      {
        "title": "Create Strategy",
        "body": "POST ${baseUrl}/api/agent/v1/strategies\nAuthorization: Bearer {api_key}\n\n// PRICE_ALERT example: Sell if price drops below 0.35\n{\n  \"name\": \"BTC Stop-Loss\",\n  \"type\": \"PRICE_ALERT\",\n  \"config\": {\n    \"marketQuery\": \"bitcoin\",\n    \"outcome\": \"Yes\",\n    \"side\": \"SELL\",\n    \"triggerCondition\": \"PRICE_LTE\",\n    \"triggerPrice\": 0.35,\n    \"size\": 100,\n    \"orderType\": \"MARKET\"\n  },\n  \"maxBudget\": 50\n}\n\n// RECURRING_BUY example: Buy $10 of Bitcoin every hour\n{\n  \"name\": \"BTC Recurring Hourly\",\n  \"type\": \"RECURRING_BUY\",\n  \"config\": {\n    \"marketQuery\": \"bitcoin\",\n    \"outcome\": \"Yes\",\n    \"amountPerInterval\": 10,\n    \"interval\": \"1h\",\n    \"maxTotalAmount\": 200,\n    \"priceLimit\": 0.70\n  },\n  \"maxBudget\": 200\n}\n\n// BUY_LOW_SELL_HIGH example: Buy below 0.40, sell above 0.60\n{\n  \"name\": \"BTC Range Trader\",\n  \"type\": \"BUY_LOW_SELL_HIGH\",\n  \"config\": {\n    \"marketQuery\": \"bitcoin\",\n    \"outcome\": \"Yes\",\n    \"buyBelow\": 0.40,\n    \"sellAbove\": 0.60,\n    \"sizePerTrade\": 50,\n    \"maxOpenSize\": 200\n  },\n  \"maxBudget\": 500\n}\n\n// COPY_TRADE example: Mirror a wallet's trades with $10 per copy\n{\n  \"name\": \"Copy Whale\",\n  \"type\": \"COPY_TRADE\",\n  \"config\": {\n    \"targetAddress\": \"0x1234567890abcdef1234567890abcdef12345678\",\n    \"sizingMode\": \"fixed\",\n    \"fixedAmount\": 10,\n    \"copySells\": true,\n    \"maxPositionSize\": 500\n  },\n  \"maxBudget\": 500\n}\n\n// COPY_TRADE proportional example: Copy 50% of target's trade size\n{\n  \"name\": \"Mirror Trader\",\n  \"type\": \"COPY_TRADE\",\n  \"config\": {\n    \"targetAddress\": \"0xabcdefabcdefabcdefabcdefabcdefabcdefabcd\",\n    \"sizingMode\": \"proportional\",\n    \"proportionPct\": 50,\n    \"copySells\": true\n  },\n  \"maxBudget\": 1000\n}"
      },
      {
        "title": "COPY_TRADE Config Fields",
        "body": "FieldRequiredDescriptiontargetAddressYesWallet address to copy (0x + 40 hex chars)sizingModeYes\"fixed\" (fixed USDC per trade) or \"proportional\" (% of target's size)fixedAmountWhen fixedUSDC to spend per copy tradeproportionPctWhen proportional1-100, percentage of target's trade sizecopySellsYestrue to also copy sell trades, false for buys onlymaxPositionSizeNoMax shares to hold per tokentokenFilterNoArray of token IDs — only copy trades for these tokens\n\nCopy trading monitors the Polygon blockchain in real-time (~2 second detection). It cannot copy your own wallet."
      },
      {
        "title": "List Strategies",
        "body": "GET ${baseUrl}/api/agent/v1/strategies\nGET ${baseUrl}/api/agent/v1/strategies?status=ACTIVE&type=DCA"
      },
      {
        "title": "Get Strategy Details",
        "body": "GET ${baseUrl}/api/agent/v1/strategies/{id}\n\nReturns full strategy with last 20 execution records."
      },
      {
        "title": "Update Strategy",
        "body": "PATCH ${baseUrl}/api/agent/v1/strategies/{id}\n{ \"config\": { ... }, \"maxBudget\": 300 }"
      },
      {
        "title": "Pause / Resume / Cancel",
        "body": "POST ${baseUrl}/api/agent/v1/strategies/{id}/pause\nPOST ${baseUrl}/api/agent/v1/strategies/{id}/resume\nDELETE ${baseUrl}/api/agent/v1/strategies/{id}"
      },
      {
        "title": "Strategy Lifecycle",
        "body": "ACTIVE - Server evaluates every ~10 seconds\nPAUSED - Paused by user (from dashboard) or agent. Not evaluated until resumed.\nERROR - Auto-paused after 3 consecutive failures. Use POST /strategies/{id}/resume to retry.\nCOMPLETED - Budget exhausted or one-shot trigger fired\nCANCELLED - Cancelled by user (from dashboard) or agent. Cannot be resumed.\nEXPIRED - Past 24-hour default TTL (or custom expiresAt). Cannot be resumed."
      },
      {
        "title": "Crypto Market Auto-Discovery",
        "body": "For strategies using marketQuery instead of tokenId: the server automatically discovers the current active market each evaluation. For known crypto assets (btc, eth, sol, xrp, etc.), this uses deterministic slug-based lookups — the same approach as the market-data-worker. This reliably handles Polymarket's ephemeral crypto markets (15-min, hourly, daily) that expire and are replaced. Non-crypto queries fall back to text search."
      },
      {
        "title": "COPY_TRADE Real-Time Monitoring",
        "body": "Copy trade strategies use blockchain event monitoring (not polling) to detect target wallet activity in ~2 seconds. The server watches ERC1155 transfer events on Polymarket's CTF contract via Alchemy WebSocket RPC. Events are deduplicated, so reconnections don't cause double-execution."
      },
      {
        "title": "Heartbeat Integration",
        "body": "The heartbeat response includes a strategies section and these action types:\n\nSTRATEGY_EXECUTED (medium) — Trades placed by your strategies\nSTRATEGY_ERROR (high) — Strategies auto-paused after consecutive errors\nSTRATEGY_COMPLETED (low) — Strategies that finished (budget exhausted or trigger fired)\nSTRATEGY_PAUSED (high) — Strategy paused by the user from the dashboard. POST /strategies/{id}/resume to restart.\nSTRATEGY_CANCELLED (high) — Strategy cancelled by the user from the dashboard. Create a new strategy if needed."
      },
      {
        "title": "Best Practices",
        "body": "Set maxBudget on every strategy to limit exposure\nUse PRICE_ALERT for stop-loss/take-profit on existing positions\nUse RECURRING_BUY with marketQuery for crypto markets (handles market expiry)\nReview heartbeat periodically to see strategy execution results\nMax 10 active strategies per agent"
      },
      {
        "title": "Error Handling",
        "body": "{\n  \"success\": false,\n  \"error\": \"Error Type\",\n  \"message\": \"Human-readable message\"\n}\n\nStatus Codes:\n\n401: Invalid API key\n403: Insufficient permissions or budget exceeded\n404: Resource not found\n429: Rate limit exceeded"
      },
      {
        "title": "Permissions",
        "body": "read: View markets, orders, positions, balance\ntrade: Place orders\ncancel: Cancel orders\nredeem: Redeem settled positions"
      }
    ],
    "body": "LuckyLobster - Polymarket Trading API\n\nTrade prediction markets on Polymarket through a secure API designed for AI agents.\n\nHow Polymarket Works\n\nPolymarket is a prediction market where you trade on the outcomes of real-world events.\n\nBuying Contracts:\n\nIn active markets, you can buy outcome contracts priced from $0.01 to $0.99\nEach contract entitles you to 1 share at your purchase price\nLower prices = higher potential return, but less likely outcome (market's view)\n\nSelling Contracts:\n\nYou can sell your shares at any time before the market closes\nSell price depends on current market conditions\n\nMarket Resolution:\n\nWhen a market resolves, the winning outcome pays $1.00 USDC per share\nLosing outcomes pay $0 (or a negligible amount in rare cases)\n\nExample: You buy 100 \"Yes\" shares at $0.35 each (cost: $35). If \"Yes\" wins, you receive $100 (profit: $65). If \"No\" wins, you lose your $35.\n\nSetup\n\nIf you don't have an API key configured, use the device authorization flow to link your account.\n\nDevice Authorization Flow\n\nStep 1: Request a Device Code\n\nPOST https://luckylobster.io/api/auth/device\nContent-Type: application/json\n\n{\n  \"agent_name\": \"OpenClaw Agent\"\n}\n\n\nResponse:\n\n{\n  \"device_code\": \"abc123...\",\n  \"user_code\": \"ABCD-1234\",\n  \"verification_uri\": \"https://luckylobster.io/link\",\n  \"verification_uri_complete\": \"https://luckylobster.io/link?code=ABCD-1234\",\n  \"expires_in\": 900,\n  \"interval\": 5\n}\n\n\nStep 2: Direct the User\n\nParse the JSON response and extract the verification_uri_complete field. Display it to the user as a clickable link:\n\n🦞 To connect LuckyLobster, click: {verification_uri_complete}\n\n\nImportant: Use the verification_uri_complete value exactly as returned — do NOT concatenate fields or build the URL yourself. The value is a complete, ready-to-use URL.\n\nStep 3: Poll for Authorization\n\nPoll every 5 seconds until authorized:\n\nGET https://luckylobster.io/api/auth/device/token?device_code=abc123...\n\n\nPending response:\n\n{ \"error\": \"authorization_pending\" }\n\n\nSuccess response:\n\n{\n  \"api_key\": \"ll_abc123...\",\n  \"user_email\": \"user@example.com\",\n  \"permissions\": [\"read\", \"trade\", \"cancel\", \"redeem\"]\n}\n\n\nAll linked agents receive standard permissions: read (view markets/orders/positions), trade (buy/sell), cancel (cancel orders), and redeem (settle positions).\n\nStep 4: Store the API Key\n\nSave the API key persistently so it survives restarts. It is only returned once.\n\nUse the gateway tool with config.patch to save it in the skill config:\n\ngateway.config.patch({\n  patch: {\n    skills: {\n      entries: {\n        luckylobster: {\n          env: {\n            LUCKYLOBSTER_API_KEY: \"ll_abc123...\"\n          }\n        }\n      }\n    }\n  }\n})\n\nAuthentication\n\nAll API requests require an API key in the Authorization header:\n\nAuthorization: Bearer YOUR_API_KEY\n\nBase URL\nhttps://luckylobster.io/api/agent/v1\n\nRate Limits\nDefault: 100 requests per minute\nRate limit headers included in responses:\nX-RateLimit-Limit: Max requests allowed\nX-RateLimit-Remaining: Requests remaining\nX-RateLimit-Reset: Reset time (ISO 8601)\nEndpoints\nSearch Markets\n\nFind prediction markets on Polymarket. The search uses smart relevance scoring to return the best matches first.\n\nGET /markets/search?q={query}\n\n\nParameters:\n\nq (required for search): Natural language query - \"bitcoin 15m\", \"trump election\", \"superbowl winner\"\nlimit (optional): Max results (default: 10, max: 100)\noffset (optional): Pagination offset\nsort (optional): \"relevance\" (default), \"volume\", \"liquidity\", \"end_date\", \"recent\"\nending_soon (optional): Prioritize markets ending within 24h (default: false)\nmin_volume (optional): Minimum volume in USD (default: 100)\nmin_liquidity (optional): Minimum liquidity in USD\ntag (optional): Filter by category: \"crypto\", \"politics\", \"sports\", \"entertainment\"\naccepting_orders (optional): Only tradeable markets (default: true)\n\nSearch Tips:\n\nShorthand supported: \"btc 15m\" → \"Bitcoin Up or Down\", \"eth daily\" → \"Ethereum Up or Down on\"\nThe search auto-expands: btc→Bitcoin, eth→Ethereum, sol→Solana, etc.\nTime keywords (15m, hourly, daily) auto-expand to \"Up or Down\" queries\nResults are ranked by relevance: query match + liquidity + volume + accepting orders\nFor time-sensitive markets, add ending_soon=true to prioritize markets expiring within 24h\nFirst result is usually the best match - check context.topMatch\n\nExample - Find Current BTC Market:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/markets/search?q=bitcoin%20up%20down&ending_soon=true&limit=5\"\n\n\nExample - High-Volume Politics Markets:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/markets/search?q=election&tag=politics&sort=volume\"\n\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": \"1314069\",\n      \"slug\": \"bitcoin-up-or-down-on-february-3\",\n      \"question\": \"Bitcoin Up or Down on February 3?\",\n      \"outcomes\": [\"Up\", \"Down\"],\n      \"outcomePrices\": [\"0.65\", \"0.35\"],\n      \"volume\": \"409100.65\",\n      \"liquidity\": \"39255.13\",\n      \"endDate\": \"2026-02-03T17:00:00Z\",\n      \"active\": true,\n      \"acceptingOrders\": true\n    }\n  ],\n  \"pagination\": { \"limit\": 5, \"offset\": 0, \"count\": 1, \"hasMore\": false },\n  \"context\": {\n    \"hasResults\": true,\n    \"topMatch\": { \"id\": \"1314069\", \"question\": \"Bitcoin Up or Down on February 3?\", \"acceptingOrders\": true },\n    \"endingSoonCount\": 1\n  },\n  \"options\": {\n    \"sortBy\": [\"relevance\", \"volume\", \"liquidity\", \"end_date\", \"recent\"],\n    \"tags\": [\"crypto\", \"politics\", \"sports\", \"entertainment\"]\n  }\n}\n\n\nWorkflow for Trading:\n\nSearch: GET /markets/search?q=bitcoin up down\nUse the id from the top result to get full details: GET /markets/{id}\nResponse includes clobTokenIds - use these with trading endpoints\nQuick Crypto Market Lookup\n\nFor crypto up/down markets, use this dedicated endpoint. It uses deterministic slug-based lookups (not text search) and is the most reliable way to find crypto markets:\n\nGET /markets/crypto?asset={btc|eth|sol|xrp|doge|matic}&timeframe={daily|hourly|15m}\n\n\nExamples:\n\n/markets/crypto?asset=btc - Today's Bitcoin daily market\n/markets/crypto?asset=btc&timeframe=15m - Current Bitcoin 15-minute market\n/markets/crypto?asset=eth&timeframe=hourly - Current Ethereum hourly market\n/markets/crypto?asset=xrp&timeframe=15m - Current XRP 15-minute market\n\nResponse includes tokens array with tokenId, negRisk, and live spread data ready for trading.\n\nFind Market by Slug\n\nIf you know the exact market slug (from a Polymarket URL), use this for direct lookup:\n\nGET /markets/by-slug?slug={slug}\n\n\nExample: For URL https://polymarket.com/event/btc-updown-15m-1770129900\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/markets/by-slug?slug=btc-updown-15m-1770129900\"\n\n\nResponse includes clobTokenIds and tokens ready for trading.\n\nNote: For crypto markets, always prefer /markets/crypto over /markets/search — it uses the same deterministic slug lookups as the internal market-data-worker and is far more reliable.\n\nGet Market Details\n\nGet detailed information about a specific market, including token IDs required for market data and trading.\n\nGET /markets/{id}\n\n\nParameters:\n\nid: Market ID or condition ID (from search results)\n\nExample:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/markets/0x1234...\"\n\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": \"1314069\",\n    \"conditionId\": \"0xf46bf33576e8341821161316705ab2357312f58d58b7d157cb8dca73b656b326\",\n    \"question\": \"Bitcoin Up or Down on February 3?\",\n    \"outcomes\": [\"Up\", \"Down\"],\n    \"outcomePrices\": [\"0.345\", \"0.655\"],\n    \"tokens\": [\n      {\"tokenId\": \"36656454529662513...\", \"outcome\": \"Up\", \"price\": \"0.345\"},\n      {\"tokenId\": \"10609233133841503...\", \"outcome\": \"Down\", \"price\": \"0.655\"}\n    ],\n    \"clobTokenIds\": [\"36656454529662513...\", \"10609233133841503...\"],\n    \"volume\": \"409100.65\",\n    \"liquidity\": \"39255.13\",\n    \"active\": true,\n    \"acceptingOrders\": true,\n    \"spreads\": [\n      {\"outcome\": \"Up\", \"tokenId\": \"36656454...\", \"bid\": \"0.34\", \"ask\": \"0.35\", \"spread\": \"0.01\"}\n    ]\n  }\n}\n\n\nImportant: Use the tokenId from the tokens array or clobTokenIds for the market data endpoints below.\n\nMarket Data Endpoints\n\nThese endpoints provide real-time order book and pricing data from the Polymarket CLOB (Central Limit Order Book).\n\nWorkflow for getting market data:\n\nSearch markets: GET /markets/search?q=Bitcoin\nGet market details: GET /markets/{id} → This returns tokens[].tokenId\nGet market data: GET /orderbook?token_id={tokenId} or GET /market-data?token_id={tokenId}\nGet Order Book\n\nGet the order book summary for a token, including all bids and asks.\n\nGET /orderbook?token_id={tokenId}\n\n\nParameters:\n\ntoken_id (required): The outcome token address\ntoken_ids (optional): Comma-separated list for batch request (max 20)\n\nExample:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/orderbook?token_id=71321045...\"\n\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"tokenId\": \"71321045...\",\n    \"market\": \"0xabc...\",\n    \"timestamp\": \"2025-01-15T12:00:00Z\",\n    \"bids\": [\n      {\"price\": \"0.65\", \"size\": \"1000\"},\n      {\"price\": \"0.64\", \"size\": \"500\"}\n    ],\n    \"asks\": [\n      {\"price\": \"0.66\", \"size\": \"800\"},\n      {\"price\": \"0.67\", \"size\": \"1200\"}\n    ],\n    \"tickSize\": \"0.01\",\n    \"minOrderSize\": \"1\",\n    \"summary\": {\n      \"bidCount\": 15,\n      \"askCount\": 12,\n      \"bestBid\": \"0.65\",\n      \"bestAsk\": \"0.66\",\n      \"spread\": \"0.01\",\n      \"totalBidSize\": \"5000.00\",\n      \"totalAskSize\": \"4200.00\"\n    }\n  }\n}\n\nGet Prices\n\nGet current prices for a token including midpoint, buy/sell prices, and last trade.\n\nReal-time data: When you have open positions, the server automatically subscribes to Polymarket WebSocket feeds for those markets. Price data from /prices and /heartbeat will use cached real-time data when available (indicated by \"source\": \"websocket\" in the response). This is significantly faster than HTTP polling.\n\nGET /prices?token_id={tokenId}\n\n\nParameters:\n\ntoken_id (required): The outcome token address\nside (optional): BUY or SELL to get price for specific side\ntoken_ids (optional): Comma-separated list for batch request (max 20)\n\nExample:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/prices?token_id=71321045...\"\n\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"tokenId\": \"71321045...\",\n    \"midpoint\": \"0.655\",\n    \"lastTradePrice\": \"0.65\",\n    \"buyPrice\": \"0.66\",\n    \"sellPrice\": \"0.65\",\n    \"timestamp\": \"2025-01-15T12:00:00Z\",\n    \"source\": \"websocket\"\n  }\n}\n\nGet Spread\n\nGet the bid-ask spread for a token.\n\nGET /spread?token_id={tokenId}\n\n\nParameters:\n\ntoken_id (required): The outcome token address\ntoken_ids (optional): Comma-separated list for batch request (max 20)\n\nExample:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/spread?token_id=71321045...\"\n\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"tokenId\": \"71321045...\",\n    \"bid\": \"0.65\",\n    \"ask\": \"0.66\",\n    \"spread\": \"0.01\",\n    \"spreadPercent\": \"1.52\",\n    \"timestamp\": \"2025-01-15T12:00:00Z\"\n  }\n}\n\nGet Comprehensive Market Data\n\nGet all market data in a single request (order book summary, prices, spread).\n\nGET /market-data?token_id={tokenId}\n\n\nParameters:\n\ntoken_id (required): The outcome token address\n\nExample:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/market-data?token_id=71321045...\"\n\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"tokenId\": \"71321045...\",\n    \"prices\": {\n      \"midpoint\": \"0.655\",\n      \"bestBid\": \"0.65\",\n      \"bestAsk\": \"0.66\",\n      \"lastTrade\": \"0.65\"\n    },\n    \"spread\": {\n      \"absolute\": \"0.01\",\n      \"percent\": \"1.52\"\n    },\n    \"orderbook\": {\n      \"bidCount\": 15,\n      \"askCount\": 12,\n      \"totalBidSize\": \"5000.00\",\n      \"totalAskSize\": \"4200.00\",\n      \"topBids\": [{\"price\": \"0.65\", \"size\": \"1000\"}],\n      \"topAsks\": [{\"price\": \"0.66\", \"size\": \"800\"}]\n    },\n    \"parameters\": {\n      \"tickSize\": \"0.01\",\n      \"minOrderSize\": \"1\"\n    },\n    \"timestamp\": \"2025-01-15T12:00:00Z\"\n  }\n}\n\nTrading Endpoints\nPlace Order\n\nPlace a buy or sell order on a market. Returns real-time order status.\n\nPOST /orders\nContent-Type: application/json\n\n{\n  \"tokenId\": \"0x1234...\",\n  \"side\": \"BUY\",\n  \"price\": 0.65,\n  \"size\": 50,\n  \"type\": \"LIMIT\"\n}\n\n\nParameters:\n\ntokenId: Outcome token address (from market data)\nside: BUY or SELL\nprice: Price per share (0.01 to 0.99)\nsize: Number of shares\ntype: LIMIT, MARKET, FOK, or FAK\n\nConstraints:\n\nMinimum order amount: price * size must be >= $1.00 USDC\nMinimum order size: 5 shares\nPrice must be a multiple of 0.01 (tick size)\n\nOrder Type Behavior:\n\nMARKET: Fills as much as available at your price or better, kills the rest (recommended for most trades)\nLIMIT: Rests on the order book until filled or cancelled\nFOK: Fill-or-Kill — must fill 100% or the entire order is rejected. Use only when you need guaranteed full fills. High failure rate on thin markets.\nFAK: Fill-and-Kill — same as MARKET\n\nTip: For short-timeframe markets (5m, 15m) where order books can be thin, prefer MARKET or LIMIT over FOK. MARKET orders will fill whatever is available. LIMIT orders rest on the book and can fill as liquidity arrives.\n\nReal-time Status: The response includes the order's current status from Polymarket. MARKET and FAK orders return faster (~500ms) since they execute immediately. LIMIT orders are checked after ~1 second.\n\nExample:\n\ncurl -X POST -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"tokenId\":\"0x1234...\",\"side\":\"BUY\",\"price\":0.65,\"size\":50,\"type\":\"LIMIT\"}' \\\n  \"https://luckylobster.io/api/agent/v1/orders\"\n\n\nResponse (with fill data when available):\n\n{\n  \"success\": true,\n  \"data\": {\n    \"order\": {\n      \"id\": \"ord_abc123\",\n      \"polyOrderId\": \"0x...\",\n      \"status\": \"FILLED\",\n      \"side\": \"BUY\",\n      \"price\": 0.65,\n      \"size\": 50,\n      \"filledSize\": 50,\n      \"avgFillPrice\": 0.65,\n      \"transactionHash\": \"0x...\",\n      \"filledAt\": \"2025-01-15T12:00:01Z\"\n    }\n  }\n}\n\nList Orders\n\nGet your orders with real-time status from Polymarket.\n\nGET /orders?status=OPEN&limit=50\n\n\nParameters:\n\nstatus (optional): Filter by status - PENDING, OPEN, FILLED, PARTIALLY_FILLED, CANCELLED, EXPIRED, FAILED\nlimit (optional): Max results (default: 50, max: 100)\noffset (optional): Pagination offset\nsync (optional): Set to false to skip live status sync (default: true)\n\nReal-time Sync: Open orders (PENDING, OPEN, PARTIALLY_FILLED) are automatically synced with Polymarket in parallel for real-time status. The response includes sync metadata.\n\nExample:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/orders?status=OPEN\"\n\n\nResponse includes sync info:\n\n{\n  \"success\": true,\n  \"data\": [...],\n  \"sync\": { \"enabled\": true, \"updated\": 2 }\n}\n\nGet Order Status\n\nGet details for a specific order, including live status from Polymarket.\n\nGET /orders/{orderId}\n\n\nExample:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/orders/ord_abc123\"\n\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"order\": {\n      \"id\": \"ord_abc123\",\n      \"polyOrderId\": \"0x...\",\n      \"tokenId\": \"123456...\",\n      \"side\": \"BUY\",\n      \"type\": \"LIMIT\",\n      \"price\": \"0.65\",\n      \"size\": \"50\",\n      \"filledSize\": \"25\",\n      \"status\": \"PARTIALLY_FILLED\",\n      \"marketQuestion\": \"Bitcoin Up or Down?\",\n      \"outcome\": \"Up\",\n      \"submittedAt\": \"2025-01-15T12:00:00Z\"\n    },\n    \"liveStatus\": {\n      \"polymarketStatus\": \"LIVE\",\n      \"originalSize\": 50,\n      \"sizeMatched\": 25,\n      \"price\": 0.65\n    }\n  }\n}\n\nCancel Order\n\nCancel an open order. Only orders with status PENDING, OPEN, or PARTIALLY_FILLED can be cancelled.\n\nDELETE /orders/{orderId}\n\n\nExample:\n\ncurl -X DELETE -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/orders/ord_abc123\"\n\n\nResponse:\n\n{\n  \"success\": true,\n  \"message\": \"Order cancelled successfully\",\n  \"data\": {\n    \"order\": {\n      \"id\": \"ord_abc123\",\n      \"polyOrderId\": \"0x...\",\n      \"status\": \"CANCELLED\",\n      \"previousStatus\": \"OPEN\",\n      \"filledSize\": \"25\",\n      \"cancelledAt\": \"2025-01-15T12:05:00Z\"\n    }\n  }\n}\n\n\nError Responses:\n\n400: Order cannot be cancelled (already filled, cancelled, or failed)\n403: Order was not placed by your agent\n404: Order not found\n\nNotes:\n\nYou can only cancel orders that your agent placed\nIf an order is partially filled, cancelling stops further fills but keeps the filled portion\nThe previousStatus field shows what status the order had before cancellation\nClose Position (One-Shot)\n\nClose an entire position with a single API call. The server handles determining the correct side, fetching current price, and placing the market order.\n\nPOST /positions/{positionId}/close\n\n\nURL Parameters:\n\npositionId: Position ID from GET /positions\n\nOptional Body:\n\n{\n  \"type\": \"MARKET\",   // Order type: \"MARKET\" (default), \"FOK\", or \"LIMIT\"\n  \"slippage\": 0.02,   // Max slippage for LIMIT orders (default: 2%)\n  \"dryRun\": true      // Preview without executing\n}\n\n\nExample - Close a position:\n\ncurl -X POST -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/positions/pos_abc123/close\"\n\n\nExample - Preview first (dry run):\n\ncurl -X POST -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dryRun\": true}' \\\n  \"https://luckylobster.io/api/agent/v1/positions/pos_abc123/close\"\n\n\nResponse:\n\n{\n  \"success\": true,\n  \"message\": \"Position closed successfully\",\n  \"data\": {\n    \"order\": {\n      \"id\": \"ord_xyz789\",\n      \"polyOrderId\": \"0x...\",\n      \"status\": \"FILLED\",\n      \"side\": \"SELL\",\n      \"type\": \"MARKET\",\n      \"price\": 0.65,\n      \"size\": 100,\n      \"filledSize\": 100,\n      \"avgFillPrice\": 0.65,\n      \"transactionHash\": \"0x...\"\n    },\n    \"position\": {\n      \"id\": \"pos_abc123\",\n      \"remainingSize\": 0,\n      \"isClosed\": true\n    },\n    \"execution\": {\n      \"proceeds\": 65.00,\n      \"pnl\": 10.00,\n      \"pnlPercent\": 18.18\n    },\n    \"market\": {\n      \"slug\": \"bitcoin-up-or-down-on-february-3\",\n      \"question\": \"Bitcoin Up or Down on February 3?\",\n      \"outcome\": \"Up\"\n    }\n  }\n}\n\n\nDry Run Response:\n\n{\n  \"success\": true,\n  \"dryRun\": true,\n  \"message\": \"Position close preview - no order placed\",\n  \"data\": {\n    \"position\": {\n      \"id\": \"pos_abc123\",\n      \"tokenId\": \"123456...\",\n      \"size\": 100,\n      \"avgEntryPrice\": 0.55\n    },\n    \"closeOrder\": {\n      \"side\": \"SELL\",\n      \"type\": \"MARKET\",\n      \"price\": 0.65,\n      \"size\": 100\n    },\n    \"estimates\": {\n      \"currentPrice\": 0.65,\n      \"bidPrice\": 0.65,\n      \"proceeds\": 65.00,\n      \"pnl\": 10.00,\n      \"pnlPercent\": 18.18\n    }\n  }\n}\n\n\nError Responses:\n\n400: Position is already closed (size=0) or already settled\n403: Position belongs to another user\n404: Position not found\n503: Unable to fetch market price (market may be closed/illiquid)\n\nNotes:\n\nUses the current bid price for immediate execution\nFor LIMIT orders, applies slippage tolerance (default 2%) below bid\nPosition is partially closed if order only partially fills\nCheck position.isClosed to verify complete exit\nGet Balance\n\nGet raw wallet balance (live from chain).\n\nGET /balance\n\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"usdc\": 93.16,\n    \"matic\": 0.5,\n    \"address\": \"0x1234...\",\n    \"walletType\": \"proxy\"\n  }\n}\n\n\nFields:\n\nusdc: Raw USDC in wallet\nmatic: For gas (rarely needed)\naddress: Your trading wallet on Polygon\nApprove Tokens (Fix \"not enough allowance\" errors)\n\nIf you get a \"not enough balance / allowance\" error when selling or closing positions, you need to approve the CTF (Conditional Token Framework) contract. This is a one-time setup per wallet.\n\nPOST /wallet/approve\n\n\nRequest Body:\n\n{\n  \"token\": \"CTF\"  // or \"USDC\", \"NEG_RISK\", \"all\"\n}\n\n\nToken Types:\n\nUSDC: Required for buying (usually already approved)\nCTF: Required for selling/closing positions\nNEG_RISK: Required for multi-outcome markets\nall: Approve all tokens at once\n\nExample - Fix selling errors:\n\ncurl -X POST -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"token\": \"CTF\"}' \\\n  \"https://luckylobster.io/api/agent/v1/wallet/approve\"\n\n\nResponse:\n\n{\n  \"success\": true,\n  \"message\": \"CTF approved successfully\",\n  \"data\": {\n    \"approvals\": { \"CTF\": \"0x...\" },\n    \"successful\": [\"CTF\"],\n    \"failed\": []\n  }\n}\n\n\nWhen to use:\n\nError: \"not enough balance / allowance\" when selling\nError: \"not enough balance / allowance\" when closing a position\nFirst time selling after wallet setup\nGet Budget\n\nGet how much you can spend. Use this before placing orders.\n\nBudget = min(wallet balance, fixed limit, % of wallet)\n\nGET /budget\n\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"usdc\": 46.58,\n    \"limitedBy\": \"percent\",\n    \"wallet\": 93.16,\n    \"config\": {\n      \"fixedLimit\": null,\n      \"budgetPercent\": 50,\n      \"maxPositionValue\": null,\n      \"used\": 0\n    }\n  }\n}\n\n\nFields:\n\nusdc: What you can spend (accounts for all limits)\nlimitedBy: Why you're capped (\"wallet\", \"fixed_limit\", \"percent\", \"position_limit\")\nwallet: Raw wallet balance\nconfig: Your budget settings\nGet Positions\n\nGet your current positions directly from Polymarket. The endpoint fetches from the Polymarket Data API (source of truth) with automatic fallback to CLOB trades if Data API returns empty.\n\nGET /positions\n\n\nParameters:\n\nstatus (optional): Filter by status - \"open\" (default), \"settled\", \"redeemable\", or \"all\"\ntoken_id (optional): Filter by specific token ID\ncondition_id (optional): Filter by condition ID (market)\nsource (optional): Force data source - \"clob\" to bypass Data API and fetch directly from CLOB trades\n\nExample - Get Open Positions:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/positions\"\n\n\nExample - Get Redeemable Positions:\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/positions?status=redeemable\"\n\n\nExample - Force CLOB Source (for freshest data):\n\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/positions?source=clob\"\n\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"positions\": [\n      {\n        \"id\": \"0xabc123_0\",\n        \"tokenId\": \"12345...\",\n        \"conditionId\": \"0xabc123...\",\n        \"market\": {\n          \"slug\": \"bitcoin-up-or-down-on-february-3\",\n          \"question\": \"Bitcoin Up or Down on February 3?\",\n          \"outcome\": \"Up\",\n          \"endDate\": \"2026-02-03T17:00:00Z\",\n          \"eventSlug\": \"btc-updown\"\n        },\n        \"size\": 100.0,\n        \"avgEntryPrice\": 0.55,\n        \"currentPrice\": 0.62,\n        \"currentValue\": 62.00,\n        \"pnl\": {\n          \"unrealized\": 7.00,\n          \"unrealizedPercent\": 12.73,\n          \"realized\": 0.00,\n          \"realizedPercent\": 0.00\n        },\n        \"status\": {\n          \"isOpen\": true,\n          \"isSettled\": false,\n          \"isRedeemable\": false,\n          \"isMergeable\": false,\n          \"isNegRisk\": false\n        },\n        \"oppositeOutcome\": \"Down\",\n        \"oppositeAsset\": \"67890...\",\n        \"updatedAt\": \"2026-02-03T14:45:00.000Z\"\n      }\n    ],\n    \"summary\": {\n      \"totalPositions\": 1,\n      \"totalUnrealizedPnl\": 7.00,\n      \"totalRealizedPnl\": 0.00,\n      \"totalValue\": 62.00\n    },\n    \"filters\": {\n      \"status\": \"open\",\n      \"tokenId\": null,\n      \"conditionId\": null\n    },\n    \"wallet\": {\n      \"address\": \"0x539b2de928064898...\",\n      \"type\": \"proxy\"\n    },\n    \"source\": \"data-api\"\n  }\n}\n\n\nKey Fields:\n\nsize: Number of outcome tokens held\navgEntryPrice: Average price paid per token (0.00 to 1.00)\ncurrentPrice: Live price from Polymarket\ncurrentValue: Current value in USDC\npnl.unrealized: Unrealized profit/loss\npnl.unrealizedPercent: Unrealized P&L as percentage\nstatus.isRedeemable: true if market resolved and position can be redeemed\nstatus.isNegRisk: true for multi-outcome markets (require special redemption)\nwallet.type: \"proxy\" (Polymarket smart wallet) or \"eoa\" (direct wallet)\nsource: \"data-api\" or \"clob-trades\" - shows which data source was used\n\nData Source Behavior:\n\nDefault: Fetches from Polymarket Data API (most reliable, includes all historical positions)\nFallback: If Data API returns empty, automatically falls back to CLOB trades\nForced CLOB: Use ?source=clob for freshest data immediately after placing an order (Data API can have ~30s delay)\n\nWhen to use source=clob:\n\nRight after placing an order (Data API has indexing delay)\nWhen Data API returns fewer positions than expected\nFor debugging position discrepancies\nSettlement & Redemption\n\nWhen a market resolves, winning outcome tokens can be redeemed for $1.00 USDC each. The redemption endpoint automatically fetches all redeemable positions from Polymarket and redeems them in a single batched transaction.\n\nList Redeemable Positions\n\nCheck what positions are ready for redemption.\n\nGET /settlements/redeem\n\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"positions\": [\n      {\n        \"conditionId\": \"0xbc13af0a940bb9a...\",\n        \"title\": \"Bitcoin Up or Down - February 4, 1:45PM-2:00PM ET\",\n        \"outcome\": \"Down\",\n        \"size\": 5.0,\n        \"estimatedValue\": \"$5.00\",\n        \"negRisk\": false\n      }\n    ],\n    \"count\": 3,\n    \"totalValue\": \"$42.50\",\n    \"wallet\": \"0x539b2de928064898...\"\n  },\n  \"message\": \"Found 3 redeemable positions (~$42.50). POST to redeem.\"\n}\n\nRedeem Positions\n\nRedeem winning positions in a single batched transaction. You can redeem all positions or target specific ones.\n\nPOST /settlements/redeem\n\n\nOptional Parameters:\n\n{\n  \"conditionId\": \"0x...\",           // Redeem ONLY this specific position\n  \"conditionIds\": [\"0x...\", \"...\"], // Redeem ONLY these specific positions\n  \"limit\": 50,       // Max positions to redeem (default: 10, max: 50)\n  \"minValue\": 1.00,  // Skip positions below this value (default: $0.10)\n  \"dryRun\": true     // Preview what would be redeemed without executing\n}\n\n\nExample - Redeem a specific position:\n\ncurl -X POST -H \"X-API-Key: $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"conditionId\": \"0xbc13af0a940bb9a...\"}' \\\n  \"https://luckylobster.io/api/agent/v1/settlements/redeem\"\n\n\nExample - Redeem all:\n\ncurl -X POST -H \"X-API-Key: $LUCKYLOBSTER_API_KEY\" \\\n  \"https://luckylobster.io/api/agent/v1/settlements/redeem\"\n\n\nExample - Dry run first:\n\ncurl -X POST -H \"X-API-Key: $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dryRun\": true}' \\\n  \"https://luckylobster.io/api/agent/v1/settlements/redeem\"\n\n\nExample - Redeem up to 50, skip dust:\n\ncurl -X POST -H \"X-API-Key: $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"limit\": 50, \"minValue\": 1.00}' \\\n  \"https://luckylobster.io/api/agent/v1/settlements/redeem\"\n\n\nResponse:\n\n{\n  \"success\": true,\n  \"message\": \"Redeemed 3 positions (~$42.50)\",\n  \"data\": {\n    \"processed\": 3,\n    \"redeemed\": [\n      {\n        \"conditionId\": \"0xbc13af0a...\",\n        \"title\": \"Bitcoin Up or Down - February 4, 1:45PM-2:00PM ET\",\n        \"outcome\": \"Down\",\n        \"size\": 5.0,\n        \"txHash\": \"0x82d8d7e4d63185...\"\n      }\n    ],\n    \"failed\": [],\n    \"remaining\": 0,\n    \"totalValueRedeemed\": \"$42.50\"\n  }\n}\n\n\nError Responses:\n\n404: Wallet not found\n403: Missing \"redeem\" permission\n501: Polymarket Builder API not configured\n\nNotes:\n\nRedemption is gasless (executed via Polymarket relayer)\nAll positions are batched into a single on-chain transaction for efficiency\nOnly positions marked as \"redeemable\" by Polymarket are included\nBoth standard and NegRisk markets are handled automatically\nHeartbeat (Status Check)\n\nThe heartbeat endpoint provides a single-call summary of your portfolio, pending actions, and account status. Call it periodically to stay informed.\n\nCheck Heartbeat\nGET /heartbeat?skill_version=10\n\n\nInclude skill_version so the server can indicate if a newer version is available.\n\nReturns aggregated data: open positions, redeemable positions, filled orders since last check, budget status, and items that may need attention.\n\nResponse:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"status\": \"ACTION_NEEDED\",\n    \"timestamp\": \"2026-02-06T15:30:00Z\",\n    \"actions\": [\n      {\n        \"type\": \"REDEEM\",\n        \"priority\": \"high\",\n        \"summary\": \"2 positions ready to redeem (~$42.50)\",\n        \"details\": { \"positions\": [...], \"action\": \"POST /settlements/redeem\" }\n      },\n      {\n        \"type\": \"ORDER_FILLED\",\n        \"priority\": \"medium\",\n        \"summary\": \"3 order(s) filled since last check\",\n        \"details\": { \"fills\": [...], \"totalPnl\": 12.50 }\n      }\n    ],\n    \"portfolio\": {\n      \"openPositions\": 5,\n      \"totalValue\": 250.00,\n      \"unrealizedPnl\": 12.50,\n      \"redeemableCount\": 2,\n      \"redeemableValue\": 42.50\n    },\n    \"orderActivity\": {\n      \"openOrders\": 1,\n      \"filledSinceLastHeartbeat\": 3,\n      \"recentFills\": [...]\n    },\n    \"budget\": {\n      \"available\": 46.58,\n      \"limitedBy\": \"percent\",\n      \"walletBalance\": 93.16\n    },\n    \"heartbeat\": {\n      \"next_check_at\": \"2026-02-06T16:00:00Z\",\n      \"interval_ms\": 1800000,\n      \"active_hours\": { \"start\": \"09:00\", \"end\": \"22:00\", \"timezone\": \"America/New_York\" },\n      \"heartbeat_count\": 42,\n      \"latest_skill_version\": 10\n    },\n    \"realtime\": {\n      \"subscribedMarkets\": 3,\n      \"clobConnected\": true,\n      \"sportsConnected\": false,\n      \"cryptoConnected\": true\n    }\n  }\n}\n\n\nStatus Values:\n\nACTION_NEEDED: Items may need attention. Check the actions array.\nOK: Nothing needs attention.\nSLEEPING: Outside configured active hours.\n\nAction Types:\n\nREDEEM (high): Settled positions ready for redemption. Call POST /settlements/redeem.\nORDER_FILLED (medium): Orders filled since last heartbeat. Includes P&L details.\nBUDGET_LOW (medium): Budget running low.\nPOSITION_EXPIRING (low): Open positions in markets closing within 30 minutes.\nSEEK_TRADES (low): Budget is available. Trading opportunities may exist — use GET /markets/search or GET /markets/crypto to browse.\n\nHeartbeat Scheduling:\n\nThe response includes heartbeat.next_check_at as a suggested time for your next call, and heartbeat.latest_skill_version so you can check whether a newer skill version is available on ClawHub. Use the suggested interval or your own preferred schedule.\n\nAutonomous Strategies\n\nCreate server-side trading strategies that execute automatically. Instead of making trade decisions on every heartbeat (which costs tokens), define rules once and let the server trade for you.\n\nStrategy Types\n\nPRICE_ALERT - Buy or sell when price hits a target (stop-loss, take-profit, limit buy) RECURRING_BUY - Dollar-cost average into a market at fixed intervals BUY_LOW_SELL_HIGH - Buy below a floor, sell above a ceiling, repeat\n\nCreate Strategy\nPOST ${baseUrl}/api/agent/v1/strategies\nAuthorization: Bearer {api_key}\n\n// PRICE_ALERT example: Sell if price drops below 0.35\n{\n  \"name\": \"BTC Stop-Loss\",\n  \"type\": \"PRICE_ALERT\",\n  \"config\": {\n    \"marketQuery\": \"bitcoin\",\n    \"outcome\": \"Yes\",\n    \"side\": \"SELL\",\n    \"triggerCondition\": \"PRICE_LTE\",\n    \"triggerPrice\": 0.35,\n    \"size\": 100,\n    \"orderType\": \"MARKET\"\n  },\n  \"maxBudget\": 50\n}\n\n// RECURRING_BUY example: Buy $10 of Bitcoin every hour\n{\n  \"name\": \"BTC Recurring Hourly\",\n  \"type\": \"RECURRING_BUY\",\n  \"config\": {\n    \"marketQuery\": \"bitcoin\",\n    \"outcome\": \"Yes\",\n    \"amountPerInterval\": 10,\n    \"interval\": \"1h\",\n    \"maxTotalAmount\": 200,\n    \"priceLimit\": 0.70\n  },\n  \"maxBudget\": 200\n}\n\n// BUY_LOW_SELL_HIGH example: Buy below 0.40, sell above 0.60\n{\n  \"name\": \"BTC Range Trader\",\n  \"type\": \"BUY_LOW_SELL_HIGH\",\n  \"config\": {\n    \"marketQuery\": \"bitcoin\",\n    \"outcome\": \"Yes\",\n    \"buyBelow\": 0.40,\n    \"sellAbove\": 0.60,\n    \"sizePerTrade\": 50,\n    \"maxOpenSize\": 200\n  },\n  \"maxBudget\": 500\n}\n\n// COPY_TRADE example: Mirror a wallet's trades with $10 per copy\n{\n  \"name\": \"Copy Whale\",\n  \"type\": \"COPY_TRADE\",\n  \"config\": {\n    \"targetAddress\": \"0x1234567890abcdef1234567890abcdef12345678\",\n    \"sizingMode\": \"fixed\",\n    \"fixedAmount\": 10,\n    \"copySells\": true,\n    \"maxPositionSize\": 500\n  },\n  \"maxBudget\": 500\n}\n\n// COPY_TRADE proportional example: Copy 50% of target's trade size\n{\n  \"name\": \"Mirror Trader\",\n  \"type\": \"COPY_TRADE\",\n  \"config\": {\n    \"targetAddress\": \"0xabcdefabcdefabcdefabcdefabcdefabcdefabcd\",\n    \"sizingMode\": \"proportional\",\n    \"proportionPct\": 50,\n    \"copySells\": true\n  },\n  \"maxBudget\": 1000\n}\n\nCOPY_TRADE Config Fields\nField\tRequired\tDescription\ntargetAddress\tYes\tWallet address to copy (0x + 40 hex chars)\nsizingMode\tYes\t\"fixed\" (fixed USDC per trade) or \"proportional\" (% of target's size)\nfixedAmount\tWhen fixed\tUSDC to spend per copy trade\nproportionPct\tWhen proportional\t1-100, percentage of target's trade size\ncopySells\tYes\ttrue to also copy sell trades, false for buys only\nmaxPositionSize\tNo\tMax shares to hold per token\ntokenFilter\tNo\tArray of token IDs — only copy trades for these tokens\n\nCopy trading monitors the Polygon blockchain in real-time (~2 second detection). It cannot copy your own wallet.\n\nList Strategies\nGET ${baseUrl}/api/agent/v1/strategies\nGET ${baseUrl}/api/agent/v1/strategies?status=ACTIVE&type=DCA\n\nGet Strategy Details\nGET ${baseUrl}/api/agent/v1/strategies/{id}\n\n\nReturns full strategy with last 20 execution records.\n\nUpdate Strategy\nPATCH ${baseUrl}/api/agent/v1/strategies/{id}\n{ \"config\": { ... }, \"maxBudget\": 300 }\n\nPause / Resume / Cancel\nPOST ${baseUrl}/api/agent/v1/strategies/{id}/pause\nPOST ${baseUrl}/api/agent/v1/strategies/{id}/resume\nDELETE ${baseUrl}/api/agent/v1/strategies/{id}\n\nStrategy Lifecycle\nACTIVE - Server evaluates every ~10 seconds\nPAUSED - Paused by user (from dashboard) or agent. Not evaluated until resumed.\nERROR - Auto-paused after 3 consecutive failures. Use POST /strategies/{id}/resume to retry.\nCOMPLETED - Budget exhausted or one-shot trigger fired\nCANCELLED - Cancelled by user (from dashboard) or agent. Cannot be resumed.\nEXPIRED - Past 24-hour default TTL (or custom expiresAt). Cannot be resumed.\nCrypto Market Auto-Discovery\n\nFor strategies using marketQuery instead of tokenId: the server automatically discovers the current active market each evaluation. For known crypto assets (btc, eth, sol, xrp, etc.), this uses deterministic slug-based lookups — the same approach as the market-data-worker. This reliably handles Polymarket's ephemeral crypto markets (15-min, hourly, daily) that expire and are replaced. Non-crypto queries fall back to text search.\n\nCOPY_TRADE Real-Time Monitoring\n\nCopy trade strategies use blockchain event monitoring (not polling) to detect target wallet activity in ~2 seconds. The server watches ERC1155 transfer events on Polymarket's CTF contract via Alchemy WebSocket RPC. Events are deduplicated, so reconnections don't cause double-execution.\n\nHeartbeat Integration\n\nThe heartbeat response includes a strategies section and these action types:\n\nSTRATEGY_EXECUTED (medium) — Trades placed by your strategies\nSTRATEGY_ERROR (high) — Strategies auto-paused after consecutive errors\nSTRATEGY_COMPLETED (low) — Strategies that finished (budget exhausted or trigger fired)\nSTRATEGY_PAUSED (high) — Strategy paused by the user from the dashboard. POST /strategies/{id}/resume to restart.\nSTRATEGY_CANCELLED (high) — Strategy cancelled by the user from the dashboard. Create a new strategy if needed.\nBest Practices\nSet maxBudget on every strategy to limit exposure\nUse PRICE_ALERT for stop-loss/take-profit on existing positions\nUse RECURRING_BUY with marketQuery for crypto markets (handles market expiry)\nReview heartbeat periodically to see strategy execution results\nMax 10 active strategies per agent\nError Handling\n{\n  \"success\": false,\n  \"error\": \"Error Type\",\n  \"message\": \"Human-readable message\"\n}\n\n\nStatus Codes:\n\n401: Invalid API key\n403: Insufficient permissions or budget exceeded\n404: Resource not found\n429: Rate limit exceeded\nPermissions\nread: View markets, orders, positions, balance\ntrade: Place orders\ncancel: Cancel orders\nredeem: Redeem settled positions"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/rachelbastian/luckylobster-skill",
    "publisherUrl": "https://clawhub.ai/rachelbastian/luckylobster-skill",
    "owner": "rachelbastian",
    "version": "0.10.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/luckylobster-skill",
    "downloadUrl": "https://openagent3.xyz/downloads/luckylobster-skill",
    "agentUrl": "https://openagent3.xyz/skills/luckylobster-skill/agent",
    "manifestUrl": "https://openagent3.xyz/skills/luckylobster-skill/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/luckylobster-skill/agent.md"
  }
}