Skip to content

Instantly share code, notes, and snippets.

@shaunlebron

shaunlebron/polymarket-data-api-docs.md

Last active January 4, 2025 20:03
Show Gist options
  • Save shaunlebron/0dd3338f7dea06b8e9f8724981bb13bf to your computer and use it in GitHub Desktop.
Save shaunlebron/0dd3338f7dea06b8e9f8724981bb13bf to your computer and use it in GitHub Desktop.
Download ZIP
Polymarket Data API Docs
Raw
polymarket-data-api-docs.md

Polymarket Data API Docs

jon_amen | Polymarket — 12/18/24, 11:52 AM

Today, we are releasing some documentation for Polymarket Data-API:
https://polymarket.notion.site/Polymarket-Data-API-Docs-15fd316c50d58062bf8ee1b4bcf3d461

Power users and developers can use this API to:

  • List their positions
  • Track top holders of a market
  • Monitor trades
  • Monitor onchain activity, e.g Splits and Merges

We will add this to the official Polymarket docs soon.

Table of Contents

Base URL

https://data-api.polymarket.com/

Positions

GET /positions

Fetches current positions for a user(address)

  • Content-Type: "application/json"
  • Accept: "application/json"

Request:

/positions
  ?user=0x6af75d4e4aaf700450efbac3708cce1665810ff1
  &sizeThreshold=50

Query params:

  • user: The address of the user in question. Required.
  • market: The conditionId of the market in question. Supports multiple csv separated values
  • sizeThreshold: The minimum position size to be included in the response. Defaults to 1.0
  • redeemable: Boolean flag, returns only positions that can be redeemed. Optional.
  • mergeable: Boolean flag, returns only positions that can be merged. Optional.
  • title: Filter by market title. Optional
  • limit: The max number of positions to return, defaults to 100, max 500.
  • offset: The starting index for pagination, defaults to 0.
  • sortBy: The sort criteria. Defaults to TOKENS if not provided. Sort Criteria:
    • TOKENS: Sort by the size of the position in tokens. Aka To Win
    • CURRENT: Sort by the current value of the position. Aka current value
    • INITIAL: Sort by the initial value of the position.
    • CASHPNL: Sort by the cash pnl of the position.
    • PERCENTPNL: Sort by the percent pnl of the position.
    • TITLE: Sort by the title of the market.
    • RESOLVING: Sort by when the position's market is resolving.
    • PRICE: Sort by the current price of the position.
    • sortDirection: The sort direction. Must be ASC or DESC. Defaults to DESC if not provided.

Response:

[
  {
    "proxyWallet": "0x6af75d4e4aaf700450efbac3708cce1665810ff1",
    "asset": "65396714035221124737265515219989336303267439172398528294132309725835127126381",
    "conditionId": "0xd007d71fd17b0913b9d7ff198f617caa96a9e4aab1bed7d6f9abd76bb17dd507",
    "size": 90548.087076,
    "avgPrice": 0.020628,
    "initialValue": 1867.825940203728,
    "currentValue": 5840.351616402,
    "cashPnl": 3972.525676198273,
    "percentPnl": 212.6817917393834,
    "totalBought": 109548.077076,
    "realizedPnl": -894.398503,
    "percentRealizedPnl": 158.45030351384662,
    "curPrice": 0.0645,
    "redeemable": false,
    "title": "2024 presidential election: GOP wins by 155-214",
    "slug": "2024-presidential-election-gop-wins-by-155-214",
    "icon": "https://polymarket-upload.s3.us-east-2.amazonaws.com/goplogo1.png",
    "eventSlug": "electoral-college-margin-of-victory-in-the-2024-presidential-election",
    "outcome": "Yes",
    "outcomeIndex": 0,
    "oppositeOutcome": "No",
    "oppositeAsset": "52050340002752890901105180731616786223343503725333424175929498217562194356499",
    "endDate": "2024-11-05",
    "negativeRisk": true
  },
  {
    "proxyWallet": "0x6af75d4e4aaf700450efbac3708cce1665810ff1",
    "asset": "10057237541929696185971116542487795282113077727880089878027691009747516185940",
    "conditionId": "0x96f6fb6567b5938fc3c2e75f9829d7287340b9581a9c4817b8bc0aff82e1c45f",
    "size": 45666.487374,
    "avgPrice": 0.398204,
    "initialValue": 18184.577938276296,
    "currentValue": 22604.91125013,
    "cashPnl": 4420.333311853707,
    "percentPnl": 24.308143564605093,
    "totalBought": 45666.487374,
    "realizedPnl": 0,
    "percentRealizedPnl": 24.308143564605093,
    "curPrice": 0.495,
    "redeemable": false,
    "title": "2024 Balance of Power: R Prez R Senate R House",
    "slug": "2024-balance-of-power-r-prez-r-senate-r-house",
    "icon": "https://polymarket-upload.s3.us-east-2.amazonaws.com/balance-of-power-2024-election-r-Fp-y4ONJBS.jpg",
    "eventSlug": "balance-of-power-2024-election",
    "outcome": "Yes",
    "outcomeIndex": 0,
    "oppositeOutcome": "No",
    "oppositeAsset": "5221303279467844582975968922199141012019086576325749464715776376494178025469",
    "endDate": "2024-11-05",
    "negativeRisk": true
  }
]

