> ## Documentation Index
> Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List events

> List venue events such as fills, liquidations and stop-loss or take-profit triggers for a wallet.

Requires `address` and `providerId` or `providerIds`. Filter with `eventType` (one) or `eventTypes` (up to 10, CSV or repeated), `marketId`, `perpActionId`, `providerOrderId`, and `fromDate` / `toDate` (ISO 8601, inclusive, applied to `occurredAt`). Results are newest first. Event values are in [Event types](/api-reference/perps-api/objects#event-types). Poll this route; the API does not push events.


## OpenAPI

````yaml openapi-perps.json GET /v1/events
openapi: 3.0.0
info:
  title: 'Yield API: Trade (Perps)'
  description: >-
    API Documentation. Errors follow a uniform envelope with `details.code` from
    the public catalog (https://docs.yield.xyz). ValidationPipe failures use
    `validation.message: string[]`.
  version: '1.0'
  contact: {}
servers:
  - url: https://perps.yield.xyz
    description: Production
security: []
tags:
  - name: Discovery
    description: Browse and discover perps markets, networks, and providers
  - name: Portfolio
    description: User-specific positions, orders, and balances
  - name: Actions
    description: Generate transactions to open, close, and manage positions
externalDocs:
  description: For more information
  url: https://docs.yield.xyz
paths:
  /v1/events:
    get:
      tags:
        - Events
        - Actions
      summary: Get perp events
      description: >-
        Retrieve async venue outcomes (fills, liquidations, SL/TP triggers) for
        a user on a specific provider. Returns a paginated list ordered by most
        recent first.
      operationId: EventsController_getEvents_v1
      parameters:
        - name: offset
          required: false
          in: query
          description: Offset for pagination
          schema:
            minimum: 0
            default: 0
            example: 0
            type: number
        - name: limit
          required: false
          in: query
          description: Maximum number of items to return
          schema:
            minimum: 1
            maximum: 500
            default: 100
            example: 100
            type: number
        - name: providerId
          required: false
          in: query
          description: >-
            Single provider identifier. At least one of providerId or
            providerIds must be provided.
          schema:
            example: hyperliquid
            type: string
            enum:
              - hyperliquid
              - hyperliquid-xyz
        - name: providerIds
          required: false
          in: query
          description: >-
            Filter by multiple providers (CSV, repeated query params, or JSON
            array). At least one of providerId or providerIds must be provided.
            When both providerId and providerIds are set, results include all
            listed providers.
          schema:
            example:
              - hyperliquid
              - hyperliquid-xyz
            type: array
            items:
              type: string
              enum:
                - hyperliquid
                - hyperliquid-xyz
        - name: address
          required: true
          in: query
          description: User wallet address
          schema:
            example: '0xb8c8eb8efc68796e766f6ab320db8c165c064949'
            type: string
        - name: eventType
          required: false
          in: query
          description: Filter by a single event type
          schema:
            $ref: '#/components/schemas/PerpEventType'
        - name: eventTypes
          required: false
          in: query
          description: Filter by multiple event types (CSV or repeated query params)
          schema:
            type: array
            items:
              $ref: '#/components/schemas/PerpEventType'
        - name: marketId
          required: false
          in: query
          description: Filter by market (e.g. hyperliquid-eth-usdc)
          schema:
            example: hyperliquid-eth-usdc
            type: string
        - name: perpActionId
          required: false
          in: query
          description: Filter events linked to a specific action
          schema:
            type: string
            format: uuid
        - name: providerOrderId
          required: false
          in: query
          description: Filter by venue order identifier (e.g. Hyperliquid oid)
          schema:
            type: string
        - name: fromDate
          required: false
          in: query
          description: Include events with occurredAt >= fromDate (ISO 8601)
          schema:
            example: '2026-04-01T00:00:00.000Z'
            type: string
        - name: toDate
          required: false
          in: query
          description: Include events with occurredAt <= toDate (ISO 8601)
          schema:
            example: '2026-04-30T23:59:59.999Z'
            type: string
      responses:
        '200':
          description: Paginated list of perp events
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponseDto'
                  - properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/EventDto'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 401
                  timestamp:
                    type: string
                    example: '2026-05-04T12:00:00.000Z'
                  path:
                    type: string
                    example: /v1/actions
                  message:
                    type: string
                    example: Invalid API key
                  details:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Invalid API key
                      code:
                        type: string
                        example: AUTH_INVALID_API_KEY
        '429':
          description: Rate limit exceeded
          headers:
            x-ratelimit-limit:
              description: Request limit per window
              schema:
                type: string
            x-ratelimit-remaining:
              description: Remaining requests (will be 0)
              schema:
                type: string
            x-ratelimit-reset:
              description: Unix timestamp when window resets
              schema:
                type: string
            retry-after:
              description: Seconds to wait before retrying
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 429
                  timestamp:
                    type: string
                    example: '2026-05-04T12:00:00.000Z'
                  path:
                    type: string
                    example: /v1/actions
                  message:
                    type: string
                    example: Rate limit exceeded
                  details:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Rate limit exceeded
                      code:
                        type: string
                        example: RATE_LIMIT_EXCEEDED
                      error:
                        type: string
                        example: Too Many Requests
                      retryAfter:
                        type: number
                        example: 30
      security:
        - ApiKey: []
components:
  schemas:
    PerpEventType:
      type: string
      enum:
        - order_filled
        - liquidation
        - stop_loss_triggered
        - take_profit_triggered
    PaginatedResponseDto:
      type: object
      properties:
        total:
          type: number
          description: Total number of items available
          example: 150
        offset:
          type: number
          description: Offset of the current page
          example: 0
        limit:
          type: number
          description: Limit of the current page
          example: 100
      required:
        - total
        - offset
        - limit
    EventDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        eventType:
          allOf:
            - $ref: '#/components/schemas/PerpEventType'
        providerId:
          type: string
          example: hyperliquid
        occurredAt:
          type: string
          format: date-time
        marketId:
          type: string
          nullable: true
        perpActionId:
          type: string
          nullable: true
          format: uuid
          description: Linked action; null for liquidations
        providerOrderId:
          type: string
          nullable: true
          description: Venue order identifier (e.g. Hyperliquid oid)
        explorerUrl:
          type: string
          nullable: true
          description: Block explorer URL for the settlement transaction
          example: >-
            https://app.hyperliquid.xyz/explorer/tx/0x8a3fb2c1d4e5f67890abcdef12345678901234567890abcdef1234567890abcd
        order:
          description: Normalized order details for the venue event
          allOf:
            - $ref: '#/components/schemas/EventOrderDto'
      required:
        - id
        - eventType
        - providerId
        - occurredAt
        - order
    EventOrderDto:
      type: object
      properties:
        orderId:
          type: string
          description: Venue order identifier (e.g. Hyperliquid oid)
          example: '394438950581'
        marketId:
          type: string
          description: Market identifier
          example: hyperliquid-eth-usdc
        asset:
          type: string
          description: Base asset ticker
          example: ETH
        side:
          description: Order side
          example: buy
          allOf:
            - $ref: '#/components/schemas/OrderSide'
        type:
          description: Normalized order type
          example: market
          allOf:
            - $ref: '#/components/schemas/OrderType'
        originalSizeBase:
          type: string
          description: Original order size in base asset units
          example: '0.0063'
        remainingSizeBase:
          type: string
          description: Remaining order size in base asset units
          example: '0.0'
        limitPrice:
          type: number
          description: Limit price
          example: 2395.2
        timeInForce:
          description: Normalized time in force
          example: ioc
          allOf:
            - $ref: '#/components/schemas/EventOrderTimeInForce'
        triggerPrice:
          type: number
          description: Trigger price when present on a trigger order
          example: 2500
        reduceOnly:
          type: boolean
          description: Reduce only flag
          example: false
        isPositionLevel:
          type: boolean
          description: Whether the order is a position-level TP/SL order
          example: false
        clientOrderId:
          type: object
          description: Client-supplied order id when present
          example: null
          nullable: true
        childOrderIds:
          description: Child order identifiers
          example: []
          type: array
          items:
            type: string
        createdAt:
          type: string
          description: Order creation timestamp
          format: date-time
          example: '2026-04-23T07:52:05.187Z'
        closedPnl:
          type: string
          description: >-
            PnL realized when an order closes, net of fees in USDC
            (string-encoded decimal). Absent on open / non-closing fills.
          example: '-12.45'
        fillPrice:
          type: number
          description: >-
            Realized fill price for fill-sourced events (e.g. order_filled,
            stop_loss_triggered). One per partial fill — aggregate across rows
            with the same orderId for an order-level average.
          example: 2500.5
      required:
        - orderId
        - marketId
        - asset
        - side
        - type
        - originalSizeBase
        - remainingSizeBase
        - reduceOnly
        - isPositionLevel
        - clientOrderId
        - childOrderIds
        - createdAt
    OrderSide:
      type: string
      enum:
        - buy
        - sell
      description: Order side
    OrderType:
      type: string
      enum:
        - market
        - limit
        - stop_loss
        - take_profit
      description: Order type
    EventOrderTimeInForce:
      type: string
      enum:
        - ioc
        - gtc
        - alo
      description: Normalized time in force
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.