Discover Markets

Find the events and markets your integration needs, from a specific Polymarket link to a broader view of what is active. This data is public and does not require authentication.

Events

An event groups one or more markets under a shared question set. A single-market event asks one yes/no question; a multi-market event splits a broader question into individual outcomes, such as one market per candidate in an election.

Fetch an Event

Fetch an event when you already know its identifier.

TypeScript
Python
API

Call fetchEvent() on a PublicClient or SecureClient to fetch an event by ID.

const event = await client.fetchEvent({ id: "90177" });

// event: Event

You can also fetch an event by its Polymarket URL or slug:

const event = await client.fetchEvent({
  url: "https://polymarket.com/event/will-the-us-confirm-that-aliens-exist-before-2027",
});

const event = await client.fetchEvent({
  slug: "will-the-us-confirm-that-aliens-exist-before-2027",
});

Output: Event

type Market = {
  id: string;
  slug?: string | null;
  question?: string | null;
  conditionId: string | null;
  outcomes: {
    yes: { tokenId: string | null };
    no: { tokenId: string | null };
  };
};

type Event = {
  id: string;
  slug?: string | null;
  title?: string | null;
  markets: Market[];
};

{
  "id": "90177",
  "slug": "will-the-us-confirm-that-aliens-exist-before-2027",
  "title": "Will the US confirm that aliens exist by...?",
  "markets": [
    {
      "id": "703257",
      "slug": "will-the-us-confirm-that-aliens-exist-before-2027-789-924-249",
      "question": "Will the US confirm that aliens exist before 2027?",
      "conditionId": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
      "outcomes": {
        "yes": {
          "tokenId": "107505882767731489358349912513945399560393482969656700824895970500493757150417"
        },
        "no": {
          "tokenId": "7305630249804085635496399869905769372294302716159034447326228509068694952392"
        }
      }
    },
    "..."
  ]
}

Call get_event() on an AsyncPublicClient or AsyncSecureClient to fetch an event by ID. The synchronous PublicClient and SecureClient provide the same method.

event = await client.get_event(id="90177")

# event: Event

You can also fetch an event by its Polymarket URL or slug:

event = await client.get_event(
    url="https://polymarket.com/event/will-the-us-confirm-that-aliens-exist-before-2027",
)

event = await client.get_event(
    slug="will-the-us-confirm-that-aliens-exist-before-2027",
)

Output: Event

class MarketOutcome:
    token_id: str | None

class MarketOutcomes:
    yes: MarketOutcome
    no: MarketOutcome

class Market:
    id: str
    slug: str | None
    question: str | None
    condition_id: str | None
    outcomes: MarketOutcomes

class Event:
    id: str
    slug: str | None
    title: str | None
    markets: tuple[Market, ...]

{
  "id": "90177",
  "slug": "will-the-us-confirm-that-aliens-exist-before-2027",
  "title": "Will the US confirm that aliens exist by...?",
  "markets": [
    {
      "id": "703257",
      "slug": "will-the-us-confirm-that-aliens-exist-before-2027-789-924-249",
      "question": "Will the US confirm that aliens exist before 2027?",
      "condition_id": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
      "outcomes": {
        "yes": {
          "token_id": "107505882767731489358349912513945399560393482969656700824895970500493757150417"
        },
        "no": {
          "token_id": "7305630249804085635496399869905769372294302716159034447326228509068694952392"
        }
      }
    },
    "..."
  ]
}

Fetch an event by ID:

curl "https://gamma-api.polymarket.com/events/90177"

You can also fetch an event by slug:

curl "https://gamma-api.polymarket.com/events/slug/will-the-us-confirm-that-aliens-exist-before-2027"

Output: Event

type Market = {
  id: string;
  slug: string;
  question: string | null;
  conditionId: string | null;
  clobTokenIds: string | null;
};

type Event = {
  id: string;
  slug: string | null;
  title: string | null;
  markets: Market[];
};

{
  "id": "90177",
  "slug": "will-the-us-confirm-that-aliens-exist-before-2027",
  "title": "Will the US confirm that aliens exist by...?",
  "markets": [
    {
      "id": "703257",
      "slug": "will-the-us-confirm-that-aliens-exist-before-2027-789-924-249",
      "question": "Will the US confirm that aliens exist before 2027?",
      "conditionId": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
      "clobTokenIds": "[\"107505882767731489358349912513945399560393482969656700824895970500493757150417\",\"7305630249804085635496399869905769372294302716159034447326228509068694952392\"]"
    },
    "..."
  ]
}