Trades

GET /trades

Fetches trades. Ordered by timestamp in descending order(most recent trade first)

  • Content-Type: "application/json"
  • Accept: "application/json"

Request:

/trades
  ?user=0x6af75d4e4aaf700450efbac3708cce1665810ff1
  &filterType=CASH
  &filterAmount=100

Query params (All Optional)

  • limit: The max number of trades to return, defaults to 100, max 500.
  • offset: The starting index for pagination.
  • takerOnly: Flag that determines whether to return only taker orders. Defaults to true. Otherwise return maker and taker orders.
  • filterType: Flag indicating whether to filter trades by a parameter. Must be [CASH or TOKENS].
  • filterAmount: The amount to filter by. Related to filterType above.
  • market: The conditionId of the market in question. Supports multiple csv separated values
  • user: The address of the user in question.
  • side: The side of the trade. Must be BUY or SELL

Response:

[
  {
    "proxyWallet": "0x6af75d4e4aaf700450efbac3708cce1665810ff1",
    "side": "SELL",
    "asset": "28774665463932631392072718054733378944250725021214679767633993409918492440355",
    "conditionId": "0x1731c2d00c722fa4d53d1bddae549f14cf1870e2cf59dc040e7791046672cda5",
    "size": 160.26,
    "price": 0.89,
    "timestamp": 1724210494,
    "title": "2024 August hottest on record?",
    "slug": "2024-august-hottest-on-record",
    "icon": "https://polymarket-upload.s3.us-east-2.amazonaws.com/earth+on+fire.png",
    "eventSlug": "2024-august-hottest-on-record",
    "outcome": "Yes",
    "outcomeIndex": 0,
    "name": "gopfan",
    "pseudonym": "Mean-Record",
    "bio": "",
    "profileImage": "https://polymarket-upload.s3.us-east-2.amazonaws.com/rus_gopfan_1695145206069.jpeg",
    "profileImageOptimized": "",
    "transactionHash": "0x5620f25e2772f0ec2c5b2f2f814f6e20b52b4363286a9043b62632418729c7f9"
  },
  {
    "proxyWallet": "0x6af75d4e4aaf700450efbac3708cce1665810ff1",
    "side": "BUY",
    "asset": "28774665463932631392072718054733378944250725021214679767633993409918492440355",
    "conditionId": "0x1731c2d00c722fa4d53d1bddae549f14cf1870e2cf59dc040e7791046672cda5",
    "size": 196.23,
    "price": 0.9,
    "timestamp": 1724165399,
    "title": "2024 August hottest on record?",
    "slug": "2024-august-hottest-on-record",
    "icon": "https://polymarket-upload.s3.us-east-2.amazonaws.com/earth+on+fire.png",
    "eventSlug": "2024-august-hottest-on-record",
    "outcome": "Yes",
    "outcomeIndex": 0,
    "name": "gopfan",
    "pseudonym": "Mean-Record",
    "bio": "",
    "profileImage": "https://polymarket-upload.s3.us-east-2.amazonaws.com/rus_gopfan_1695145206069.jpeg",
    "profileImageOptimized": "",
    "transactionHash": "0xc98ead6ed4a8f9bb75e20babf150fcb137c3dcb9439358d18054bb519fe2448b"
  },
  ...
]

Activity

GET /activity

Fetches Polymarket onchain activity for a user. Ordered by timestamp in descending order(most recent event first)

  • Content-Type: "application/json"
  • Accept: "application/json"

Request:

/activity
  ?user=0x6af75d4e4aaf700450efbac3708cce1665810ff1
  &market=0x2c95c926e924f243aab41e96a90d22fcaf8cf273a678a07c49abb95fde489678

Query params:

  • user: The address of the user in question. Required.
  • limit: The max number of trades to return, defaults to 100, max 500.
  • offset: The starting index for pagination, defaults to 0.
  • market: The conditionId of the market in question. Supports multiple comma separated values
  • type: The type of activity to filter by. Optional. Supports multiple comma separated values. If given, must be TRADE, SPLIT, MERGE, REDEEM, REWARD or CONVERSION.
  • start: The start timestamp(in seconds) on which to filter by.
  • end: The end timestamp(in seconds) on which to filter by.
  • side: The side of the trade. Must be BUY or SELL. Only applies to Trades
  • sortBy: The sort criteria. If given, must be TIMESTAMP, TOKENS or CASH. Defaults to TIMESTAMP if not provided.
  • sortDirection: The sort direction. If given, must be ASC or DESC. Defaults to DESC if not provided.

Response:

