Skip to main content
A deposit starts as PENDING the moment OpenFX observes incoming funds (a stablecoin transfer to your address, a wire from your customer’s bank) and transitions to COMPLETED once those funds are cleared and credited to your balance, or ERROR if they don’t clear.
You don’t initiate a deposit — funds arrive via your customer’s wire or on-chain transfer, and you find out about them after the fact. That makes detection a notification problem. Webhooks (type: "deposits", eventType: "deposit.completed", with a top-level data object) are the primary channel because they fire the instant funds become spendable; polling GET /v3/fx/deposits with cursor pagination is the fallback when webhooks miss or your handler is down.

​
State machine

Status values are summarized in the Status enums reference.

​
State semantics

​
How OpenFX detects deposits

You don’t initiate a deposit through the API; funds arrive via your customer’s wire or on-chain transfer to addresses configured on your account. You observe deposits via GET /v3/fx/deposits (or GET /v3/fx/deposits/{id} to fetch a single deposit) or the Deposits webhook. Webhook payloads share the API’s convention — type: "deposits" (the resource), the dotted eventType (e.g. deposit.completed), a top-level data object holding the Deposit, camelCase keys, and string amounts; see Webhook authentication for the envelope.

​
Listing recent deposits

Cursor pagination (startingAfter / endingBefore); see Pagination. To reconcile incremental new deposits since your last check, use endingBefore with the most recent ID you’ve processed.

​
Field reference

  • id: permanent deposit ID (readable, dpt_-prefixed)
  • depositAmount, currency: what was deposited
  • network: settlement network (e.g. ETHEREUM for a stablecoin deposit, FIAT for a bank-rail deposit)
  • transactionHash: on-chain transaction hash for crypto deposits, null otherwise
  • referenceId: external reference id supplied by the customer, if any
  • comments, memo: free-text notes and an optional memo line captured at deposit time
  • paymentDetails: rail-specific reference data for fiat deposits (e.g. FEDWIRE imad/omad), keyed by transfer type; null for crypto deposits or without rail metadata
  • createdAt: when OpenFX first observed the deposit
Full schema in the API reference.

​
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.
  • Assuming status has more than three values. Deposit’s status is a closed enum: PENDING, COMPLETED, ERROR.

​
What’s next

Trade Settlement

How deposits flow into balances and out as withdrawals.

Withdrawal lifecycle

The companion state machine.

Pagination

Cursor-based reconciliation patterns.