api.md 20 KB
Polymarket - Api
Pages: 46
Get sports metadata information
URL: llms-txt#get-sports-metadata-information
Source: https://docs.polymarket.com/api-reference/sports/get-sports-metadata-information
api-reference/gamma-openapi.json get /sports Retrieves metadata for various sports including images, resolution sources, ordering preferences, tags, and series information. This endpoint provides comprehensive sport configuration data used throughout the platform.
Get user activity
URL: llms-txt#get-user-activity
Source: https://docs.polymarket.com/api-reference/core/get-user-activity
api-reference/data-api-openapi.yaml get /activity Returns on-chain activity for a user.
Get comments by comment id
URL: llms-txt#get-comments-by-comment-id
Source: https://docs.polymarket.com/api-reference/comments/get-comments-by-comment-id
api-reference/gamma-openapi.json get /comments/{id}
Get open interest
URL: llms-txt#get-open-interest
Source: https://docs.polymarket.com/api-reference/misc/get-open-interest
api-reference/data-api-openapi.yaml get /oi
Get total value of a user's positions
URL: llms-txt#get-total-value-of-a-user's-positions
Source: https://docs.polymarket.com/api-reference/core/get-total-value-of-a-users-positions
api-reference/data-api-openapi.yaml get /value
Get related tags (relationships) by tag id
URL: llms-txt#get-related-tags-(relationships)-by-tag-id
Source: https://docs.polymarket.com/api-reference/tags/get-related-tags-relationships-by-tag-id
api-reference/gamma-openapi.json get /tags/{id}/related-tags
List events
URL: llms-txt#list-events
Source: https://docs.polymarket.com/api-reference/events/list-events
api-reference/gamma-openapi.json get /events
Get tag by id
URL: llms-txt#get-tag-by-id
Source: https://docs.polymarket.com/api-reference/tags/get-tag-by-id
api-reference/gamma-openapi.json get /tags/{id}
Get market by id
URL: llms-txt#get-market-by-id
Source: https://docs.polymarket.com/api-reference/markets/get-market-by-id
api-reference/gamma-openapi.json get /markets/{id}
WSS Authentication
URL: llms-txt#wss-authentication
Source: https://docs.polymarket.com/developers/CLOB/websocket/wss-auth
Only connections to user channel require authentication.
| Field | Optional | Description |
|---|---|---|
| apikey | yes | Polygon account's CLOB api key |
| secret | yes | Polygon account's CLOB api secret |
| passphrase | yes | Polygon account's CLOB api passphrase |
Get tags related to a tag slug
URL: llms-txt#get-tags-related-to-a-tag-slug
Source: https://docs.polymarket.com/api-reference/tags/get-tags-related-to-a-tag-slug
api-reference/gamma-openapi.json get /tags/slug/{slug}/related-tags/tags
Get related tags (relationships) by tag slug
URL: llms-txt#get-related-tags-(relationships)-by-tag-slug
Source: https://docs.polymarket.com/api-reference/tags/get-related-tags-relationships-by-tag-slug
api-reference/gamma-openapi.json get /tags/slug/{slug}/related-tags
Get total markets a user has traded
URL: llms-txt#get-total-markets-a-user-has-traded
Source: https://docs.polymarket.com/api-reference/misc/get-total-markets-a-user-has-traded
api-reference/data-api-openapi.yaml get /traded
Get market by slug
URL: llms-txt#get-market-by-slug
Source: https://docs.polymarket.com/api-reference/markets/get-market-by-slug
api-reference/gamma-openapi.json get /markets/slug/{slug}
List tags
URL: llms-txt#list-tags
Source: https://docs.polymarket.com/api-reference/tags/list-tags
api-reference/gamma-openapi.json get /tags
Get market price
URL: llms-txt#get-market-price
Source: https://docs.polymarket.com/api-reference/pricing/get-market-price
api-reference/clob-subset-openapi.yaml get /price Retrieves the market price for a specific token and side
Next page of markets with tag filtering
URL: llms-txt#next-page-of-markets-with-tag-filtering
Contents:
- Best Practices
- Related Endpoints
curl "https://gamma-api.polymarket.com/markets?tag_id=100381&closed=false&limit=25&offset=25"
1. **For Individual Markets:** Always use the slug method for best performance
2. **For Category Browsing:** Use tag filtering to reduce API calls
3. **For Complete Market Discovery:** Use the events endpoint with pagination
4. **Always Include `closed=false`:** Unless you specifically need historical data
5. **Implement Rate Limiting:** Respect API limits for production applications
* [Get Markets](/developers/gamma-markets-api/get-markets) - Full markets endpoint documentation
* [Get Events](/developers/gamma-markets-api/get-events) - Full events endpoint documentation
* [Search Markets](/developers/gamma-markets-api/get-public-search) - Search functionality
---
## API Key Operations
**URL:** llms-txt#api-key-operations
**Contents:**
- Create API Key
- Derive API Key
- Get API Keys
- Delete API Key
- Access Status
- Get Closed Only Mode Status
<Tip>This endpoint requires an **L1 Header**.</Tip>
Create new API key credentials for a user.
<Tip>This endpoint requires an **L1 Header**. </Tip>
Derive an existing API key for an address and nonce.
<Tip>This endpoint requires an **L2 Header**. </Tip>
Retrieve all API keys associated with a Polygon address.
<Tip>This endpoint requires an **L2 Header**.</Tip>
Delete an API key used to authenticate a request.
Check the value of `cert_required` by signer address.
## Get Closed Only Mode Status
<Tip>This endpoint requires an **L2 Header**.</Tip>
Retrieve the closed-only mode flag status.
**Examples:**
Example 1 (unknown):
unknown
Derive API Key
This endpoint requires an L1 Header.
Derive an existing API key for an address and nonce.
HTTP Request:
Example 2 (unknown):
unknown
Get API Keys
This endpoint requires an L2 Header.
Retrieve all API keys associated with a Polygon address.
HTTP Request:
Example 3 (unknown):
unknown
Delete API Key
This endpoint requires an L2 Header.
Delete an API key used to authenticate a request.
HTTP Request:
Example 4 (unknown):
unknown
Access Status
Check the value of cert_required by signer address.
HTTP Request:
---
## List comments
**URL:** llms-txt#list-comments
Source: https://docs.polymarket.com/api-reference/comments/list-comments
api-reference/gamma-openapi.json get /comments
---
## Get trades for a user or markets
**URL:** llms-txt#get-trades-for-a-user-or-markets
Source: https://docs.polymarket.com/api-reference/core/get-trades-for-a-user-or-markets
api-reference/data-api-openapi.yaml get /trades
---
## Get event tags
**URL:** llms-txt#get-event-tags
Source: https://docs.polymarket.com/api-reference/events/get-event-tags
api-reference/gamma-openapi.json get /events/{id}/tags
---
## Create and Place an Order
**URL:** llms-txt#create-and-place-an-order
**Contents:**
- Request Payload Parameters
- Order types
- Response Format
- Insert Error Messages
- Insert Statuses
<Tip> This endpoint requires a L2 Header </Tip>
Create and place an order using the Polymarket CLOB API clients. All orders are represented as "limit" orders, but "market" orders are also supported. To place a market order, simply ensure your price is marketable against current resting limit orders, which are executed on input at the best price.
`POST /<clob-endpoint>/order`
### Request Payload Parameters
| Name | Required | Type | Description |
| --------- | -------- | ------ | -------------------------------- |
| order | yes | Order | signed object |
| owner | yes | string | api key of order owner |
| orderType | yes | string | order type ("FOK", "GTC", "GTD") |
An `order` object is the form:
| Name | Required | Type | Description |
| ------------- | -------- | ------- | -------------------------------------------------- |
| salt | yes | integer | random salt used to create unique order |
| maker | yes | string | maker address (funder) |
| signer | yes | string | signing address |
| taker | yes | string | taker address (operator) |
| tokenId | yes | string | ERC1155 token ID of conditional token being traded |
| makerAmount | yes | string | maximum amount maker is willing to spend |
| takerAmount | yes | string | minimum amount taker will pay the maker in return |
| expiration | yes | string | unix expiration timestamp |
| nonce | yes | string | maker's exchange nonce of the order is associated |
| feeRateBps | yes | string | fee rate basis points as required by the operator |
| side | yes | string | buy or sell enum index |
| signatureType | yes | integer | signature type enum index |
| signature | yes | string | hex encoded signature |
* **FOK**: A Fill-Or-Kill order is an market order to buy (in dollars) or sell (in shares) shares that must be executed immediately in its entirety; otherwise, the entire order will be cancelled.
* **FAK**: A Fill-And-Kill order is a market order to buy (in dollars) or sell (in shares) that will be executed immediately for as many shares as are available; any portion not filled at once is cancelled.
* **GTC**: A Good-Til-Cancelled order is a limit order that is active until it is fulfilled or cancelled.
* **GTD**: A Good-Til-Date order is a type of order that is active until its specified date (UTC seconds timestamp), unless it has already been fulfilled or cancelled. There is a security threshold of one minute. If the order needs to expire in 90 seconds the correct expiration value is: now + 1 minute + 30 seconds
| Name | Type | Description |
| ----------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| success | boolean | boolean indicating if server-side err (`success = false`) -> server-side error |
| errorMsg | string | error message in case of unsuccessful placement (in case `success = false`, e.g. `client-side error`, the reason is in `errorMsg`) |
| orderId | string | id of order |
| orderHashes | string\[] | hash of settlement transaction order was marketable and triggered a match |
### Insert Error Messages
If the `errorMsg` field of the response object from placement is not an empty string, the order was not able to be immediately placed. This might be because of a delay or because of a failure. If the `success` is not `true`, then there was an issue placing the order. The following `errorMessages` are possible:
| Error | Success | Message | Description |
| ------------------------------------ | ------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| INVALID\_ORDER\_MIN\_TICK\_SIZE | yes | order is invalid. Price breaks minimum tick size rules | order price isn't accurate to correct tick sizing |
| INVALID\_ORDER\_MIN\_SIZE | yes | order is invalid. Size lower than the minimum | order size must meet min size threshold requirement |
| INVALID\_ORDER\_DUPLICATED | yes | order is invalid. Duplicated. Same order has already been placed, can't be placed again | |
| INVALID\_ORDER\_NOT\_ENOUGH\_BALANCE | yes | not enough balance / allowance | funder address doesn't have sufficient balance or allowance for order |
| INVALID\_ORDER\_EXPIRATION | yes | invalid expiration | expiration field expresses a time before now |
| INVALID\_ORDER\_ERROR | yes | could not insert order | system error while inserting order |
| EXECUTION\_ERROR | yes | could not run the execution | system error while attempting to execute trade |
| ORDER\_DELAYED | no | order match delayed due to market conditions | order placement delayed |
| DELAYING\_ORDER\_ERROR | yes | error delaying the order | system error while delaying order |
| FOK\_ORDER\_NOT\_FILLED\_ERROR | yes | order couldn't be fully filled, FOK orders are fully filled/killed | FOK order not fully filled so can't be placed |
| MARKET\_NOT\_READY | no | the market is not yet ready to process new orders | system not accepting orders for market yet |
When placing an order, a status field is included. The status field provides additional information regarding the order's state as a result of the placement. Possible values include:
| Status | Description |
| --------- | ------------------------------------------------------------ |
| matched | order placed and matched with an existing resting order |
| live | order placed and resting on the book |
| delayed | order marketable, but subject to matching delay |
| unmatched | order marketable, but failure delaying, placement successful |
**Examples:**
Example 1 (unknown):
unknown
```
Get series by id
URL: llms-txt#get-series-by-id
Source: https://docs.polymarket.com/api-reference/series/get-series-by-id
api-reference/gamma-openapi.json get /series/{id}
List markets
URL: llms-txt#list-markets
Source: https://docs.polymarket.com/api-reference/markets/list-markets
api-reference/gamma-openapi.json get /markets
Get bid-ask spreads
URL: llms-txt#get-bid-ask-spreads
Source: https://docs.polymarket.com/api-reference/spreads/get-bid-ask-spreads
api-reference/clob-subset-openapi.yaml post /spreads Retrieves bid-ask spreads for multiple tokens
List series
URL: llms-txt#list-series
Source: https://docs.polymarket.com/api-reference/series/list-series
api-reference/gamma-openapi.json get /series
Search markets, events, and profiles
URL: llms-txt#search-markets,-events,-and-profiles
Source: https://docs.polymarket.com/api-reference/search/search-markets-events-and-profiles
api-reference/gamma-openapi.json get /public-search
Get multiple order books summaries by request
URL: llms-txt#get-multiple-order-books-summaries-by-request
Source: https://docs.polymarket.com/api-reference/orderbook/get-multiple-order-books-summaries-by-request
api-reference/clob-subset-openapi.yaml post /books Retrieves order book summaries for specified tokens via POST request
Get multiple market prices
URL: llms-txt#get-multiple-market-prices
Source: https://docs.polymarket.com/api-reference/pricing/get-multiple-market-prices
api-reference/clob-subset-openapi.yaml get /prices Retrieves market prices for multiple tokens and sides
Get midpoint price
URL: llms-txt#get-midpoint-price
Source: https://docs.polymarket.com/api-reference/pricing/get-midpoint-price
api-reference/clob-subset-openapi.yaml get /midpoint Retrieves the midpoint price for a specific token
List teams
URL: llms-txt#list-teams
Source: https://docs.polymarket.com/api-reference/sports/list-teams
api-reference/gamma-openapi.json get /teams
Get current positions for a user
URL: llms-txt#get-current-positions-for-a-user
Source: https://docs.polymarket.com/api-reference/core/get-current-positions-for-a-user
api-reference/data-api-openapi.yaml get /positions Returns positions filtered by user and optional filters.
Health check
URL: llms-txt#health-check
Source: https://docs.polymarket.com/api-reference/health/health-check
api-reference/data-api-openapi.yaml get /
Get tags related to a tag id
URL: llms-txt#get-tags-related-to-a-tag-id
Source: https://docs.polymarket.com/api-reference/tags/get-tags-related-to-a-tag-id
api-reference/gamma-openapi.json get /tags/{id}/related-tags/tags
Get multiple market prices by request
URL: llms-txt#get-multiple-market-prices-by-request
Source: https://docs.polymarket.com/api-reference/pricing/get-multiple-market-prices-by-request
api-reference/clob-subset-openapi.yaml post /prices Retrieves market prices for specified tokens and sides via POST request
Get market tags by id
URL: llms-txt#get-market-tags-by-id
Source: https://docs.polymarket.com/api-reference/markets/get-market-tags-by-id
api-reference/gamma-openapi.json get /markets/{id}/tags
Get closed positions for a user
URL: llms-txt#get-closed-positions-for-a-user
Source: https://docs.polymarket.com/api-reference/core/get-closed-positions-for-a-user
api-reference/data-api-openapi.yaml get /closed-positions Fetches closed positions for a user(address)
Get event by slug
URL: llms-txt#get-event-by-slug
Source: https://docs.polymarket.com/api-reference/events/get-event-by-slug
api-reference/gamma-openapi.json get /events/slug/{slug}
Get live volume for an event
URL: llms-txt#get-live-volume-for-an-event
Source: https://docs.polymarket.com/api-reference/misc/get-live-volume-for-an-event
api-reference/data-api-openapi.yaml get /live-volume
Get tag by slug
URL: llms-txt#get-tag-by-slug
Source: https://docs.polymarket.com/api-reference/tags/get-tag-by-slug
api-reference/gamma-openapi.json get /tags/slug/{slug}
Get comments by user address
URL: llms-txt#get-comments-by-user-address
Source: https://docs.polymarket.com/api-reference/comments/get-comments-by-user-address
api-reference/gamma-openapi.json get /comments/user_address/{user_address}
Get order book summary
URL: llms-txt#get-order-book-summary
Source: https://docs.polymarket.com/api-reference/orderbook/get-order-book-summary
api-reference/clob-subset-openapi.yaml get /book Retrieves the order book summary for a specific token
Endpoint
URL: llms-txt#endpoint
https://gamma-api.polymarket.com
Get top holders for markets
URL: llms-txt#get-top-holders-for-markets
Source: https://docs.polymarket.com/api-reference/core/get-top-holders-for-markets
api-reference/data-api-openapi.yaml get /holders
Get event by id
URL: llms-txt#get-event-by-id
Source: https://docs.polymarket.com/api-reference/events/get-event-by-id
api-reference/gamma-openapi.json get /events/{id}
Get price history for a traded token
URL: llms-txt#get-price-history-for-a-traded-token
Source: https://docs.polymarket.com/api-reference/pricing/get-price-history-for-a-traded-token
api-reference/clob-subset-openapi.yaml get /prices-history Fetches historical price data for a specified market token