[
  {
    "proxyWallet": "0x6af75d4e4aaf700450efbac3708cce1665810ff1",
    "timestamp": 1723772457,
    "conditionId": "0x2c95c926e924f243aab41e96a90d22fcaf8cf273a678a07c49abb95fde489678",
    "type": "TRADE",
    "size": 600,
    "usdcSize": 354,
    "transactionHash": "0x40b774108c44bf3182002f3a296c8e5642ba91f304d45243e60ade35a636b58d",
    "price": 0.59,
    "asset": "107836146654370381106713545566652432255048724122024565798298277212699312945505",
    "side": "BUY",
    "outcomeIndex": 1,
    "title": "August temperature increase greater than 1.29°C?",
    "slug": "august-temperature-increase-greater-than-1pt29c",
    "icon": "https://polymarket-upload.s3.us-east-2.amazonaws.com/earth+on+fire.png",
    "eventSlug": "august-2024-temperature-increase-c",
    "outcome": "No",
    "name": "gopfan",
    "pseudonym": "Mean-Record",
    "bio": "",
    "profileImage": "https://polymarket-upload.s3.us-east-2.amazonaws.com/rus_gopfan_1695145206069.jpeg",
    "profileImageOptimized": ""
  },
  {
    "proxyWallet": "0x6af75d4e4aaf700450efbac3708cce1665810ff1",
    "timestamp": 1723769203,
    "conditionId": "0x2c95c926e924f243aab41e96a90d22fcaf8cf273a678a07c49abb95fde489678",
    "type": "MERGE",
    "size": 316.48,
    "usdcSize": 316.48,
    "transactionHash": "0x10e1ae6f284c26d06aa3031381dba30a6db9ea9f62ea9523bbd3394f6569db5c",
    "price": 0,
    "asset": "",
    "side": "",
    "outcomeIndex": 999,
    "title": "August temperature increase greater than 1.29°C?",
    "slug": "august-temperature-increase-greater-than-1pt29c",
    "icon": "https://polymarket-upload.s3.us-east-2.amazonaws.com/earth+on+fire.png",
    "eventSlug": "august-2024-temperature-increase-c",
    "outcome": "",
    "name": "gopfan",
    "pseudonym": "Mean-Record",
    "bio": "",
    "profileImage": "https://polymarket-upload.s3.us-east-2.amazonaws.com/rus_gopfan_1695145206069.jpeg",
    "profileImageOptimized": ""
  }
]

Holders

GET /holders

Fetches the top holders of a market

  • Content-Type: "application/json"
  • Accept: "application/json"

Request:

/holders
  ?market=0x7883a3c40bb01cbd3b9ec9e3b73d75af705e300c9369f27178739cf3f4fa089a
  &limit=2

Query params:

  • market: The market(conditionId) to query. Required.
  • limit: The max number of holders to return, defaults to 100.

Response:

[
  {
    "token": "70018807773238020915361161897719073078804647330583488591369599275024873820020",
    "holders": [
      {
        "proxyWallet": "0xa59516996b5803e2b1ecb9df4db492c494743fde",
        "bio": "",
        "asset": "70018807773238020915361161897719073078804647330583488591369599275024873820020",
        "pseudonym": "Bossy-Figurine",
        "amount": 215678.947713,
        "displayUsernamePublic": true,
        "outcomeIndex": 0,
        "name": "Dumbguy88",
        "profileImage": "",
        "profileImageOptimized": ""
      },
      {
        "proxyWallet": "0x58053ef6d4b8a7f1816397110284799e725cc2b8",
        "bio": "",
        "asset": "70018807773238020915361161897719073078804647330583488591369599275024873820020",
        "pseudonym": "Grateful-Nylon",
        "amount": 28368.570362,
        "displayUsernamePublic": true,
        "outcomeIndex": 0,
        "name": "SadKek",
        "profileImage": "",
        "profileImageOptimized": ""
      }
    ]
  },
  {
    "token": "38040810336402647860524961857216751324740229233874430685472918943584669196682",
    "holders": [
      {
        "proxyWallet": "0xa5ef39c3d3e10d0b270233af41cac69796b12966",
        "bio": "",
        "asset": "38040810336402647860524961857216751324740229233874430685472918943584669196682",
        "pseudonym": "",
        "amount": 187979.613302,
        "displayUsernamePublic": false,
        "outcomeIndex": 1,
        "name": "",
        "profileImage": "",
        "profileImageOptimized": ""
      },
      {
        "proxyWallet": "0x53d2d3c78597a78402d4db455a680da7ef560c3f",
        "bio": "",
        "asset": "38040810336402647860524961857216751324740229233874430685472918943584669196682",
        "pseudonym": "Tricky-Pressure",
        "amount": 100000,
        "displayUsernamePublic": true,
        "outcomeIndex": 1,
        "name": "abeautifulmind",
        "profileImage": "",
        "profileImageOptimized": ""
      }
    ]
  }
]

Positions Value

GET /value

Fetches the total USD value of a user's positions

  • Content-Type: "application/json"
  • Accept: "application/json"

Request:

/value
  ?user=0x6af75d4e4aaf700450efbac3708cce1665810ff1

Query params:

  • user: The address of the user in question. Required.
  • market: The conditionId of the market in question. Supports multiple csv separated values. Optional

Response:

[
  {
    "user": "0x6af75d4e4aaf700450efbac3708cce1665810ff1",
    "value": 0.483401645205675
  }
]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment