> For the complete documentation index, see [llms.txt](https://noiho.gitbook.io/noiho/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://noiho.gitbook.io/noiho/developers/api-consumers/deposits-and-recovery.md).

# Top-ups, expiry and recovery

Recover eligible deposits at unchanged terms. Refund requests require operator review and do not send XMR.

| Situation                                 | Observation                        | Action                                                           |
| ----------------------------------------- | ---------------------------------- | ---------------------------------------------------------------- |
| Short deposit                             | AWAITING\_TOP\_UP; remainingAtomic | Send only the remaining amount to the same order address.        |
| Full funding observed before expiry       | Confirmation pending               | Let confirmation continue after expiry.                          |
| Incomplete or newly observed late funding | EXPIRED; funds are not returned    | Use an owner wallet session to request eligible resume.          |
| Excess payment                            | surplusAtomic                      | Request operator review. Extra deposits do not buy extra tokens. |

receivedAtomic, confirmedReceivedAtomic, remainingAtomic, surplusAtomic and depositTransactions describe deposits. Quote expiry, deposit expiry and contract deadlines are separate. The API reads the live contract window instead of assuming four hours.

POST /v1/orders/{id}/resume with {} requires the original owner wallet session, not just a partner token. It extends the deposit window at unchanged amounts, recipient and minimum output. It never creates another address or resets a payment claim.

Resume refuses an active worker, prior chain attempt, chain-bound order or refund review. Full funding first observed after expiry needs authorization even after an outage. Deposit detection pauses on expiry, but private status can still observe late deposits.

> **Warning: Refund review is not automatic payment**
>
> POST /v1/orders/{id}/refund-request records an operator review. A 202 response contains automaticPayment: false. There is no public refund execution endpoint or promised refund time. Depositing XMR does not prove ownership of the order wallet.

The order owner signs this exact message with personal\_sign. Preserve the JSON field order. expiresAt uses milliseconds and is no more than five minutes ahead. Use the deployment chain and lower-case bridge contract address.

```javascript
const message = 'Noiho refund review v1\n' + JSON.stringify({
  orderId,
  chainId,
  contract: diamondAddress.toLowerCase(),
  refundAddress,
  expiresAt,
  action: 'Request an operator-reviewed XMR refund. Eligible pre-chain orders are frozen; completed settlements remain unchanged. Network fees may be deducted. This signature does not authorize automatic payment.'
});
```

Submit { refundAddress, expiresAt, signature } with an owned-order credential. The server validates the address network and original wallet signature. Eligible pre-chain processing freezes atomically. Active workers and prior chain attempts prevent that freeze.

The same destination and review type return the existing review; a changed destination conflicts. A completed wrap can request surplus review without changing completed settlement. Operators must verify deposits, previous claims, fees and signer authorization before payment.

| Unwrap state                   | Unsigned recovery transaction                               | Effect                                                     |
| ------------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------- |
| Open                           | cancel(orderId)                                             | Returns the held XMRn, not an XMR refund.                  |
| Intended after the live window | removeUnwrapIntent(orderId), for an eligible original maker | Reopens the order. Cancellation is a separate transaction. |

Owned status returns recovery.transactions only when eligible. Recheck current chain state before signing; an LP can progress meanwhile. The user broadcasts recovery calls. windowsUnavailable means window reads failed; the API does not guess an intent-removal transaction.

Label REFUNDED only after a verified unwrap cancellation returned XMRn. A pending XMR review is not a refund. Do not reset an in-flight order to resolve a support request.