Events

List Events

GET /api/v1/events

Authentication: Public Query parameters:

Query	Type	Required	Description
`eventStatus`	enum string	No	`DRAFT`, `ACTIVE`, `RESOLVED` or `ENDED`.
`term`	string	No	Search event names, slugs and descriptions.
`category`	UUID string	No	Category ID.
`tag`	UUID string	No	Tag ID. When `category` is also supplied, both filters must match.
`ends`	enum string	No	`TODAY`, `THIS_WEEK` or `THIS_MONTH`.
`addedWithin`	enum string	No	`LAST_24H`, `LAST_7D` or `LAST_30D`.
`minLiquidity`	number	No	Minimum USD liquidity.
`maxLiquidity`	number	No	Maximum USD liquidity.
`isSettled`	boolean	No	Filter by market settlement status.
`isResolved`	boolean	No	Filter by market resolution status.
`endDateFrom`	string (date-time)	No	Include events ending on or after this timestamp.
`endDateTo`	string (date-time)	No	Include events ending on or before this timestamp.
`includeVolume`	boolean	No	Include market `tradeVolumeUsd` and `tradeVolumeUsd24h`.
`includeResolution`	boolean	No	Include the `resolution` timeline on each market. Default `false`.
`includeRewards`	boolean	No	Include each market’s current-period reward opportunity as `reward`. Default `false`.
`protected`	boolean	No	Include protected events.
`single`	boolean	No	`true` for single-market events, `false` for multi-market events.
`sortBy`	enum string	No	`id`, `name`, `startDate`, `endDate`, `tradeVolumeUsd`, `tradeVolumeUsd24h`, `createdAt`, `eventStatus`, `slug` or `liquidity`.
`order`	enum string	No	`ASC` or `DESC`.
`page`	integer	No	Page number. Default `1`.
`limit`	integer	No	Results per page. Default `10`.
`total`	boolean	No	Include total count. Default `true`.

When sortBy=liquidity, send minLiquidity or maxLiquidity. For public callers, nested markets with status=DRAFT are omitted. Pagination totals are capped server-side; when the real count exceeds the cap, total contains the cap and totalCapped is true. Response type: Pagination<Event>.

Get Event

GET /api/v1/events/{id_or_slug}

Authentication: Public Path parameters:

Parameter	Type	Required	Description
`id_or_slug`	UUID string or string	Yes	Event UUID or slug.

Query parameters:

Query	Type	Required	Description
`includeVolume`	boolean	No	Include market `tradeVolumeUsd` and `tradeVolumeUsd24h`.
`includeResolution`	boolean	No	Include the `resolution` timeline on each market. Default `false`.
`marketScope`	enum string	No	`AUTO`, `RECENT` or `ALL`. Default `AUTO` for every caller.
`marketLimit`	integer	No	Number of markets returned when the effective scope is `RECENT`. Default `50`, range `1` to `200`. Still validated under `ALL`, where it does not change the page size.
`marketCursor`	string	No	Opaque cursor from the previous response’s `nextMarketCursor`. Valid only with `marketScope=ALL`.

AUTO uses a recent bounded window for series-layout events and otherwise returns all public markets in one response. Public responses omit DRAFT markets under every scope. With marketScope=ALL, the response carries at most 50 markets, newest first (latest startDate first, then createdAt, then id), and a nextMarketCursor field. Pass its value back unchanged as marketCursor to get the next page; when nextMarketCursor is null there are no more markets. Do not parse or modify the cursor. nextMarketCursor is absent under the other scopes. Sending marketCursor without marketScope=ALL, or a value that is not a well-formed cursor, returns 400. Response type: Event.

Get Event Volume

GET /api/v1/events/{id_or_slug}/volume

Authentication: Public Path parameters:

Parameter	Type	Required	Description
`id_or_slug`	UUID string or string	Yes	Event UUID or slug.

Response type: number.

Get Event Positions by User

GET /api/v1/events/{id}/positions

Authentication: Public with optional user authentication Returns public-safe positions in one event for up to 50 users. Users without positions in the event are omitted. The backend reads at most 10,000 matching position rows across the request and does not include a truncation marker. Path parameters:

Parameter	Type	Required	Description
`id`	UUID string	Yes	Event UUID.

Query parameters:

Query	Type	Required	Description
`users`	string	Yes	A single comma-separated list of 1 to 50 user UUIDs. Duplicate IDs are removed. Repeated or structured query values are rejected.

Response type: EventUserPositions[].

