Subscriptions

Follow a trader, billed by the hour.

Live fills: by the hour

$0.01 per entity per hour (about $7.20 a month), taken from your account balance. The first hour is charged on subscribe, one more every hour after. An empty balance pauses the subscription without creating debt. Topping up does not restart it; resume it manually, from the current head (less ~96 seconds); the rest of the paused span is not backfilled. Cancelling stops the charges; the hour already paid for is not refunded.

Subscribe to an entity

entityId takes either name an entity has: the handle the board gives you (12 characters, e.g. 7KQ2MF9X4B1C), or its 0x address if you already hold it. The board shows a handle and a masked address, because an address is readable on Polymarket by anyone who has it; the full address comes back on an entity you subscribe to, and in the fills pushed to you. channels takes ws, webhook, or both. A subscription delivers from 65 blocks before the current chain head (about 96 seconds). This is the span reorgs are re-delivered over, so a reorg at that moment cannot lose a block. Your first frames may therefore be fills from up to ~96 seconds before you subscribed: deduplicate by eventId and judge freshness by each fill’s timestamp. Anything earlier is what the export path is for.

Unlock the address first. Every pushed fill names the wallet, so following an entity requires its address to be yours (bought, unlocked from your plan, or a free unlock while it is still free); otherwise the reply is a 402 with error: "address_not_unlocked" and nothing is charged. Subscribing also spends one unit of the daily distinct-entity allowance described under Unlock an address.

# the handle the board shows, or the full 0x address if you already hold it — a masked one is a 400.
# The address must be unlocked first (POST /v1/account/reveals).
ENTITY=7KQ2MF9X4B1C

curl -X POST https://api.pmwallets.com/v1/account/subscriptions \
  -H "Authorization: Bearer $PMW_KEY" -H 'content-type: application/json' \
  -d "{\"entityId\":\"$ENTITY\",\"channels\":[\"ws\",\"webhook\"]}"

# 402 address_not_unlocked if you have not unlocked its address
# 402 if the balance will not cover the first hour; body carries price and balance
# 403 past the daily distinct-entity allowance (subscribing spends one unit, as unlocking does)
# 409 if the entity has had no fill in 7 days — resend with "acceptInactive": true

An entity with no fill in 7 days returns 409 with no figures about the entity, not even when it last traded; resend with acceptInactive: true to subscribe anyway. This prevents paying by the hour for a wallet that has stopped trading. A balance that will not cover the first hour is a 402, with the price and your balance in the body.

States are active / paused / canceled. An exhausted balance moves a subscription to paused. At most 200 subscriptions may be active at once; both subscribing and resuming are refused with a 400 past that.

List subscriptions

Returns the active and paused ones, newest first. Canceled subscriptions are not in it. To check whether an entity is still being pushed to you, ask whether it is in this list. Each carries id (what cancel and resume take), entityId, channels, status, and fromBlock, the block this subscription started delivering from.

Cancel a subscription

Billing stops here, and the hour already paid for is not refunded. Cancelling is final: the same entity can be subscribed to again at any time (POST /v1/account/subscriptions), but that is a new subscription with a new fromBlock, and the gap between is not backfilled. Returns the cancelled subscription, with status set to canceled.

Resume after running out of balance

Manual pausing is unavailable; cancel a subscription you no longer want. For a balance-related pause, when the balance cannot cover the next hour at renewal, the subscription becomes paused (pausedReason: "insufficient_balance"), delivery stops and nothing more is charged. Use this after you top up. It charges another hour and restarts from the current head (less the same 65 blocks, so fills from the last ~96 seconds of the paused span may be pushed; older paused fills are not backfilled); that span is what the export path is for. A canceled subscription cannot be resumed (409); subscribe again instead. A balance that still will not cover the first hour is a 402, and going past the 200-subscription limit is a 400.

# what is still being pushed — active and paused only, newest first
curl -s https://api.pmwallets.com/v1/account/subscriptions -H "Authorization: Bearer $PMW_KEY"

# stop one. Billing stops here; the hour already paid for is not refunded
curl -s -X DELETE https://api.pmwallets.com/v1/account/subscriptions/$SUB_ID \
  -H "Authorization: Bearer $PMW_KEY"

# restart one that ran out of balance. Charges another hour and resumes 65 blocks
# (~96 s) behind the head — those last fills may arrive (dedupe on eventId); anything
# older in the paused span is not backfilled
curl -s -X POST https://api.pmwallets.com/v1/account/subscriptions/$SUB_ID/resume \
  -H "Authorization: Bearer $PMW_KEY"

Typical delay from the block being mined is under a second; the latency page publishes measured p50 and p95 values, which are not a latency guarantee. Our servers are in the United Kingdom. Check where your bot trades from: Polymarket does not accept new API orders from the UK, the US, Germany, France and a number of other countries. Ireland (AWS eu-west-1) is the nearest region where it does, close to our servers and to Polymarket's own in London. pmwallets-copytrade check tells you whether your machine's region is allowed.