> ## 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_status_change

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

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

## 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.

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

## 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

```json theme={null}
{
  "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

```bash theme={null}
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