List Events

List events when you need a browsable or filterable feed.

TypeScript
Python
API

Call listEvents() on a PublicClient or SecureClient to page through events.

const pages = client.listEvents({ closed: false, pageSize: 20 });

for await (const page of pages) {
  // page.items: Event[]
}

Output: Event[]

type Market = {
  id: string;
  slug?: string | null;
  question?: string | null;
  conditionId: string | null;
};

type Event = {
  id: string;
  slug?: string | null;
  title?: string | null;
  markets: Market[];
};

type Page = {
  items: Event[];
  hasMore: boolean;
  nextCursor?: string;
};

{
  "items": [
    {
      "id": "16183",
      "slug": "kraken-ipo-in-2025",
      "title": "Kraken IPO by ___ ?",
      "markets": [
        {
          "id": "516950",
          "slug": "kraken-ipo-in-2025",
          "question": "Kraken IPO in 2025?"
        },
        "..."
      ]
    },
    {
      "id": "16263",
      "slug": "macron-out-in-2025",
      "title": "Macron out by...?",
      "markets": ["..."]
    },
    "..."
  ],
  "hasMore": true,
  "nextCursor": "9YTr9qyfU9571U9_leL7LNSWUI6EXd7rpAqdh-EbPr17InYiOjEsImsiOiJldmVudHMiLCJvaCI6IjRmNTNjZGExOGMyYmFhMGMwMzU0YmI1ZjlhM2VjYmU1ZWQxMmFiNGQ4ZTExYmE4NzNjMmYxMTE2MTIwMmI5NDUiLCJrZXlzIjpbeyJ0Ijoic3RyaW5nIiwidiI6IjI1ODE1In1dfQ"
}

Filter by tag by passing one or more numeric tag IDs:

const pages = client.listEvents({
  tagIds: [745], // numeric ID for the "nba" tag; see Tags below to look these up
  closed: false,
});

for await (const page of pages) {
  // page.items: Event[]
}

Call list_events() on an AsyncPublicClient or AsyncSecureClient to page through events. The synchronous PublicClient and SecureClient provide the same method.

pages = client.list_events(closed=False, page_size=20)

async for page in pages:
    ...  # page.items: tuple[Event, ...]

Output: Event[]

class Market:
    id: str
    slug: str | None
    question: str | None
    condition_id: str | None

class Event:
    id: str
    slug: str | None
    title: str | None
    markets: tuple[Market, ...]

class Page:
    items: tuple[Event, ...]
    has_more: bool
    next_cursor: str | None

{
  "items": [
    {
      "id": "16183",
      "slug": "kraken-ipo-in-2025",
      "title": "Kraken IPO by ___ ?"
    },
    {
      "id": "16263",
      "slug": "macron-out-in-2025",
      "title": "Macron out by...?"
    },
    "..."
  ],
  "has_more": true,
  "next_cursor": "eyJmIjoiYWQyZjRkNmY4ZDZkIiwiayI6IjlZVHI5cXlmVTk1NzFVOV9sZUw3TE5TV1VJNkVYZDdycEFxZGgtRWJQcjE3SW5ZaU9qRXNJbXNpT2lKbGRtVnVkSE1pTENKdmFDSTZJalJtTlROalpHRXhPR015WW1GaE1HTXdNelUwWW1JMVpqbGhNMlZqWW1VMVpXUXhNbUZpTkdRNFpURXhZbUU0TnpOak1tWXhNVEUyTVRJd01tSTVORFVpTENKclpYbHpJanBiZXlKMElqb2ljM1J5YVc1bklpd2lkaUk2SWpJMU9ERTFJbjFkZlEiLCJwIjoiL2V2ZW50cy9rZXlzZXQiLCJzdmMiOiJnYW1tYSIsInYiOjF9"
}

Filter by tag by passing a numeric tag ID:

pages = client.list_events(
    tag_ids=[745],  # numeric ID for the "nba" tag; see Tags below to look these up
    closed=False,
)

async for page in pages:
    ...  # page.items: tuple[Event, ...]

List active events:

curl "https://gamma-api.polymarket.com/events/keyset?closed=false&limit=20"

Output: Events Page

Example

