Skip to main content
Event: position_holder_metrics
Cost: 0.025 credits per delivery
Fires with updated holder metrics for the positions you subscribe to, including holder count, total balance, and total cost basis. The full payload schema is in the auto-generated Position Holder Metrics callback reference; this page documents the filters and matching behavior.

​
When to use this

  • Track how many wallets hold a specific outcome token over time.
  • Watch total balance and cost basis concentration on positions you care about.
  • Detect accumulation or distribution as holder counts move on key positions.

​
Subscription filters

Add these to the filters object when you create the subscription.
FilterTypeRequiredDescription
position_idsstring[]YesPosition token IDs to track (at least one, max 500).
Unlike the optional filters on the PnL webhooks, position_ids is required: a subscription must name at least one position to receive deliveries.

​
Example

{
  "url": "https://your-server.com/webhooks",
  "event": "position_holder_metrics",
  "filters": {
    "position_ids": [
      "71321045679252212594626385532706912750332728571942532289631379312455583992563"
    ]
  }
}

​
Notes

  • The payload is a PositionHolderMetricsRow with holder count, total balance, and total cost basis, plus the owning condition and event holder counts when available.
  • Each subscription accepts up to 500 position IDs.
Last modified on June 13, 2026