API Workflow

This example shows a Platform converting $20 into BTC which is automatically sent on-chain to the specified withdrawal address. Summary of all involved participants:

Platform (participant_code: PLAT01)
End Customer (participant_code: CUST01)

Get a quote

Platform hits GET /convert_withdraw/rfq

Request

{
	"participant_code" : "CUST01",
	"side" : "buy",
	"underlying" : "BTC",
	"quoted_currency" : "USD",
	"total" : 20,
	"withdrawal_address" : "2N8PYGKSQRpHa5VDNZ4iLwxi5crpRWb3TR1"
}

Response

{
   "message": {
       "request_id": "64f34a8d-f5f5-4e37-b01d-7c6814aed4bc",
       "participant_code": "CUST01",
       "quoted_currency": "USD",
       "side": "buy",
       "quantity": "0.00087097",
       "price": "22962.90",
       "quote_id": "5aaaa8af-5d0c-4d55-868b-b56ea19a5443",
       "expire_ts": 1661449335103,
       "account_group": "00SCXM",
       "account_label": "general",
       "obo_participant": {
           "participant_code": "CUST01",
           "account_group": "PLAT01",
           "account_label": "general"
       },
       "network_fee_notional": "1.50",
       "network_fee_quantity": "0.00001",
       "total_notional": "21.5",
       "underlying": "BTC",
       "asset_cost_notional": "20"
   }
}

Execute a quote

Platform hits POST /convert_withdraw/execute using the quote_id from the response above
Response:

{
    "message": {
        "request_id": "945c41ba-c06e-4e69-aaf6-ea27cb7c75b2",
        "quote": {
            "request_id": "7a8a8526-3614-4373-9ab4-0069dc643109",
            "participant_code": "PLAT01",
            "quoted_currency": "USD",
            "side": "buy",
            "quantity": "0.00087097",
            "price": "22962.90",
            "quote_id": "dc179192-5bdf-41f2-9ffa-badb1396a0a7",
            "expire_ts": 1658512268578,
            "account_group": "00SCXM",
            "account_label": "general",
            "obo_participant": {
                "participant_code": "CUST01",
                "account_group": "PLAT01",
                "account_label": "general"
            },
     				"network_fee_notional": "1.50",
            "network_fee_quantity": "0.00001",
            "total_notional": "21.5",
            "underlying": "BTC",
				    "asset_cost_notional": "20",
            “withdrawal_request_id”:”12345”,
            "transaction_timestamp": 1658512266138
        },
        "trade_id": "9c4820e9-bf6d-4f59-ad4f-94ec9e5fc665",
        "status": "Completed",
        "trade_ids_list": [
            "9c4820e9-bf6d-4f59-ad4f-94ec9e5fc665"
        ]
    }
}

Monitor Withdrawals

When monitoring a withdrawal, the platform can hit GET /withdrawals/requests/12345 .

Response:

{
    "id": 12345,
    "withdrawal_account_id": 152089,
    "participant_code": "CUST01",
    "account_group": "PLAT01",
    "account_label": null,
    "requestor_participant_code": "PLAT01",
    "asset": "BTC",
    "requested_amount": "20",
    "settled_amount": "20",
    "gas_price": null,
    "status": "SETTLED",
    "on_chain_status": "PENDING",
    "client_withdrawal_request_id": "zh_withdrawal_17845eeffd5f71abaa85e9722e76c931a",
    "requested_timestamp": 1659542191772,
    "transaction_id": "3899526c5f986297d3b2ba29f2c4c8b0fb486bef2fc76f7c11aae2b1faf3fe76",
    "input_data": null,
    "fee_amount": 0.00001,
    "quoted_fee_amount": 0.00001 
}

Parmeter	Description
status	The Zero Hash internal settlement status. - `PENDING`: The request has been created and is pending approval from users. - `APPROVED`: The request is approved but not settled. - `REJECTED`: The request is rejected and in a terminal state. - `SETTLED`: The funds have been deducted from the participan
on_chain_status	The blockchain status. - `PENDING`: The withdrawal has been broadcasted on-chain but is not yet confirmed. - `CONFIRMED`: The withdrawal has been sufficiently confirmed on-chain.
transaction_id	The on-chain transaction hash, useful to display out to customers so that they can follow the transaction if they wish.