{
  "events": [
    {
      "id": "16183",
      "slug": "kraken-ipo-in-2025",
      "title": "Kraken IPO by ___ ?"
    },
    "..."
  ],
  "next_cursor": "9YTr9qyfU9571U9_leL7LNSWUI6EXd7rpAqdh-EbPr17InYiOjEsImsiOiJldmVudHMiLCJvaCI6IjRmNTNjZGExOGMyYmFhMGMwMzU0YmI1ZjlhM2VjYmU1ZWQxMmFiNGQ4ZTExYmE4NzNjMmYxMTE2MTIwMmI5NDUiLCJrZXlzIjpbeyJ0Ijoic3RyaW5nIiwidiI6IjI1ODE1In1dfQ"
}

Pass next_cursor as after_cursor to fetch the next page:

curl "https://gamma-api.polymarket.com/events/keyset?closed=false&limit=20&after_cursor=<next_cursor>"

Filter by tag with tag_id:

curl "https://gamma-api.polymarket.com/events/keyset?tag_id=745&closed=false&limit=20"

Markets

A market is a single yes/no question with two outcome token IDs: one for YES and one for NO.

Fetch a Market

Fetch a market when you already know its identifier.

TypeScript
Python
API

Call fetchMarket() on a PublicClient or SecureClient to fetch a market by ID.

const market = await client.fetchMarket({ id: "703257" });

// market: Market

You can also fetch a market by its Polymarket URL or slug:

const market = await client.fetchMarket({
  url: "https://polymarket.com/market/will-the-us-confirm-that-aliens-exist-before-2027-789-924-249",
});

const market = await client.fetchMarket({
  slug: "will-the-us-confirm-that-aliens-exist-before-2027-789-924-249",
});

Output: Market

type Market = {
  id: string;
  slug?: string | null;
  question?: string | null;
  conditionId: string | null;
  outcomes: {
    yes: { tokenId: string | null };
    no: { tokenId: string | null };
  };
};

{
  "id": "703257",
  "slug": "will-the-us-confirm-that-aliens-exist-before-2027-789-924-249",
  "question": "Will the US confirm that aliens exist before 2027?",
  "conditionId": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
  "outcomes": {
    "yes": {
      "tokenId": "107505882767731489358349912513945399560393482969656700824895970500493757150417"
    },
    "no": {
      "tokenId": "7305630249804085635496399869905769372294302716159034447326228509068694952392"
    }
  }
}

Call get_market() on an AsyncPublicClient or AsyncSecureClient to fetch a market by ID. The synchronous PublicClient and SecureClient provide the same method.

market = await client.get_market(id="703257")

# market: Market

You can also fetch a market by its Polymarket URL or slug:

market = await client.get_market(
    url="https://polymarket.com/market/will-the-us-confirm-that-aliens-exist-before-2027-789-924-249",
)

market = await client.get_market(
    slug="will-the-us-confirm-that-aliens-exist-before-2027-789-924-249",
)

Output: Market

class MarketOutcome:
    token_id: str | None

class MarketOutcomes:
    yes: MarketOutcome
    no: MarketOutcome

class Market:
    id: str
    slug: str | None
    question: str | None
    condition_id: str | None
    outcomes: MarketOutcomes

{
  "id": "703257",
  "slug": "will-the-us-confirm-that-aliens-exist-before-2027-789-924-249",
  "question": "Will the US confirm that aliens exist before 2027?",
  "condition_id": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
  "outcomes": {
    "yes": {
      "token_id": "107505882767731489358349912513945399560393482969656700824895970500493757150417"
    },
    "no": {
      "token_id": "7305630249804085635496399869905769372294302716159034447326228509068694952392"
    }
  }
}

Fetch a market by ID:

curl "https://gamma-api.polymarket.com/markets/703257"

You can also fetch a market by slug:

curl "https://gamma-api.polymarket.com/markets/slug/will-the-us-confirm-that-aliens-exist-before-2027-789-924-249"

Output: Market

Example

{
  "id": "703257",
  "slug": "will-the-us-confirm-that-aliens-exist-before-2027-789-924-249",
  "question": "Will the US confirm that aliens exist before 2027?",
  "conditionId": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
  "clobTokenIds": "[\"107505882767731489358349912513945399560393482969656700824895970500493757150417\",\"7305630249804085635496399869905769372294302716159034447326228509068694952392\"]"
}

List Markets

List markets when you need a filterable feed, such as browsing by tag, sport, or liquidity.

TypeScript
Python
API

Call listMarkets() on a PublicClient or SecureClient to page through markets.

const pages = client.listMarkets({
  tagId: 745, // numeric ID for the "nba" tag; see Tags below to look these up
  closed: false,
  pageSize: 20,
});

for await (const page of pages) {
  // page.items: Market[]
}

