> ## Documentation Index
> Fetch the complete documentation index at: https://public-openfx.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Deposits

> Deposit status values, detection mechanics per rail, and the reconciliation pattern for incoming funds.

A deposit record uses one of the four statuses listed below. A deposit starts as <span class="ofx-enum">PENDING</span> and ends in exactly one of the other three.

<Note title="Track deposit completion">
  A deposit reaches <span class="ofx-enum">COMPLETED</span> when the funds are
  credited to your balance. Use the [Deposit completed webhook](/v3/webhooks/deposits/deposit-completed)
  to receive completion updates. Use [`GET /v3/fx/deposits`](/v3/api-reference/trade-settlement/list-deposits)
  with cursor pagination to reconcile deposit records and check their current
  statuses when a webhook is unavailable.
</Note>

## State machine

```mermaid theme={"theme":{"light":"poimandres","dark":"poimandres"}}
%%{init: {'theme':'base','themeVariables':{'fontFamily':'Inter, system-ui, sans-serif','fontSize':'13px'}}}%%
stateDiagram-v2
  direction TB
  [*] --> PENDING: OpenFX observes incoming funds
  PENDING --> COMPLETED: Funds credited to your balance
  PENDING --> REJECTED: Bank rejects the deposit
  PENDING --> ERROR: Processing error
  COMPLETED --> [*]
  REJECTED --> [*]
  ERROR --> [*]

  classDef ok stroke-width:1px
  classDef bad stroke-width:1px
  classDef pending stroke-width:1px
  classDef hold stroke-width:1px
  classDef returned stroke-width:1px
  classDef neutral stroke-width:1px
  class PENDING pending
  class COMPLETED ok
  class REJECTED,ERROR bad
```

| Status | Meaning |
| - | - |
| <span class="ofx-status-pill ofx-status-pill--purple">PENDING</span> | OpenFX has observed the incoming funds. They are not in your balance yet |
| <span class="ofx-status-pill ofx-status-pill--green">COMPLETED</span> | The funds are credited to your balance. Final |
| <span class="ofx-status-pill ofx-status-pill--red">REJECTED</span> | The bank rejected the deposit. Final |
| <span class="ofx-status-pill ofx-status-pill--red">ERROR</span> | A processing error stopped the deposit. Final |

Only <span class="ofx-enum">COMPLETED</span> sends a webhook; poll [`GET /v3/fx/deposits`](/v3/api-reference/trade-settlement/list-deposits) to see the other two.

## How OpenFX detects deposits

| Rail | Detection mechanism |
| - | - |
| Stablecoin (see [Supported networks](/v3/supported-networks) for the chain matrix) | On-chain monitoring of OpenFX's wallet addresses |
| Wire (Fedwire) | Bank notification webhook from partner |
| ACH | Bank file processing |

## Listing recent deposits

```bash theme={"theme":{"light":"poimandres","dark":"poimandres"}}
curl "https://api.openfx.com/v3/fx/deposits?limit=25" \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE"
```

Deposit lists use cursor pagination with `startingAfter` and `endingBefore`. See [Pagination](/v3/pagination).

## Field reference

* `id`: permanent deposit ID (readable, `dpt_`-prefixed)
* `depositAmount`, `currency`: what was deposited
* `network`: settlement network (for example, <span class="ofx-enum">ETHEREUM</span> 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 <span class="ofx-enum">USDC</span> 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.** <span class="ofx-enum">fx.deposit.completed</span> is the only deposit webhook. A <span class="ofx-enum">REJECTED</span> or <span class="ofx-enum">ERROR</span> deposit sends nothing, so poll `GET /v3/fx/deposits` to find it.

## What's next

<CardGroup cols={2}>
  <Card title="Settlement models" icon="https://public-assets.openfx.com/docs/icons/settlement-models.svg" href="/v3/settlement-models">
    How deposits flow into balances and out as withdrawals.
  </Card>

  <Card title="Withdrawals" icon="https://public-assets.openfx.com/docs/icons/withdrawals.svg" href="/v3/withdrawals">
    The companion state machine.
  </Card>

  <Card title="Pagination" icon="https://public-assets.openfx.com/docs/icons/pagination.svg" href="/v3/pagination">
    Cursor-based reconciliation patterns.
  </Card>
</CardGroup>