openapi: 3.0.0
info:
title: Arkham Intel Analytics Polymarket API
version: 1.1.0
tags:
- name: Polymarket
paths:
/polymarket/activity:
get:
summary: Polymarket activity feed
description: Returns a paginated feed of Polymarket trade and lifecycle events (trades, splits, merges, converts), newest first. Use `actions`, `eventType`, or `direction` to scope which event types are returned (`actions` can't be combined with the other two).
operationId: GetPolymarketActivity
parameters:
- name: userAddresses
in: query
description: Optional. Filter to specific Polymarket trade addresses.
schema:
type: array
items:
type: string
description: Polymarket trade address (0x + 40 hex chars).
example: '0xBDDF61Af533fF524D27154e589d2D7A81510C684'
description: Optional. Filter to specific Polymarket trade addresses.
example:
- '0xBDDF61Af533fF524D27154e589d2D7A81510C684'
- name: conditionID
in: query
description: Optional. Filter to a single market condition ID (all of its outcome tokens).
schema:
type: string
description: Optional. Filter to a single market condition ID (all of its outcome tokens).
example: '0x9be56371f6a29d12769b2f196847ee825b9585ebb8bfa042136be031b081eba1'
- name: eventID
in: query
description: Optional. Filter to all markets and outcomes in a Polymarket event.
schema:
type: integer
description: Optional. Filter to all markets and outcomes in a Polymarket event.
nullable: true
example: 30615
- name: tokenAddresses
in: query
description: Optional. Filter to specific outcome token addresses. The conditionID, eventID, and tokenAddresses filters are intersected (a token must satisfy all provided).
schema:
type: array
items:
type: string
description: Polymarket outcome token ID encoded as 0x-prefixed uint256 hex.
example: '0x7baa312d6393ea83c631fb77b47061651a2a9992c40fcac017009611d6a03df4'
description: Optional. Filter to specific outcome token addresses. The conditionID, eventID, and tokenAddresses filters are intersected (a token must satisfy all provided).
example:
- '0x7baa312d6393ea83c631fb77b47061651a2a9992c40fcac017009611d6a03df4'
- name: minUsd
in: query
description: Optional. Minimum notional (size * price) in whole USD.
schema:
minimum: 0
type: integer
description: Optional. Minimum notional (size * price) in whole USD.
nullable: true
example: 100
- name: maxUsd
in: query
description: Optional. Maximum notional (size * price) in whole USD.
schema:
minimum: 0
type: integer
description: Optional. Maximum notional (size * price) in whole USD.
nullable: true
example: 1000
- name: minPrice
in: query
description: Optional. Minimum per-share price as a 0-1 fraction.
schema:
type: number
description: Optional. Minimum per-share price as a 0-1 fraction.
nullable: true
example: 0.25
- name: maxPrice
in: query
description: Optional. Maximum per-share price as a 0-1 fraction.
schema:
type: number
description: Optional. Maximum per-share price as a 0-1 fraction.
nullable: true
example: 0.75
- name: minSize
in: query
description: Optional. Minimum trade size in whole outcome-token shares.
schema:
minimum: 0
type: integer
description: Optional. Minimum trade size in whole outcome-token shares.
nullable: true
example: 10
- name: maxSize
in: query
description: Optional. Maximum trade size in whole outcome-token shares.
schema:
minimum: 0
type: integer
description: Optional. Maximum trade size in whole outcome-token shares.
nullable: true
example: 500
- name: actions
in: query
description: 'Optional. Filter to one or more actions: buy, sell, split, merge, convert. Cannot be combined with eventType or direction.'
schema:
type: array
items:
$ref: '#/components/schemas/PolymarketActivityAction'
description: 'Optional. Filter to one or more actions: buy, sell, split, merge, convert. Cannot be combined with eventType or direction.'
example:
- buy
- name: eventType
in: query
description: 'Optional. Filter by event class: trade, split, merge, or convert. Use direction to narrow trades to one side.'
schema:
$ref: '#/components/schemas/PolymarketActivityEventType'
- name: direction
in: query
description: 'Optional. Narrow trades to one side: buy or sell. Only valid with eventType=trade (or no eventType).'
schema:
$ref: '#/components/schemas/PolymarketActivityDirection'
- name: startTime
in: query
description: Optional. Unix timestamp in seconds for the start of the range (inclusive).
schema:
type: integer
description: Optional. Unix timestamp in seconds for the start of the range (inclusive).
nullable: true
example: 1717200000
- name: endTime
in: query
description: Optional. Unix timestamp in seconds for the end of the range (exclusive).
schema:
type: integer
description: Optional. Unix timestamp in seconds for the end of the range (exclusive).
nullable: true
example: 1719878400
- name: limit
in: query
description: Max results (default 50, max 500).
schema:
type: integer
description: Max results (default 50, max 500).
example: 50
- name: offset
in: query
description: Offset for pagination (default 0).
schema:
type: integer
description: Offset for pagination (default 0).
example: 0
- name: fastPagination
in: query
description: Fast pagination defaults to true. When enabled, totalCount is only large enough to determine whether another page exists; set false to count matches up to 10,000.
schema:
type: boolean
description: Fast pagination defaults to true. When enabled, totalCount is only large enough to determine whether another page exists; set false to count matches up to 10,000.
default: true
nullable: true
example: true
- name: sortBy
in: query
description: 'Column to order by: time (default), size (outcome-token shares), price (cents-per-share), usd (notional).'
schema:
$ref: '#/components/schemas/PolymarketActivitySortBy'
- name: sortOrder
in: query
description: 'Sort direction: asc or desc (default).'
schema:
$ref: '#/components/schemas/SortDir'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PolymarketActivityResponse'
'400':
description: Bad Request
'500':
description: Internal Server Error
tags:
- Polymarket
/polymarket/event-positions/{conditionId}:
get:
summary: Polymarket positions in a market
description: Returns holders and their positions for a market's outcome tokens — one row per user and token, with shares, price, value, and PnL.
operationId: GetPolymarketEventPositions
parameters:
- name: tokenAddresses
in: query
description: Optional. Explicit outcome token list; overrides condition-derived tokens and can span markets beyond the path conditionId.
schema:
type: array
items:
type: string
description: Polymarket outcome token ID encoded as 0x-prefixed uint256 hex.
example: '0x7baa312d6393ea83c631fb77b47061651a2a9992c40fcac017009611d6a03df4'
description: Optional. Explicit outcome token list; overrides condition-derived tokens and can span markets beyond the path conditionId.
example:
- '0x7baa312d6393ea83c631fb77b47061651a2a9992c40fcac017009611d6a03df4'
- name: userAddresses
in: query
description: Optional. Filter to specific Polymarket trade addresses.
schema:
type: array
items:
type: string
description: Polymarket trade address (0x + 40 hex chars).
example: '0xBDDF61Af533fF524D27154e589d2D7A81510C684'
description: Optional. Filter to specific Polymarket trade addresses.
example:
- '0xBDDF61Af533fF524D27154e589d2D7A81510C684'
- name: outcome
in: query
description: Optional. 0 for Yes token, 1 for No token.
schema:
type: integer
description: Optional. 0 for Yes token, 1 for No token.
nullable: true
example: 1
- name: minShares
in: query
description: Optional. Minimum held shares (whole outcome-token shares).
schema:
minimum: 0
type: integer
description: Optional. Minimum held shares (whole outcome-token shares).
nullable: true
example: 10
- name: maxShares
in: query
description: Optional. Maximum held shares (whole outcome-token shares).
schema:
minimum: 0
type: integer
description: Optional. Maximum held shares (whole outcome-token shares).
nullable: true
example: 500
- name: minValue
in: query
description: Optional. Minimum current position value in whole USD.
schema:
type: integer
description: Optional. Minimum current position value in whole USD.
nullable: true
example: 100
- name: maxValue
in: query
description: Optional. Maximum current position value in whole USD.
schema:
type: integer
description: Optional. Maximum current position value in whole USD.
nullable: true
example: 1000
- name: minPnl
in: query
description: Optional. Minimum PnL in whole USD (can be negative).
schema:
type: integer
description: Optional. Minimum PnL in whole USD (can be negative).
nullable: true
example: -100
- name: maxPnl
in: query
description: Optional. Maximum PnL in whole USD (can be negative).
schema:
type: integer
description: Optional. Maximum PnL in whole USD (can be negative).
nullable: true
example: 500
- name: sortBy
in: query
description: Optional. "pnl" (default), "shares", or "value".
schema:
$ref: '#/components/schemas/PolymarketEventPositionsSortBy'
- name: sortOrder
in: query
description: Optional. "asc" or "desc" (default).
schema:
$ref: '#/components/schemas/SortDir'
- name: limit
in: query
description: Max results (default 50, max 1000).
schema:
type: integer
description: Max results (default 50, max 1000).
example: 50
- name: offset
in: query
description: Offset for pagination (default 0).
schema:
type: integer
description: Offset for pagination (default 0).
example: 0
- name: conditionId
in: path
description: Required. Polymarket condition ID.
required: true
schema:
type: string
description: Required. Polymarket condition ID.
example: '0x9be56371f6a29d12769b2f196847ee825b9585ebb8bfa042136be031b081eba1'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PolymarketEventPositionsResponse'
'400':
description: Bad Request
'500':
description: Internal Server Error
tags:
- Polymarket
/polymarket/events:
get:
summary: List Polymarket events
description: Returns a filtered, paginated list of Polymarket events, each with a few top-market previews and current prices.
operationId: GetPolymarketEvents
parameters:
- name: tag
in: query
description: Optional. Filter by event tag. Matches lowercase Polymarket tags case-insensitively.
schema:
type: string
description: Optional. Filter by event tag. Matches lowercase Polymarket tags case-insensitively.
example: crypto
- name: excludeTag
in: query
description: Optional. Exclude events carrying this tag (case-insensitive).
schema:
type: string
description: Optional. Exclude events carrying this tag (case-insensitive).
example: sports
- name: active
in: query
description: Optional. Filter to active events — not closed and not ended (true/false).
schema:
type: boolean
description: Optional. Filter to active events — not closed and not ended (true/false).
nullable: true
example: true
- name: search
in: query
description: Optional. Search event titles, market questions, and grouped-market titles.
schema:
type: string
description: Optional. Search event titles, market questions, and grouped-market titles.
example: bitcoin
- name: sortBy
in: query
description: 'Optional. Sort field: volume, endDate, or createdAt. Default: volume when no tag, endDate when tag is set.'
schema:
$ref: '#/components/schemas/PolymarketEventSortBy'
- name: order
in: query
description: 'Sort order: asc or desc. Default: desc.'
schema:
$ref: '#/components/schemas/SortDir'
- name: limit
in: query
description: 'Max events to return (1-100). Default: 50.'
schema:
type: integer
description: 'Max events to return (1-100). Default: 50.'
example: 50
- name: offset
in: query
description: 'Pagination offset. Default: 0.'
schema:
type: integer
description: 'Pagination offset. Default: 0.'
example: 0
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PolymarketEventsResponse'
'400':
description: Bad Request
'500':
description: Internal Server Error
tags:
- Polymarket
/polymarket/events/{eventId}:
get:
summary: Get a Polymarket event
description: Returns a single Polymarket event by its event ID, along with every active or resolved market in the event. Each market includes its outcomes, current Yes price, 24h volume, and resolution status. Returns 404 if the event does not exist.
operationId: GetPolymarketEvent
parameters:
- name: eventId
in: path
description: Required. Polymarket event ID.
required: true
schema:
type: integer
description: Required. Polymarket event ID.
example: 30615
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PolymarketEventResponse'
'400':
description: Bad Request
'500':
description: Internal Server Error
tags:
- Polymarket
/polymarket/leaderboard:
get:
summary: Polymarket PnL leaderboard
description: 'Returns the Polymarket total-PnL leaderboard (realized plus unrealized) for a period: 1d, 1w, 1m, or all (default 1d). Order desc for top traders or asc for worst. Pass an address to also receive that trader''s rank.'
operationId: GetPolymarketLeaderboard
parameters:
- name: period
in: query
description: 'Time period: 1d, 1w, 1m, all. Default: 1d'
schema:
$ref: '#/components/schemas/PolymarketLeaderboardPeriod'
- name: order
in: query
description: 'Sort order: desc (top traders) or asc (worst traders). Default: desc'
schema:
$ref: '#/components/schemas/SortDir'
- name: limit
in: query
description: 'Max entries (1-200). Default: 100'
schema:
type: integer
description: 'Max entries (1-200). Default: 100'
example: 100
- name: offset
in: query
description: 'Pagination offset. Default: 0'
schema:
type: integer
description: 'Pagination offset. Default: 0'
example: 0
- name: address
in: query
description: Optional trade address. If set, also returns this user's rank.
schema:
type: string
description: Optional trade address. If set, also returns this user's rank.
example: '0xBDDF61Af533fF524D27154e589d2D7A81510C684'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PolymarketLeaderboardResponse'
'400':
description: Bad Request
'500':
description: Internal Server Error
tags:
- Polymarket
/polymarket/order-book/{conditionId}:
get:
summary: Polymarket order book
description: 'Returns the live CLOB order book for each of a market''s outcome tokens: bids, asks, and last trade price per side. Returns 404 when the conditionID has no matching tokens.'
operationId: GetPolymarketOrderBook
parameters:
- name: conditionId
in: path
description: Required. Polymarket condition ID for the market.
required: true
schema:
type: string
description: Required. Polymarket condition ID for the market.
example: '0x9be56371f6a29d12769b2f196847ee825b9585ebb8bfa042136be031b081eba1'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PolymarketOrderBookResponse'
'400':
description: Bad Request
'500':
description: Internal Server Error
tags:
- Polymarket
/polymarket/pnl/chart:
get:
summary: Polymarket PnL chart
description: Returns a time series of cumulative PnL for a trade address — portfolio-wide, or for a single market when `conditionID` is set. Window follows the `period` preset or an explicit `startTime`/`endTime` range.
operationId: GetPolymarketPnLChart
parameters:
- name: userAddress
in: query
description: Polymarket trade address (0x + 40 hex chars).
required: true
schema:
type: string
description: Polymarket trade address (0x + 40 hex chars).
example: '0xBDDF61Af533fF524D27154e589d2D7A81510C684'
- name: conditionID
in: query
description: Optional. Market condition ID (0x-prefixed bytes32 hex). Aggregates across all outcome tokens. Omit for portfolio-level PnL.
schema:
type: string
description: Optional. Market condition ID (0x-prefixed bytes32 hex). Aggregates across all outcome tokens. Omit for portfolio-level PnL.
example: '0x9be56371f6a29d12769b2f196847ee825b9585ebb8bfa042136be031b081eba1'
- name: period
in: query
description: 'Time period: 24h, 7d, 30d, all. Presets auto-shrink to the wallet''s available history; all is portfolio-only. Default: 30d'
schema:
$ref: '#/components/schemas/PolymarketPnLPeriod'
- name: startTime
in: query
description: Optional Unix timestamp in seconds for start of range. Not supported with period=all. Condition-level custom ranges must be 30 days or less; all condition-level fixed windows must start within the last 30 days.
schema:
type: integer
description: Optional Unix timestamp in seconds for start of range. Not supported with period=all. Condition-level custom ranges must be 30 days or less; all condition-level fixed windows must start within the last 30 days.
nullable: true
example: 1717200000
- name: endTime
in: query
description: Optional Unix timestamp in seconds for end of range. For conditionID requests, preset windows derived from endTime must start within the last 30 days.
schema:
type: integer
description: Optional Unix timestamp in seconds for end of range. For conditionID requests, preset windows derived from endTime must start within the last 30 days.
nullable: true
example: 1719878400
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PolymarketPnLChartResponse'
'400':
description: Bad Request
'500':
description: Internal Server Error
tags:
- Polymarket
/polymarket/positions/{addr}:
get:
summary: Polymarket user positions
description: Returns a trade address's current open positions, one row per outcome token, with net position, net USDC flow, last price, and unrealized PnL. Sort by trades (default), shares, value, or pnl. Supports offset pagination.
operationId: GetPolymarketPositions
parameters:
- name: sortBy
in: query
description: 'Column to order by: trades (default), shares, value, pnl.'
schema:
$ref: '#/components/schemas/PolymarketPositionsSortBy'
- name: sortOrder
in: query
description: 'Sort direction: asc or desc (default).'
schema:
$ref: '#/components/schemas/SortDir'
- name: limit
in: query
description: Max results (default 50, max 1000).
schema:
type: integer
description: Max results (default 50, max 1000).
example: 50
- name: offset
in: query
description: Offset for pagination (default 0).
schema:
type: integer
description: Offset for pagination (default 0).
example: 0
- name: addr
in: path
description: Required. Polymarket trade address (0x + 40 hex chars).
required: true
schema:
type: string
description: Required. Polymarket trade address (0x + 40 hex chars).
example: '0xBDDF61Af533fF524D27154e589d2D7A81510C684'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PolymarketPositionsResponse'
'400':
description: Bad Request
'500':
description: Internal Server Error
tags:
- Polymarket
/polymarket/prices:
get:
summary: Polymarket price history
description: Returns a midprice time series for a single Polymarket outcome token, identified by either `tokenAddress` or `conditionID` (not both).
operationId: GetPolymarketPrices
parameters:
- name: tokenAddress
in: query
description: Polymarket token address (0x-prefixed hex). Provide exactly one of tokenAddress or conditionID.
schema:
type: string
description: Polymarket token address (0x-prefixed hex). Provide exactly one of tokenAddress or conditionID.
example: '0x7baa312d6393ea83c631fb77b47061651a2a9992c40fcac017009611d6a03df4'
- name: conditionID
in: query
description: Market condition ID (0x-prefixed bytes32 hex). Returns prices for the first outcome (outcome_index=0) token. Provide exactly one of tokenAddress or conditionID.
schema:
type: string
description: Market condition ID (0x-prefixed bytes32 hex). Returns prices for the first outcome (outcome_index=0) token. Provide exactly one of tokenAddress or conditionID.
example: '0x9be56371f6a29d12769b2f196847ee825b9585ebb8bfa042136be031b081eba1'
- name: interval
in: query
description: 'Price interval: 1s, 5s, 1m, 1h, 1d, auto. Default: 1h. 1s and 5s require startTime and endTime, with a maximum 2-hour span, and return a dense series carrying the last price forward across quiet periods.'
schema:
$ref: '#/components/schemas/PolymarketPriceInterval'
- name: range
in: query
description: 'Window selector anchored on the token''s last bucket: 1d, 1w, 1m, all. Server picks the granularity. Overrides startTime, endTime and interval except interval=1s or interval=5s, which cannot be combined with range.'
schema:
$ref: '#/components/schemas/PolymarketPriceRange'
- name: startTime
in: query
description: Optional Unix timestamp in seconds for start of range. Ignored when range is set.
schema:
type: integer
description: Optional Unix timestamp in seconds for start of range. Ignored when range is set.
nullable: true
example: 1717200000
- name: endTime
in: query
description: Optional Unix timestamp in seconds for end of range. Ignored when range is set.
schema:
type: integer
description: Optional Unix timestamp in seconds for end of range. Ignored when range is set.
nullable: true
example: 1719878400
- name: limit
in: query
description: 'Max number of price points to return (1-7500). Default: 500, or 7500 for interval=1s and interval=5s. When the requested window holds more points than limit, the newest points are returned.'
schema:
type: integer
description: 'Max number of price points to return (1-7500). Default: 500, or 7500 for interval=1s and interval=5s. When the requested window holds more points than limit, the newest points are returned.'
example: 500
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PolymarketPricesResponse'
'400':
description: Bad Request
'500':
description: Internal Server Error
tags:
- Polymarket
/polymarket/stats:
get:
summary: Polymarket platform stats
description: 'Returns global Polymarket platform statistics: total volume, 24h volume, total traders, active and resolved market counts, and total trades.'
operationId: GetPolymarketStats
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PolymarketStatsResponse'
'400':
description: Bad Request
'500':
description: Internal Server Error
tags:
- Polymarket
/polymarket/top-events:
get:
summary: Polymarket top events leaderboard
description: 'Returns the top (trader, event) entries by PnL for a period: 1d, 1w, 1m, or all (default 1d). Each entry sums a trader''s PnL across every market within a single Polymarket event. Order desc for top wins or asc for top losses.'
operationId: GetPolymarketTopEvents
parameters:
- name: period
in: query
description: 'Time period: 1d, 1w, 1m, all. Default: 1d'
schema:
$ref: '#/components/schemas/PolymarketLeaderboardPeriod'
- name: order
in: query
description: 'Sort order: desc (top wins) or asc (top losses). Default: desc'
schema:
$ref: '#/components/schemas/SortDir'
- name: limit
in: query
description: 'Max entries (1-200). Default: 100'
schema:
type: integer
description: 'Max entries (1-200). Default: 100'
example: 100
- name: offset
in: query
description: 'Pagination offset. Default: 0'
schema:
type: integer
description: 'Pagination offset. Default: 0'
example: 0
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PolymarketTopEventEntry'
example:
- eventId: 511447
eventTitle: Belgium vs. IR Iran - More Markets
iconUrl: https://polymarket-upload.s3.us-east-2.amazonaws.com/soccer ball-bba4025f77.png
imageUrl: https://polymarket-upload.s3.us-east-2.amazonaws.com/soccer ball-bba4025f77.png
periodPnl: '1242863.7688589205'
rank: 1
tradeCount: 3311
userAddress: '0x204f72f35326db932158CBA6AdfF0B9A1DA95e14'
'400':
description: Bad Request
'500':
description: Internal Server Error
tags:
- Polymarket
/polymarket/top-events/{eventId}/breakdown:
get:
summary: Polymarket top event breakdown
description: Returns the per-market PnL breakdown for a single trader within one event over a period (1d, 1w, 1m, all; default 1d). Each row is one market in the event with its PnL and trade count; markets with exactly zero PnL are omitted. The address query parameter is required.
operationId: GetPolymarketTopEventBreakdown
parameters:
- name: address
in: query
description: Polymarket trader address.
required: true
schema:
type: string
description: Polymarket trader address.
example: '0xBDDF61Af533fF524D27154e589d2D7A81510C684'
- name: period
in: query
description: 'Period: 1d, 1w, 1m, all. Default: 1d.'
schema:
$ref: '#/components/schemas/PolymarketLeaderboardPeriod'
- name: eventId
in: path
description: Polymarket event ID.
required: true
schema:
type: integer
description: Polymarket event ID.
example: 30615
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PolymarketTopEventBreakdownResponse'
'400':
description: Bad Request
'500':
description: Internal Server Error
tags:
- Polymarket
/polymarket/top-holders/{conditionId}:
get:
summary: Polymarket market top holders
description: Returns the largest position holders for a market, ranked by net position, each with their per-token positions and net USDC flow. Optionally narrow to a single outcome (0 for Yes, 1 for No). Returns 404 when the conditionID has no matching tokens.
operationId: GetPolymarketTopHolders
parameters:
- name: limit
in: query
description: 'Max entries to return (1-100). Default: 20.'
schema:
type: integer
description: 'Max entries to return (1-100). Default: 20.'
example: 100
- name: outcome
in: query
description: Optional. 0 for Yes token, 1 for No token. Omit for all tokens.
schema:
type: integer
description: Optional. 0 for Yes token, 1 for No token. Omit for all tokens.
nullable: true
example: 0
- name: conditionId
in: path
description: Required. Polymarket condition ID for the market.
required: true
schema:
type: string
description: Required. Polymarket condition ID for the market.
example: '0x9be56371f6a29d12769b2f196847ee825b9585ebb8bfa042136be031b081eba1'
responses:
'200':
description: OK
# --- truncated at 32 KB (124 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arkham/refs/heads/main/openapi/arkham-polymarket-api-openapi.yml