Output: Market[]

Example

[
  {
    "id": "741099",
    "slug": "will-lebron-james-retire-before-next-nba-season",
    "question": "Will LeBron James retire before next NBA season?",
    "conditionId": "0x73057b771600660ac6e659c5b831587fd3bdd378e63f359731aa3e1538577fb0"
  },
  {
    "id": "1747460",
    "slug": "will-giannis-antetokounmpo-play-for-the-atlanta-hawks-in-2026-27",
    "question": "Will Giannis Antetokounmpo play for the Atlanta Hawks in 2026-27?",
    "conditionId": "0xff2715084bb2cf20d9b88b74ef809c3317b1e99f6c006faee9b83bc85aa0fc99"
  },
  "..."
]

Call list_markets() on an AsyncPublicClient or AsyncSecureClient to page through markets. The synchronous PublicClient and SecureClient provide the same method.

pages = client.list_markets(
    tag_id=745,  # numeric ID for the "nba" tag; see Tags below to look these up
    closed=False,
    page_size=20,
)

async for page in pages:
    ...  # page.items: tuple[Market, ...]

Output: Market[]

Example

[
  {
    "id": "741099",
    "slug": "will-lebron-james-retire-before-next-nba-season",
    "question": "Will LeBron James retire before next NBA season?",
    "condition_id": "0x73057b771600660ac6e659c5b831587fd3bdd378e63f359731aa3e1538577fb0"
  },
  {
    "id": "1747460",
    "slug": "will-giannis-antetokounmpo-play-for-the-atlanta-hawks-in-2026-27",
    "question": "Will Giannis Antetokounmpo play for the Atlanta Hawks in 2026-27?",
    "condition_id": "0xff2715084bb2cf20d9b88b74ef809c3317b1e99f6c006faee9b83bc85aa0fc99"
  },
  "..."
]

List active markets by tag:

curl "https://gamma-api.polymarket.com/markets/keyset?tag_id=745&closed=false&limit=20"

Output: Markets Page

Example

{
  "markets": [
    {
      "id": "540817",
      "slug": "new-rhianna-album-before-gta-vi-926",
      "question": "New Rihanna Album before GTA VI?",
      "conditionId": "0x1fad72fae204143ff1c3035e99e7c0f65ea8d5cd9bd1070987bd1a3316f772be"
    },
    "..."
  ],
  "next_cursor": "8ejWEAtEdA8gG05m-tRMeLtBDl1Wbw1fUbXVfm0eYSZ7InYiOjEsImsiOiJtYXJrZXRzIiwib2giOiI0ZjUzY2RhMThjMmJhYTBjMDM1NGJiNWY5YTNlY2JlNWVkMTJhYjRkOGUxMWJhODczYzJmMTExNjEyMDJiOTQ1Iiwia2V5cyI6W3sidCI6InN0cmluZyIsInYiOiI1NTg5NDAifV19"
}

Pass next_cursor as after_cursor to fetch the next page:

curl "https://gamma-api.polymarket.com/markets/keyset?tag_id=745&closed=false&limit=20&after_cursor=<next_cursor>"

After you choose a market, continue to Market Details to extract token IDs and trading fields.

Series

A series groups a recurring set of events under one theme. For example, a weekly Fed rate-decision series has one event per meeting, and a season-long league series has one event per matchup.

Fetch a Series

Fetch a series by ID.

TypeScript
Python
API

Call fetchSeries() on a PublicClient or SecureClient to fetch a series by ID.

const series = await client.fetchSeries({ id: "1" });

// series: Series

Output: Series

Example

{
  "id": "1",
  "slug": "nfl",
  "title": "NFL",
  "recurrence": "weekly",
  "closed": false
}

Call get_series() on an AsyncPublicClient or AsyncSecureClient to fetch a series by ID. The synchronous PublicClient and SecureClient provide the same method.

series = await client.get_series("1")

# series: Series

Output: Series

Example

{
  "id": "1",
  "slug": "nfl",
  "title": "NFL",
  "recurrence": "weekly",
  "closed": false
}

Fetch a series by ID:

curl "https://gamma-api.polymarket.com/series/1"

Output: Series

Example

{
  "id": "1",
  "slug": "nfl",
  "title": "NFL",
  "recurrence": "weekly",
  "closed": false
}

List Series

TypeScript
Python
API

Call listSeries() on a PublicClient or SecureClient to page through series.

const pages = client.listSeries({
  recurrence: "weekly",
  closed: false,
  pageSize: 20,
});

