Ask us anything. We're here to help.

Trade and Withdrawal API Flow

General

A standard flow on the Zero Hash settlement network is to submit a trade (which moves assets from Entity A → Entity B) and then follow that up with a withdrawal soon after. The withdrawal can be either a crypto or fiat currency.

This page is a step-by-step best practice guide mainly intended for Product Managers and Engineers. 

Flow and API Sequencing

Here's an example:

  • Zero Hash integrated platform, "Platform A" with participant code ABC123, onboards a new customer, "Customer B" with participant code DEF456.
  • Customer B requests to purchase .1 BTC on Platform A.
  • Platform A submits a trade via the POST /trades endpoint. This a single-sided trade mostly used by payment processors.
{ 
"symbol":"BTC/USD",
"trade_price":"40000.00000",
"product_type":"spot",
"trade_type":"regular",
"trade_reporter":"reporter@platform.com",
"platform_code":"ABC123",
"client_trade_id":"test1",
"physical_delivery":true,
"parties_anonymous":false,
"transaction_timestamp":1569014063570,
"parties":[
{
"participant_code":"DEF456", <-- customer's participant_code
"asset":"BTC",
"amount":"0.1",
"side":"buy",
"settling": true
},
{
"participant_code":"ABC123", <-- platform's participant_code
"asset":"USD",
"amount":"4000",
"side":"sell"
"settling": false
}
]
}
  • The response to the POST /trades will return like this, see the trade_state field:
{

"message": {
"trade_id": "3e2255f7-5ffe-47b5-a0d0-ae0d79d44fe1",
"trade_state": "accepted", <-- see here
"market_identifier_code": null,
"trade_reporter_code": "RROED8",
"symbol": "BTC/USD",
"trade_quantity": "0.1",
"trade_price": "40000.00000",

etc....
  • Depending on your settlement schedule, this trade will "settle", ie transition from accepted → active → terminated with varying lengths of time. It's best to consult with a Zero Hash representative directly to confirm this.
  • Regardless, it is best practice to confirm that the trade has a trade_state of terminated before executing a withdrawal.
  • To do this, you can query GET /trades or look for a specific trade via GET /trades/:trade_id and confirm that the trade_state = terminated.
  • This means that the .1 BTC has officially moved from Platform A (ABC123) to Customer B (DEF456) and you can now submit a withdrawal.
  • If you fail to wait for the trade_state to reach terminated and you submit a withdrawal, the settled amount will be 0. In this case, you can simply resubmit a new withdrawal given that the trade has terminated.
  • Here is an example POST /withdrawals/requests payload:
{
"address":"bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
"participant_code":"DEF123",
"amount":".1",
"asset":"BTC",
"account_group":"ABC123",
"client_withdrawal_request_id":"Platform_Example"
}