For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

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.

Last updated