position_status_change

Fires when a watched wallet’s CTF position changes state, including first observed opens.

Beta / polynode exclusive — this event watches explicit wallet filters and detects CTF position lifecycle changes from on-chain ERC-1155 transfer deltas.

What It Detects

position_status_change tracks state transitions for watched wallets:

• none -> open when the wallet first receives shares for a token after the webhook is active
• open -> closed when the wallet’s active-market balance returns to zero
• open -> redeemable or none -> redeemable when the position is in a resolved market and the wallet holds shares
• redeemable -> redeemed when the resolved-market balance returns to zero

Existing positions are seeded when a new watched wallet is first seen, so the webhook does not backfill historical opens that happened before registration. It emits future transitions from that point forward.

For this beta, wallet_addresses is required. Unfiltered/global position-status webhooks are intentionally not enabled.

Filters

Filter	Type	Description
wallet_addresses	string[]	Required. Wallets to watch. Use lowercase 0x addresses. Max 500.
token_ids	string[]	Optional outcome token IDs.
condition_ids	string[]	Optional market condition IDs.
event_slugs	string[]	Optional parent event slugs.
tags	string[]	Optional tag filters.
status_from	string	Optional previous status: none, open, closed, redeemable, or redeemed.
status_to	string	Optional new status: open, closed, redeemable, or redeemed.

Use status_from: "none" and status_to: "open" to detect a wallet opening a new position after registration.

Payload

{
  "id": "evt_c3d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
  "type": "position_status_change",
  "created_at": "2026-05-26T12:00:00.000000000+00:00",
  "data": {
    "wallet": "0xdb27bf2ac5d428a9c63dbc910c5e6e75560c0ae5",
    "token_id": "83970135942868582996575481879514955574496723508450032076038091728966335782753",
    "condition_id": "0x3b7ad6a803daeb1994c840027b95d711d634e79a09ff3b02625600dc9d31a8bc",
    "from_status": "none",
    "to_status": "open",
    "previous_amount": 0,
    "new_amount": 150,
    "delta_amount": 150,
    "transfer_amount": 150,
    "source": "erc1155_transfer",
    "raw_event_type": "TransferSingle",
    "source_event_id": "0x4f606b3d4c58c723e4aeb3051e3ba92100f9b0d9116e5d60f7668c34087c8167_621",
    "transaction_hash": "0x4f606b3d4c58c723e4aeb3051e3ba92100f9b0d9116e5d60f7668c34087c8167",
    "block_number": 87481303,
    "timestamp": "2026-05-26T10:58:22.000000+00:00",
    "market": "Will Bitcoin hit $100k by 2026?",
    "slug": "will-bitcoin-hit-100k-by-2026",
    "event_slug": "bitcoin-100k-2026",
    "outcome": "Yes",
    "tags": "{Crypto,Bitcoin}"
  }
}

Fields

Field	Type	Description
wallet	string	Watched wallet address.
token_id	string	ERC-1155 outcome token ID.
condition_id	string	Market condition ID.
from_status	string	Previous tracked state. none means no prior tracked balance/state.
to_status	string	New tracked state.
previous_amount	number	Previous share balance, scaled to normal token units.
new_amount	number	New share balance, scaled to normal token units.
delta_amount	number	Signed balance change for the watched wallet.
transfer_amount	number	Absolute transfer amount from the ERC-1155 event.
source	string	erc1155_transfer, split, merge, or redemption.
raw_event_type	string	Raw ERC-1155 event type.
source_event_id	string	Source CTF transfer-delta ID.
transaction_hash	string	Polygon transaction hash.
block_number	number	Polygon block number.
timestamp	string	Source ingestion timestamp.
market	string	Market question, when enrichment is available.
slug	string	Market slug, when enrichment is available.
event_slug	string	Parent event slug.
outcome	string	Outcome label.
tags	string	Market tag array as text.

Example

curl -X POST https://api.polynode.dev/v3/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/hooks/position-opened",
    "event_types": ["position_status_change"],
    "filters": {
      "wallet_addresses": ["0xdb27bf2ac5d428a9c63dbc910c5e6e75560c0ae5"],
      "status_from": "none",
      "status_to": "open"
    },
    "description": "Notify when a watched wallet opens a new Polymarket position"
  }'

Use Cases

• Copy-trading: detect when a leader opens a new position, including opens that come from ERC-1155 transfers
• Portfolio automation: react when a watched wallet fully exits a position
• Settlement workflows: detect redemption-style zero-balance transitions for resolved markets