# Deposits (/reference/deposits)

## GET /v1/deposits

`GET /v1/deposits`

### Parameters

- `limit` (query, optional, integer)
- `cursor` (query, optional, string) — Opaque cursor from the previous page's `next_cursor`.
- `customer_id` (query, optional, string (uuid))
- `wallet_id` (query, optional, string (uuid))
- `chain` (query, optional, string, one of: ethereum, bsc, polygon, arbitrum, base, avalanche, tron, solana, ton, bitcoin, dogecoin, optimism, linea, zksync, scroll)
- `status` (query, optional, string, one of: detected, confirmed, failed, orphaned)
- `since` (query, optional, string (date-time))
- `tx_hash` (query, optional, string) — Exact transaction hash or signature. Hex ids are matched case-insensitively.

### Responses

- `200` — Deposits.
  - `object` (required, string)
  - `data` (required, array)
  - `has_more` (required, boolean)
  - `next_cursor` (optional, string | null) — Opaque. Pass as `cursor` for the next page. Do not construct or parse it.
  - `data` (optional, array)
    - `object` (required, string)
    - `id` (required, string (uuid))
    - `ref` (required, string) — The MolnPay ID of this deposit — `MOLN-` and twelve hex characters, shown on the receipt in the console and quoted to support. Stable for the life of the record; unlike `id`, safe to put in front of a person.
    - `customer_id` (optional, string | null (uuid))
    - `wallet_id` (optional, string | null (uuid))
    - `chain` (required, string, one of: ethereum, bsc, polygon, arbitrum, base, avalanche, tron, solana, ton, bitcoin, dogecoin, optimism, linea, zksync, scroll)
    - `asset` (optional, object)
      - `chain` (required, string, one of: ethereum, bsc, polygon, arbitrum, base, avalanche, tron, solana, ton, bitcoin, dogecoin, optimism, linea, zksync, scroll)
      - `symbol` (required, string)
      - `decimals` (required, integer) — Authoritative scale for this asset ON THIS CHAIN. USDT and USDC are 18 on BSC and 6 everywhere else — never hardcode 6.
      - `contract` (optional, string | null) — null for the chain's native coin.
      - `logo_url` (optional, string | null) — The coin's logo, served from MolnPay's own CDN (assets.molnpay.com) — not a third party, so it is safe to render on a payment page. Decoration: it can 404 for a coin whose art we have not uploaded yet, and it is the same art our own console renders — build a picker on it rather than maintaining your own symbol-to-logo map, but never block a render on it. Sizes are 32, 64 and 128; the URL gives 64.
    - `amount` (required, string) — Amount received, atomic units.
    - `amount_decimal` (optional, string)
    - `tx_hash` (required, string)
    - `log_index` (optional, integer) — Distinguishes several transfers of the same asset within one transaction.
    - `from_address` (optional, string | null)
    - `confirmations` (optional, integer)
    - `required_confirmations` (optional, integer | null)
    - `status` (required, string, one of: detected, confirmed, failed, orphaned) — Only `confirmed` is money. `detected` is seen-on-chain but not credited. `orphaned` was confirmed and then reversed — **read `status_reason` before acting on it**: only `reorg` means the chain took the money back and you must reverse your own credit.
    - `status_reason` (optional, string | null) — Why a `failed` or `orphaned` deposit ended that way; `null` on any other status. - `reorg` — the chain reorganised and the transfer no longer exists. The credit is reversed and **you must reverse yours**. - `swap_output` — the transfer was the output of one of your own in-place swaps landing in your own address. It was briefly credited as a deposit in error and that duplicate credit has been reversed. No money moved and there is **nothing for you to reverse**. Not an enum: new reasons may be added, so treat an unrecognised value the same as `reorg` and reconcile manually. A deposit orphaned before 2026-09-19 predates this field; those rows report `reorg` unless a backfill has since identified them as `swap_output`.
    - `block_time` (optional, string | null (date-time))
    - `explorer_url` (optional, string)
    - `network_fee` (optional, string | null) — What the SENDER's transaction cost the network, in the chain's NATIVE coin, atomic units. Nobody is charged this by us and nothing is deducted from `amount` — it is published so a receipt can show what the explorer shows. It is the WHOLE TRANSACTION's fee, so when one transaction credits several deposits each reports the same figure and they must not be summed. Null = we could not determine it (unmined when we looked, a chain with no fee-by-hash lookup, or an RPC failure) — never "it was free".
    - `network_fee_decimal` (optional, string | null) — `network_fee` in whole units.
    - `network_fee_asset` (optional, string | null) — The native coin `network_fee` is denominated in — BNB, ETH, TRX.
    - `network_fee_usd` (optional, string | null) — `network_fee` in US dollars **at the price it held when the fee was paid**, not at spot — frozen when we first priced it, so an old receipt keeps saying what it cost that day. Null where we could not price it (a chain we have no quote for, a moment beyond the price history, a failed lookup) — never "it was free".
    - `ledger_tx_id` (optional, string | null (uuid))
    - `created_at` (optional, string (date-time))
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## GET /v1/deposits/{id}

