Articles in this section

See more

2022-09-02 New Convert and Withdrawal Liquidity Endpoints

  • Updated

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

 

 

Related articles