Field	Type	Required	Description
`userId`	UUID string	Yes	Markets user UUID.
`positions`	`EventUserPosition[]`	Yes	Positions sorted by current value descending.

EventUserPosition:

Field	Type	Required	Description
`market_uuid`	UUID string	Yes	Market UUID.
`tokenId`	string	Yes	Held outcome token ID.
`amount`	string	Yes	Outcome tokens held in display units.
`current`	string	Yes	Current mark-to-market value.
`outcome`	string	No	Outcome label.
`outcomeIndex`	integer	No	Outcome index, `0` or `1`.
`title`	string	No	Market title.
`displayName`	string or null	Yes	Optional market presentation label. Use `title` when this is `null`.
`slug`	string	No	Market slug.
`icon`	string	No	Market icon URL.
`status`	enum string	No	Current market status.
`conditionId`	string	No	Conditional Tokens condition ID.
`resolvedTo`	string or number	No	Resolution outcome.

Event

Field	Type	Required	Description
`id`	UUID string	Yes	Event UUID.
`name`	string	Yes	Event name.
`slug`	string	Yes	Event slug.
`description`	string	Yes	Event description.
`createdAt`	string (date-time)	Yes	Creation timestamp.
`createdBy`	UUID string	Yes	Creator user ID.
`updatedAt`	string (date-time)	Yes	Last update timestamp.
`startDate`	string (date-time)	Yes	Event start timestamp.
`endDate`	string (date-time) or null	Yes	Event end timestamp; unbounded multi-market events can return `null`.
`icon`	string	Yes	Event icon URL.
`eventStatus`	enum string	Yes	`DRAFT`, `ACTIVE`, `RESOLVED` or `ENDED`.
`protected`	boolean	Yes	Whether the event is protected.
`single`	boolean	Yes	Whether the event was created as a single event. A single event has exactly one market; an event with `single` false can also hold one market.
`negRisk`	boolean	Yes	Whether this is a mutually exclusive negative-risk event.
`isDetermined`	boolean	Yes	Whether the event’s winning market has been determined.
`winningMarketId`	UUID string or null	No	Winning market UUID for resolved multi-market events.
`feeBips`	integer or null	No	Event fee in basis points.
`reward`	string	Yes	UMA reward amount.
`proposalBond`	string	Yes	UMA proposal bond amount.
`liveness`	integer	Yes	UMA liveness period in seconds.
`orderFeeRateBps`	integer	Yes	Active order fee rate in basis points.
`passiveOrderFeeRateBps`	integer	Yes	Passive order fee rate in basis points.
`marketId`	string or null	No	The event’s single on-chain market ID. On a single event (`single` true) it is that market’s `marketId`; on a neg-risk event it is the neg-risk market ID its markets share. `null` on an event that is neither (`single` false and not neg-risk, whatever its number of markets; read each market’s `marketId` instead) and on an event not yet on chain.
`ancillaryData`	string or null	No	The event’s prepared on-chain market ID, the same value as the event’s `marketId` when both are set. On a single event (`single` true) that is the market’s question text, equal to that market’s `ancillaryData`; on a neg-risk event it is the neg-risk market ID, not question text. `null` whenever `marketId` is `null`.
`metadata`	object	No	Optional JSON metadata.
`templateId`	UUID string	No	Template UUID when generated from a template.
`categories`	`Category[]`	No	Event categories.
`tags`	`Tag[]`	No	Normalized tag assignments when loaded.
`markets`	`Market[]`	Yes	Markets in the event. On Get Event, a window of them when the effective scope is `RECENT`, and one page of them under `ALL`; see `marketScope`.
`nextMarketCursor`	string or null	No	Get Event with `marketScope=ALL` only: the cursor for the next page of markets, or `null` on the last page.
`isInitialized`	boolean	Yes	Whether the event has been initialized on chain.
`totalVolumeUSD`	string	No	Total trade volume across event markets. Present when volume is calculated.
`liquidity`	string	No	Total pending-order liquidity. Present when liquidity is calculated.

Market

