> ## 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:
                  - address: '0x1198f33d4f889cafaf4a07a7dea55d615bf44ebc'
                    event: increased
                    instrument_id: 6
                    liquidation: false
                    mark_price: '64128'
                    new_size: '-1.04134'
                    notional: '66779.051520'
                    prev_size: '-0.99553'
                    symbol: BTC-USD
                    timestamp: 1783739413988
                    unrealized_pnl: '-14.3833150202127'
                  - address: '0x1198f33d4f889cafaf4a07a7dea55d615bf44ebc'
                    event: flipped
                    instrument_id: 8
                    liquidation: false
                    mark_price: '77.724'
                    new_size: '569.68'
                    notional: '44277.808320'
                    prev_size: '-588.63'
                    symbol: SOL-USD
                    timestamp: 1783739413988
                    unrealized_pnl: '-143.05582313907624'
components:
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: x-api-key

````