Skip to main content
GET
/
positions
List live positions
curl --request GET \
  --url https://data-api.forka.st/positions
[
  {
    "proxyWallet": "0x56687bF447db6fFa42FfE2204a05edAa20f55839",
    "asset": "0xdd22472e552920b8438158ea7238bfadfa4f736aa4cee91a6b86c39ead110917:0",
    "conditionId": "0xdd22472e552920b8438158ea7238bfadfa4f736aa4cee91a6b86c39ead110917",
    "size": 1185.42,
    "avgPrice": 0.41,
    "initialValue": 486.02,
    "currentValue": 623.55,
    "cashPnl": 137.53,
    "percentPnl": 28.32,
    "totalBought": 1625,
    "realizedPnl": 212.48,
    "percentRealizedPnl": 13.07,
    "curPrice": 0.53,
    "redeemable": true,
    "mergeable": false,
    "title": "Will the Fed cut rates in September?",
    "slug": "fed-rate-cut-sep-2024",
    "icon": "https://cdn.forka.st/markets/fed.png",
    "eventSlug": "fomc-2024-policy",
    "outcome": "Yes",
    "outcomeIndex": 0,
    "oppositeOutcome": "No",
    "oppositeAsset": "0xdd22472e552920b8438158ea7238bfadfa4f736aa4cee91a6b86c39ead110917:1",
    "timestamp": 1719273600,
    "endDate": "2024-09-18T18:00:00Z",
    "negativeRisk": true
  },
  {
    "proxyWallet": "0x56687bF447db6fFa42FfE2204a05edAa20f55839",
    "asset": "0x8eee3789813eead2d47db3bdf6a1c5021f564ef18e2aefc8b80b9dcd5d6f8ac5:1",
    "conditionId": "0x8eee3789813eead2d47db3bdf6a1c5021f564ef18e2aefc8b80b9dcd5d6f8ac5",
    "size": 940.11,
    "avgPrice": 0.47,
    "initialValue": 441.85,
    "currentValue": 389.84,
    "cashPnl": -52.01,
    "percentPnl": -11.77,
    "totalBought": 1300,
    "realizedPnl": 98.67,
    "percentRealizedPnl": 7.59,
    "curPrice": 0.42,
    "redeemable": false,
    "mergeable": true,
    "title": "Will turnout exceed 60% in the French election?",
    "slug": "france-turnout-60",
    "icon": "https://cdn.forka.st/markets/france-election.png",
    "eventSlug": "french-presidential-2024",
    "outcome": "No",
    "outcomeIndex": 1,
    "oppositeOutcome": "Yes",
    "oppositeAsset": "0x8eee3789813eead2d47db3bdf6a1c5021f564ef18e2aefc8b80b9dcd5d6f8ac5:0",
    "timestamp": 1718083200,
    "endDate": "2024-07-07T20:00:00Z",
    "negativeRisk": false
  }
]
GET https://data-api.forka.st/positions returns every open claim held by a wallet, enriched with market metadata (titles, slugs, icons, and event slugs). The user query parameter is mandatory and must be an EVM address.

​
Key filters

  • Use market (CSV list of condition IDs) to scope down the response.
  • Apply sizeThreshold to strip dust balances. It defaults to 1 so you can raise it for dashboards that only care about sizable exposure.
  • Toggle redeemable=true or mergeable=true to surface lifecycle-specific positions.
  • Use the title substring filter when you need fuzzy search against human-readable market names.

​
Sorting and pagination

limit (max 500) and offset (max 10,000) implement simple pagination. Additional knobs:
  • sortBy: choose between value-based fields (CURRENT, TOKENS, etc.) or descriptive ones like TITLE or RESOLVING.
  • sortDirection: ascending or descending ordering.
The schema surfaces both unrealized (cashPnl, percentPnl) and realized metrics, plus hints such as negativeRisk to help front-ends flag advanced positions.

Query Parameters

​
user
string
required

Wallet address whose positions should be returned.

Example:

"0x56687bf447db6ffa42ffe2204a05edaa20f55839"

​
market
string[]

Comma-separated list of condition IDs.

0x-prefixed 64-character hex string.

​
sizeThreshold
number
default:1

Minimum token balance to include in the response.

Required range: x >= 0
​
redeemable
boolean
default:false

Set to true to only return claims that can currently be redeemed.

​
mergeable
boolean
default:false

Set to true to only return positions that can be merged.

​
limit
integer
default:100

Maximum number of rows to return (max 500).

Required range: 0 <= x <= 500
​
offset
integer
default:0

Cursor offset for pagination (max 10,000).

Required range: 0 <= x <= 10000
​
sortBy
enum<string>
default:TOKENS

Sort column for the response.

Available options:
CURRENT,
INITIAL,
TOKENS,
CASHPNL,
PERCENTPNL,
TITLE,
RESOLVING,
PRICE,
AVGPRICE
​
sortDirection
enum<string>
default:DESC

Sort direction (ascending or descending).

Available options:
ASC,
DESC
​
title
string

Substring search against market title (max 100 chars).

Maximum string length: 100

Response

Positions were found.

​
proxyWallet
string

0x-prefixed EVM address (40 hex chars).

Example:

"0x56687bf447db6ffa42ffe2204a05edaa20f55839"

​
asset
string
​
conditionId
string

0x-prefixed 64-character hex string.

Example:

"0xdd22472e552920b8438158ea7238bfadfa4f736aa4cee91a6b86c39ead110917"

​
size
number
​
avgPrice
number
​
initialValue
number
​
currentValue
number
​
cashPnl
number
​
totalBought
number
​
realizedPnl
number
​
percentPnl
number
​
percentRealizedPnl
number
​
curPrice
number
​
redeemable
boolean
​
mergeable
boolean
​
title
string
​
slug
string
​
icon
string
​
eventSlug
string
​
outcome
string
​
outcomeIndex
integer
​
oppositeOutcome
string
​
oppositeAsset
string
​
timestamp
integer<int64>
​
endDate
string<date-time>
​
negativeRisk
boolean