for await (const page of pages) {
  // page.items: Series[]
}

Output: Series[]

Example

[
  { "id": "1", "slug": "nfl", "title": "NFL" },
  { "id": "2", "slug": "nba", "title": "NBA" },
  { "id": "3", "slug": "mlb", "title": "MLB" },
  "..."
]

Call list_series() on an AsyncPublicClient or AsyncSecureClient to page through series. The synchronous PublicClient and SecureClient provide the same method.

pages = client.list_series(
    recurrence="weekly",
    closed=False,
    page_size=20,
)

async for page in pages:
    ...  # page.items: tuple[Series, ...]

Output: Series[]

Example

[
  { "id": "1", "slug": "nfl", "title": "NFL" },
  { "id": "2", "slug": "nba", "title": "NBA" },
  { "id": "3", "slug": "mlb", "title": "MLB" },
  "..."
]

List active weekly series:

curl "https://gamma-api.polymarket.com/series?recurrence=weekly&closed=false&limit=20"

Output: Series[]

Example

[
  { "id": "1", "slug": "nfl", "title": "NFL" },
  { "id": "2", "slug": "nba", "title": "NBA" },
  { "id": "3", "slug": "mlb", "title": "MLB" },
  "..."
]

Sports

Sports metadata maps a sport to its Polymarket tags and market types. Use it to browse sports markets by league, look up the valid market types for filtering, find events associated with a game, or resolve team rosters.

List Sports

TypeScript
Python
API

Call listSports() on a PublicClient or SecureClient to list supported sports.

const sports = await client.listSports();

// sports: SportsMetadata[]

Output: SportsMetadata[]

Example

[
  { "id": 1, "sport": "ncaab", "tags": "1,100149,100639" },
  { "id": 2, "sport": "epl", "tags": "1,82,306,100639,100350" },
  { "id": 3, "sport": "lal", "tags": "1,780,100639,100350" }
]

Call get_sports() on an AsyncPublicClient or AsyncSecureClient to list supported sports. The synchronous PublicClient and SecureClient provide the same method.

sports = await client.get_sports()

# sports: tuple[SportsMetadata, ...]

Output: SportsMetadata[]

Example

[
  { "id": 1, "sport": "ncaab", "tags": "1,100149,100639" },
  { "id": 2, "sport": "epl", "tags": "1,82,306,100639,100350" },
  { "id": 3, "sport": "lal", "tags": "1,780,100639,100350" }
]

List supported sports:

curl "https://gamma-api.polymarket.com/sports"

Output: SportsMetadata[]

Example

[
  { "sport": "ncaab", "tags": "1,100149,100639" },
  { "sport": "epl", "tags": "1,82,306,100639,100350" },
  { "sport": "lal", "tags": "1,780,100639,100350" }
]

Sports Market Types

Every sports market carries a market type that tells you which line it prices: a moneyline (which team wins), a spread (win by how much), or a total (over/under a combined score). Fetch the valid values, then pass one or more of them when listing markets to filter.

TypeScript
Python
API

Call fetchSportsMarketTypes() on a PublicClient or SecureClient to list the supported market types. When present, a market reports its type in sports.sportsMarketType.

const { marketTypes } = await client.fetchSportsMarketTypes();

// marketTypes: string[]

Output: string[]

Example

{
  "marketTypes": ["moneyline", "spreads", "totals"]
}

Filter markets by type:

const pages = client.listMarkets({
  sportsMarketTypes: ["spreads"],
  closed: false,
  pageSize: 20,
});

for await (const page of pages) {
  // page.items: Market[]
}

Call get_sports_market_types() on an AsyncPublicClient or AsyncSecureClient to list the supported market types. The synchronous PublicClient and SecureClient provide the same method. Each market reports its type in sports.sports_market_type when present.

market_types = await client.get_sports_market_types()

# market_types.market_types: tuple[str, ...] | None

Output: string[]

Example

{
  "market_types": ["moneyline", "spreads", "totals"]
}

Filter markets by type:

pages = client.list_markets(
    sports_market_types=["spreads"],
    closed=False,
    page_size=20,
)

async for page in pages:
    ...  # page.items: tuple[Market, ...]

List supported sports market types. When present, a market reports its type in sportsMarketType:

curl "https://gamma-api.polymarket.com/sports/market-types"

Output: string[]

Example

{
  "marketTypes": ["moneyline", "spreads", "totals"]
}

Filter markets by type:

curl "https://gamma-api.polymarket.com/markets/keyset?sports_market_types=spreads&closed=false&limit=20"

