# Positions

View and sync user positions in prediction markets.

## Get Position

Returns a user's position in a specific market by market contract address.

GET /api/v1/positions/{marketAddress}

### Path Parameters

| Parameter       | Type    | Description             |
| --------------- | ------- | ----------------------- |
| `marketAddress` | address | Market contract address |

### Query Parameters

| Parameter | Type    | Required | Description           |
| --------- | ------- | -------- | --------------------- |
| `user`    | address | Yes      | User's wallet address |

### Response

```json
{
  "yesShares": 50000000,
  "noShares": 0,
  "totalInvested": 25000000,
  "yesCost": 25000000,
  "noCost": 0
}
```

| Field           | Type  | Description                                            |
| --------------- | ----- | ------------------------------------------------------ |
| `yesShares`     | int64 | YES token balance (6 decimals). `50000000` = 50 shares |
| `noShares`      | int64 | NO token balance (6 decimals)                          |
| `totalInvested` | int64 | Total USDC invested (6 decimals). `25000000` = $25     |
| `yesCost`       | int64 | Cost basis for YES position                            |
| `noCost`        | int64 | Cost basis for NO position                             |

If no position exists, returns `{"yesShares": 0, "noShares": 0}`.

### Example

```bash
curl "https://api.turbinefi.com/api/v1/positions/0xMarketContract?user=0xYourAddress"
```

***

## Sync Position

Force-sync a user's position from on-chain CTF token balances. Useful when positions are out of sync with the blockchain.

POST /api/v1/positions/{marketId}/sync

### Path Parameters

| Parameter  | Type    | Description       |
| ---------- | ------- | ----------------- |
| `marketId` | bytes32 | Market identifier |

### Request Body

```json
{
  "userAddress": "0xYourAddress..."
}
```

The `userAddress` can also be passed as a query parameter instead of in the body.

| Field         | Type    | Required | Description          |
| ------------- | ------- | -------- | -------------------- |
| `userAddress` | address | Yes      | User address to sync |

### Response

```json
{
  "success": true,
  "position": {
    "yesShares": 50000000,
    "noShares": 0,
    "totalInvested": 25000000
  },
  "message": "Position synced from blockchain"
}
```

Returns `503 Service Unavailable` if blockchain sync is not available on the server.

### Example

```bash
curl -X POST "https://api.turbinefi.com/api/v1/positions/0x1234...abcd/sync" \
  -H "Content-Type: application/json" \
  -d '{"userAddress": "0xYourAddress"}'
```

***

## Get All User Positions

Returns all positions for a user across all markets on a specific chain.

GET /api/v1/users/{address}/positions

### Path Parameters

| Parameter | Type    | Description           |
| --------- | ------- | --------------------- |
| `address` | address | User's wallet address |

### Query Parameters

| Parameter  | Type    | Required | Description            |
| ---------- | ------- | -------- | ---------------------- |
| `chain_id` | integer | Yes      | Chain ID (e.g., `137`) |

### Response

```json
{
  "positions": [
    {
      "marketId": "0x...",
      "marketQuestion": "Will ETH reach $5000?",
      "contractAddress": "0xMarketContract...",
      "yesShares": 50000000,
      "noShares": 0,
      "totalInvested": 25000000,
      "expiration": 1735689600,
      "resolved": false
    }
  ]
}
```

| Field             | Type   | Description                          |
| ----------------- | ------ | ------------------------------------ |
| `marketId`        | string | Market identifier                    |
| `marketQuestion`  | string | Market question                      |
| `contractAddress` | string | Market contract address              |
| `yesShares`       | int64  | YES token balance (6 decimals)       |
| `noShares`        | int64  | NO token balance (6 decimals)        |
| `totalInvested`   | int64  | Total USDC invested (6 decimals)     |
| `expiration`      | int64  | Market expiration timestamp          |
| `resolved`        | bool   | Whether the market has been resolved |

### Example

```bash
curl "https://api.turbinefi.com/api/v1/users/0xYourAddress/positions?chain_id=137"
```