@spec get_event_by_id(
  non_neg_integer() | String.t(),
  keyword()
) :: {:ok, Polymarket.Schemas.Event.t()} | {:error, :get_event_failed}

Retrieves a single event by its unique ID using GET /events/{id}.

Returns the parsed Polymarket.Schemas.Event, including its nested markets, series, tags, and event_metadata.

Options

opts are sent verbatim as query parameters. The Gamma API supports:

• :include_chat - when true, includes the event's chat channels.
• :include_template - when true, includes the event's templates.

Examples

Polymarket.Gamma.get_event_by_id(2890)

@spec get_event_by_slug(
  String.t(),
  keyword()
) :: {:ok, Polymarket.Schemas.Event.t()} | {:error, :get_event_failed}

Retrieves a single event by its unique slug using GET /events/slug/{slug}.

Returns the parsed Polymarket.Schemas.Event, including its nested markets, series, tags, and event_metadata.

Options

opts are sent verbatim as query parameters. The Gamma API supports:

• :include_chat - when true, includes the event's chat channels.
• :include_template - when true, includes the event's templates.

Examples

Polymarket.Gamma.get_event_by_slug("nba-mavericks-grizzlies-2021-12-04")

@spec get_event_tags(non_neg_integer() | String.t()) ::
  {:ok, [Polymarket.Schemas.Tag.t()]} | {:error, :get_event_tags_failed}

Retrieves the tags attached to an event by the event's unique ID using GET /events/{id}/tags.

Returns the list of Polymarket.Schemas.Tag structs for the event.

Examples

Polymarket.Gamma.get_event_tags(2890)

@spec get_market_by_id(non_neg_integer() | String.t(), options()) ::
  {:ok, Polymarket.Schemas.Market.t()} | {:error, :get_market_failed}

Retrieves a single market by its unique ID.

Returns detailed information about a market.

Options

opts are sent verbatim as query parameters. The Gamma API supports:

• :include_tag - when true, includes the market's tags in the response.

Examples

Polymarket.Gamma.get_market_by_id(2_691_932, include_tag: true)

@spec get_market_by_slug(String.t(), options()) ::
  {:ok, Polymarket.Schemas.Market.t()} | {:error, :get_market_failed}

Retrieves a single market by its unique slug.

Returns detailed information about a market.

Options

opts are sent verbatim as query parameters. The Gamma API supports:

• :include_tag - when true, includes the market's tags in the response.

Examples

Polymarket.Gamma.get_market_by_slug("sol-updown-5m-1782566100", include_tag: true)

@spec get_market_tags(non_neg_integer() | String.t()) ::
  {:ok, [Polymarket.Schemas.Tag.t()]} | {:error, :get_market_tags_failed}

Retrieves the tags attached to a market by the market's unique ID.

Returns the list of Polymarket.Schemas.Tag structs for the market.

Examples

Polymarket.Gamma.get_market_tags(2_691_932)

@spec list_events(keyword()) ::
  {:ok,
   %{events: [Polymarket.Schemas.Event.t()], next_cursor: String.t() | nil}}
  | {:error, :list_events_failed}

Fetches a single page of events using the keyset (cursor) pagination endpoint GET /events/keyset.

Returns the parsed events plus the next_cursor to pass as :after_cursor on the following call. next_cursor is nil on the last page. To page through all events, prefer stream_events/1.

Options

opts are sent verbatim as query parameters. The keyset endpoint supports many filters; the most useful are:

• :limit - max results per page (1..500, default 20)
• :after_cursor - the next_cursor from a previous response
• :order / :ascending - sort field and direction
• :closed / :active / :archived / :featured - status filters
• :tag_id / :tag_slug - tag filters

The :offset parameter is rejected by the endpoint; use :after_cursor.

Examples

Polymarket.Gamma.list_events(limit: 100, closed: false)

@spec stream_events(keyword()) :: Enumerable.t()

Returns a lazy Stream of every event matching opts, transparently following the keyset cursor across pages.

Each element is a Polymarket.Schemas.Event. The stream fetches one page at a time as it is consumed, so it is safe to use over the full (large) event set, e.g. with Stream.take/2. Materialise the whole result with Enum.to_list/1.

opts are forwarded to list_events/1 (an :after_cursor in opts is used as the starting page). A larger :limit reduces the number of round-trips.

Raises if a page fails to fetch, so that a partial result is never silently mistaken for the complete set.

Examples

# All open events.
Polymarket.Gamma.stream_events(closed: false) |> Enum.to_list()

# Just the first 50, without fetching everything.
Polymarket.Gamma.stream_events(limit: 100) |> Enum.take(50)