{"id":37063563,"url":"https://github.com/qualiaenjoyer/polymarket-apis","last_synced_at":"2026-01-14T07:15:21.926Z","repository":{"id":295248222,"uuid":"918420403","full_name":"qualiaenjoyer/polymarket-apis","owner":"qualiaenjoyer","description":"Unified Polymarket APIs with Pydantic data validation - Clob, Gamma, Data, Web3, Websockets, GraphQL clients.","archived":false,"fork":false,"pushed_at":"2026-01-10T21:15:06.000Z","size":156,"stargazers_count":96,"open_issues_count":4,"forks_count":19,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-01-11T06:31:13.176Z","etag":null,"topics":["polymarket"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qualiaenjoyer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-17T22:33:15.000Z","updated_at":"2026-01-11T04:52:59.000Z","dependencies_parsed_at":"2025-05-24T13:43:09.258Z","dependency_job_id":"1847bf75-fcfc-4318-b75c-f3b7c223c47d","html_url":"https://github.com/qualiaenjoyer/polymarket-apis","commit_stats":null,"previous_names":["qualiaenjoyer/polymarket-apis"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/qualiaenjoyer/polymarket-apis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualiaenjoyer%2Fpolymarket-apis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualiaenjoyer%2Fpolymarket-apis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualiaenjoyer%2Fpolymarket-apis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualiaenjoyer%2Fpolymarket-apis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qualiaenjoyer","download_url":"https://codeload.github.com/qualiaenjoyer/polymarket-apis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualiaenjoyer%2Fpolymarket-apis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28412751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T05:26:33.345Z","status":"ssl_error","status_checked_at":"2026-01-14T05:21:57.251Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["polymarket"],"created_at":"2026-01-14T07:15:21.455Z","updated_at":"2026-01-14T07:15:21.911Z","avatar_url":"https://github.com/qualiaenjoyer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# polymarket-apis [![PyPI version](https://img.shields.io/pypi/v/polymarket-apis.svg)](https://pypi.org/project/polymarket-apis/)\n\nUnified Polymarket APIs with Pydantic data validation - Clob, Gamma, Data, Web3, Websockets, GraphQL clients.\n\n## Polymarket Mental Models\n\n### Events, Markets and Outcomes\n\nThe Polymarket ecosystem is organized hierarchically:\n\n```mermaid\nflowchart LR\n    A([Event]) --- B([Market A])\n    A --- C([Market B])\n    A ~~~ Dot1@{ shape: sm-circ}\n    A ~~~ Dot2@{ shape: sm-circ}\n    A ~~~ Dot3@{ shape: sm-circ}\n    A -.- D([Market n])\n    B --- E([Outcome 1])\n    B --- F([Outcome 2])\n    C --- G([Outcome 1])\n    C --- H([Outcome 2])\n```\n\n- **Event** — represents a proposition or question such as “How many Fed rate cuts in 2025?”.  \n  - Identified by a human-readable **`slug`** (e.g. `how-many-fed-rate-cuts-in-2025`) and an **event `id`** (e.g. `16085`).\n\n- **Market** — represents a specific option for the related event (e.g. 1 rate cut in 2025). An Event has 1 or more corresponding Markets. (e.g. 9 options in this case - {0, 1, 2, ..., 7, 8 or more} rate cuts in 2025)\n  - Identified by a **`condition id`** (e.g. `0x8e9b6942b4dac3117dadfacac2edb390b6d62d59c14152774bb5fcd983fc134e` for 1 rate cut in 2025), a human-readable **`slug`** (e.g. `'will-1-fed-rate-cut-happen-in-2025'`) and a **market `id`** (e.g. `516724`).\n\n- **Outcome** — represents a binary option related to a market. (most commonly `Yes`/`No`, but can be e.g. `Paris Saint-Germain`/`Inter Milan` in the case of a match where draws are not possible)\n  - Identified by a **`token id`** (e.g. `15353185604353847122370324954202969073036867278400776447048296624042585335546` for the `Yes` outcome in the 1 rate cut in 2025 market)\n\n- The different APIs represent Events/Markets differently (e.g. Event, QueryEvent / ClobMarket, GammaMarket, RewardsMarket) but they all use to the same underlying identifiers.\n\n\n### Tokens\n- **Tokens** are the blockchain implementation of **Outcomes** - tradable digital assets on the Polygon blockchain that users buy, hold and sell on Polygon. \n- This helps ensure the logic of binary outcome prediction markets through smart contracts (e.g. collateralization, token prices going to $1.00 or $0.00 after resolution, splits/merges).\n\n### Splits and Merges\n- Holding 1 `Yes` share + 1 `No` share in a **Market** (e.g. `'will-1-fed-rate-cut-happen-in-2025'`) covers the entire universe of possibilities and guarantees a $1.00 payout regardless of outcome. This mathematical relationship enables Polymarket's core mechanisms: splitting (1 USDC → 1 `Yes` + 1 `No`) and merging (1 `Yes` + 1 `No` → 1 USDC) at any point before resolution.\n- Splits are the only way tokens are created. Either a user splits USDC into equal shares of the complementary tokens or Polymarket automatically splits USDC when it matches an `Yes` buy order at e.g. 30¢ with a `No` buy order at 70¢.\n\n### Unified Order Book\n- Polymarket uses traditional exchange mechanics - a Central Limit Order Book (CLOB), where users place buy and sell orders that get matched by price and time priority.\n- However, because the `Yes` and `No` outcomes form a complete probability universe, certain orders become mathematically equivalent - allowing the matching engine to find trades as exemplified above.\n- This unified structure means every **BUY** order for `Outcome 1` at price **X** is simultaneously visible as a **SELL** order for `Outcome 2` at price **(100¢ - X)**, creating deeper liquidity and tighter spreads than separate order books would allow.\n\n### Negative Risk and Conversions\n- If the **Markets** in and **Event** collectively cover a complete universe of possibilities (e.g. {0, 1, 2, ..., 7, 8 or more} rate cuts in 2025) and only one winner is possible, two collections of positions (made up of tokens and USDC) become mathematically equivalent and the **Event** is said to support negative risk.\n  - e.g. Hold 1 `No` token in the 0 rate cuts in 2025. This is equivalent to holding 1 `Yes` token in each of the other **Markets** {1, 2, ..., 7, 8 or more}.\n- An interesting consequence is that holding `No` tokens in more than one **Market** is equivalent to `Yes` tokens ***and*** some USDC.\n  - e.g. Hold 1 `No` token on each of {0, 1, 2, ..., 7, 8 or more} rate cuts in 2025. Because only one winner is possible, this guarantees that 8 out of the 9 **Markets** resolve to `No`. This is equivalent to a position of 8 USDC.\n  - e.g. Hold 1 `No` token on each of {0, 1} rate cuts in 2025. This is equivalent to 1 `Yes` token in {2, ..., 7, 8 or more} and 1 USDC.\n- Polymarket allows for the one way (for capital efficiency) conversion from `No` tokens to a collection of `Yes` tokens and USDC before resolution through a smart contract.\n\n## Clients overview\n- ### PolymarketClobClient - Order book related operations\n  - #### Order book\n    - get one or more order books, best price, spread, midpoint, last trade price by `token_id`(s)\n  - #### Orders\n    - create and post limit or market orders\n    - cancel one or more orders by `order_id`(s)\n    - get active orders\n  - #### Trades\n    - get trade history for a user with filtering by `condition_id`, `token_id`, `trade_id`, time window\n  - #### Rewards\n    - check if one or more orders are scoring for liquidity rewards by `order_id`(s)\n    - get daily earned rewards\n    - check if a **Market** offers rewards by `condition_id` - **get_market_rewards()**\n    - get all active markets that offer rewards sorted by different metrics and ordered, filtered by a query, show your favourites from the web app  - **get_reward_markets()** (*naming would do with some work*)\n  - #### Miscellaneous\n    - get USDC balance\n    - get token balance by `token_id`\n    - get recent price history by `token_id` in the last 1h, 6h, 1d, 1w, 1m\n    - get price history by `token_id` in start/end interval\n    - get all price history by `token_id` in 2 min increments\n    - get **ClobMarket** by `condition_id`\n    - get all **ClobMarkets**\n\n  ### PolymarketGammaClient - Market/Event related operations\n    - #### Market\n      - get **GammaMarket** by `market_id`\n      - get **GammaMarket** by `slug`\n      - get **GammaMarkets** with pagination (offset and limit), filter by `slug`s, `market_id`s, `token_id`s, `condition_id`s, `tag_id` or filtered by active, closed, archived, liquidity window, volume window, start date window, end date window and ordered\n      - get **Tags** for a **Market** by `market_id`\n    - #### Event\n      - get **Event** by `event_id`\n      - get **Event** by `slug`\n      - get **Events** with pagination, filter by `slug`s, `event_id`s, `tag_id` or filtered by active, closed, archived, liquidity window, volume window, start date window, end date window and ordered\n      - get all **Events** given some filtration\n      - search **Events**, **Tags**, **Profiles**, filter by text query, tags, active/resolved, recurrence, sort by volume/volume_24hr/liquidity/start_date/end_date/competitive\n      - grok event summary by **Event** `slug`\n      - grok election market explanation by candidate name and election title\n      - get **Tags** for an **Event** by `event_id`\n    - #### Tag\n      - get **Tags** with pagination, order by any **Tag** field\n      - get all **Tags**\n      - get **Tag** by `tag_id`\n      - get **Tag** relations by `tag_id` or `slug`\n      - get **Tags** related to a **Tag** by `tag_id` or `slug`\n    - #### Sport\n      - get **Teams** with pagination, filter by `league`, `name`, `abbreviation`\n      - get all **Teams** given some filtration\n      - get **Sports** with pagination, filter by `name`\n      - get **Sports** metadata\n    - #### Series\n      - get **Series** with pagination, filter by `slug`, closed status, order by any **Series** field\n      - get all **Series** given some filtration\n    - #### Comments\n      - get comments by `parent_entity_type` and `parent_entity_id` with pagination, order by any **Comment** field\n      - get comments by `comment_id` - gets all comments in a thread.\n      - get comments by user base address (not proxy address) with pagination, order by any **Comment** field\n\n  ### PolymarketDataClient - Portfolio related operations\n  - #### Positions\n    - get positions with pagination (offset and limit) by user address, filter by `condition_id`, position size, redeemability, mergeability, title\n  - #### Trades\n    - get trades with pagination, filter by `condition id`, user address, side, taker only or not, cash amount/token amount\n  - #### Activity\n    - get activity with pagination by user address, filter by type (trade, split, merge, redeem, reward, conversion), `condition_id`, time window, side, sort by timestamp/tokens/cash\n  - #### Holders\n    - get top holders by `condition_id`\n  - #### Value\n    - get positions value by user address and condition_ids\n      - `condition_ids` is ***None*** → total value of positions\n      - `condition_ids` is ***str*** → value of positions on a market\n      - `condition_ids` is ***list[str]*** → sum of values of positions on multiple markets\n  - #### Closed positions\n    - get closed positions, filter by condition_ids\n  - #### Miscellaneous\n    - get total number of markets traded by user address\n    - get open interest for a list of condition_ids\n    - get live volume for an event by `event_id`\n    - get pnl timeseries by user address for a period (1d, 1w, 1m, all) with frequency (1h, 3h, 12h, 1d)\n    - get overall pnl/volume by user address for a recent window (1d, 7d, 30d, all)\n    - get user rank on the profit/volume leaderboards by user address for a recent window (1d, 7d, 30d, all)\n    - get top users on the profit/volume leaderboards (at most 100) for a recent window (1d, 7d, 30d, all)\n\n  ### PolymarketWeb3Client - Blockchain operations (pays gas)\n  - #### Supported wallet types:\n    - EOA(signature_type=0)\n    - Email/Magic wallets (signature_type=1)\n    - Safe/Gnosis wallets (signature_type=2)\n  - #### Setup and deployment\n    - set approvals for all needed USDC and conditional token spenders (needed for full trading functionality)\n      - Safe/Gnosis wallet holders need to run deploy_safe before setting approvals\n  - #### Balance\n    - get POL balance by user address\n    - get USDC balance by user address\n    - get token balance by `token_id` and user address\n  - #### Transfers\n    - transfer USDC to another address - needs recipient address, amount\n    - transfer token to another address - needs `token_id`, recipient address, amount\n  - #### Token/USDC conversions\n    - split USDC into complementary tokens - needs `condition_id`, amount, neg_risk bool\n    - merge complementary tokens into USDC - needs `condition_id`, amount, neg_risk bool\n    - redeem token into USDC - needs `condition_id`, amounts array [`Yes` shares, `No` shares], neg_risk bool\n    - convert 1 or more `No` tokens in a *negative risk* **Event** into a collection of USDC and `Yes` tokens on the other **Markets** in the **Event**\n\n  ### PolymarketGaslessWeb3Client - Relayed blockchain operations (doesn't pay gas)\n  - #### Supported wallet types:\n    - Email/Magic wallets (signature_type=1)\n    - Safe/Gnosis wallets (signature_type=2)\n  - #### Available operations\n    - balance methods from PolymarketWeb3Client (read only)\n    - split / merge / convert / redeem (gasless)\n\n  ### PolymarketWebsocketsClient - Real time data subscriptions\n  - subscribe to **market socket** with `token_ids` list, receive different event types:\n    - order book summary\n    - price change\n    - tick size change\n    - last trade price\n  - subscribe to **user socket** with **ApiCreds**, receive different event types:\n    - order (status - live, canceled, matched)\n    - trade (status - matched, mined, confirmed, retrying, failed)\n  - subscribe to **live data socket** with any combination described [here](https://github.com/Polymarket/real-time-data-client?tab=readme-ov-file#subscribe) - ***newest endpoint*** - includes the other sockets, receive:\n    - all of the above event types\n    - market (created, resolved)\n    - comment/reaction (created, removed)\n    - trades/orders_matched (all, not just yours) - filter by **Event** `slug` or **Market** `slug`\n    - crypto price\n    - request/quote (created, edited, canceled, expired) - rqf not public yet\n\n  ### PolymarketGraphQLClient/AsyncPolymarketGraphQLClient - Goldsky hosted Subgraphs queries\n  - instantiate with an endpoint name from:\n    - activity_subgraph\n    - fpmm_subgraph\n    - open_interest_subgraph\n    - orderbook_subgraph\n    - pnl_subgraph\n    - positions_subgraph\n    - sports_oracle_subgraph\n    - wallet_subgraph\n  - ****query()**** takes in a GraphQL query string and returns the raw json\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqualiaenjoyer%2Fpolymarket-apis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqualiaenjoyer%2Fpolymarket-apis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqualiaenjoyer%2Fpolymarket-apis/lists"}