订阅实体

# 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

// POST /v1/account/subscriptions  →  201
{
  "id": "sub_9f2c1a7e",
  "userId": "usr_3b8d",
  "chain": 137,
  "entityId": "0x9d84ce0306f8551e02efef1680475fc0f1dc1344",
  "channels": ["ws", "webhook"],
  "status": "active",
  "fromBlock": 94146218,       // delivery starts AFTER this block
  "createdAt": "2026-09-21T02:14:07.611Z",
  "canceledAt": null
}

// GET /v1/account/subscriptions  →  200   (active + paused, newest first)
[ { "id": "sub_9f2c1a7e", "entityId": "0x9d84…", "status": "active", "fromBlock": 94146218, … } ]

// 402 — the balance will not cover the first hour
{ "statusCode": 402, "message": "insufficient balance for the first hour",
  "priceCentsPerHour": 1, "balanceCents": 0 }

// 409 — the entity has not traded recently; resend with acceptInactive
// (no figures about the entity: naming an address here would otherwise describe it for free)
{ "statusCode": 409, "message": "entity is dormant: no fill in the last 7 days",
  "status": "dormant", "hint": "resend with acceptInactive: true to subscribe anyway" }

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