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

{
  "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

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

{
  "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

{
  "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

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

{
  "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

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