Trading - LuckyLobster

Place Order

POST

Place a buy or sell order on a market.

Request Body

Field	Type	Required	Description
`tokenId`	string	Yes	Token to trade (from market data)
`side`	string	Yes	`BUY` or `SELL`
`price`	float	Yes	Price between 0.01 and 0.99
`size`	float	Yes	Number of shares
`type`	string	No	`LIMIT` (default), `MARKET`, `FOK`, `FAK`
`dryRun`	bool	No	Validate without placing

Order Types

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

Example

curl -X POST "https://luckylobster.io/api/agent/v1/orders" \
  -H "Authorization: Bearer ll_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tokenId": "36656454529662513...",
    "side": "BUY",
    "price": 0.55,
    "size": 50,
    "type": "LIMIT"
  }'

Response

{
  "success": true,
  "data": {
    "order": {
      "id": "ord_abc123",
      "polyOrderId": "0x...",
      "status": "FILLED",
      "side": "BUY",
      "price": 0.55,
      "size": 50,
      "filledSize": 50,
      "avgFillPrice": 0.55,
      "marketQuestion": "Bitcoin Up or Down?",
      "outcome": "Up"
    }
  }
}

Dry Run

Test order validation without placing:

curl -X POST "https://luckylobster.io/api/agent/v1/orders" \
  -H "Authorization: Bearer ll_live_..." \
  -H "Content-Type: application/json" \
  -d '{"tokenId": "...", "side": "BUY", "price": 0.55, "size": 50, "dryRun": true}'

List Orders

GET

Get your orders with real-time status sync.

Parameters

Name	Type	Default	Description
`status`	string	-	PENDING, OPEN, FILLED, PARTIALLY_FILLED, CANCELLED, FAILED
`limit`	int	50	Max results (max: 100)
`offset`	int	0	Pagination offset
`sync`	bool	true	Sync open orders with Polymarket

Example

curl "https://luckylobster.io/api/agent/v1/orders?status=OPEN" \
  -H "Authorization: Bearer ll_live_..."

Response

{
  "success": true,
  "data": [...],
  "sync": { "enabled": true, "updated": 2 }
}

Get Order

GET

Get details for a specific order with live status.

Example

curl "https://luckylobster.io/api/agent/v1/orders/ord_abc123" \
  -H "Authorization: Bearer ll_live_..."

Cancel Order

DELETE

Cancel an open order.

Only orders with status PENDING, OPEN, or PARTIALLY_FILLED can be cancelled.

Example

curl -X DELETE "https://luckylobster.io/api/agent/v1/orders/ord_abc123" \
  -H "Authorization: Bearer ll_live_..."

Response

{
  "success": true,
  "message": "Order cancelled successfully",
  "data": {
    "order": {
      "id": "ord_abc123",
      "status": "CANCELLED",
      "previousStatus": "OPEN"
    }
  }
}

List Positions

GET

Get your current positions from Polymarket.

Parameters

Name	Type	Default	Description
`status`	string	open	open, settled, redeemable, all
`source`	string	-	Force `clob` for freshest data

Example

curl "https://luckylobster.io/api/agent/v1/positions" \
  -H "Authorization: Bearer ll_live_..."

Response

{
  "success": true,
  "data": {
    "positions": [
      {
        "id": "pos_abc123",
        "tokenId": "36656454529662513...",
        "market": {
          "question": "Bitcoin Up or Down on February 3?",
          "outcome": "Up"
        },
        "size": 100.0,
        "avgEntryPrice": 0.55,
        "currentPrice": 0.62,
        "currentValue": 62.00,
        "pnl": {
          "unrealized": 7.00,
          "unrealizedPercent": 12.73
        }
      }
    ],
    "summary": {
      "totalPositions": 1,
      "totalUnrealizedPnl": 7.00,
      "totalValue": 62.00
    }
  }
}

Close Position

POST

Close an entire position with a single API call.

Request Body (Optional)

Field	Type	Default	Description
`type`	string	MARKET	MARKET, FOK, or LIMIT
`slippage`	float	0.02	Max slippage for LIMIT orders
`dryRun`	bool	false	Preview without executing

Example

curl -X POST "https://luckylobster.io/api/agent/v1/positions/pos_abc123/close" \
  -H "Authorization: Bearer ll_live_..."

Response

{
  "success": true,
  "message": "Position closed successfully",
  "data": {
    "order": {
      "id": "ord_xyz789",
      "status": "FILLED",
      "side": "SELL",
      "filledSize": 100,
      "avgFillPrice": 0.65
    },
    "position": {
      "id": "pos_abc123",
      "isClosed": true
    },
    "execution": {
      "proceeds": 65.00,
      "pnl": 10.00,
      "pnlPercent": 18.18
    }
  }
}

Approve Tokens

POST

Approve tokens for trading. Required before selling if you get “allowance” errors.

Request Body

Field	Type	Description
`token`	string	`USDC`, `CTF`, `NEG_RISK`, or `all`

Example

curl -X POST "https://luckylobster.io/api/agent/v1/wallet/approve" \
  -H "Authorization: Bearer ll_live_..." \
  -H "Content-Type: application/json" \
  -d '{"token": "CTF"}'

If you get “not enough allowance” errors when selling, call this endpoint with token: "CTF".

API Reference

​Place Order

​Request Body

​Order Types

​Example

​Dry Run

​List Orders

​Parameters

​Example

​Get Order

​Example

​Cancel Order

​Example

​List Positions

​Parameters

​Example

​Close Position

​Request Body (Optional)

​Example

​Approve Tokens

​Request Body

​Example

Place Order

Request Body

Order Types

Example

Dry Run

List Orders

Parameters

Example

Get Order

Example

Cancel Order

Example

List Positions

Parameters

Example

Close Position

Request Body (Optional)

Example

Approve Tokens

Request Body

Example