---
title: "Get perp events"
method: GET
path: "/v1/events"
tags: ["Actions"]
---

# Get perp events

`GET /v1/events`

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.

## Query parameters

- `offset` number
- `limit` number
- `providerId` 'hyperliquid' | 'hyperliquid-xyz'
- `providerIds` string[]
- `address` string, required
- `eventType` 'order_filled' | 'liquidation' | 'stop_loss_triggered' | 'take_profit_triggered'
- `eventTypes` PerpEventType[]
- `marketId` string
- `perpActionId` string, uuid
- `providerOrderId` string
- `fromDate` string
- `toDate` string

## Response `200`

Paginated list of perp events

- object
  - `total` number, required — Total number of items available
  - `offset` number, required — Offset of the current page
  - `limit` number, required — Limit of the current page
  - `items` EventDto[]
    - `id` string, uuid, required
    - `eventType` 'order_filled' | 'liquidation' | 'stop_loss_triggered' | 'take_profit_triggered', required
    - `providerId` string, required
    - `occurredAt` string, date-time, required
    - `marketId` string, nullable
    - `perpActionId` string, uuid, nullable — Linked StakeKit action; null for liquidations
    - `providerOrderId` string, nullable — Venue order identifier (e.g. Hyperliquid oid)
    - `explorerUrl` string, nullable — Block explorer URL for the settlement transaction
    - `order` EventOrderDto, required
      - `orderId` string, required — Venue order identifier (e.g. Hyperliquid oid)
      - `marketId` string, required — Market identifier
      - `asset` string, required — Base asset ticker
      - `side` 'buy' | 'sell', required — Order side
      - `type` 'market' | 'limit' | 'stop_loss' | 'take_profit', required — Normalized order type
      - `originalSizeBase` string, required — Original order size in base asset units
      - `remainingSizeBase` string, required — Remaining order size in base asset units
      - `limitPrice` number — Limit price
      - `timeInForce` 'ioc' | 'gtc' | 'alo' — Normalized time in force
      - `triggerPrice` number — Trigger price when present on a trigger order
      - `reduceOnly` boolean, required — Reduce only flag
      - `isPositionLevel` boolean, required — Whether the order is a position-level TP/SL order
      - `clientOrderId` object, nullable, required — Client-supplied order id when present
      - `childOrderIds` string[], required — Child order identifiers
      - `createdAt` string, date-time, required — Order creation timestamp
      - `closedPnl` string — PnL realized when an order closes, net of fees in USDC (string-encoded decimal). Absent on open / non-closing fills.
      - `fillPrice` number — 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.

## Other responses

- `401` — Invalid or missing API key
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/yield/apis/yield-xyz-api.md) · [All operations](https://skmtc.net/yield/apis/yield-xyz-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yield/yield-xyz-api/revisions/acfa80015ca5/schema)