Skip to main content
A deposit record uses one of the four statuses listed below. A deposit starts as PENDING and ends in exactly one of the other three.
A deposit reaches COMPLETED when the funds are credited to your balance. Use the Deposit completed webhook to receive completion updates. Use GET /v3/fx/deposits with cursor pagination to reconcile deposit records and check their current statuses when a webhook is unavailable.

​
State machine

Only COMPLETED sends a webhook; poll GET /v3/fx/deposits to see the other two.

​
How OpenFX detects deposits

​
Listing recent deposits

Deposit lists use cursor pagination with startingAfter and endingBefore. See Pagination.

​
Field reference

  • id: permanent deposit ID (readable, dpt_-prefixed)
  • depositAmount, currency: what was deposited
  • network: settlement network (for example, ETHEREUM for a stablecoin deposit); null for a fiat deposit
  • transactionHash: on-chain transaction hash for crypto deposits, null otherwise
  • referenceId: external reference id supplied by the customer, if any
  • paymentDetails: payment-rail-specific identifiers keyed by transfer type (for example, Fedwire IMAD/OMAD). Present only for fiat deposits; null for crypto deposits and any deposit without rail metadata
  • createdAt: when OpenFX first observed the deposit

​
Common mistakes

  • Ignoring network for stablecoin reconciliation. A USDC deposit on Ethereum and a USDC deposit on Polygon are both USDC but different on-chain rails: read network to tell them apart.
  • Reaching for transactionHash on a fiat deposit. It’s null for fiat. Match fiat deposits on referenceId and paymentDetails instead.
  • Waiting for a webhook on a failed deposit. fx.deposit.completed is the only deposit webhook. A REJECTED or ERROR deposit sends nothing, so poll GET /v3/fx/deposits to find it.

​
What’s next

Settlement models

How deposits flow into balances and out as withdrawals.

Withdrawals

The companion state machine.

Pagination

Cursor-based reconciliation patterns.