Field	Type	Required	Description
`id`	UUID string	Yes	Market UUID.
`name`	string	Yes	Market name.
`slug`	string	Yes	Market URL slug.
`createdAt`	string (date-time)	Yes	Creation timestamp.
`updatedAt`	string (date-time)	Yes	Last update timestamp.
`startDate`	string (date-time) or null	No	Market start timestamp.
`endDate`	string (date-time) or null	No	Market end timestamp.
`description`	string or null	No	Market description.
`chance`	number	Yes	Current market chance.
`status`	enum string	Yes	`DRAFT`, `ACTIVE` or `RESOLVED`.
`icon`	string	Yes	Market icon URL.
`tokenId1`	string	Yes	Outcome 1 token ID.
`tokenId2`	string	Yes	Outcome 2 token ID.
`ancillaryData`	string or null	No	The market’s on-chain question text, as `0x`-prefixed hex. On UMA markets it ends with the `,initializer:` suffix and the initializer address, which UMA adds; on price-resolver and direct-resolver markets there is no suffix. `null` until the market is initialized on chain (`isInitialized` false).
`isInitialized`	boolean	Yes	Whether the market has been initialized.
`conditionId`	string	Yes	Conditional Tokens condition ID.
`questionId`	string	Yes	UMA question ID.
`outcome1`	string	Yes	Outcome 1 label.
`outcome2`	string	Yes	Outcome 2 label.
`orderFeeRateBps`	integer	Yes	Active order fee rate in basis points.
`passiveOrderFeeRateBps`	integer	Yes	Passive order fee rate in basis points.
`tickSize`	string	Yes	Minimum price increment.
`speedBumpDelayMs`	integer	Yes	Taker-order matching delay in milliseconds.
`firstPriceDataAt`	string (date-time) or null	No	First price-history timestamp.
`hasProposedPrice`	boolean	Yes	Whether a UMA price has been proposed.
`isDisputed`	boolean	Yes	Whether the proposed price is disputed.
`isSettled`	boolean	Yes	Whether the UMA request is settled.
`resolvedOnAdapterTimestamp`	integer	Yes	Adapter resolution timestamp.
`isResolved`	boolean	Yes	Whether the market is resolved.
`isRegistered`	boolean	Yes	Whether the market is registered on chain.
`isPaused`	boolean	Yes	Whether the market is paused.
`hidden`	boolean	Yes	Whether the market is hidden from the public event page.
`marketResolvedTo`	string	Yes	Raw resolved outcome value.
`marketId`	string or null	No	On-chain market ID. Equal to `ancillaryData`, except on neg-risk markets (`negRisk` is `true`), where it is the neg-risk market ID. `null` until the market is initialized on chain (`isInitialized` false).
`negRisk`	boolean	Yes	Whether the market uses negative-risk resolution.
`questionFlaggedTimestamp`	integer	Yes	Question-flagged timestamp.
`transactionHash`	string	Yes	Creation or registration transaction hash.
`eventId`	UUID string	Yes	Parent event UUID.
`questionIndex`	integer or null	No	Question index for multi-market events.
`tradeVolumeUsd`	string	No	All-time trade volume in USD.
`tradeVolumeUsd24h`	string	No	24-hour trade volume in USD.
`proposedAt`	string (date-time) or null	No	Current proposal timestamp.
`proposedPrice`	string or null	No	Current UMA proposed value.
`resolution`	object	No	Resolution timeline, returned when `includeResolution=true`. It can be absent even when requested: that means the market’s status is not known right now (it has not been computed yet after a deploy, or the server cannot vouch for it), not that nothing has been proposed.
`priceTargetConfig`	object	No	Per-market price-target configuration when present.
`displayTimezone`	string or null	Yes	IANA timezone used to render this market’s times. Markets without a configured timezone return `null` and should be displayed in UTC.
`reward`	`MarketReward` or null	No	Current-period reward opportunity, present when `includeRewards=true`; `null` when the market has no active or later-today opportunity.

On GET /api/v1/events/{id_or_slug}, a started CLOSE_PRICE market using the PYTH price source can have an empty stored target derived from the live price feed at read time. The event-list endpoint does not perform this live derivation. If the source price is unavailable, the target remains null. When the derived market is also the market selected for the event’s compatibility metadata, the value can populate metadata.cryptoPairTargetPrice. MarketReward uses the same current-period shape documented in Rewards, including rewardStatus, accrual-window fields and boost information.

Tag

Field	Type	Required	Description
`id`	UUID string	Yes	Tag UUID.
`slug`	string	Yes	Tag slug.
`label`	string	Yes	Display label.
`type`	string	Yes	Tag taxonomy type.

Overview

Market Data

Trading

Realtime

List Events

Get Event

Get Event Volume

Get Event Positions by User

Event

Market

Tag

Category

​List Events

​Get Event

​Get Event Volume

​Get Event Positions by User

​Event

​Market

​Tag

​Category

List Events

Get Event

Get Event Volume

Get Event Positions by User

Event

Market

Tag

Category