accounts.backfill_wallet_monitor
What it does
Import a monitored wallet’s confirmed history from an earlier block up to its opening block. Read accounts wallet_backfill_quote first: it states the range and the events the import can record against the current plan’s allowance and overage terms, and its quote is required here. The opening is never changed; the earlier balance is reconciled additively and imported movements stay reviewable.
When completion and classifying every imported movement would record more than 50 events or more than the plan has left, the import waits (status awaiting_acceptance, with a warning) until you request it again with acceptWarning: true and the current quote; pass it up front to skip the wait. Asking again records nothing more; the same range again after its delivery ended resumes where it stopped, and another range replaces an unfinished import.
Before you send it
An authorized OAuth connection may call it, including a headless client. Effective membership, application grant and token permissions still apply. Describe accounts.backfill_wallet_monitor through GET /v1/catalog/commands/{name} before acting.
This command does not accept source_document_id in its envelope. Any input evidence requirements remain as documented below.
Inputs
Put these fields inside the envelope’s input object. The outer envelope names the command, a stable idempotency_key and effective_at; request and recovery rules explain those separately. Use exact minor-unit integer strings for monetary fields. Take existing IDs from prior reads or command results; choose a new identity only where the command asks for one.
Required means required within its containing object; an optional parent can be omitted.
| Field | Type | Required | Meaning and accepted values |
|---|---|---|---|
monitorId | string | Yes | Maximum length: 512. |
fromBlock | string | Yes | Pattern: "^(0|[1-9][0-9]{0,77})$". |
quote | string | Yes | Maximum length: 128. |
acceptWarning | boolean | No | Accept the event-usage warning: start although completion exceeds the events left, or complete an import waiting on its projected events. |
After acceptance
When the command emits events, its documented effects and receipt are recorded in the command transaction. The response returns commandId, replayed, the command-specific result below and emitted events with their IDs and CIDs. A command is not automatically a cash movement or revenue recognition: use the behavior above to determine what this command records.
Inspect result and the affected records or reports before continuing. Save returned identifiers for later calls. Fetch GET /v1/commands/{id} with commandId to recover the accepted receipt; retry the same intent with the same idempotency key if the response was lost. Some commands can succeed with events: [] and return a transient result and commandId without persisting a receipt. A lookup of that ID can return null; retain the returned result and verify the affected record. Retrying can re-evaluate the current state rather than replay a stored result. A domain no_change is a separate success outcome with no persisted receipt.
Result fields
See the exact schema below for the accepted shape.
All commands · Operation and errors · Reusable schemas
Keep credentials out of prompts; rehearse writes only in a disposable sandbox.
Exact request schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"const": "accounts.backfill_wallet_monitor"
},
"input": {
"type": "object",
"additionalProperties": false,
"required": [
"monitorId",
"fromBlock",
"quote"
],
"properties": {
"monitorId": {
"type": "string",
"maxLength": 512
},
"fromBlock": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,77})$"
},
"quote": {
"type": "string",
"maxLength": 128
},
"acceptWarning": {
"type": "boolean",
"description": "Accept the event-usage warning: start although completion exceeds the events left, or complete an import waiting on its projected events."
}
}
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"description": "A key you choose, stable for this one command: retrying with it returns the original receipt instead of running again; reusing it for a different command is refused."
},
"effective_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the change takes effect in the books, in UTC with Z: the business date it happened, not when you record it."
}
},
"required": [
"name",
"input",
"idempotency_key",
"effective_at"
],
"additionalProperties": false
}Accepted command receipt
{
"type": "object",
"required": [
"commandId",
"replayed",
"result",
"events"
],
"properties": {
"commandId": {
"type": "string"
},
"replayed": {
"type": "boolean"
},
"imported": {
"const": true,
"description": "The command's events are history from before the business joined Economico, recorded as an import: free of monthly events."
},
"result": {
"type": "object"
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"cid": {
"type": "string"
}
}
}
}
}
}