Customer Withdrawal Fee

Release Details

• Release Date: Nov 17th, 2023
• Release Type: Actionable – Platforms must share the configs to start using this feature.

Summary

It is possible to charge end customers fees to withdraw assets from their platforms to external wallets similar to traditional finance fees (wire fees, account closure fees, etc.). This is a separate configuration than the one used to manage custom spreads on liquidity quotes.

If enabled, a fee will be collected on every withdrawal execution and ledgered accordingly. The current feature works in NETTED (fixed sending amount) and ADDITIVE (fixed receiving amount) settings. Fee can be set in either a flat amount or spread (or both) per asset.

Action Required

To begin using this functionality, the following platform configurations must be set per ASSET with your Zero Hash team:

• "withdrawal_spread_type": 'NETTED|ADDITIVE'
  • Netted deducts a fixed amount from the participant and any fees will be deducted from the quantity that is sent
  • Additive deducts the sending quantity in addition to any fees, so that the sending quantity is received by the destination wallet
• "withdrawal_spread_fixed_fee": '0.000015'(This is defined in base currency and NOT in atomic units. So ETH and not WEI)
• "withdrawal_spread_percentage_fee": '3'(This is in absolute % so here 3 means 3%)
• "withdrawal_spread_platform_revenue_percentage": '60'(This is the revenue % based on agreement. In this scenario, the collected withdrawal fee account 60% to platform and 40% to ZH accounts)

Sample API Payload

{
  "message": {
    "request_id": "6a8c267b-2f9e-4cb1-a8ee-901311891722",
    "withdrawal_quote_id": "129f5825-1a1a-40b6-8770-fcf102125e2b",
    "withdrawal_request_id": "e4b1135a-a88f-45c0-93c0-eef5f7e62729",
    "participant_code": "1NY182",
    "account_group": "JB41VN",
    "account_label": "general",
    "withdrawal_address": "0xD4eD0e192c2DBb5594eDA4601f9403a8af64e7cF",
    "destination_tag": "",
    "no_destination_tag": false,
    "asset": "ETH",
    "amount": "0.01",
    "amount_notional": "20.52",
    "network_fee": "0.000031500000252",
    "network_fee_notional": "0.06",
    "on_chain_status": "PENDING",
    "withdrawal_fee": "0.0001"
  }
}

Endpoints Impacted

All impacted endpoints. Include code samples or json schema for publicly available changes.

• POST /withdrawals/requests
• POST /withdrawals/execute
• GET /withdrawals/requests
• GET /withdrawals/requests/:id
• GET /withdrawals/locked_network_fee

More info under each endpoint in our API documentation.

Related Documentation

Please see the Withdrawal Spreads Guide for the most up-to-date information.