List Events for a Game

A sports game’s markets can be split across a main event and companion events. Depending on the game, companion events may cover player props, half-time and second-half results, exact score, or additional lines grouped under a more-markets event. Their slugs extend the main event’s slug with a suffix such as -player-props, -halftime-result, or -more-markets. Append a known suffix when you need one companion event. To discover current companion events, use the listing workflow instead of guessing each suffix.

TypeScript
Python
API

Call fetchEvent() on a PublicClient or SecureClient. To fetch only the more-markets event, append -more-markets to the main event’s slug.

const mainSlug = "mls-chi-vwh-2026-07-16";

const moreMarkets = await client.fetchEvent({
  slug: `${mainSlug}-more-markets`,
});

To list the game’s current events, fetch the main event and read sports.gameId, then pass it to listEvents(). Not every event has a game ID, so check it before filtering.

const mainSlug = "mls-chi-vwh-2026-07-16";
const game = await client.fetchEvent({ slug: mainSlug });
const gameId = game.sports.gameId;

if (gameId == null) {
  throw new Error("Event does not have a game ID");
}

const pages = client.listEvents({ gameIds: [gameId], pageSize: 20 });

for await (const page of pages) {
  // page.items: Event[]
}

Output: Event Page

Example

{
  "items": [
    {
      "id": "662915",
      "slug": "mls-chi-vwh-2026-07-16",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC"
    },
    {
      "id": "662970",
      "slug": "mls-chi-vwh-2026-07-16-halftime-result",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC - Halftime Result"
    },
    {
      "id": "662972",
      "slug": "mls-chi-vwh-2026-07-16-second-half-result",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC - Second Half Result"
    },
    {
      "id": "662974",
      "slug": "mls-chi-vwh-2026-07-16-exact-score",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC - Exact Score"
    },
    {
      "id": "662976",
      "slug": "mls-chi-vwh-2026-07-16-first-to-score",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC - First Team to Score"
    },
    {
      "id": "663131",
      "slug": "mls-chi-vwh-2026-07-16-more-markets",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC - More Markets"
    }
  ],
  "hasMore": false
}

When present, market.sports.sportsMarketType identifies lines in the more-markets event such as first_half_totals, both_teams_to_score, and soccer_team_totals.

Call get_event() on an AsyncPublicClient or AsyncSecureClient. To fetch only the more-markets event, append -more-markets to the main event’s slug. The synchronous PublicClient and SecureClient provide the same method.

main_slug = "mls-chi-vwh-2026-07-16"

more_markets = await client.get_event(slug=f"{main_slug}-more-markets")

To list the game’s current events, fetch the main event and read sports.game_id, then pass it to list_events(). Not every event has a game ID, so check it before filtering.

main_slug = "mls-chi-vwh-2026-07-16"
game = await client.get_event(slug=main_slug)
game_id = game.sports.game_id

if game_id is None:
    raise ValueError("Event does not have a game ID")

pages = client.list_events(game_ids=[game_id], page_size=20)

async for page in pages:
    ...  # page.items: tuple[Event, ...]

Output: Event Page

Example

{
  "items": [
    {
      "id": "662915",
      "slug": "mls-chi-vwh-2026-07-16",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC"
    },
    {
      "id": "662970",
      "slug": "mls-chi-vwh-2026-07-16-halftime-result",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC - Halftime Result"
    },
    {
      "id": "662972",
      "slug": "mls-chi-vwh-2026-07-16-second-half-result",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC - Second Half Result"
    },
    {
      "id": "662974",
      "slug": "mls-chi-vwh-2026-07-16-exact-score",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC - Exact Score"
    },
    {
      "id": "662976",
      "slug": "mls-chi-vwh-2026-07-16-first-to-score",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC - First Team to Score"
    },
    {
      "id": "663131",
      "slug": "mls-chi-vwh-2026-07-16-more-markets",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC - More Markets"
    }
  ],
  "has_more": false
}

When present, market.sports.sports_market_type identifies lines in the more-markets event such as first_half_totals, both_teams_to_score, and soccer_team_totals.

To fetch only the more-markets event, append -more-markets to the main event’s slug:

curl "https://gamma-api.polymarket.com/events/slug/mls-chi-vwh-2026-07-16-more-markets"

To list the game’s current events, fetch the main event and read its gameId:

curl "https://gamma-api.polymarket.com/events/slug/mls-chi-vwh-2026-07-16"

Pass the ID as game_id:

