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.

{
  "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

{
  "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:

"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.