# Social Fetch API - Polymarket endpoints
# Base URL: https://api.socialfetch.dev
# Auth: x-api-key header (sfk_...)
# Full catalog: https://www.socialfetch.dev/llms-endpoints.txt | JSON: https://www.socialfetch.dev/llms.json
# Docs hub: https://www.socialfetch.dev/docs/api | OpenAPI: https://www.socialfetch.dev/openapi.json

42 documented Polymarket operations. Do not invent paths - only the routes below (and their linked markdown pages) are supported.

## GET /v1/polymarket/events
List Polymarket events
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/events/get.mdx
SDK: client.polymarket.listEvents({ status: "open", limit: 5 })
Parameters:
- status (optional, string, enum: open | closed | all) - Which items to list: `open` (default), `closed` (ended or resolved) or `all`. `open` is Polymarket's own flag and can outlast the end date.
- tag (optional, string) - Only events with this tag: a tag id or slug.
- query (optional, string) - Words to find in event titles. Titles are English, so search in English.
- sort (optional, string, enum: volume | volume24h | liquidity | startDate | endDate | createdAt | closedTime) - Sort field. Default: `volume`.
- ascending (optional, boolean) - Sort from smallest to largest. Default: false (largest first).
- featured (optional, boolean) - Only events Polymarket features (true) or only those it does not (false).
- seriesId (optional, string) - Only events in this series.
- minVolume (optional, number) - Only events with at least this much volume (US dollars).
- maxVolume (optional, number) - Only events with at most this much volume (US dollars).
- minLiquidity (optional, number) - Only events with at least this much liquidity.
- startDateFrom (optional, string) - Only events starting on or after this date.
- startDateTo (optional, string) - Only events starting on or before this date.
- endDateFrom (optional, string) - Only events ending on or after this date.
- endDateTo (optional, string) - Only events ending on or before this date.
- locale (optional, string, enum: es | fr | de | ja | zh | ko | ru | hi | th | tr | vi | pt | it | pl | id | bn | uk | zh-hant | tl) - Translate titles and market questions into this language. Descriptions stay in English.
- limit (optional, integer) - Events per page, 1–25. Default: 20. Each event carries all of its markets and the busiest hold hundreds, so a page stays small. Use `cursor` for the next page.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/events?status=open&limit=5" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/events/{eventIdOrSlug}
Get Polymarket event
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/events/eventidorslug/get.mdx
SDK: client.polymarket.getEvent({ eventIdOrSlug: "democratic-presidential-nominee-2028" })
Parameters:
- eventIdOrSlug (required, string) - Event id (digits) or slug, as in polymarket.com/event/{slug}.
- locale (optional, string, enum: es | fr | de | ja | zh | ko | ru | hi | th | tr | vi | pt | it | pl | id | bn | uk | zh-hant | tl) - Translate titles and market questions into this language. Descriptions stay in English.
- include (optional, array) - Extras to add, comma separated: `insights` (the written market context) and `annotations` (dated explanations of price moves). Each is one extra lookup and can be absent, in which case it is null.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/events/democratic-presidential-nominee-2028" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/events/{eventIdOrSlug}/insights
Get Polymarket event insights
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/events/eventidorslug/insights/get.mdx
SDK: client.polymarket.getEventInsights({ eventIdOrSlug: "democratic-presidential-nominee-2028" })
Parameters:
- eventIdOrSlug (required, string) - Event id (digits) or slug, as in polymarket.com/event/{slug}.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/events/democratic-presidential-nominee-2028/insights" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/events/{eventIdOrSlug}/annotations
List Polymarket event annotations
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/events/eventidorslug/annotations/get.mdx
SDK: client.polymarket.listEventAnnotations({ eventIdOrSlug: "democratic-presidential-nominee-2028" })
Parameters:
- eventIdOrSlug (required, string) - Event id (digits) or slug, as in polymarket.com/event/{slug}.
- outcome (optional, string) - Only annotations about this outcome, matched on its name without regard to case.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/events/democratic-presidential-nominee-2028/annotations" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/events/{eventId}/comments
List Polymarket event comments
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/events/eventid/comments/get.mdx
SDK: client.polymarket.listEventComments({ eventId: "30829", limit: 20 })
Parameters:
- eventId (required, string) - Event id (digits). Slugs are not accepted here.
- sort (optional, string, enum: newest | oldest) - Order of top-level comments by time. Default: `newest`. Polymarket can sort by likes only on a route that stops after 250 rows, so it is not offered here.
- holdersOnly (optional, boolean) - `true` keeps comments by people who hold a position.
- limit (optional, integer) - Top-level comments per page, 1–100. Default: 40. Replies come with their parent and do not count towards the limit.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/events/30829/comments?limit=20" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/markets
List Polymarket markets
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/markets/get.mdx
SDK: client.polymarket.listMarkets({ status: "open", limit: 10 })
Parameters:
- status (optional, string, enum: open | closed) - Which markets to list: `open` (default) or `closed`. When you filter by `conditionIds` or `tokenIds` and omit this, open and closed markets are both searched.
- tagId (optional, string) - Only markets with this tag id. Find ids with the tags list.
- sort (optional, string, enum: volume | volume24h | liquidity | startDate | endDate | createdAt | closedTime) - Sort field. Default: `volume`.
- ascending (optional, boolean) - Sort from smallest to largest. Default: false (largest first).
- minVolume (optional, number) - Only markets with at least this much volume (US dollars).
- maxVolume (optional, number) - Only markets with at most this much volume (US dollars).
- minLiquidity (optional, number) - Only markets with at least this much liquidity.
- maxLiquidity (optional, number) - Only markets with at most this much liquidity.
- conditionIds (optional, array) - Only these markets, by condition id, up to 50. Repeat the parameter or separate ids with commas. For more ids use the batch endpoint.
- tokenIds (optional, array) - Only the markets these outcome tokens belong to, up to 30. Repeat the parameter or separate ids with commas. For more ids use the batch endpoint.
- sportsMarketType (optional, string) - Only sports markets of this kind, such as `moneyline`.
- locale (optional, string, enum: es | fr | de | ja | zh | ko | ru | hi | th | tr | vi | pt | it | pl | id | bn | uk | zh-hant | tl) - Translate titles and market questions into this language. Descriptions stay in English.
- limit (optional, integer) - Items per page, 1–100. Default: 50.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/markets?status=open&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/markets/batch
Get several Polymarket markets
Credit cost: 1 credit per market id. Up to 100 market ids per request. Max 100 credits. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/markets/batch/get.mdx
SDK: client.polymarket.getMarketsBatch({ conditionIds: ["0x0f49db97f71c68b1e42a6d16e3de93d85dbf7d4148e3f018eb79e88554be9f75"] })
Parameters:
- conditionIds (optional, array) - Condition ids to look up. Repeat the parameter or separate ids with commas.
- tokenIds (optional, array) - Outcome token ids to look up. Repeat the parameter or separate ids with commas.
- locale (optional, string, enum: es | fr | de | ja | zh | ko | ru | hi | th | tr | vi | pt | it | pl | id | bn | uk | zh-hant | tl) - Translate titles and market questions into this language. Descriptions stay in English.
curl "https://api.socialfetch.dev/v1/polymarket/markets/batch?conditionIds=0x0f49db97f71c68b1e42a6d16e3de93d85dbf7d4148e3f018eb79e88554be9f75" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/markets/{marketIdSlugOrConditionId}
Get Polymarket market
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/markets/marketidslugorconditionid/get.mdx
SDK: client.polymarket.getMarket({ marketIdSlugOrConditionId: "0x0f49db97f71c68b1e42a6d16e3de93d85dbf7d4148e3f018eb79e88554be9f75" })
Parameters:
- marketIdSlugOrConditionId (required, string) - Market id (digits), slug, or condition id (0x and 64 hex digits).
- locale (optional, string, enum: es | fr | de | ja | zh | ko | ru | hi | th | tr | vi | pt | it | pl | id | bn | uk | zh-hant | tl) - Translate titles and market questions into this language. Descriptions stay in English.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/markets/0x0f49db97f71c68b1e42a6d16e3de93d85dbf7d4148e3f018eb79e88554be9f75" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/markets/{conditionId}/resolution
Get Polymarket market resolution
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/markets/conditionid/resolution/get.mdx
SDK: client.polymarket.getMarketResolution({ conditionId: "0x0f49db97f71c68b1e42a6d16e3de93d85dbf7d4148e3f018eb79e88554be9f75" })
Parameters:
- conditionId (required, string) - Condition id of the market: 0x followed by 64 hex digits.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/markets/0x0f49db97f71c68b1e42a6d16e3de93d85dbf7d4148e3f018eb79e88554be9f75/resolution" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/markets/{conditionId}/stats
Get Polymarket market statistics
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/markets/conditionid/stats/get.mdx
SDK: client.polymarket.getMarketStats({ conditionId: "0x0f49db97f71c68b1e42a6d16e3de93d85dbf7d4148e3f018eb79e88554be9f75" })
Parameters:
- conditionId (required, string) - Condition id of the market: 0x followed by 64 hex digits.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/markets/0x0f49db97f71c68b1e42a6d16e3de93d85dbf7d4148e3f018eb79e88554be9f75/stats" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/markets/{conditionId}/holders
List Polymarket market holders
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/markets/conditionid/holders/get.mdx
SDK: client.polymarket.listMarketHolders({ conditionId: "0x0f49db97f71c68b1e42a6d16e3de93d85dbf7d4148e3f018eb79e88554be9f75", includePnl: true, limit: 5 })
Parameters:
- conditionId (required, string) - Condition id of the market: 0x followed by 64 hex digits.
- includePnl (optional, boolean) - Add each holder's entry price, cost, current value and profit. Default: false.
- minBalance (optional, number) - Only holders with at least this many shares.
- limit (optional, integer) - Items per page, 1–1000. Default: 20.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/markets/0x0f49db97f71c68b1e42a6d16e3de93d85dbf7d4148e3f018eb79e88554be9f75/holders?includePnl=true&limit=5" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/markets/{conditionId}/trades
List Polymarket market trades
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/markets/conditionid/trades/get.mdx
SDK: client.polymarket.listMarketTrades({ conditionId: "0x0f49db97f71c68b1e42a6d16e3de93d85dbf7d4148e3f018eb79e88554be9f75", limit: 10 })
Parameters:
- conditionId (required, string) - Condition id of the market: 0x followed by 64 hex digits.
- side (optional, string, enum: BUY | SELL) - Only trades on this side.
- minSize (optional, number) - Only trades of at least this many US dollars.
- from (optional, integer) - Only trades at or after this time, unix seconds.
- to (optional, integer) - Only trades at or before this time, unix seconds.
- limit (optional, integer) - Items per page, 1–1000. Default: 100.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/markets/0x0f49db97f71c68b1e42a6d16e3de93d85dbf7d4148e3f018eb79e88554be9f75/trades?limit=10" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/books
Get Polymarket order books
Credit cost: 1 credit per token id. Up to 150 token ids per request. Max 150 credits. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/books/get.mdx
SDK: client.polymarket.getBooks({ tokenIds: ["54533043819946592547517511176940999955633860128497669742211153063842200957669"], depth: 5 })
Parameters:
- tokenIds (required, array) - Outcome token ids, 1–150. Repeat the parameter or separate ids with commas. Token ids are the `tokenId` of a market outcome.
- depth (optional, integer) - Price levels returned per side, 1–200. Default: 20. Levels run from the best price outward.
curl "https://api.socialfetch.dev/v1/polymarket/books?tokenIds=54533043819946592547517511176940999955633860128497669742211153063842200957669" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/prices
Get Polymarket prices
Credit cost: 1 credit per token id. Up to 150 token ids per request. Max 150 credits. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/prices/get.mdx
SDK: client.polymarket.getPrices({ tokenIds: ["54533043819946592547517511176940999955633860128497669742211153063842200957669"] })
Parameters:
- tokenIds (required, array) - Outcome token ids, 1–150. Repeat the parameter or separate ids with commas. Token ids are the `tokenId` of a market outcome.
curl "https://api.socialfetch.dev/v1/polymarket/prices?tokenIds=54533043819946592547517511176940999955633860128497669742211153063842200957669" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/tokens/{tokenId}/price-history
List Polymarket price history
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/tokens/tokenid/price-history/get.mdx
SDK: client.polymarket.listPriceHistory({ tokenId: "54533043819946592547517511176940999955633860128497669742211153063842200957669", interval: "1w" })
Parameters:
- tokenId (required, string) - Outcome token id: a market outcome's `tokenId`.
- interval (optional, string, enum: 1h | 6h | 1d | 1w | 1m | max | all) - How far back to go: `1h`, `6h`, `1d`, `1w`, `1m` (one month), `max` or `all`. Default: `1w`. Ignored when `from` is given.
- from (optional, integer) - Start of the range, unix seconds.
- to (optional, integer) - End of the range, unix seconds. Default: now.
- bucketSeconds (optional, integer) - Seconds per point, 60–86400. Default: chosen from the range.
- limit (optional, integer) - Items per page, 1–1000. Default: 500.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/tokens/54533043819946592547517511176940999955633860128497669742211153063842200957669/price-history?interval=1w" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/trades
List Polymarket trades
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/trades/get.mdx
SDK: client.polymarket.listTrades({ limit: 10 })
Parameters:
- wallet (optional, string) - Only this wallet's trades. Without it the list is the live tape across all markets.
- eventId (optional, string) - Only trades in this event.
- side (optional, string, enum: BUY | SELL) - Only trades on this side.
- minSize (optional, number) - Only trades of at least this many US dollars.
- from (optional, integer) - Only trades at or after this time, unix seconds.
- to (optional, integer) - Only trades at or before this time, unix seconds.
- limit (optional, integer) - Items per page, 1–1000. Default: 100.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/trades?limit=10" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/tags
List Polymarket tags
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/tags/get.mdx
SDK: client.polymarket.listTags({ limit: 10 })
Parameters:
- limit (optional, integer) - Items per page, 1–100. Default: 100.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/tags?limit=10" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/tags/{idOrSlug}
Get Polymarket tag
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/tags/idorslug/get.mdx
SDK: client.polymarket.getTag({ idOrSlug: "sports", include: "related" })
Parameters:
- idOrSlug (required, string) - Tag id (digits) or slug, for example `politics`.
- include (optional, string, enum: related) - `related` adds the tags most often used together with this one (one more lookup).
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/tags/sports?include=related" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/series
List Polymarket series
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/series/get.mdx
SDK: client.polymarket.listSeries({ limit: 10 })
Parameters:
- recurrence (optional, string, enum: daily | weekly | monthly | annual | hourly | quarterly) - Only series that add an event on this schedule.
- closed (optional, boolean) - Only series that have ended (true) or are still running (false).
- limit (optional, integer) - Items per page, 1–50. Default: 50.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/series?limit=10" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/series/{idOrSlug}
Get Polymarket series
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/series/idorslug/get.mdx
SDK: client.polymarket.getSeries({ idOrSlug: "nfl", includeEvents: true })
Parameters:
- idOrSlug (required, string) - Series id (digits) or slug.
- includeEvents (optional, boolean) - Add the series' most recent events with their markets' headline numbers (one more lookup). Default: false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/series/nfl?includeEvents=true" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/sports
List Polymarket sports
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/sports/get.mdx
SDK: client.polymarket.listSports({ sport: "nfl" })
Parameters:
- sport (optional, string) - Only this league, by code such as `nfl` or `epl`.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/sports?sport=nfl" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/teams
List Polymarket teams
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/teams/get.mdx
SDK: client.polymarket.listTeams({ league: "nfl" })
Parameters:
- league (optional, string) - Only teams in this league, by code such as `nfl`.
- name (optional, string) - Only teams with this name.
- limit (optional, integer) - Items per page, 1–100. Default: 100.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/teams?league=nfl" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/search
Search Polymarket
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/search/get.mdx
SDK: client.polymarket.search({ query: "election", types: ["events", "tags"] })
Parameters:
- query (required, string) - Search text. The index is English: other scripts return nothing.
- types (optional, array) - What to search, comma separated: `events`, `tags`, `profiles`. Default: `events,tags`.
- page (optional, integer) - Page number, 1–100. Default: 1. Polymarket can stop a deep page early and report `hasMore: false`.
- limitPerType (optional, integer) - Items per page, 1–50. Default: 10.
- locale (optional, string, enum: es | fr | de | ja | zh | ko | ru | hi | th | tr | vi | pt | it | pl | id | bn | uk | zh-hant | tl) - Translate titles and market questions into this language. Descriptions stay in English.
Pagination: send query `page` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/search?query=election" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/movers
List Polymarket biggest movers
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/movers/get.mdx
SDK: client.polymarket.listMovers({ category: "politics" })
Parameters:
- category (optional, string, enum: politics | sports | crypto | finance | tech | culture | world) - Only markets in this category: `politics`, `sports`, `crypto`, `finance`, `tech`, `culture` or `world`. Any other value is rejected. Default: all.
- locale (optional, string, enum: es | fr | de | ja | zh | ko | ru | hi | th | tr | vi | pt | it | pl | id | bn | uk | zh-hant | tl) - Translate titles and market questions into this language. Descriptions stay in English.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/movers?category=politics" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/users/{walletOrUsername}
Get Polymarket user
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/users/walletorusername/get.mdx
SDK: client.polymarket.getUser({ walletOrUsername: "0x56687bf447db6ffa42ffe2204a05edaa20f55839" })
Parameters:
- walletOrUsername (required, string) - Wallet address (0x and 40 hex digits) or username. A username costs one more lookup to find the wallet.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/users/0x56687bf447db6ffa42ffe2204a05edaa20f55839" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/users
Search Polymarket users
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/users/get.mdx
SDK: client.polymarket.searchUsers({ query: "election", limit: 5 })
Parameters:
- query (required, string) - A username or part of one.
- limit (optional, integer) - Items per page, 1–50. Default: 10.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/users?query=election" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/users/{wallet}/positions
List Polymarket user positions
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/users/wallet/positions/get.mdx
SDK: client.polymarket.listUserPositions({ wallet: "0x93abbc022ce98d6f45d4444b594791cc4b7a9723", status: "open", limit: 10 })
Parameters:
- wallet (required, string) - Wallet address: 0x followed by 40 hex digits.
- status (optional, string, enum: open | closed | redeemable | mergeable) - Which positions to list. Default: `open`.
- sort (optional, string, enum: currentValue | totalPnl | realizedPnl | unrealizedPnl | tokens | price) - Sort field, largest first. Default: `currentValue`.
- eventId (optional, string) - Only positions in this event.
- limit (optional, integer) - Items per page, 1–1000. Default: 50.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/users/0x93abbc022ce98d6f45d4444b594791cc4b7a9723/positions?status=open&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/users/{wallet}/activity
List Polymarket user activity
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/users/wallet/activity/get.mdx
SDK: client.polymarket.listUserActivity({ wallet: "0x56687bf447db6ffa42ffe2204a05edaa20f55839", type: "TRADE", limit: 10 })
Parameters:
- wallet (required, string) - Wallet address: 0x followed by 40 hex digits.
- type (optional, string, enum: TRADE | SPLIT | MERGE | REDEEM | REWARD | CONVERSION | YIELD | MAKER_REBATE) - Only this kind of activity.
- conditionId (optional, string) - Only activity in this market.
- from (optional, integer) - Only activity at or after this time, unix seconds.
- to (optional, integer) - Only activity at or before this time, unix seconds.
- limit (optional, integer) - Items per page, 1–1000. Default: 100.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/users/0x56687bf447db6ffa42ffe2204a05edaa20f55839/activity?type=TRADE&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/users/{wallet}/stats
Get Polymarket user statistics
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/users/wallet/stats/get.mdx
SDK: client.polymarket.getUserStats({ wallet: "0x56687bf447db6ffa42ffe2204a05edaa20f55839" })
Parameters:
- wallet (required, string) - Wallet address: 0x followed by 40 hex digits.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/users/0x56687bf447db6ffa42ffe2204a05edaa20f55839/stats" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/users/{wallet}/pnl
List Polymarket user profit over time
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/users/wallet/pnl/get.mdx
SDK: client.polymarket.listUserPnl({ wallet: "0x56687bf447db6ffa42ffe2204a05edaa20f55839", interval: "1m", fidelity: "1d" })
Parameters:
- wallet (required, string) - Wallet address: 0x followed by 40 hex digits.
- interval (optional, string, enum: 6h | 12h | 1d | 1w | 1m | all | max) - How far back to go. Default: `1m`.
- fidelity (optional, string, enum: 1h | 3h | 12h | 18h | 1d) - Spacing of the points. Default: `1d`.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/users/0x56687bf447db6ffa42ffe2204a05edaa20f55839/pnl?interval=1m&fidelity=1d" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/leaderboard
List Polymarket leaderboard
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/leaderboard/get.mdx
SDK: client.polymarket.listLeaderboard({ window: "week", limit: 10 })
Parameters:
- window (optional, string, enum: day | week | month | all) - Time window. Default: `all`.
- category (optional, string) - Only this category, for example `sports`, `crypto` or `politics`. An unknown category returns an empty list.
- sortBy (optional, string, enum: pnl | volume) - Rank by profit (`pnl`, default) or traded volume (`volume`).
- wallet (optional, string) - Return this wallet's rank instead of the board: one row with `rankPnl` and `rankVolume`. A wallet that is not on the board for this window and category returns an empty list.
- limit (optional, integer) - Items per page, 1–1000. Default: 100.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/leaderboard?window=week&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/biggest-wins
List Polymarket biggest wins
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/biggest-wins/get.mdx
SDK: client.polymarket.listBiggestWins({ window: "month", limit: 10 })
Parameters:
- window (optional, string, enum: day | week | month | all) - Time window. Default: `all`.
- category (optional, string) - Only this category, for example `sports`, `crypto` or `politics`. An unknown category returns an empty list.
- limit (optional, integer) - Items per page, 1–500. Default: 100.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/biggest-wins?window=month&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/perps/instruments
List Polymarket perps instruments
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/perps/instruments/get.mdx
SDK: client.polymarket.listPerpsInstruments({ category: "index" })
Parameters:
- category (optional, string, enum: index | commodity | crypto | equity | pre_ipo) - Only instruments of this kind.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/perps/instruments?category=index" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/perps/tickers
List Polymarket perps tickers
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/perps/tickers/get.mdx
SDK: client.polymarket.listPerpsTickers({ instrumentId: "1" })
Parameters:
- instrumentId (optional, string) - Only this instrument. Default: all.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/perps/tickers?instrumentId=1" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/perps/instruments/{instrumentId}/klines
List Polymarket perps candles
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/perps/instruments/instrumentid/klines/get.mdx
SDK: client.polymarket.listPerpsKlines({ instrumentId: "1", interval: "1h" })
Parameters:
- instrumentId (required, string) - Perps instrument id from the instruments list.
- interval (optional, string, enum: 1m | 5m | 15m | 30m | 1h | 4h | 6h | 12h | 1d | 1w) - Candle length. Default: `1h`.
- from (optional, integer) - Start of the range, unix seconds. Default: 48 hours before `to`.
- to (optional, integer) - End of the range, unix seconds. Default: now.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/perps/instruments/1/klines?interval=1h" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/perps/instruments/{instrumentId}/book
Get Polymarket perps order book
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/perps/instruments/instrumentid/book/get.mdx
SDK: client.polymarket.getPerpsBook({ instrumentId: "1", depth: 10 })
Parameters:
- instrumentId (required, string) - Perps instrument id from the instruments list.
- depth (optional, string, enum: 10 | 100 | 500 | 1000) - Price levels per side: 10, 100, 500 or 1000. Default: 10.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/perps/instruments/1/book?depth=10" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/perps/instruments/{instrumentId}/trades
List Polymarket perps trades
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/perps/instruments/instrumentid/trades/get.mdx
SDK: client.polymarket.listPerpsTrades({ instrumentId: "1" })
Parameters:
- instrumentId (required, string) - Perps instrument id from the instruments list.
- from (optional, integer) - Start of the range, unix seconds. Default: 24 hours before `to`.
- to (optional, integer) - End of the range, unix seconds. Default: now.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/perps/instruments/1/trades" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/perps/leaderboard
List Polymarket perps leaderboard
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/perps/leaderboard/get.mdx
SDK: client.polymarket.listPerpsLeaderboard({ window: "week", limit: 10 })
Parameters:
- window (optional, string, enum: day | week | month | all) - Time window. Default: `all`.
- limit (optional, integer) - Items per page, 1–100. Default: 100.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/perps/leaderboard?window=week&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/us/events
List Polymarket US events
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/us/events/get.mdx
SDK: client.polymarket.listUsEvents({ status: "open", limit: 5 })
Parameters:
- status (optional, string, enum: open | closed) - Which events to list: `open` (default) or `closed`.
- limit (optional, integer) - Events per page, 1–100. Default: 20. Each event carries all its markets; pages shift as events open or close, so de-duplicate by `id`.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/us/events?status=open&limit=5" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/us/events/{idOrSlug}
Get Polymarket US event
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/us/events/idorslug/get.mdx
SDK: client.polymarket.getUsEvent({ idOrSlug: "81089" })
Parameters:
- idOrSlug (required, string) - US exchange event id (digits) or slug.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/us/events/81089" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/us/markets/{idOrSlug}
Get Polymarket US market
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/us/markets/idorslug/get.mdx
SDK: client.polymarket.getUsMarket({ idOrSlug: "425746", include: ["book"] })
Parameters:
- idOrSlug (required, string) - US exchange market id (digits) or slug.
- include (optional, array) - `book` adds the order book (one more lookup).
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/us/markets/425746?include=book" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/polymarket/us/series
List Polymarket US series
Credit cost: 1 credit. Failed requests are free.
Auth: API key or x402 payment (no key needed for payment)
Docs: https://www.socialfetch.dev/docs/api/v1/polymarket/us/series/get.mdx
SDK: client.polymarket.listUsSeries({ limit: 10 })
Parameters:
- limit (optional, integer) - Items per page, 1–100. Default: 50.
- cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Keep the other filters the same.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/polymarket/us/series?limit=10" \
  -H "x-api-key: YOUR_API_KEY"