Ask us anything. We're here to help.

2022-09-06 New Convert and Withdrawal Liquidity Endpoints

API updates

General

  • We've added 2 new API endpoints:GET /convert_withdraw/rfq and POST /convert_withdraw/execute
  • They allow a platform to offer a quote, execute it, and trigger an automated on-chain withdrawal to a withdrawal address of choice
  • Digging into the details, this quote
    • Requires the platform to specify a withdrawal_address on the GET /convert_withdraw/rfq call
    • Can be locked in for 5 or 30 seconds, this is configurable
    • Includes the asset purchase price (asset_cost_notional), network fee notional value (network_fee_notional) network fee quantity (network_fee_quantity), and the cumulative purchase price (total_notional)
  • These endpoints are very similar to the existing GET /liquidity/rfq and POST /liquidity/execute endpoints except:
    • withdrawal_address is required on the GET
    • Zero Hash will auto-send the crypto on-chain as a withdrawal
  • There is a new API key permission called Convert and Withdraw that will need to be enabled at the time of API key creation in order to use these new endpoints

Use Cases

  • Payment acquirers offering an on-ramp product to their merchant partners
  • Crypto on-ramps offering a direct-to-consumer crypto purchasing product

API Sequencing

Get quote

  • A platform hits GET /convert_withdraw/rfq using the following query params:
    • participant_code: CUST01
    • underlying: BTC
    • quoted_currency: USD
    • total: 20
    • withdrawal_address (required): 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",
  }
}

bold: new fields compared to the /liquidity endpoints

 

Execute Quote

  • A 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"
       ]
   }
}

bold: see withdrawal_request_id field. this is the identifier of the withdrawal that Zero Hash has sent on-chain

 

Monitor Withdrawal

  • Platform hits GET /withdrawals/requests/12345
  • Reponse:
{
            "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 

}

bold:

  • status: the zero hash internal settlement status
    • PENDING: The request has been created and is pending approval from users. Not relevant for some use cases. If configured for 0 withdrawal approvals required, the withdrawal instantly goes into an APPROVED state.
    • APPROVED: The request is approved but not settled
    • REJECTED: The request is rejected and in a terminal state
    • PENDING_TRADE: The withdrawal has been created, but is waiting for the trade to be terminated in order for the withdrawal to settle
    • SETTLED: The funds have been deducted from the participant
  • 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 according to our confirmation thresholds, which can be viewed here in Confirms column here.
  • transaction_id: the on-chain transaction hash, useful to display out to customers so that they can follow the transaction if they wish

Performance Expectations

  • CERT: A platform should expect latency response times of less than 800ms, at the 99th percentile, at a maximum of 8 requests per seconds

* Please note that certification performance at the stated rps may be impacted (i.e. higher latency and/or error rates) given LPs own cert environment. LPs tend to limit bandwidth in cert (reduce allocated resources) based on production trading needs.

  • PROD: A platform should expect latency response times of less than 800ms, at the 99th percentile, at a maximum of 100 requests per seconds