Skip to main content

Reconciliation

Webhooks are the primary signal, but you should also poll as a backstop for missed or delayed deliveries. Treat ZenVault's transfer state as the source of truth.

Poll transfers incrementally​

GET /v1/transfers?since=<last-checkpoint>&limit=200
  • since is an ISO timestamp — transfers created at/after it.
  • Page with cursor until a page returns fewer than limit items.
  • Advance your checkpoint to the newest createdAt you've processed.

Other useful filters: state, assetCanonical, accountId (source or destination), srcAccountId, destAccountId.

Deposits show up here too​

Inbound deposits appear as external transfers with srcAccountId: null and metadata.direction: "inbound" — so a single GET /v1/transfers sweep reconciles both withdrawals and deposits.

Force a re-poll​

If you need the freshest state for one transfer right now (rather than waiting for the next webhook or poll), force an on-demand provider re-poll:

POST /v1/transfers/{id}/refresh

A simple reconciler loop​

  1. GET /v1/transfers?since=<checkpoint>&limit=200, paging on cursor.
  2. For each item, upsert into your ledger keyed by transfer id (idempotent).
  3. Move your checkpoint forward.
  4. Run it on a schedule (e.g. every few minutes) alongside your webhook handler.