> ## Documentation Index > Fetch the complete documentation index at: https://docs.hit.com/llms.txt > Use this file to discover all available pages before exploring further. # Events > Event discovery and volume endpoint reference ## List Events ```text theme={null} 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`. ## Get Event ```text theme={null} 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`. Public default `AUTO`; admin default `ALL`. | | `marketLimit` | integer | No | Number of markets returned when the effective scope is `RECENT`. Default `50`, range `1` to `200`. | `AUTO` uses a recent bounded window for series-layout events and otherwise returns all public markets. Public responses omit DRAFT markets even when `marketScope=ALL`. Response type: `Event`. ## Get Event Volume ```text theme={null} 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 ```text theme={null} 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 has 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 | Yes | On-chain market ID. | | `ancillaryData` | string | Yes | UMA ancillary data. | | `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. | | `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 | Yes | UMA ancillary data. | | `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 | Yes | On-chain market ID. | | `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, present when `includeResolution=true`. | | `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](/api-reference/rewards#list-reward-markets), 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. | ## Category | Field | Type | Required | Description | | ----------- | ------------------- | -------- | ------------------------------- | | `id` | UUID string | Yes | Category UUID. | | `name` | string | Yes | Category name. | | `createdAt` | string (date-time) | Yes | Creation timestamp. | | `createdBy` | UUID string | Yes | Creator user ID. | | `updatedAt` | string (date-time) | Yes | Last update timestamp. | | `updatedBy` | UUID string or null | No | Last updater user ID. | | `active` | boolean | Yes | Whether the category is active. | | `position` | integer | Yes | Sort position. |