/v4/reallocations/report/{campaignId}/walk

Start a Reallocation Walk

Starts a background walk of the historical merkle trees and returns a job ID immediately. Poll GET /v4/reallocations/jobs/{jobId}; once status is completed, result holds the report with each sender's settled amount and stagedAt waves filled in.

Amounts come from each marker's positive jumps between consecutive roots — a marker goes 0 → staged → 0, possibly over several waves, so only the rises are staging events.

No window to position. It covers the campaign's whole root history: settled + returned + inFlight only ever grows, so equal endpoints prove nothing happened between them and the walk bisects straight to the roots where a wave landed. Cost is O(waves × log roots) tree reads rather than one per root — a few dozen for a typical campaign, however long the chain's history.

A walk that cannot account for every wave returns walk.complete: false with an incompleteReason, and omits per-sender settled rather than reporting an understated amount as exact. That happens if it exhausts its snapshot budget, if the markers disagree with the staged total (a reallocation leaf edited outside the producer), or if the tree service holds no tree for the older roots a wave landed in.

Partly converted history. The tree service serves the roots its backfill has converted, so the walk covers the newest run of roots it can read and says in incompleteReason how many older ones it had to drop. When that run still starts before the campaign's first wave the report is exact all the same, and walk.oldestRoot names the oldest tree actually read.

The job ID is the campaign, so repeating a request joins the running or finished job instead of starting a second walk — that dedup runs before any tree read. A failed job is retried. Job state lives in Redis for 30 minutes.

Authentication: Requires either a valid x-api-key header or the back-office bearer secret.

⚠️ Beta: this endpoint is in beta. The behavior, response shape and data format may change at any time without notice.