[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6N08FGDP0CB7XG2RKKR6T6R":3,"skill-same:01M6N08FGDP0CB7XG2RKKR6T6R":70},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":30,"linkOnly":31,"markdownContent":32,"markdownBody":33,"frontMatter":34,"refName":43,"commitSha":44,"skillDirectory":45,"forksCount":46,"repositoryHtmlUrl":47,"repositoryHomepageUrl":6,"ownerHtmlUrl":48,"ownerBlogUrl":6,"ownerDescription":49,"updatedAt":50,"install":51,"resources":63},"01M6N08FGDP0CB7XG2RKKR6T6R","luckylobster",null,"Trade prediction markets on Polymarket. Search markets, place orders, and manage positions.","Kernel8901\u002Fai-agent-skills-classification","Kernel8901","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F72647553?v=4","01M6KV388J2H5PNC8D8P940BJD","01M6KV38CS5B3AY63RKZB410YM",7,"MIT","https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F人工智能与大型语言模型\u002Fluckylobster-skill\u002Fskill.md",[],[5,18,19,20,21,22,23,24,25,26,27,28,29],"search","https","api","polymarket","manage","positions","orders","trade","io","prediction markets","markets","true","2026-11-10 10:12:30",false,"---\nname: luckylobster\ndescription: Trade prediction markets on Polymarket. Search markets, place orders, and manage positions.\nhomepage: https:\u002F\u002Fluckylobster.io\nuser-invocable: true\nmetadata: {\"openclaw\":{\"primaryEnv\":\"LUCKYLOBSTER_API_KEY\",\"emoji\":\"?\",\"homepage\":\"https:\u002F\u002Fluckylobster.io\",\"requires\":{\"env\":[\"LUCKYLOBSTER_API_KEY\"]}}}\n---\n\n# LuckyLobster - Polymarket Trading API\n\nTrade prediction markets on Polymarket through a secure API designed for AI agents.\n\n## How Polymarket Works\n\nPolymarket is a prediction market where you trade on the outcomes of real-world events.\n\n**Buying Contracts:**\n- In active markets, you can buy outcome contracts priced from $0.01 to $0.99\n- Each contract entitles you to 1 share at your purchase price\n- Lower prices = higher potential return, but less likely outcome (market's view)\n\n**Selling Contracts:**\n- You can sell your shares at any time before the market closes\n- Sell price depends on current market conditions\n\n**Market Resolution:**\n- When a market resolves, the winning outcome pays **$1.00 USDC per share**\n- Losing outcomes pay $0 (or a negligible amount in rare cases)\n\n**Example:** 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\n## Setup\n\nIf you don't have an API key configured, use the device authorization flow to link your account.\n\n### Device Authorization Flow\n\n**Step 1: Request a Device Code**\n\n```http\nPOST https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fauth\u002Fdevice\nContent-Type: application\u002Fjson\n\n{\n  \"agent_name\": \"OpenClaw Agent\"\n}\n```\n\nResponse:\n```json\n{\n  \"device_code\": \"abc123...\",\n  \"user_code\": \"ABCD-1234\",\n  \"verification_uri\": \"https:\u002F\u002Fluckylobster.io\u002Flink\",\n  \"verification_uri_complete\": \"https:\u002F\u002Fluckylobster.io\u002Flink?code=ABCD-1234\",\n  \"expires_in\": 900,\n  \"interval\": 5\n}\n```\n\n**Step 2: Direct the User**\n\nDisplay this message to the user:\n\n```\n? To connect LuckyLobster, visit: https:\u002F\u002Fluckylobster.io\u002Flink\n   Enter code: ABCD-1234\n```\n\n**Step 3: Poll for Authorization**\n\nPoll every 5 seconds until authorized:\n\n```http\nGET https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fauth\u002Fdevice\u002Ftoken?device_code=abc123...\n```\n\nPending response:\n```json\n{ \"error\": \"authorization_pending\" }\n```\n\nSuccess response:\n```json\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\u002Forders\u002Fpositions), **trade** (buy\u002Fsell), **cancel** (cancel orders), and **redeem** (settle positions).\n\n**Step 4: Store the API Key**\n\nSave the API key persistently so it survives restarts. It is only returned once.\n\n**Option A: OpenClaw Config (Recommended)**\nUse the `gateway` tool with `config.patch` to save it in the skill entry:\n\n```javascript\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```\n\n**Option B: Environment File**\nAppend it to `~\u002F.openclaw\u002F.env` or the workspace `.env` file if one exists:\n\n```bash\necho \"LUCKYLOBSTER_API_KEY=ll_abc123...\" >> ~\u002F.openclaw\u002F.env\n```\n\n---\n\n## Authentication\n\nAll API requests require an API key in the Authorization header:\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\n## Base URL\n\n```\nhttps:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\n```\n\n## Rate Limits\n\n- Default: 100 requests per minute\n- Rate limit headers included in responses:\n  - `X-RateLimit-Limit`: Max requests allowed\n  - `X-RateLimit-Remaining`: Requests remaining\n  - `X-RateLimit-Reset`: Reset time (ISO 8601)\n\n## Endpoints\n\n### Search Markets\n\nFind prediction markets on Polymarket. The search uses smart relevance scoring to return the best matches first.\n\n```http\nGET \u002Fmarkets\u002Fsearch?q={query}\n```\n\n**Parameters:**\n- `q` (required for search): Natural language query - \"bitcoin 15m\", \"trump election\", \"superbowl winner\"\n- `limit` (optional): Max results (default: 10, max: 100)\n- `offset` (optional): Pagination offset\n- `sort` (optional): \"relevance\" (default), \"volume\", \"liquidity\", \"end_date\", \"recent\"\n- `ending_soon` (optional): Prioritize markets ending within 24h (default: false)\n- `min_volume` (optional): Minimum volume in USD (default: 100)\n- `min_liquidity` (optional): Minimum liquidity in USD\n- `tag` (optional): Filter by category: \"crypto\", \"politics\", \"sports\", \"entertainment\"\n- `accepting_orders` (optional): Only tradeable markets (default: true)\n\n**Search Tips:**\n- **Shorthand supported:** \"btc 15m\" → \"Bitcoin Up or Down\", \"eth daily\" → \"Ethereum Up or Down on\"\n- The search auto-expands: btc→Bitcoin, eth→Ethereum, sol→Solana, etc.\n- Time keywords (15m, hourly, daily) auto-expand to \"Up or Down\" queries\n- Results are ranked by relevance: query match + liquidity + volume + accepting orders\n- For time-sensitive markets, add `ending_soon=true` to prioritize markets expiring within 24h\n- First result is usually the best match - check `context.topMatch`\n\n**Example - Find Current BTC Market:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fmarkets\u002Fsearch?q=bitcoin%20up%20down&ending_soon=true&limit=5\"\n```\n\n**Example - High-Volume Politics Markets:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fmarkets\u002Fsearch?q=election&tag=politics&sort=volume\"\n```\n\n**Response:**\n```json\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\n**Workflow for Trading:**\n1. Search: `GET \u002Fmarkets\u002Fsearch?q=bitcoin up down`\n2. Use the `id` from the top result to get full details: `GET \u002Fmarkets\u002F{id}`\n3. Response includes `clobTokenIds` - use these with trading endpoints\n\n---\n\n### Quick Crypto Market Lookup\n\nFor crypto up\u002Fdown markets, use this simplified endpoint:\n\n```http\nGET \u002Fmarkets\u002Fcrypto?asset={btc|eth|sol}&timeframe={daily|hourly|15m}\n```\n\n**Examples:**\n- `\u002Fmarkets\u002Fcrypto?asset=btc` - Today's Bitcoin daily market\n- `\u002Fmarkets\u002Fcrypto?asset=btc&timeframe=15m` - Current Bitcoin 15-minute market\n- `\u002Fmarkets\u002Fcrypto?asset=eth&timeframe=hourly` - Current Ethereum hourly market\n\n**Response includes `tokens` array with `tokenId` ready for trading.**\n\n---\n\n### Find Market by Slug\n\nIf you know the exact market slug (from a Polymarket URL), use this for direct lookup:\n\n```http\nGET \u002Fmarkets\u002Fby-slug?slug={slug}\n```\n\n**Example:** For URL `https:\u002F\u002Fpolymarket.com\u002Fevent\u002Fbtc-updown-15m-1770129900`\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fmarkets\u002Fby-slug?slug=btc-updown-15m-1770129900\"\n```\n\nResponse includes `clobTokenIds` and `tokens` ready for trading.\n\n**Note:** For most use cases, `\u002Fmarkets\u002Fsearch` or `\u002Fmarkets\u002Fcrypto` is easier than constructing slugs.\n\n### Get Market Details\n\nGet detailed information about a specific market, **including token IDs required for market data and trading**.\n\n```http\nGET \u002Fmarkets\u002F{id}\n```\n\n**Parameters:**\n- `id`: Market ID or condition ID (from search results)\n\n**Example:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fmarkets\u002F0x1234...\"\n```\n\n**Response:**\n```json\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\n**Important:** Use the `tokenId` from the `tokens` array or `clobTokenIds` for the market data endpoints below.\n\n---\n\n## Market Data Endpoints\n\nThese endpoints provide real-time order book and pricing data from the Polymarket CLOB (Central Limit Order Book).\n\n**Workflow for getting market data:**\n1. Search markets: `GET \u002Fmarkets\u002Fsearch?q=Bitcoin`\n2. Get market details: `GET \u002Fmarkets\u002F{id}` → This returns `tokens[].tokenId`\n3. Get market data: `GET \u002Forderbook?token_id={tokenId}` or `GET \u002Fmarket-data?token_id={tokenId}`\n\n### Get Order Book\n\nGet the order book summary for a token, including all bids and asks.\n\n```http\nGET \u002Forderbook?token_id={tokenId}\n```\n\n**Parameters:**\n- `token_id` (required): The outcome token address\n- `token_ids` (optional): Comma-separated list for batch request (max 20)\n\n**Example:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Forderbook?token_id=71321045...\"\n```\n\n**Response:**\n```json\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```\n\n### Get Prices\n\nGet current prices for a token including midpoint, buy\u002Fsell prices, and last trade.\n\n```http\nGET \u002Fprices?token_id={tokenId}\n```\n\n**Parameters:**\n- `token_id` (required): The outcome token address\n- `side` (optional): `BUY` or `SELL` to get price for specific side\n- `token_ids` (optional): Comma-separated list for batch request (max 20)\n\n**Example:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fprices?token_id=71321045...\"\n```\n\n**Response:**\n```json\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  }\n}\n```\n\n### Get Spread\n\nGet the bid-ask spread for a token.\n\n```http\nGET \u002Fspread?token_id={tokenId}\n```\n\n**Parameters:**\n- `token_id` (required): The outcome token address\n- `token_ids` (optional): Comma-separated list for batch request (max 20)\n\n**Example:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fspread?token_id=71321045...\"\n```\n\n**Response:**\n```json\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```\n\n### Get Comprehensive Market Data\n\nGet all market data in a single request (order book summary, prices, spread).\n\n```http\nGET \u002Fmarket-data?token_id={tokenId}\n```\n\n**Parameters:**\n- `token_id` (required): The outcome token address\n\n**Example:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fmarket-data?token_id=71321045...\"\n```\n\n**Response:**\n```json\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```\n\n---\n\n## Trading Endpoints\n\n### Place Order\n\nPlace a buy or sell order on a market. Returns real-time order status.\n\n```http\nPOST \u002Forders\nContent-Type: application\u002Fjson\n\n{\n  \"tokenId\": \"0x1234...\",\n  \"side\": \"BUY\",\n  \"price\": 0.65,\n  \"size\": 50,\n  \"type\": \"LIMIT\"\n}\n```\n\n**Parameters:**\n- `tokenId`: Outcome token address (from market data)\n- `side`: `BUY` or `SELL`\n- `price`: Price per share (0.01 to 0.99)\n- `size`: Number of shares\n- `type`: `LIMIT`, `MARKET`, `FOK`, or `FAK`\n\n**Real-time Status:** The response includes the order's current status from Polymarket. FOK and MARKET orders return faster (~500ms) since they execute immediately. LIMIT orders are checked after ~1 second.\n\n**Example:**\n```bash\ncurl -X POST -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"tokenId\":\"0x1234...\",\"side\":\"BUY\",\"price\":0.65,\"size\":50,\"type\":\"LIMIT\"}' \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Forders\"\n```\n\n**Response (with fill data when available):**\n```json\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```\n\n### List Orders\n\nGet your orders with real-time status from Polymarket.\n\n```http\nGET \u002Forders?status=OPEN&limit=50\n```\n\n**Parameters:**\n- `status` (optional): Filter by status - `PENDING`, `OPEN`, `FILLED`, `PARTIALLY_FILLED`, `CANCELLED`, `EXPIRED`, `FAILED`\n- `limit` (optional): Max results (default: 50, max: 100)\n- `offset` (optional): Pagination offset\n- `sync` (optional): Set to `false` to skip live status sync (default: true)\n\n**Real-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\n**Example:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Forders?status=OPEN\"\n```\n\n**Response includes sync info:**\n```json\n{\n  \"success\": true,\n  \"data\": [...],\n  \"sync\": { \"enabled\": true, \"updated\": 2 }\n}\n```\n\n### Get Order Status\n\nGet details for a specific order, including live status from Polymarket.\n\n```http\nGET \u002Forders\u002F{orderId}\n```\n\n**Example:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Forders\u002Ford_abc123\"\n```\n\n**Response:**\n```json\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```\n\n### Cancel Order\n\nCancel an open order. Only orders with status `PENDING`, `OPEN`, or `PARTIALLY_FILLED` can be cancelled.\n\n```http\nDELETE \u002Forders\u002F{orderId}\n```\n\n**Example:**\n```bash\ncurl -X DELETE -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Forders\u002Ford_abc123\"\n```\n\n**Response:**\n```json\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\n**Error Responses:**\n- `400`: Order cannot be cancelled (already filled, cancelled, or failed)\n- `403`: Order was not placed by your agent\n- `404`: Order not found\n\n**Notes:**\n- You can only cancel orders that your agent placed\n- If an order is partially filled, cancelling stops further fills but keeps the filled portion\n- The `previousStatus` field shows what status the order had before cancellation\n\n### Close 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\n```http\nPOST \u002Fpositions\u002F{positionId}\u002Fclose\n```\n\n**URL Parameters:**\n- `positionId`: Position ID from `GET \u002Fpositions`\n\n**Optional Body:**\n```json\n{\n  \"type\": \"MARKET\",   \u002F\u002F Order type: \"MARKET\" (default), \"FOK\", or \"LIMIT\"\n  \"slippage\": 0.02,   \u002F\u002F Max slippage for LIMIT orders (default: 2%)\n  \"dryRun\": true      \u002F\u002F Preview without executing\n}\n```\n\n**Example - Close a position:**\n```bash\ncurl -X POST -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fpositions\u002Fpos_abc123\u002Fclose\"\n```\n\n**Example - Preview first (dry run):**\n```bash\ncurl -X POST -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"dryRun\": true}' \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fpositions\u002Fpos_abc123\u002Fclose\"\n```\n\n**Response:**\n```json\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\n**Dry Run Response:**\n```json\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\n**Error Responses:**\n- `400`: Position is already closed (size=0) or already settled\n- `403`: Position belongs to another user\n- `404`: Position not found\n- `503`: Unable to fetch market price (market may be closed\u002Filliquid)\n\n**Notes:**\n- Uses the current bid price for immediate execution\n- For LIMIT orders, applies slippage tolerance (default 2%) below bid\n- Position is partially closed if order only partially fills\n- Check `position.isClosed` to verify complete exit\n\n### Get Balance\n\nGet raw wallet balance (live from chain).\n\n```http\nGET \u002Fbalance\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"usdc\": 93.16,\n    \"matic\": 0.5,\n    \"address\": \"0x1234...\",\n    \"walletType\": \"proxy\"\n  }\n}\n```\n\n**Fields:**\n- `usdc`: Raw USDC in wallet\n- `matic`: For gas (rarely needed)\n- `address`: Your trading wallet on Polygon\n\n### Approve Tokens (Fix \"not enough allowance\" errors)\n\nIf you get a \"not enough balance \u002F 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\n```http\nPOST \u002Fwallet\u002Fapprove\n```\n\n**Request Body:**\n```json\n{\n  \"token\": \"CTF\"  \u002F\u002F or \"USDC\", \"NEG_RISK\", \"all\"\n}\n```\n\n**Token Types:**\n- `USDC`: Required for buying (usually already approved)\n- `CTF`: **Required for selling\u002Fclosing positions**\n- `NEG_RISK`: Required for multi-outcome markets\n- `all`: Approve all tokens at once\n\n**Example - Fix selling errors:**\n```bash\ncurl -X POST -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"token\": \"CTF\"}' \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fwallet\u002Fapprove\"\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"message\": \"CTF approved successfully\",\n  \"data\": {\n    \"approvals\": { \"CTF\": \"0x...\" },\n    \"successful\": [\"CTF\"],\n    \"failed\": []\n  }\n}\n```\n\n**When to use:**\n- Error: \"not enough balance \u002F allowance\" when selling\n- Error: \"not enough balance \u002F allowance\" when closing a position\n- First time selling after wallet setup\n\n### Get Budget\n\nGet how much you can spend. **Use this before placing orders.**\n\nBudget = min(wallet balance, fixed limit, % of wallet)\n\n```http\nGET \u002Fbudget\n```\n\n**Response:**\n```json\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\n**Fields:**\n- `usdc`: **What you can spend** (accounts for all limits)\n- `limitedBy`: Why you're capped (`\"wallet\"`, `\"fixed_limit\"`, `\"percent\"`, `\"position_limit\"`)\n- `wallet`: Raw wallet balance\n- `config`: Your budget settings\n\n### Get 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\n```http\nGET \u002Fpositions\n```\n\n**Parameters:**\n- `status` (optional): Filter by status - `\"open\"` (default), `\"settled\"`, `\"redeemable\"`, or `\"all\"`\n- `token_id` (optional): Filter by specific token ID\n- `condition_id` (optional): Filter by condition ID (market)\n- `source` (optional): Force data source - `\"clob\"` to bypass Data API and fetch directly from CLOB trades\n\n**Example - Get Open Positions:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fpositions\"\n```\n\n**Example - Get Redeemable Positions:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fpositions?status=redeemable\"\n```\n\n**Example - Force CLOB Source (for freshest data):**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fpositions?source=clob\"\n```\n\n**Response:**\n```json\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\n**Key Fields:**\n- `size`: Number of outcome tokens held\n- `avgEntryPrice`: Average price paid per token (0.00 to 1.00)\n- `currentPrice`: Live price from Polymarket\n- `currentValue`: Current value in USDC\n- `pnl.unrealized`: Unrealized profit\u002Floss\n- `pnl.unrealizedPercent`: Unrealized P&L as percentage\n- `status.isRedeemable`: `true` if market resolved and position can be redeemed\n- `status.isNegRisk`: `true` for multi-outcome markets (require special redemption)\n- `wallet.type`: `\"proxy\"` (Polymarket smart wallet) or `\"eoa\"` (direct wallet)\n- `source`: `\"data-api\"` or `\"clob-trades\"` - shows which data source was used\n\n**Data Source Behavior:**\n1. **Default**: Fetches from Polymarket Data API (most reliable, includes all historical positions)\n2. **Fallback**: If Data API returns empty, automatically falls back to CLOB trades\n3. **Forced CLOB**: Use `?source=clob` for freshest data immediately after placing an order (Data API can have ~30s delay)\n\n**When to use `source=clob`:**\n- Right after placing an order (Data API has indexing delay)\n- When Data API returns fewer positions than expected\n- For debugging position discrepancies\n\n---\n\n## Settlement & 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\n### List Redeemable Positions\n\nCheck what positions are ready for redemption.\n\n```http\nGET \u002Fsettlements\u002Fredeem\n```\n\n**Response:**\n```json\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```\n\n### Redeem Positions\n\nRedeem winning positions in a single batched transaction. You can redeem all positions or target specific ones.\n\n```http\nPOST \u002Fsettlements\u002Fredeem\n```\n\n**Optional Parameters:**\n```json\n{\n  \"conditionId\": \"0x...\",           \u002F\u002F Redeem ONLY this specific position\n  \"conditionIds\": [\"0x...\", \"...\"], \u002F\u002F Redeem ONLY these specific positions\n  \"limit\": 50,       \u002F\u002F Max positions to redeem (default: 10, max: 50)\n  \"minValue\": 1.00,  \u002F\u002F Skip positions below this value (default: $0.10)\n  \"dryRun\": true     \u002F\u002F Preview what would be redeemed without executing\n}\n```\n\n**Example - Redeem a specific position:**\n```bash\ncurl -X POST -H \"X-API-Key: $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"conditionId\": \"0xbc13af0a940bb9a...\"}' \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fsettlements\u002Fredeem\"\n```\n\n**Example - Redeem all:**\n```bash\ncurl -X POST -H \"X-API-Key: $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fsettlements\u002Fredeem\"\n```\n\n**Example - Dry run first:**\n```bash\ncurl -X POST -H \"X-API-Key: $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"dryRun\": true}' \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fsettlements\u002Fredeem\"\n```\n\n**Example - Redeem up to 50, skip dust:**\n```bash\ncurl -X POST -H \"X-API-Key: $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"limit\": 50, \"minValue\": 1.00}' \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fsettlements\u002Fredeem\"\n```\n\n**Response:**\n```json\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\n**Error Responses:**\n- `404`: Wallet not found\n- `403`: Missing \"redeem\" permission\n- `501`: Polymarket Builder API not configured\n\n**Notes:**\n- Redemption is gasless (executed via Polymarket relayer)\n- All positions are batched into a single on-chain transaction for efficiency\n- Only positions marked as \"redeemable\" by Polymarket are included\n- Both standard and NegRisk markets are handled automatically\n\n---\n\n## Error Handling\n\n```json\n{\n  \"success\": false,\n  \"error\": \"Error Type\",\n  \"message\": \"Human-readable message\"\n}\n```\n\n**Status Codes:**\n- `401`: Invalid API key\n- `403`: Insufficient permissions or budget exceeded\n- `404`: Resource not found\n- `429`: Rate limit exceeded\n\n## Permissions\n\n- `read`: View markets, orders, positions, balance\n- `trade`: Place orders\n- `cancel`: Cancel orders\n- `redeem`: Redeem settled positions\n","# LuckyLobster - Polymarket Trading API\n\nTrade prediction markets on Polymarket through a secure API designed for AI agents.\n\n## How Polymarket Works\n\nPolymarket is a prediction market where you trade on the outcomes of real-world events.\n\n**Buying Contracts:**\n- In active markets, you can buy outcome contracts priced from $0.01 to $0.99\n- Each contract entitles you to 1 share at your purchase price\n- Lower prices = higher potential return, but less likely outcome (market's view)\n\n**Selling Contracts:**\n- You can sell your shares at any time before the market closes\n- Sell price depends on current market conditions\n\n**Market Resolution:**\n- When a market resolves, the winning outcome pays **$1.00 USDC per share**\n- Losing outcomes pay $0 (or a negligible amount in rare cases)\n\n**Example:** 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\n## Setup\n\nIf you don't have an API key configured, use the device authorization flow to link your account.\n\n### Device Authorization Flow\n\n**Step 1: Request a Device Code**\n\n```http\nPOST https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fauth\u002Fdevice\nContent-Type: application\u002Fjson\n\n{\n  \"agent_name\": \"OpenClaw Agent\"\n}\n```\n\nResponse:\n```json\n{\n  \"device_code\": \"abc123...\",\n  \"user_code\": \"ABCD-1234\",\n  \"verification_uri\": \"https:\u002F\u002Fluckylobster.io\u002Flink\",\n  \"verification_uri_complete\": \"https:\u002F\u002Fluckylobster.io\u002Flink?code=ABCD-1234\",\n  \"expires_in\": 900,\n  \"interval\": 5\n}\n```\n\n**Step 2: Direct the User**\n\nDisplay this message to the user:\n\n```\n? To connect LuckyLobster, visit: https:\u002F\u002Fluckylobster.io\u002Flink\n   Enter code: ABCD-1234\n```\n\n**Step 3: Poll for Authorization**\n\nPoll every 5 seconds until authorized:\n\n```http\nGET https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fauth\u002Fdevice\u002Ftoken?device_code=abc123...\n```\n\nPending response:\n```json\n{ \"error\": \"authorization_pending\" }\n```\n\nSuccess response:\n```json\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\u002Forders\u002Fpositions), **trade** (buy\u002Fsell), **cancel** (cancel orders), and **redeem** (settle positions).\n\n**Step 4: Store the API Key**\n\nSave the API key persistently so it survives restarts. It is only returned once.\n\n**Option A: OpenClaw Config (Recommended)**\nUse the `gateway` tool with `config.patch` to save it in the skill entry:\n\n```javascript\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```\n\n**Option B: Environment File**\nAppend it to `~\u002F.openclaw\u002F.env` or the workspace `.env` file if one exists:\n\n```bash\necho \"LUCKYLOBSTER_API_KEY=ll_abc123...\" >> ~\u002F.openclaw\u002F.env\n```\n\n---\n\n## Authentication\n\nAll API requests require an API key in the Authorization header:\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\n## Base URL\n\n```\nhttps:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\n```\n\n## Rate Limits\n\n- Default: 100 requests per minute\n- Rate limit headers included in responses:\n  - `X-RateLimit-Limit`: Max requests allowed\n  - `X-RateLimit-Remaining`: Requests remaining\n  - `X-RateLimit-Reset`: Reset time (ISO 8601)\n\n## Endpoints\n\n### Search Markets\n\nFind prediction markets on Polymarket. The search uses smart relevance scoring to return the best matches first.\n\n```http\nGET \u002Fmarkets\u002Fsearch?q={query}\n```\n\n**Parameters:**\n- `q` (required for search): Natural language query - \"bitcoin 15m\", \"trump election\", \"superbowl winner\"\n- `limit` (optional): Max results (default: 10, max: 100)\n- `offset` (optional): Pagination offset\n- `sort` (optional): \"relevance\" (default), \"volume\", \"liquidity\", \"end_date\", \"recent\"\n- `ending_soon` (optional): Prioritize markets ending within 24h (default: false)\n- `min_volume` (optional): Minimum volume in USD (default: 100)\n- `min_liquidity` (optional): Minimum liquidity in USD\n- `tag` (optional): Filter by category: \"crypto\", \"politics\", \"sports\", \"entertainment\"\n- `accepting_orders` (optional): Only tradeable markets (default: true)\n\n**Search Tips:**\n- **Shorthand supported:** \"btc 15m\" → \"Bitcoin Up or Down\", \"eth daily\" → \"Ethereum Up or Down on\"\n- The search auto-expands: btc→Bitcoin, eth→Ethereum, sol→Solana, etc.\n- Time keywords (15m, hourly, daily) auto-expand to \"Up or Down\" queries\n- Results are ranked by relevance: query match + liquidity + volume + accepting orders\n- For time-sensitive markets, add `ending_soon=true` to prioritize markets expiring within 24h\n- First result is usually the best match - check `context.topMatch`\n\n**Example - Find Current BTC Market:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fmarkets\u002Fsearch?q=bitcoin%20up%20down&ending_soon=true&limit=5\"\n```\n\n**Example - High-Volume Politics Markets:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fmarkets\u002Fsearch?q=election&tag=politics&sort=volume\"\n```\n\n**Response:**\n```json\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\n**Workflow for Trading:**\n1. Search: `GET \u002Fmarkets\u002Fsearch?q=bitcoin up down`\n2. Use the `id` from the top result to get full details: `GET \u002Fmarkets\u002F{id}`\n3. Response includes `clobTokenIds` - use these with trading endpoints\n\n---\n\n### Quick Crypto Market Lookup\n\nFor crypto up\u002Fdown markets, use this simplified endpoint:\n\n```http\nGET \u002Fmarkets\u002Fcrypto?asset={btc|eth|sol}&timeframe={daily|hourly|15m}\n```\n\n**Examples:**\n- `\u002Fmarkets\u002Fcrypto?asset=btc` - Today's Bitcoin daily market\n- `\u002Fmarkets\u002Fcrypto?asset=btc&timeframe=15m` - Current Bitcoin 15-minute market\n- `\u002Fmarkets\u002Fcrypto?asset=eth&timeframe=hourly` - Current Ethereum hourly market\n\n**Response includes `tokens` array with `tokenId` ready for trading.**\n\n---\n\n### Find Market by Slug\n\nIf you know the exact market slug (from a Polymarket URL), use this for direct lookup:\n\n```http\nGET \u002Fmarkets\u002Fby-slug?slug={slug}\n```\n\n**Example:** For URL `https:\u002F\u002Fpolymarket.com\u002Fevent\u002Fbtc-updown-15m-1770129900`\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fmarkets\u002Fby-slug?slug=btc-updown-15m-1770129900\"\n```\n\nResponse includes `clobTokenIds` and `tokens` ready for trading.\n\n**Note:** For most use cases, `\u002Fmarkets\u002Fsearch` or `\u002Fmarkets\u002Fcrypto` is easier than constructing slugs.\n\n### Get Market Details\n\nGet detailed information about a specific market, **including token IDs required for market data and trading**.\n\n```http\nGET \u002Fmarkets\u002F{id}\n```\n\n**Parameters:**\n- `id`: Market ID or condition ID (from search results)\n\n**Example:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fmarkets\u002F0x1234...\"\n```\n\n**Response:**\n```json\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\n**Important:** Use the `tokenId` from the `tokens` array or `clobTokenIds` for the market data endpoints below.\n\n---\n\n## Market Data Endpoints\n\nThese endpoints provide real-time order book and pricing data from the Polymarket CLOB (Central Limit Order Book).\n\n**Workflow for getting market data:**\n1. Search markets: `GET \u002Fmarkets\u002Fsearch?q=Bitcoin`\n2. Get market details: `GET \u002Fmarkets\u002F{id}` → This returns `tokens[].tokenId`\n3. Get market data: `GET \u002Forderbook?token_id={tokenId}` or `GET \u002Fmarket-data?token_id={tokenId}`\n\n### Get Order Book\n\nGet the order book summary for a token, including all bids and asks.\n\n```http\nGET \u002Forderbook?token_id={tokenId}\n```\n\n**Parameters:**\n- `token_id` (required): The outcome token address\n- `token_ids` (optional): Comma-separated list for batch request (max 20)\n\n**Example:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Forderbook?token_id=71321045...\"\n```\n\n**Response:**\n```json\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```\n\n### Get Prices\n\nGet current prices for a token including midpoint, buy\u002Fsell prices, and last trade.\n\n```http\nGET \u002Fprices?token_id={tokenId}\n```\n\n**Parameters:**\n- `token_id` (required): The outcome token address\n- `side` (optional): `BUY` or `SELL` to get price for specific side\n- `token_ids` (optional): Comma-separated list for batch request (max 20)\n\n**Example:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fprices?token_id=71321045...\"\n```\n\n**Response:**\n```json\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  }\n}\n```\n\n### Get Spread\n\nGet the bid-ask spread for a token.\n\n```http\nGET \u002Fspread?token_id={tokenId}\n```\n\n**Parameters:**\n- `token_id` (required): The outcome token address\n- `token_ids` (optional): Comma-separated list for batch request (max 20)\n\n**Example:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fspread?token_id=71321045...\"\n```\n\n**Response:**\n```json\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```\n\n### Get Comprehensive Market Data\n\nGet all market data in a single request (order book summary, prices, spread).\n\n```http\nGET \u002Fmarket-data?token_id={tokenId}\n```\n\n**Parameters:**\n- `token_id` (required): The outcome token address\n\n**Example:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fmarket-data?token_id=71321045...\"\n```\n\n**Response:**\n```json\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```\n\n---\n\n## Trading Endpoints\n\n### Place Order\n\nPlace a buy or sell order on a market. Returns real-time order status.\n\n```http\nPOST \u002Forders\nContent-Type: application\u002Fjson\n\n{\n  \"tokenId\": \"0x1234...\",\n  \"side\": \"BUY\",\n  \"price\": 0.65,\n  \"size\": 50,\n  \"type\": \"LIMIT\"\n}\n```\n\n**Parameters:**\n- `tokenId`: Outcome token address (from market data)\n- `side`: `BUY` or `SELL`\n- `price`: Price per share (0.01 to 0.99)\n- `size`: Number of shares\n- `type`: `LIMIT`, `MARKET`, `FOK`, or `FAK`\n\n**Real-time Status:** The response includes the order's current status from Polymarket. FOK and MARKET orders return faster (~500ms) since they execute immediately. LIMIT orders are checked after ~1 second.\n\n**Example:**\n```bash\ncurl -X POST -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"tokenId\":\"0x1234...\",\"side\":\"BUY\",\"price\":0.65,\"size\":50,\"type\":\"LIMIT\"}' \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Forders\"\n```\n\n**Response (with fill data when available):**\n```json\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```\n\n### List Orders\n\nGet your orders with real-time status from Polymarket.\n\n```http\nGET \u002Forders?status=OPEN&limit=50\n```\n\n**Parameters:**\n- `status` (optional): Filter by status - `PENDING`, `OPEN`, `FILLED`, `PARTIALLY_FILLED`, `CANCELLED`, `EXPIRED`, `FAILED`\n- `limit` (optional): Max results (default: 50, max: 100)\n- `offset` (optional): Pagination offset\n- `sync` (optional): Set to `false` to skip live status sync (default: true)\n\n**Real-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\n**Example:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Forders?status=OPEN\"\n```\n\n**Response includes sync info:**\n```json\n{\n  \"success\": true,\n  \"data\": [...],\n  \"sync\": { \"enabled\": true, \"updated\": 2 }\n}\n```\n\n### Get Order Status\n\nGet details for a specific order, including live status from Polymarket.\n\n```http\nGET \u002Forders\u002F{orderId}\n```\n\n**Example:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Forders\u002Ford_abc123\"\n```\n\n**Response:**\n```json\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```\n\n### Cancel Order\n\nCancel an open order. Only orders with status `PENDING`, `OPEN`, or `PARTIALLY_FILLED` can be cancelled.\n\n```http\nDELETE \u002Forders\u002F{orderId}\n```\n\n**Example:**\n```bash\ncurl -X DELETE -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Forders\u002Ford_abc123\"\n```\n\n**Response:**\n```json\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\n**Error Responses:**\n- `400`: Order cannot be cancelled (already filled, cancelled, or failed)\n- `403`: Order was not placed by your agent\n- `404`: Order not found\n\n**Notes:**\n- You can only cancel orders that your agent placed\n- If an order is partially filled, cancelling stops further fills but keeps the filled portion\n- The `previousStatus` field shows what status the order had before cancellation\n\n### Close 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\n```http\nPOST \u002Fpositions\u002F{positionId}\u002Fclose\n```\n\n**URL Parameters:**\n- `positionId`: Position ID from `GET \u002Fpositions`\n\n**Optional Body:**\n```json\n{\n  \"type\": \"MARKET\",   \u002F\u002F Order type: \"MARKET\" (default), \"FOK\", or \"LIMIT\"\n  \"slippage\": 0.02,   \u002F\u002F Max slippage for LIMIT orders (default: 2%)\n  \"dryRun\": true      \u002F\u002F Preview without executing\n}\n```\n\n**Example - Close a position:**\n```bash\ncurl -X POST -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fpositions\u002Fpos_abc123\u002Fclose\"\n```\n\n**Example - Preview first (dry run):**\n```bash\ncurl -X POST -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"dryRun\": true}' \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fpositions\u002Fpos_abc123\u002Fclose\"\n```\n\n**Response:**\n```json\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\n**Dry Run Response:**\n```json\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\n**Error Responses:**\n- `400`: Position is already closed (size=0) or already settled\n- `403`: Position belongs to another user\n- `404`: Position not found\n- `503`: Unable to fetch market price (market may be closed\u002Filliquid)\n\n**Notes:**\n- Uses the current bid price for immediate execution\n- For LIMIT orders, applies slippage tolerance (default 2%) below bid\n- Position is partially closed if order only partially fills\n- Check `position.isClosed` to verify complete exit\n\n### Get Balance\n\nGet raw wallet balance (live from chain).\n\n```http\nGET \u002Fbalance\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"usdc\": 93.16,\n    \"matic\": 0.5,\n    \"address\": \"0x1234...\",\n    \"walletType\": \"proxy\"\n  }\n}\n```\n\n**Fields:**\n- `usdc`: Raw USDC in wallet\n- `matic`: For gas (rarely needed)\n- `address`: Your trading wallet on Polygon\n\n### Approve Tokens (Fix \"not enough allowance\" errors)\n\nIf you get a \"not enough balance \u002F 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\n```http\nPOST \u002Fwallet\u002Fapprove\n```\n\n**Request Body:**\n```json\n{\n  \"token\": \"CTF\"  \u002F\u002F or \"USDC\", \"NEG_RISK\", \"all\"\n}\n```\n\n**Token Types:**\n- `USDC`: Required for buying (usually already approved)\n- `CTF`: **Required for selling\u002Fclosing positions**\n- `NEG_RISK`: Required for multi-outcome markets\n- `all`: Approve all tokens at once\n\n**Example - Fix selling errors:**\n```bash\ncurl -X POST -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"token\": \"CTF\"}' \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fwallet\u002Fapprove\"\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"message\": \"CTF approved successfully\",\n  \"data\": {\n    \"approvals\": { \"CTF\": \"0x...\" },\n    \"successful\": [\"CTF\"],\n    \"failed\": []\n  }\n}\n```\n\n**When to use:**\n- Error: \"not enough balance \u002F allowance\" when selling\n- Error: \"not enough balance \u002F allowance\" when closing a position\n- First time selling after wallet setup\n\n### Get Budget\n\nGet how much you can spend. **Use this before placing orders.**\n\nBudget = min(wallet balance, fixed limit, % of wallet)\n\n```http\nGET \u002Fbudget\n```\n\n**Response:**\n```json\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\n**Fields:**\n- `usdc`: **What you can spend** (accounts for all limits)\n- `limitedBy`: Why you're capped (`\"wallet\"`, `\"fixed_limit\"`, `\"percent\"`, `\"position_limit\"`)\n- `wallet`: Raw wallet balance\n- `config`: Your budget settings\n\n### Get 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\n```http\nGET \u002Fpositions\n```\n\n**Parameters:**\n- `status` (optional): Filter by status - `\"open\"` (default), `\"settled\"`, `\"redeemable\"`, or `\"all\"`\n- `token_id` (optional): Filter by specific token ID\n- `condition_id` (optional): Filter by condition ID (market)\n- `source` (optional): Force data source - `\"clob\"` to bypass Data API and fetch directly from CLOB trades\n\n**Example - Get Open Positions:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fpositions\"\n```\n\n**Example - Get Redeemable Positions:**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fpositions?status=redeemable\"\n```\n\n**Example - Force CLOB Source (for freshest data):**\n```bash\ncurl -H \"Authorization: Bearer $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fpositions?source=clob\"\n```\n\n**Response:**\n```json\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\n**Key Fields:**\n- `size`: Number of outcome tokens held\n- `avgEntryPrice`: Average price paid per token (0.00 to 1.00)\n- `currentPrice`: Live price from Polymarket\n- `currentValue`: Current value in USDC\n- `pnl.unrealized`: Unrealized profit\u002Floss\n- `pnl.unrealizedPercent`: Unrealized P&L as percentage\n- `status.isRedeemable`: `true` if market resolved and position can be redeemed\n- `status.isNegRisk`: `true` for multi-outcome markets (require special redemption)\n- `wallet.type`: `\"proxy\"` (Polymarket smart wallet) or `\"eoa\"` (direct wallet)\n- `source`: `\"data-api\"` or `\"clob-trades\"` - shows which data source was used\n\n**Data Source Behavior:**\n1. **Default**: Fetches from Polymarket Data API (most reliable, includes all historical positions)\n2. **Fallback**: If Data API returns empty, automatically falls back to CLOB trades\n3. **Forced CLOB**: Use `?source=clob` for freshest data immediately after placing an order (Data API can have ~30s delay)\n\n**When to use `source=clob`:**\n- Right after placing an order (Data API has indexing delay)\n- When Data API returns fewer positions than expected\n- For debugging position discrepancies\n\n---\n\n## Settlement & 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\n### List Redeemable Positions\n\nCheck what positions are ready for redemption.\n\n```http\nGET \u002Fsettlements\u002Fredeem\n```\n\n**Response:**\n```json\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```\n\n### Redeem Positions\n\nRedeem winning positions in a single batched transaction. You can redeem all positions or target specific ones.\n\n```http\nPOST \u002Fsettlements\u002Fredeem\n```\n\n**Optional Parameters:**\n```json\n{\n  \"conditionId\": \"0x...\",           \u002F\u002F Redeem ONLY this specific position\n  \"conditionIds\": [\"0x...\", \"...\"], \u002F\u002F Redeem ONLY these specific positions\n  \"limit\": 50,       \u002F\u002F Max positions to redeem (default: 10, max: 50)\n  \"minValue\": 1.00,  \u002F\u002F Skip positions below this value (default: $0.10)\n  \"dryRun\": true     \u002F\u002F Preview what would be redeemed without executing\n}\n```\n\n**Example - Redeem a specific position:**\n```bash\ncurl -X POST -H \"X-API-Key: $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"conditionId\": \"0xbc13af0a940bb9a...\"}' \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fsettlements\u002Fredeem\"\n```\n\n**Example - Redeem all:**\n```bash\ncurl -X POST -H \"X-API-Key: $LUCKYLOBSTER_API_KEY\" \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fsettlements\u002Fredeem\"\n```\n\n**Example - Dry run first:**\n```bash\ncurl -X POST -H \"X-API-Key: $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"dryRun\": true}' \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fsettlements\u002Fredeem\"\n```\n\n**Example - Redeem up to 50, skip dust:**\n```bash\ncurl -X POST -H \"X-API-Key: $LUCKYLOBSTER_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"limit\": 50, \"minValue\": 1.00}' \\\n  \"https:\u002F\u002Fluckylobster.io\u002Fapi\u002Fagent\u002Fv1\u002Fsettlements\u002Fredeem\"\n```\n\n**Response:**\n```json\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\n**Error Responses:**\n- `404`: Wallet not found\n- `403`: Missing \"redeem\" permission\n- `501`: Polymarket Builder API not configured\n\n**Notes:**\n- Redemption is gasless (executed via Polymarket relayer)\n- All positions are batched into a single on-chain transaction for efficiency\n- Only positions marked as \"redeemable\" by Polymarket are included\n- Both standard and NegRisk markets are handled automatically\n\n---\n\n## Error Handling\n\n```json\n{\n  \"success\": false,\n  \"error\": \"Error Type\",\n  \"message\": \"Human-readable message\"\n}\n```\n\n**Status Codes:**\n- `401`: Invalid API key\n- `403`: Insufficient permissions or budget exceeded\n- `404`: Resource not found\n- `429`: Rate limit exceeded\n\n## Permissions\n\n- `read`: View markets, orders, positions, balance\n- `trade`: Place orders\n- `cancel`: Cancel orders\n- `redeem`: Redeem settled positions\n",{"name":5,"homepage":35,"metadata":36,"description":7,"user-invocable":42},"https:\u002F\u002Fluckylobster.io",{"openclaw":37},{"emoji":38,"homepage":35,"requires":39,"primaryEnv":41},"?",{"env":40},[41],"LUCKYLOBSTER_API_KEY",true,"main","f4cb2d49f7667e79ef7804f50396d5aaffdf1f56","人工智能与大型语言模型\u002Fluckylobster-skill",1,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification","https:\u002F\u002Fgithub.com\u002FKernel8901","a little little little dobe in life but science geek","2026-04-05 16:43:56",{"source":8,"skillName":5,"commands":52,"prompt":62,"zipAvailable":42},[53,56,59],{"tool":54,"command":55},"npx","npx skills add Kernel8901\u002Fai-agent-skills-classification --skill luckylobster",{"tool":57,"command":58},"bunx","bunx skills add Kernel8901\u002Fai-agent-skills-classification --skill luckylobster",{"tool":60,"command":61},"pnpm","pnpm dlx skills add Kernel8901\u002Fai-agent-skills-classification --skill luckylobster","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F人工智能与大型语言模型\u002Fluckylobster-skill\u002Fskill.md",[64],{"path":65,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":68,"sourceHtmlUrl":69},"_meta.json","REFERENCE","参考文档",289,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F人工智能与大型语言模型\u002Fluckylobster-skill\u002F_meta.json",[71,95,129,140,150,179],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":30},"01M6Q5R6WZ06RRB9RQTW54B34B","zyfai","Earn yield on any Ethereum wallet on Base, Arbitrum, and Plasma. Use when a user wants passive DeFi yield on their funds. Deploys a non-custodial subaccount (Safe) linked to their EOA, enables automated yield optimization, and lets them deposit\u002Fwithdraw anytime.","https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F金融\u002Fzyfai-sdk\u002FSKILL.md",[],[73,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94],"safe","ethereum","defi","Optimization","user","use","Wallet","base","deposit","withdraw","yield","arbitrum","non-custodial","passive","defi yield","earn","yield optimization",{"skillNo":96,"name":97,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":113,"publishedAt":30},"01M6Q5R337B5JSNER4P4YS03TN","zerion-api","https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F金融\u002Fzerion-api\u002FSKILL.md",[100,105,108],{"categoryNo":101,"categoryName":102,"taxonomyType":103,"taxonomyTypeDesc":104},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":106,"categoryName":107,"taxonomyType":103,"taxonomyTypeDesc":104},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":109,"categoryName":110,"taxonomyType":111,"taxonomyTypeDesc":112},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[20,114,115,116,117,118,119,80,120,84,121,122,123,124,125,126,23,127,128],"zerion api","zerion","MCP","mcp server","server","blockchain","transactions","crypto wallet","crypto","evm","solana","query","across","token","prices",{"skillNo":130,"name":131,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":132,"categories":133,"keywords":137,"publishedAt":30},"01M6Q5QZFYTDAZMZ27BN5VZXAR","zerion-api-skill","https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F金融\u002Fzerion-api-skill\u002FSKILL.md",[134,135,136],{"categoryNo":101,"categoryName":102,"taxonomyType":103,"taxonomyTypeDesc":104},{"categoryNo":106,"categoryName":107,"taxonomyType":103,"taxonomyTypeDesc":104},{"categoryNo":109,"categoryName":110,"taxonomyType":111,"taxonomyTypeDesc":112},[20,138,139,114,115,116,117,118,119,80,120,84,122,123,124,125,126,23,127,128],"api skill","zerion api skill",{"skillNo":141,"name":142,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":143,"categories":144,"keywords":148,"publishedAt":30},"01M6Q5QW17QW98RA3FE45E4RD8","zerion-api-mcp","https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F金融\u002Fzerion-api-mcp\u002FSKILL.md",[145,146,147],{"categoryNo":101,"categoryName":102,"taxonomyType":103,"taxonomyTypeDesc":104},{"categoryNo":106,"categoryName":107,"taxonomyType":103,"taxonomyTypeDesc":104},{"categoryNo":109,"categoryName":110,"taxonomyType":111,"taxonomyTypeDesc":112},[116,20,149,114,115,117,118,80,120,84,121,122,123,124,125,126,23,127,128],"zerion api mcp",{"skillNo":151,"name":152,"nameZh":6,"description":153,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":154,"categories":155,"keywords":159,"publishedAt":30},"01M6Q5QQYZB7A501BDEQWKGSJT","yahoo-finance-forex","Fetches real-time FOREX news and market data from Yahoo Finance for major currency pairs (EUR\u002FUSD, GBP\u002FUSD, USD\u002FJPY, etc.). Analyzes sentiment and provides trading context.","https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F金融\u002Fyahoo-finance-forex\u002FSKILL.md",[156],{"categoryNo":157,"categoryName":158,"taxonomyType":111,"taxonomyTypeDesc":112},"01JBSEEDCAT000000000000040","财务",[160,161,162,163,164,165,19,166,167,168,169,170,171,172,173,174,175,176,177,178],"finance","yahoo finance","forex","yahoo","yahoo finance forex","github","sentiment","real-time","python3","install","Market","usd","news","time","currency","gbp","pip","market data","for",{"skillNo":180,"name":181,"nameZh":6,"description":182,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":183,"categories":184,"keywords":186,"publishedAt":30},"01M6Q5QM6VS84WZVM7BKXXPF32","yahoo-finance","This skill should be used when the user asks to \"get stock prices\", \"check stock quotes\", \"look up earnings\", \"get financial data\", \"find trending stocks\", or needs stock market data from Yahoo Finance.","https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F金融\u002Fyahoo-finance-cli\u002FSKILL.md",[185],{"categoryNo":157,"categoryName":158,"taxonomyType":111,"taxonomyTypeDesc":112},[160,161,163,187,188,189,190,191,192,170,193,194,195,196,197,198,199,200,128,177],"cli","homebrew","find","check","brew","up","local","get","stock","link","trending","sf","quotes","ln"]