Activity subscriptions notify your application when something changes — a new block, new wallet activity, or a workflow completing. These are notification events, not data events. On receipt, use the REST endpoints to retrieve updated data.

---

List of activity subscriptions

Subscription	Description
block.activity	Block tip changes, including reorg detection
pubkeys.activity	Activity on a tracked wallet’s addresses
workflow.progress	Step-level progress for running workflows

block.activity

Fires on block tip changes, including reorg detection.

{
  "subscriptions": [
    {
      "subscribe": "block.activity"
    }
  ]
}

Event:

{
  "event": "block_activity",
  "tip": {
    "hash": "00000000590f69588b42f409796be4049ad8c4528e04f26f2fdabebbab7e0e18",
    "height": 909745,
    "time": 1755032952
  }
}

On reorg, reorg_affected contains the heights of invalidated blocks:

{
  "event": "block_activity",
  "tip": {
    "hash": "00000000590f69588b42f409796be4049ad8c4528e04f26f2fdabebbab7e0e18",
    "height": 909745,
    "time": 1755032952
  },
  "reorg_affected": [909743, 909744, 909745]
}

When reorg_affected is present, one or more previously confirmed blocks have been invalidated. blockd detects reorgs by watching for block_disconnected events from bitcoind and accumulates them until the reorg is complete before notifying clients. In practice, reorgs are almost always 1–2 blocks deep — transactions with 6 or more confirmations are considered unlikely to be affected. To determine whether your wallet is affected, cross-reference the heights in reorg_affected against the block heights of your recent, low-confirmation transactions. Cached data for those block heights should be considered stale. Re-execute affected workflows to refresh.

---

pubkeys.activity

Fires when new activity is detected on any address in a tracked pubkeys set. This includes new mempool transactions and previously unconfirmed transactions that confirm.

{
  "subscriptions": [
    {
      "subscribe": "pubkeys.activity",
      "args": {
        "pubkeys_set": "test/wallet-1"
      }
    }
  ]
}

Multiple pubkeys sets can be subscribed in a single message:

{
  "subscriptions": [
    {"subscribe": "pubkeys.activity", "args": {"pubkeys_set": "test/wallet-1"}},
    {"subscribe": "pubkeys.activity", "args": {"pubkeys_set": "test/wallet-2"}}
  ]
}

Event:

{
  "event": "pubkeys_activity",
  "pubkeys_set": "test/wallet-1"
}

On receipt, re-submit the relevant workflow and query the REST endpoints for updated transactions and UTXOs.

pubkeys.scripthash.subscribe must have been run for activity notifications to be active. A workflow that omitted that step will not receive pubkeys.activity events.

When refreshing a wallet after activity, include pubkeys.scripthash.subscribe in the refresh workflow. Previous subscriptions survive a refresh, but re-running subscribe extends coverage to newly used addresses discovered since the last import — ensuring notifications remain active as the address set grows.

---

workflow.progress

Fires throughout workflow execution with step-level progress updates. Subscribe once to receive progress events for all running workflows.

{
  "subscriptions": [
    {
      "subscribe": "workflow.progress"
    }
  ]
}

The verbose argument controls whether per-step detail is included in events — useful when tracking progress through long-running workflows. By default it is false and current_step_status is absent from events entirely. Set it to true to include it:

{
  "subscriptions": [
    {
      "subscribe": "workflow.progress",
      "args": {
        "verbose": true
      }
    }
  ]
}

Event:

{
  "event": "workflow_progress",
  "id": "Dv4h1ntX",
  "request_id": "256483",
  "name": "Import wallet-1",
  "state": "running",
  "total_steps": 7,
  "current_step_status": {
    "step": 3,
    "progress": 97.5
  }
}

Event fields:

Field	Description
id	Workflow ID
request_id	Echoed from workflow submission. Absent if not set
name	Echoed from workflow submission. Absent if not set
state	Workflow state — pending, running, completed or cancelled
total_steps	Total number of steps in the workflow
current_step_status	Per-step detail — absent when verbose is false (default), or when state is pending or completed. See current_step_status for field definitions

Use request_id to correlate progress events back to the originating request in your application when running multiple concurrent workflows.