Concepts

Transfers

Quote, create, track. The stage ladder from accepted to completed, and the failure branches.

A transfer is quoted, created, then tracked. It does not complete in one call; it climbs a stage ladder, and the honest answer to “is it done?” is usually “not yet.”

The ladder

The happy path, read from the transfer's status field:

accepted
  → reservation_pending
    → awaiting_provider_dispatch
      → awaiting_finality
        → completed

Two branches leave the path: failed, and requires_review.

Creation is racy by design: the gateway answers 200 or 202, both accepted. Read the status from body.value.status, not from the HTTP code.

Reservation is where balance moves

Available balance drops at reservation, not at completion. A source with 10,000 that reserves 4,000 and pays a 2,500 fee reads 3,500 available immediately — the arithmetic teaches itself. A source without the balance is answered reservation_denied.

Honest edge

An internal-to-internal transfer parks at awaiting_finality and stays there: the public API has no completion path for it today. The playground shows this plainly rather than pretending a green checkmark.