curl "https://gamma-api.polymarket.com/events/keyset?game_id=90104306&limit=20"

Output: Events Page

Example

{
  "events": [
    {
      "id": "662915",
      "slug": "mls-chi-vwh-2026-07-16",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC",
      "gameId": 90104306
    },
    {
      "id": "662970",
      "slug": "mls-chi-vwh-2026-07-16-halftime-result",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC - Halftime Result",
      "gameId": 90104306
    },
    {
      "id": "662972",
      "slug": "mls-chi-vwh-2026-07-16-second-half-result",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC - Second Half Result",
      "gameId": 90104306
    },
    {
      "id": "662974",
      "slug": "mls-chi-vwh-2026-07-16-exact-score",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC - Exact Score",
      "gameId": 90104306
    },
    {
      "id": "662976",
      "slug": "mls-chi-vwh-2026-07-16-first-to-score",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC - First Team to Score",
      "gameId": 90104306
    },
    {
      "id": "663131",
      "slug": "mls-chi-vwh-2026-07-16-more-markets",
      "title": "Chicago Fire FC vs. Vancouver Whitecaps FC - More Markets",
      "gameId": 90104306
    }
  ]
}

If the response includes next_cursor, pass it as after_cursor in the next request. When present, market.sportsMarketType identifies lines in the more-markets event such as first_half_totals, both_teams_to_score, and soccer_team_totals.

Identify Home and Away Teams

Sports event responses identify which team is designated home and which is designated away. Use this value when aligning Polymarket data with an external sports feed.

TypeScript
Python
API

Use PublicClient.fetchEvent() or SecureClient.fetchEvent() to identify the teams.

import { TeamOrdering } from "@polymarket/client";

const event = await client.fetchEvent({
  slug: "fl1-psg-ren-2026-08-23",
});
const homeTeam = event.sports.teams.find(
  (team) => team.ordering === TeamOrdering.Home,
);
const awayTeam = event.sports.teams.find(
  (team) => team.ordering === TeamOrdering.Away,
);

Output: Team

{
  "id": 114315,
  "name": "Paris Saint-Germain FC",
  "league": "fl1",
  "abbreviation": "psg",
  "ordering": "home"
}

Each Team.ordering value is TeamOrdering.Home, TeamOrdering.Away, or null.

Use AsyncPublicClient.get_event() or AsyncSecureClient.get_event() to identify the teams.

from polymarket import TeamOrdering


event = await client.get_event(slug="fl1-psg-ren-2026-08-23")
home_team = next(
    (team for team in event.sports.teams if team.ordering is TeamOrdering.HOME),
    None,
)
away_team = next(
    (team for team in event.sports.teams if team.ordering is TeamOrdering.AWAY),
    None,
)

Output: Team

{
  "id": 114315,
  "name": "Paris Saint-Germain FC",
  "league": "fl1",
  "abbreviation": "psg",
  "ordering": "home"
}

Each Team.ordering value is TeamOrdering.HOME, TeamOrdering.AWAY, or None.

Fetch the event by slug to identify its home and away teams.

curl "https://gamma-api.polymarket.com/events/slug/fl1-psg-ren-2026-08-23"

Output: Event

{
  "slug": "fl1-psg-ren-2026-08-23",
  "title": "Paris Saint-Germain FC vs. Stade Rennais FC 1901",
  // …
  "teams": [
    {
      "id": 114315,
      "name": "Paris Saint-Germain FC",
      // …
      "ordering": "home",
    },
    {
      "id": 114317,
      "name": "Stade Rennais FC 1901",
      // …
      "ordering": "away",
    },
  ],
}

Read ordering from each entry in the event’s top-level teams field. Its value is "home", "away", or null.

Home and away assignments can change after markets are created, especially when games are rescheduled or moved. If you plan to submit quotes in Combos, check Common Footguns.

List Teams

TypeScript
Python
API

Call listTeams() on a PublicClient or SecureClient to page through teams.

const pages = client.listTeams({ league: ["nba"], pageSize: 20 });

for await (const page of pages) {
  // page.items: Team[]
}

Output: Team[]

Example

[
  {
    "id": 114168,
    "name": "Candace's Rising Stars",
    "league": "nba",
    "abbreviation": "crs"
  },
  {
    "id": 114166,
    "name": "Chuck's Global Stars",
    "league": "nba",
    "abbreviation": "cgs"
  },
  "..."
]

Call list_teams() on an AsyncPublicClient or AsyncSecureClient to page through teams. The synchronous PublicClient and SecureClient provide the same method.

