> ## Documentation Index
> Fetch the complete documentation index at: https://docs.luckylobster.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Trading

> Place orders and manage positions

## Place Order

<ParamField query="POST" path="/orders">
  Place a buy or sell order on a market.
</ParamField>

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

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

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

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

***

## List Orders

<ParamField query="GET" path="/orders">
  Get your orders with real-time status sync.
</ParamField>

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

```bash theme={null}
curl "https://luckylobster.io/api/agent/v1/orders?status=OPEN" \
  -H "Authorization: Bearer ll_..."
```

```json Response theme={null}
{
  "success": true,
  "data": [...],
  "sync": { "enabled": true, "updated": 2 }
}
```

***

## Get Order

<ParamField query="GET" path="/orders/{id}">
  Get details for a specific order with live status.
</ParamField>

### Example

```bash theme={null}
curl "https://luckylobster.io/api/agent/v1/orders/ord_abc123" \
  -H "Authorization: Bearer ll_..."
```

***

## Cancel Order

<ParamField query="DELETE" path="/orders/{id}">
  Cancel an open order.
</ParamField>

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

### Example

```bash theme={null}
curl -X DELETE "https://luckylobster.io/api/agent/v1/orders/ord_abc123" \
  -H "Authorization: Bearer ll_..."
```

```json Response theme={null}
{
  "success": true,
  "message": "Order cancelled successfully",
  "data": {
    "order": {
      "id": "ord_abc123",
      "status": "CANCELLED",
      "previousStatus": "OPEN"
    }
  }
}
```

***

## List Positions

<ParamField query="GET" path="/positions">
  Get your current positions from Polymarket.
</ParamField>

### Parameters

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

### Example

```bash theme={null}
curl "https://luckylobster.io/api/agent/v1/positions" \
  -H "Authorization: Bearer ll_..."
```

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

<ParamField query="POST" path="/positions/{id}/close">
  Close an entire position with a single API call.
</ParamField>

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

```bash theme={null}
curl -X POST "https://luckylobster.io/api/agent/v1/positions/pos_abc123/close" \
  -H "Authorization: Bearer ll_..."
```

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

<ParamField query="POST" path="/wallet/approve">
  Approve tokens for trading. Required before selling if you get "allowance" errors.
</ParamField>

### Request Body

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

### Example

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

<Note>
  If you get "not enough allowance" errors when selling, call this endpoint with `token: "CTF"`.
</Note>