Skip to main content

Estimate Cashout Fee

POST /merchant/settlements/estimate-fee previews the network fee for a cashout before you request it — a dry run. It returns the exact feeLocked and netAmount a real create settlement of the same body would produce, but creates nothing: no settlement, no address-book entry, no balance is claimed.

Use it to show a payer the fee up front, or to confirm a withdrawal clears its own network fee before committing. It sits between balances and create in the flow, and calling it is optional.

Example​

BODY='{"assetId":"<asset-uuid>","amount":"20","address":"T..."}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" | awk '{print $2}')
curl -X POST https://api-staging.finomesh.com/api/v1/merchant/settlements/estimate-fee \
  -H "X-Api-Key: $FINOMESH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -d "$BODY"

The body is the same as create minus label (nothing is stored). It is a read-only POST — it carries a body only so it can be signed — so it does not require an Idempotency-Key.

The address is validated for the asset's chain (EVM EIP-55 checksum, TRON/UTXO base58check) — a malformed address returns 422 validation_error before any fee is quoted, exactly as create would reject it.

Response​

{
  "success": true,
  "data": {
    "address": "T...",
    "assetName": "USDT",
    "network": "TRON",
    "amount": "20",
    "feeLocked": "2.59",
    "netAmount": "17.41",
    "sufficient": true
  }
}
  • feeLocked — the network fee that would be reserved, in the asset's units. It is the same figure a real cashout locks, because the quote prices the actual destination address (the fee is destination-aware — on TRON a first-time recipient costs more energy).
  • netAmount — amount − feeLocked, what would land at the destination.
  • sufficient — false when feeLocked ≥ amount (a real cashout would be rejected as below its own network fee). The numbers are still returned so you can see why.

The quote is a point-in-time estimate — network fees move with chain conditions, so the fee locked when you actually create the settlement may differ slightly.

tip

The fee is charged per settlement. Many small partial cashouts each pay it in full, so withdrawing your balance in one larger settlement is cheaper overall than repeated small ones — see Create Settlement → Fee efficiency.

Reference​