pages = client.list_teams(league="nba", page_size=20)

async for page in pages:
    ...  # page.items: tuple[Team, ...]

Output: Team[]

Example

[
  {
    "id": 114168,
    "name": "Candace's Rising Stars",
    "league": "nba",
    "abbreviation": "crs"
  },
  {
    "id": 114166,
    "name": "Chuck's Global Stars",
    "league": "nba",
    "abbreviation": "cgs"
  },
  "..."
]

List teams in a league:

curl "https://gamma-api.polymarket.com/teams?league=nba&limit=20"

Output: Team[]

Example

[
  {
    "id": 114168,
    "name": "Candace's Rising Stars",
    "league": "nba",
    "abbreviation": "crs"
  },
  "..."
]

Search

Search returns matching events, tags, and profiles for a free-text query in one call. Use it for a search bar or a “jump to market” input.

TypeScript
Python
API

Call search() on a PublicClient or SecureClient to search Polymarket.

const pages = client.search({ q: "aliens", pageSize: 10 });

for await (const page of pages) {
  // page.items.events: Event[]
  // page.items.tags: SearchTag[]
  // page.items.profiles: Profile[]
}

Output: SearchResults

type Event = {
  id: string;
  slug?: string | null;
  title?: string | null;
};

type SearchTag = {
  id: string;
  label?: string | null;
  slug?: string | null;
  eventCount?: number | null;
};

type Profile = {
  pseudonym?: string | null;
  wallet?: string | null;
};

type SearchResults = {
  events: Event[];
  tags: SearchTag[];
  profiles: Profile[];
};

{
  "events": [
    {
      "id": "90177",
      "slug": "will-the-us-confirm-that-aliens-exist-before-2027",
      "title": "Will the US confirm that aliens exist by...?"
    },
    "..."
  ],
  "tags": [],
  "profiles": []
}

Call search() on an AsyncPublicClient or AsyncSecureClient to search Polymarket. The synchronous PublicClient and SecureClient provide the same method.

pages = client.search(q="aliens", page_size=10)

async for page in pages:
    for search_results in page.items:
        # search_results.events: tuple[Event, ...]
        # search_results.tags: tuple[SearchTag, ...]
        # search_results.profiles: tuple[Profile, ...]
        ...

Output: SearchResults

class Event:
    id: str
    slug: str | None
    title: str | None

class SearchTag:
    id: str
    label: str | None
    slug: str | None
    event_count: int | None

class Profile:
    pseudonym: str | None
    wallet: str | None

class SearchResults:
    events: tuple[Event, ...]
    tags: tuple[SearchTag, ...]
    profiles: tuple[Profile, ...]

{
  "events": [
    {
      "id": "90177",
      "slug": "will-the-us-confirm-that-aliens-exist-before-2027",
      "title": "Will the US confirm that aliens exist by...?"
    },
    "..."
  ],
  "tags": [],
  "profiles": []
}

Search Polymarket:

curl "https://gamma-api.polymarket.com/public-search?q=aliens"

Output: Search

Example

{
  "events": [
    {
      "id": "90177",
      "slug": "will-the-us-confirm-that-aliens-exist-before-2027",
      "title": "Will the US confirm that aliens exist by...?"
    },
    "..."
  ],
  "tags": [],
  "profiles": [],
  "pagination": {
    "hasMore": true,
    "totalResults": 28
  }
}

Getting Started

Core Concepts

Market Data

Trading

Programs

Resources

Events

Fetch an Event

List Events

Markets

Fetch a Market

List Markets

Series

Fetch a Series

List Series

Sports

List Sports

Sports Market Types

List Events for a Game

Identify Home and Away Teams

List Teams

Search

Tags

Fetch a Tag

Fetch Tag Relationships

​Events

​Fetch an Event

​List Events

​Markets

​Fetch a Market

​List Markets

​Series

​Fetch a Series

​List Series

​Sports

​List Sports

​Sports Market Types

​List Events for a Game

​Identify Home and Away Teams

​List Teams

​Search

​Tags

​List Tags

​Fetch a Tag

​Fetch Tag Relationships

​Fetch Related Tags

Events

Fetch an Event

List Events

Markets

Fetch a Market

List Markets

Series

Fetch a Series

List Series

Sports

List Sports

Sports Market Types

List Events for a Game

Identify Home and Away Teams

List Teams

Search

Tags

List Tags

Fetch a Tag

Fetch Tag Relationships

Fetch Related Tags