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

# Position Events

> Real-time whale-activity feed: opened / closed / increased / reduced / flipped, built by diffing position snapshots. Filter by type, instrument, min_notional, address, liquidation, after.

A real-time whale-activity feed: **opened**, **closed**, **increased**, **reduced**, and **flipped** events, built by diffing each wallet's position snapshots. Filter by `type`, `instrument`, `min_notional`, `address`, `liquidation`, and `after`. Polymarket has nothing like this — it exists only because we snapshot every account continuously.


## OpenAPI

````yaml GET /v3/perps/events
openapi: 3.1.0
info:
  title: PolyNode API
  description: >-
    Real-time Polymarket data API with decoded mempool settlements, OHLCV
    candles, and full Polygon JSON-RPC proxy.
  contact:
    name: PolyNode
    url: https://polynode.dev
  license:
    name: ''
  version: 2.0.0
servers:
  - url: https://api.polynode.dev
    description: Production
security:
  - api_key: []
paths:
  /v3/perps/events:
    get:
      tags:
        - Perps
      summary: Position events
      description: >-
        Real-time whale-activity feed: opened / closed / increased / reduced /
        flipped, built by diffing position snapshots. Filter by type,
        instrument, min_notional, address, liquidation, after.
      parameters:
        - name: type
          in: query
          required: false
          description: opened | closed | increased | reduced | flipped
          schema:
            type: string
        - name: instrument
          in: query
          required: false
          description: Instrument id/symbol/asset.
          schema:
            type: string
        - name: min_notional
          in: query
          required: false
          description: Only events >= this USD size.
          schema:
            type: number
        - name: address
          in: query
          required: false
          description: One account.
          schema:
            type: string
        - name: liquidation
          in: query
          required: false
          description: true | false
          schema:
            type: boolean
        - name: after
          in: query
          required: false
          description: Only rows after this time (Unix s or ms).
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Max rows.
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                data:
                  - ts: 1783619129592
                    address: 0xc469...
                    instrument_id: 1
                    symbol: SP500-USD
                    event: closed
                    prev_size: '-0.00263'
                    new_size: '0'
                    mark_price: '7542'
                    notional: '19.76'
                    unrealized_pnl: '0.35'
                    liquidation: false
components:
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: x-api-key

````