Polymarket Analytics — Kiyotaka Docs

Weight: Fixed per request, depending on endpoint | Advanced-tier only

These endpoints expose Polymarket-specific analytics that are not served through /v1/points. They are fixed-weight GET endpoints under /v1/polymarket/analytics/*, and they do not use the usual point-based weight formula. All examples use the standard public auth header:

Header

-H "X-Kiyotaka-Key: YOUR_API_KEY"

Common behavior

Rule	Details
Tier access	Advanced-tier only
Weight model	Fixed per endpoint
HTTP method	`GET`
Pagination	`limit` defaults to `20`, `offset` defaults to `0`
Pagination bounds	`limit <= 100`, `offset <= 100`
Streaming	Not available on WebSocket

These endpoints are separate from /v1/points. They do not use type, exchange, interval, from, or period.

Top-level JSON fields are camelCase (traderProfiles, traderProfile, userPositions, marketSummary, userCategories). Nested Polymarket payload fields remain snake_case.

The JSON response can omit fields whose values are zero, empty, or unset. The response tables below list the available fields even when a specific response sample does not include every field. Long distribution arrays are shortened in the examples.

Endpoint overview

Endpoint	Weight	Purpose
`/v1/polymarket/analytics/leaderboard`	60	Browse trader leaderboard results with bounded filters and sorting
`/v1/polymarket/analytics/trader-profile`	100	Fetch a single trader profile for one wallet
`/v1/polymarket/analytics/positions`	40	Fetch bounded position rows by wallet, asset, or condition
`/v1/polymarket/analytics/market-summary`	60	Fetch a market summary for exactly one `assetId` or `conditionId`
`/v1/polymarket/analytics/user-categories`	40	Fetch a trader's category breakdown for one wallet

When the target is a known market rather than a specific outcome token, prefer conditionId.

Leaderboard

GET/v1/polymarket/analytics/leaderboard

Returns a bounded list of trader profiles. By default it sorts by realized PnL descending.

Parameters

Parameter	Type	Required	Description
`limit`	int32	No	Number of rows to return. Default: `20`. Max: `100`.
`offset`	int32	No	Zero-based pagination offset. Default: `0`. Max: `100`.
`roiPercentage`	int64	No	Minimum realized ROI percentage.
`minTotalTradeCount`	double	No	Minimum total position count.
`maxTotalTradeCount`	double	No	Maximum total position count.
`winRate`	double	No	Minimum win rate percentage.
`avgPositionSize`	double	No	Minimum average position size.
`totalVolume`	double	No	Minimum total traded size.
`primaryCategory`	string	No	Filter to traders who have traded a category, for example `Politics`.
`openPositionCount`	int64	No	Minimum number of open positions.
`timeSinceLastTrade`	int64	No	Minimum seconds since the latest trade.
`avgHoldingTime`	int64	No	Minimum average holding duration in seconds.
`sortBy`	enum	No	`REALIZED_PNL`, `ROI`, `WIN_COUNT`, `WIN_RATE`, `TOTAL_SIZE`, or `TOTAL_POSITION_COUNT`.
`sortDirection`	enum	No	`SORT_DIRECTION_ASC` or `SORT_DIRECTION_DESC`.

Response fields

Each entry in traderProfiles is a PolymarketTraderProfile:

Field	Type	Description
`wallet_address`	string	Trader wallet address
`total_position_count`	int64	Total number of tracked positions
`open_position_count`	int64	Number of currently open positions
`closed_position_count`	int64	Number of closed positions
`latest_open_position_ts`	object	Latest open position timestamp, with `seconds` and `nanoseconds`
`total_size`	double	Total tracked position size
`total_realized_pnl`	double	Total realized PnL
`total_unrealized_pnl`	double	Total unrealized PnL
`total_roi`	double	Total return on investment
`win_rate_by_positions`	double	Win rate by closed positions
`largest_win`	double	Largest realized win
`largest_loss`	double	Largest realized loss
`avg_holding_duration`	int64	Average holding duration in seconds
`total_open_pos_value`	double	Total value of open positions
`total_closed_pos_value`	double	Total value of closed positions

Example

cURL

curl "https://api.kiyotaka.ai/v1/polymarket/analytics/leaderboard?limit=1" \\
  -H "X-Kiyotaka-Key: YOUR_API_KEY"

JSON

{
  "traderProfiles": [
    {
      "wallet_address": "0xf1302aafc43aa3a69bcd8058fc7a0259dac246ab",
      "total_position_count": 1047,
      "closed_position_count": 1047,
      "total_size": 193273897.17371872,
      "total_realized_pnl": 94916520.2155992,
      "win_rate_by_positions": 80.70678127984718,
      "largest_win": 5740012.643231001,
      "largest_loss": -48.26,
      "avg_holding_duration": 3429946,
      "total_closed_pos_value": 193273897.17371872
    }
  ]
}

Trader Profile

GET/v1/polymarket/analytics/trader-profile

Returns a single trader profile for exactly one wallet.

Parameters

Parameter	Type	Required	Description
`userWallet`	string	Yes	Wallet address, for example `0x...`

Response

The response contains a single traderProfile object with the same shape as leaderboard rows.

cURL

curl "https://api.kiyotaka.ai/v1/polymarket/analytics/trader-profile?userWallet=0xf1302aafc43aa3a69bcd8058fc7a0259dac246ab" \\
  -H "X-Kiyotaka-Key: YOUR_API_KEY"

JSON

{
  "traderProfile": {
    "wallet_address": "0xf1302aafc43aa3a69bcd8058fc7a0259dac246ab",
    "total_position_count": 1047,
    "closed_position_count": 1047,
    "total_size": 193273897.17371872,
    "total_realized_pnl": 94916520.2155992,
    "win_rate_by_positions": 80.70678127984718,
    "largest_win": 5740012.643231001,
    "largest_loss": -48.26,
    "avg_holding_duration": 3429946,
    "total_closed_pos_value": 193273897.17371872
  }
}

Positions

GET/v1/polymarket/analytics/positions

Returns bounded position rows for one wallet, one asset, or one market condition.

Parameters

Parameter	Type	Required	Description
`userWallet`	string	No	Wallet address. Can be used alone or together with one identifier.
`assetId`	string	No	Outcome token identifier. Mutually exclusive with `conditionId`.
`conditionId`	string	No	Market condition identifier. Mutually exclusive with `assetId`.
`limit`	int32	No	Number of rows to return. Default: `20`. Max: `100`.
`offset`	int32	No	Zero-based pagination offset. Default: `0`. Max: `100`.

Valid request shapes

userWallet=<wallet>
userWallet=<wallet>&assetId=<asset_id>
userWallet=<wallet>&conditionId=<condition_id>
assetId=<asset_id>
conditionId=<condition_id> At least one of userWallet, assetId, or conditionId is required. assetId and conditionId cannot be set together.

Response fields

Each entry in userPositions is a PolymarketUserPositions row:

Field	Type	Description
`wallet_address`	string	Trader wallet address
`asset_id`	string	Outcome token identifier
`unrealized_size`	double	Currently unrealized position size
`realized_size`	double	Realized position size
`avg_price`	double	Average entry price
`avg_exit_price`	double	Average exit price
`realized_pnl`	double	Realized PnL
`resolved_price`	double	Final resolved price, when available
`latest_open_ts`	int64	Latest open timestamp
`prev_hold_duration`	int64	Previous holding duration in seconds
`buy_count`	int32	Number of buy events
`sell_count`	int32	Number of sell events
`split_count`	int32	Number of split events
`merge_count`	int32	Number of merge events
`transfer_in_count`	int32	Number of inbound transfer events
`transfer_out_count`	int32	Number of outbound transfer events
`conversion_in_count`	int32	Number of inbound conversion events
`conversion_out_count`	int32	Number of outbound conversion events
`market_name`	string	Market title
`outcome_name`	string	Outcome label
`category`	string	Market category
`sub_category`	string	Market sub-category
`condition_id`	string	Market condition identifier

Example

cURL

curl "https://api.kiyotaka.ai/v1/polymarket/analytics/positions?userWallet=0xf1302aafc43aa3a69bcd8058fc7a0259dac246ab&limit=1" \\
  -H "X-Kiyotaka-Key: YOUR_API_KEY"

JSON

{
  "userPositions": [
    {
      "wallet_address": "0xf1302aafc43aa3a69bcd8058fc7a0259dac246ab",
      "asset_id": "69984203794322070924779554468751071533998686576952069110752844084141678897886",
      "realized_size": 11555027.501624001,
      "avg_exit_price": 0.49675456353732356,
      "realized_pnl": 5740012.643231001,
      "resolved_price": 1,
      "prev_hold_duration": 14305671,
      "merge_count": 153,
      "transfer_in_count": 383,
      "transfer_out_count": 24,
      "market_name": "Which party will control the U.S. Senate after the 2022 election?",
      "outcome_name": "Democratic",
      "category": "Politics",
      "sub_category": "US Politics",
      "condition_id": "0xe0658c4beed2102c181b3987edff5edd578ad2952a6eb5fa8018925e5d7a48fd"
    }
  ]
}

Market Summary

GET/v1/polymarket/analytics/market-summary

Returns a market summary for exactly one assetId or one conditionId.

Parameters

Parameter	Type	Required	Description
`assetId`	string	No	Outcome token identifier
`conditionId`	string	No	Market condition identifier

Exactly one of assetId or conditionId is required.

Response fields

The response contains a single marketSummary object:

Field	Type	Description
`event_id`	string	Polymarket event identifier
`condition_id`	string[]	Condition IDs included in the summary
`total_open_positions`	int32	Open position count
`total_closed_positions`	int32	Closed position count
`total_cost_basis`	double	Total cost basis
`total_size`	double	Total traded size
`largest_open_position`	double	Largest open position size
`total_buy_count`	int32	Total buy event count
`total_sell_count`	int32	Total sell event count
`total_split_count`	int32	Total split event count
`total_merge_count`	int32	Total merge event count
`total_transfer_in_count`	int32	Total inbound transfer event count
`total_transfer_out_count`	int32	Total outbound transfer event count
`total_conversion_in_count`	int32	Total inbound conversion event count
`total_conversion_out_count`	int32	Total outbound conversion event count
`net_transfer_flow`	int32	Net transfer flow count
`net_conversion_flow`	int32	Net conversion flow count
`median_hold_duration`	double	Median holding duration in seconds
`mean_hold_duration`	double	Mean holding duration in seconds
`realized_pnl_min`	double	Minimum realized PnL
`realized_pnl_max`	double	Maximum realized PnL
`realized_pnl_distribution`	double[]	Realized PnL percentile values from p0 to p99
`win_rate`	double	Win rate for the summarized market
`avg_buy_count`	double	Average buy event count
`avg_sell_count`	double	Average sell event count
`avg_size`	double	Average position size
`outcome_pricing`	object[]	Per-outcome token pricing rows

Each row in outcome_pricing includes:

Field	Type	Description
`condition_id`	string	Market condition identifier
`token_id`	string	Outcome token identifier
`outcome_name`	string	Outcome label
`weighted_avg_entry_price`	double	Weighted average entry price
`weighted_avg_exit_price`	double	Weighted average exit price
`open_pos_avg_price_distribution`	double[]	101 buckets; index `i` is the account count with average entry price in `[i, i+1)` cents
`closed_pos_avg_exit_price_distribution`	double[]	101 buckets; index `i` is the account count with average exit price in `[i, i+1)` cents

Example

cURL

curl "https://api.kiyotaka.ai/v1/polymarket/analytics/market-summary?assetId=69984203794322070924779554468751071533998686576952069110752844084141678897886" \\
  -H "X-Kiyotaka-Key: YOUR_API_KEY"

JSON

{
  "marketSummary": {
    "event_id": "3506",
    "condition_id": [
      "0xe0658c4beed2102c181b3987edff5edd578ad2952a6eb5fa8018925e5d7a48fd"
    ],
    "total_open_positions": 12,
    "total_closed_positions": 934,
    "total_cost_basis": 3287751.5362184998,
    "total_size": 13278317.319730995,
    "largest_open_position": 6517160.129311998,
    "total_split_count": 10516,
    "total_merge_count": 6370,
    "total_transfer_in_count": 10523,
    "total_transfer_out_count": 10523,
    "median_hold_duration": 19340026,
    "mean_hold_duration": 15813372.224219989,
    "realized_pnl_min": -7865106.637885602,
    "realized_pnl_max": 5740012.643231001,
    "realized_pnl_distribution": [
      -7865106.637885602,
      -0.00046407000000012324,
      0,
      74042.54808002156
    ],
    "win_rate": 0.5288259958071279,
    "avg_size": 48280.608293311605,
    "outcome_pricing": [
      {
        "condition_id": "0xe0658c4beed2102c181b3987edff5edd578ad2952a6eb5fa8018925e5d7a48fd",
        "token_id": "111299642775108135148113523472260651188510255643046337855221699185339755388694",
        "outcome_name": "Republican",
        "weighted_avg_entry_price": 0.000005283318038929714,
        "weighted_avg_exit_price": 0.1733132532287334,
        "open_pos_avg_price_distribution": [10, 0, 0, 3],
        "closed_pos_avg_exit_price_distribution": [872, 1, 2, 24]
      }
    ]
  }
}

User Categories

GET/v1/polymarket/analytics/user-categories

Returns a category breakdown for exactly one wallet.

Parameters

Parameter	Type	Required	Description
`userWallet`	string	Yes	Wallet address, for example `0x...`

Response fields

The response contains a single userCategories object:

Field	Type	Description
`wallet_address`	string	Trader wallet address
`category_breakdown`	object[]	Category-level breakdown rows

Each row in category_breakdown includes:

Field	Type	Description
`market_category`	string	Top-level category name
`market_sub_category`	string	Sub-category name
`count`	int64	Number of positions in that category
`realized_size`	double	Realized traded size
`unrealized_size`	double	Unrealized size
`realized_pnl`	double	Realized PnL for that category

Example

cURL

curl "https://api.kiyotaka.ai/v1/polymarket/analytics/user-categories?userWallet=0xf1302aafc43aa3a69bcd8058fc7a0259dac246ab" \\
  -H "X-Kiyotaka-Key: YOUR_API_KEY"

JSON

{
  "userCategories": {
    "wallet_address": "0xf1302aafc43aa3a69bcd8058fc7a0259dac246ab",
    "category_breakdown": [
      {
        "market_category": "Politics",
        "market_sub_category": "US Politics",
        "count": 248,
        "realized_size": 114739709.61980493,
        "realized_pnl": 56646616.73381202
      }
    ]
  }
}

Typical workflows

Common starting points fall into two categories:

inspect a trader
inspect a market Choose the workflow that matches the task. Not every endpoint needs to be called in sequence.

Start from a trader

Use this flow to discover a wallet first, then inspect that trader's profile, category mix, and positions.

Call /leaderboard with a small limit to get a wallet.
Extract traderProfiles[0].wallet_address.
Reuse that wallet with /trader-profile, /user-categories, or /positions.
For market-level context on one returned position, extract condition_id from /positions and call /market-summary.

Bash

WALLET=$(curl -s "https://api.kiyotaka.ai/v1/polymarket/analytics/leaderboard?limit=1" \\
  -H "X-Kiyotaka-Key: YOUR_API_KEY" | jq -r '.traderProfiles[0].wallet_address')


curl "https://api.kiyotaka.ai/v1/polymarket/analytics/trader-profile?userWallet=\${WALLET}" \\
  -H "X-Kiyotaka-Key: YOUR_API_KEY"


curl "https://api.kiyotaka.ai/v1/polymarket/analytics/user-categories?userWallet=\${WALLET}" \\
  -H "X-Kiyotaka-Key: YOUR_API_KEY"


CONDITION_ID=$(curl -s "https://api.kiyotaka.ai/v1/polymarket/analytics/positions?userWallet=\${WALLET}&limit=1" \\
  -H "X-Kiyotaka-Key: YOUR_API_KEY" | jq -r '.userPositions[0].condition_id')


curl "https://api.kiyotaka.ai/v1/polymarket/analytics/market-summary?conditionId=\${CONDITION_ID}" \\
  -H "X-Kiyotaka-Key: YOUR_API_KEY"

Start from a market

Use this flow when the market is already known and a conditionId is available.

Start with a conditionId.
Call /market-summary with that conditionId.
Optionally call /positions?conditionId=... to inspect position rows for that market. The example below uses the same conditionId shown in the /positions example above, so the commands can be run directly.

Bash

CONDITION_ID="0xe0658c4beed2102c181b3987edff5edd578ad2952a6eb5fa8018925e5d7a48fd"


curl "https://api.kiyotaka.ai/v1/polymarket/analytics/market-summary?conditionId=\${CONDITION_ID}" \\
  -H "X-Kiyotaka-Key: YOUR_API_KEY"


curl "https://api.kiyotaka.ai/v1/polymarket/analytics/positions?conditionId=\${CONDITION_ID}&limit=5" \\
  -H "X-Kiyotaka-Key: YOUR_API_KEY"

These examples use jq to extract identifiers from JSON. Without jq, extract traderProfiles[0].wallet_address or userPositions[0].condition_id from the responses and reuse those values manually.

Monitor weight consumption with GET /v1/usage, and see the Rate Limits page for the response headers and quota model.