List events

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

GET /v1/events

Get perp events

cURL

curl --request GET \
  --url https://perps.yield.xyz/v1/events \
  --header 'x-api-key: <api-key>'

200

{
  "total": 150,
  "offset": 0,
  "limit": 100,
  "items": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "eventType": "order_filled",
      "providerId": "hyperliquid",
      "occurredAt": "2023-11-07T05:31:56Z",
      "order": {
        "orderId": "394438950581",
        "marketId": "hyperliquid-eth-usdc",
        "asset": "ETH",
        "side": "buy",
        "type": "market",
        "originalSizeBase": "0.0063",
        "remainingSizeBase": "0.0",
        "reduceOnly": false,
        "isPositionLevel": false,
        "clientOrderId": null,
        "childOrderIds": [],
        "createdAt": "2026-04-23T07:52:05.187Z",
        "limitPrice": 2395.2,
        "timeInForce": "ioc",
        "triggerPrice": 2500,
        "closedPnl": "-12.45",
        "fillPrice": 2500.5
      },
      "marketId": "<string>",
      "perpActionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "providerOrderId": "<string>",
      "explorerUrl": "https://app.hyperliquid.xyz/explorer/tx/0x8a3fb2c1d4e5f67890abcdef12345678901234567890abcdef1234567890abcd"
    }
  ]
}

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. Poll this route; the API does not push events.

Authorizations

x-api-key · string · header · required

Query Parameters

offset · number · default: 0

Offset for pagination

Required range: x >= 0

Example:

0

limit · number · default: 100

Maximum number of items to return

Required range: 1 <= x <= 500

Example:

100

providerId · enum<string>

Single provider identifier. At least one of providerId or providerIds must be provided.

Available options: hyperliquid, hyperliquid-xyz

Example:

"hyperliquid"

providerIds · enum<string>[]

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.

Available options: hyperliquid, hyperliquid-xyz

Example:

["hyperliquid", "hyperliquid-xyz"]

address · string · required

User wallet address

Example:

"0xb8c8eb8efc68796e766f6ab320db8c165c064949"

eventType · enum<string>

Filter by a single event type

Available options: order_filled, liquidation, stop_loss_triggered, take_profit_triggered

eventTypes · enum<string>[]

Filter by multiple event types (CSV or repeated query params)

Available options: order_filled, liquidation, stop_loss_triggered, take_profit_triggered

marketId · string

Filter by market (e.g. hyperliquid-eth-usdc)

Example:

"hyperliquid-eth-usdc"

perpActionId · string<uuid>

Filter events linked to a specific action

providerOrderId · string

Filter by venue order identifier (e.g. Hyperliquid oid)

fromDate · string

Include events with occurredAt >= fromDate (ISO 8601)

Example:

"2026-04-01T00:00:00.000Z"

toDate · string

Include events with occurredAt <= toDate (ISO 8601)

Example:

"2026-04-30T23:59:59.999Z"

Response

200

application/json

Paginated list of perp events

total · number · required

Total number of items available

Example:

150

offset · number · required

Offset of the current page

Example:

0

limit · number · required

Limit of the current page

Example:

100

items · object[]

Show child attributes