Articles in this section

See more

2022-12-16 New Netted Withdrawal Endpoints

  • Updated

Release date

Friday, December 16, 2022

 

Release type

Actionable – Updates required for platforms that have enabled withdrawals and want  to use the new feature. 

 

Summary

Currently Zero Hash supports a few configurations related to handling network fees for withdrawals:

  • Network fees can be charged to the Platform or Participant
  • Network fees can be charged in USD or native network fee asset
  • Network fees are additive, meaning that they are charged on top of the requested withdrawal amount.

Additionally, Zero Hash supports the ability for Platforms to get network fee estimates that can be used to give Participants an idea of what fees will be incurred when creating a withdrawal.

To increase flexibility for Platforms to deliver delightful end user experiences, Zero Hash is expanding its supported network fee charging models for withdrawals. The newly supported model will allow Platforms to do the following:

  • Generate a network fee quote and execute the quote upon approval from the end user
  • Network fees are quoted and debited based on the requested withdrawal asset, not the native network fee asset. This makes it easy for end users to understand how they are being charged and do not need to manage balances across multiple assets.
  • Network fees will be netted from the requested withdrawal amount. This means that end users will not owe more than they request to withdraw.

Ultimately we believe that this will streamline the ability for Platforms to deliver alternative experiences that are easier to understand for end users and show pricing that is all-inclusive of the fees that a user may incur to perform a withdrawal.

How this works:

  1. Platforms will need to be configured by Zero Hash for the service
  2. Platforms will first generate a withdrawal quote by using GET /withdrawals/locked_network_fee. This returns details about the requested withdrawal as well as a withdrawal_quote_id.
    1. Withdrawal_quote_ids are valid for 30 seconds
    2. Platforms can also pass a parameter, max_amount, which will generate a quote withdrawing the total amount from the participants account for the requested asset.
  3. After the Participant has accepted the quote, the Platform will need to generate a new request to execute the quote, by passing the withdrawal_quote_id. This will tell Zero Hash to submit the withdrawal to the blockchain. This can be done by using a new endpoint - POST /withdrawals/execute.
  4. Zero Hash will then perform the following ledgering actions after receiving the execute request:
    1. First: Generate a pending withdrawal for the total requested withdrawal amount.
    2. Second: After the withdrawal has been confirmed on the blockchain, create a confirmed withdrawal message for the total requested withdrawal amount.
    3. Third: Create a withdrawal movement for the netted withdrawal amount
    4. Fourth: Create a network_fee_transfer movement for the quoted network fee

Platforms can get updates regarding the withdrawals by querying GET /withdrawals/requests/:id.

The GET /withdrawals/locked_network_fee also features a parameter for “max_amount” this is a great feature that makes it easy to transfer the entire balance of a Participant’s particular asset account. By providing this parameter with a value of “true”, Zero Hash will take care of getting the balance and calculating the withdrawal details.

 

Action required

Platforms interested in using the feature will need to reach out to Zero Hash Customer Service team or Platform Solutions team as this new feature will require additional configurations to be able to use this. This will impact how Platforms are able to execute withdrawals and will require using the aforementioned endpoints to facilitate all withdrawals.

 

Endpoints impacted

  • NEW - GET /withdrawals/locked_network_fee
    • Accepted Parameters:
      • "participant_code"
        • Required
        • The participant code of the user requesting the withdrawal
      • "account_group"
        • Optional
        • The account group to withdraw against
      • “account_label"
      • "amount"
        • Required
        • The requested total amount of the withdrawal
      • "max_amount"
        • This is an optional field that will default to “false”. If “true” is provided then Zero Hash will debit the total balance of the user’s account for the specified asset.
        • "true"|"false"
      • "asset"
        • Required
        • Zero Hash supported asset 
      • "withdrawal_account_id"
        • Required if withdrawal_address is not provided
      • "withdrawal_address"
        • Required if withdrawal_account_id is not provided
      • "destination_tag"
        • Required for tag-based assets 
    • Example Request:
      • GET /withdrawals/locked_network_fee?participant_code=CUST01&account_group=PLAT01&account_label=general&amount=0.02&asset=BTC&withdrawal_address=mohjSavDdQYHRYXcS3uS6ttaHP8amyvX78
    • Example Response:
{
 'account_group': 'PLAT01',
 ‘request_id’: 'ac3se065c-a35d-xc3f-s802-2cefaabed6123’',
 'account_label': 'general',
 'amount': '0.02',
 'amount_notional': '339.39',
 'asset': 'BTC',
 'destination_tag': '',
 'max_amount': False,
 'net_withdrawal_notional': '339.34',
 'net_withdrawal_quantity': '0.01999718',
 'network_fee': '0.00000282',
 'network_fee_notional': '0.05',
 'participant_code': 'CUST01',
 'withdrawal_account_id': '',
 'withdrawal_address': 'mohjSavDdQYHRYXcS3uS6ttaHP8amyvX78',
 'withdrawal_quote_id': '53b9065c-185d-4c9f-ba90-2cefaabed6e1'
}
  • NEW - POST /withdrawals/execute
    • Request Body:
      • “withdrawal_quote_id”
        • Required
        • The withdrawal_quote_id generated from the GET request
    • Example Request - POST /withdrawals/execute 
{
    “withdrawal_quote_id”: “53b9065c-185d-4c9f-ba90-2cefaabed6e1”
}

Example Response

{
 “account_group”: “PLAT01”,
 “account_label': 'general”,
 “amount”: “0.02”,
 “amount_notional”: “339.7”,
 “asset”: “BTC”,
 “destination_tag”: “”,
 “network_fee”: “0.00000282”,
 “network_fee_notional”: “0.05”,
 “on_chain_status”: “PENDING”,,
 “participant_cod”': “NEPBS”,
 “request_id”: “7c7019cb-0084-4b7e-b83c-5ae677b50db8”,
 “withdrawal_account_id”: “”,
 “withdrawal_address”: “mohjSavDdQYHRYXcS3uS6ttaHP8amyvX78”,
 “withdrawal_quote_id”: “da3aa65c-0df7-44cb-ac76-e7f029888406”,
 “withdrawal_request_id”: ”27669”
}

 

Relevant documentation

 

Coming soon

N/A

Related articles