> For the complete documentation index, see [llms.txt](https://docs.omypayments.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omypayments.com/api/api-reference.md). # API Reference ## The `fee` object One shape, identical on every entity. All four keys are **always present**; when something does not apply or was never recorded, the value is `null` - never `0`, never an empty array. ```json { "network": [ /* FeeLeg[] or null */ ], "service": { /* FeeLeg or null */ }, "exchange": { /* FeeLeg or null */ }, "totalInUsd": "1.84" } ``` | Key | Meaning | | ------------ | ------------------------------------------------------------------------------------------------- | | `network` | Blockchain gas, as an **array of legs** - one per currency. `null` when there are none | | `service` | The OmyPayments platform fee | | `exchange` | Fee charged by the exchange. Only ever filled for swaps; other entities carry the key with `null` | | `totalInUsd` | Sum, in USD, of **only** the legs with `isChargedToMerchant: true` | ### A fee leg ```json { "amount": "210000000000000", "amountFormatted": "0.00021", "currency": "ETH", "cryptoId": "eth-ethereum", "networkId": "ETH", "amountInUsd": "0.84", "isChargedToMerchant": true } ``` | Field | Type | Meaning | | --------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `amount` | `string` | 🔴 **Minimal units** (wei / satoshi / …), same convention as every other amount in this API. Never a decimal | | `amountFormatted` | `string` | The same value as a decimal string, already divided by the currency's `decimals` | | `currency` | `string` | Ticker of the currency the fee was actually taken in | | `cryptoId` | `string \| null` | Our crypto identifier. `null` when the amount is in a network's native coin that we do not track as a separate crypto record | | `networkId` | `string \| null` | Our network identifier | | `amountInUsd` | `string \| null` | The USD value **recorded when the operation happened**. `null` when it was never recorded - see below. This is never a fresh conversion at read time | | `isChargedToMerchant` | `bool` | Whether you were actually billed for this leg | #### `isChargedToMerchant: false` Some legs are shown for transparency but are **not** billed to you, and they are **excluded from `totalInUsd`**. That happens when the gas is funded from somewhere other than your balance: * mass-payout gas - spent from your own payment address, which the Gas Manager tops up; * swap gas on the source side for address-flow merchants - self-funded from your own addresses; * swap bridge-deposit gas - not billed to anyone; * the `topUp` leg of a Gas Manager operation - the native coin we credit to your address. If you are computing "what did this operation cost me", sum only legs with `isChargedToMerchant: true` - or simply read `totalInUsd`, which already does exactly that. ### 🔴 When is `network` `null`, and why `network: null` never means "we hid something". It means there is no network leg to report. | Entity | `network` is `null` … | Why | | ------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Invoice** | **always** | The gas of the incoming payment is paid by the payer. An invoice has no network fee of ours to report | | **Deposit** | **always** | Same: an incoming operation, its gas is the sender's | | **Withdrawal** | before the transaction is sent; and **always** for address-flow merchants | Before sending, the gas is not yet known. For address-flow merchants the withdrawal leaves your own address and its gas is funded by the Gas Manager - look it up in `gas-manager/list`, not here | | **Mass payout task** | until the task has been sent | The gas is unknown before sending | | **Swap** | until at least one gas phase has completed | Legs appear as the swap progresses through its phases | | **Gas Manager operation** | **always** | The gas of the distributing transaction burns on *our* sender address and is not billed to you | ### When is `totalInUsd` `null` `totalInUsd` is `null` when at least one **charged** leg has an unknown `amountInUsd`. A partial total would look like a smaller charge than the real one, so we report nothing rather than a misleading number. In practice: * **Deposits created before this release** - the USD value of the deposit fee was not persisted back then and is never backfilled, so `service.amountInUsd` and `totalInUsd` are both `null`. The fee itself (`service.amount`) is present and correct. * **Mass payout tasks** - the gas leg has `amountInUsd: null`, but it is *not charged*, so it does not void the total. `totalInUsd` there equals the service fee and is not `null`. * **Unfinished swaps** - `totalInUsd` mirrors the stored total, which is only written when the swap finishes; the legs known so far are still returned. ### Deprecated: `gas` on withdrawals The withdrawal response still contains its original `gas` object: ```json "gas": {"amount": "210000", "amountInUsd": "0.84", "crypto": {…}, "network": {…}} ``` It is **deprecated** in favour of `fee.network[]` but keeps being returned - nothing is being removed from the withdrawal contract in this release. Both are built from the same stored columns and always agree; new integrations should read `fee.network[]`. ### Units, one more time `amount` is in **minimal units**. A 1.2 USDT fee on a 6-decimals token is `"1200000"`, and on an 18-decimals token it is `"1200000000000000000"`. Use `amountFormatted` if you want the decimal value without doing the division yourself, and `crypto.decimals` on the same response if you want to do it yourself. ### A note on USD precision `amountInUsd` is returned exactly as it was stored at the time of the operation. Different entities were historically stored at different precision, so you may see `"1.6000"` on a swap leg and `"0.84"` on a withdrawal leg in the same integration. Both are exact; neither is rounded on read. Compare them as decimals, not as strings.