`GET /v1/deposits/{id}`

### Parameters

- `id` (path, required, string (uuid))

### Responses

- `200` — The deposit.
  - `object` (required, string)
  - `id` (required, string (uuid))
  - `ref` (required, string) — The MolnPay ID of this deposit — `MOLN-` and twelve hex characters, shown on the receipt in the console and quoted to support. Stable for the life of the record; unlike `id`, safe to put in front of a person.
  - `customer_id` (optional, string | null (uuid))
  - `wallet_id` (optional, string | null (uuid))
  - `chain` (required, string, one of: ethereum, bsc, polygon, arbitrum, base, avalanche, tron, solana, ton, bitcoin, dogecoin, optimism, linea, zksync, scroll)
  - `asset` (optional, object)
    - `chain` (required, string, one of: ethereum, bsc, polygon, arbitrum, base, avalanche, tron, solana, ton, bitcoin, dogecoin, optimism, linea, zksync, scroll)
    - `symbol` (required, string)
    - `decimals` (required, integer) — Authoritative scale for this asset ON THIS CHAIN. USDT and USDC are 18 on BSC and 6 everywhere else — never hardcode 6.
    - `contract` (optional, string | null) — null for the chain's native coin.
    - `logo_url` (optional, string | null) — The coin's logo, served from MolnPay's own CDN (assets.molnpay.com) — not a third party, so it is safe to render on a payment page. Decoration: it can 404 for a coin whose art we have not uploaded yet, and it is the same art our own console renders — build a picker on it rather than maintaining your own symbol-to-logo map, but never block a render on it. Sizes are 32, 64 and 128; the URL gives 64.
  - `amount` (required, string) — Amount received, atomic units.
  - `amount_decimal` (optional, string)
  - `tx_hash` (required, string)
  - `log_index` (optional, integer) — Distinguishes several transfers of the same asset within one transaction.
  - `from_address` (optional, string | null)
  - `confirmations` (optional, integer)
  - `required_confirmations` (optional, integer | null)
  - `status` (required, string, one of: detected, confirmed, failed, orphaned) — Only `confirmed` is money. `detected` is seen-on-chain but not credited. `orphaned` was confirmed and then reversed — **read `status_reason` before acting on it**: only `reorg` means the chain took the money back and you must reverse your own credit.
  - `status_reason` (optional, string | null) — Why a `failed` or `orphaned` deposit ended that way; `null` on any other status. - `reorg` — the chain reorganised and the transfer no longer exists. The credit is reversed and **you must reverse yours**. - `swap_output` — the transfer was the output of one of your own in-place swaps landing in your own address. It was briefly credited as a deposit in error and that duplicate credit has been reversed. No money moved and there is **nothing for you to reverse**. Not an enum: new reasons may be added, so treat an unrecognised value the same as `reorg` and reconcile manually. A deposit orphaned before 2026-09-19 predates this field; those rows report `reorg` unless a backfill has since identified them as `swap_output`.
  - `block_time` (optional, string | null (date-time))
  - `explorer_url` (optional, string)
  - `network_fee` (optional, string | null) — What the SENDER's transaction cost the network, in the chain's NATIVE coin, atomic units. Nobody is charged this by us and nothing is deducted from `amount` — it is published so a receipt can show what the explorer shows. It is the WHOLE TRANSACTION's fee, so when one transaction credits several deposits each reports the same figure and they must not be summed. Null = we could not determine it (unmined when we looked, a chain with no fee-by-hash lookup, or an RPC failure) — never "it was free".
  - `network_fee_decimal` (optional, string | null) — `network_fee` in whole units.
  - `network_fee_asset` (optional, string | null) — The native coin `network_fee` is denominated in — BNB, ETH, TRX.
  - `network_fee_usd` (optional, string | null) — `network_fee` in US dollars **at the price it held when the fee was paid**, not at spot — frozen when we first priced it, so an old receipt keeps saying what it cost that day. Null where we could not price it (a chain we have no quote for, a moment beyond the price history, a failed lookup) — never "it was free".
  - `ledger_tx_id` (optional, string | null (uuid))
  - `created_at` (optional, string (date-time))
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `404` — Not found.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.