Documentation

Custom Spreads

Suggest Edits

Custom Spreads allows a Platform to programmatically specify, on a per order basis, the spread-to-be-added. This will affect the purchase or sale price that is ultimately displayed to the end customer.

Platforms know their end customers best: using the Custom Spreads feature, they can optimize for increased trading volume, thus revenue, via a simple and singular new API field (see Technical Notes section below for details).

Note

  • This feature is only offered to Platforms who use Zero Hash Liquidity Services.
  • With this launch, we created a new endpoint called POST /convert_withdraw/rfq. It functions the exact same as the GET /convert_withdraw/rfq version. Both of them will continue to be supported indefinitely until stated otherwise.

Use Cases

  • Affiliate: Platforms that act as onramps embed their payment widget within all sorts of different wallets or exchanges (i.e., an Affiliate). They may elect to apply spreads differently across the various venues.
  • Asset: Spreads can be altered depending on the asset.
  • Competition: Typically onramps are competing for volume based on the price they display their end customers (among other aspects). Platforms can use Custom Spreads in order to entice end customers to choose their payment experience over their competitors.
  • Market environment: Spreads can be altered depending on whether there is a bull or bear market.
  • Trade size: Spreads can be toggled down on larger orders and up on smaller ones, or vice-versa.

Technical Notes

  • The feature is available on the following two endpoints:
    • GET /convert_withdraw/rfq
    • POST /convert_withdraw/rfq
  • In order to define a Custom Spread, the Platform must specify a value for the spread field.
  • We will validate that submitted spread values do not breach a Zero Hash-dictated maximum threshold amount that is based on regulatory requirements. We will reject quotes made via the POST /convert_withdraw/rfq and GET /convert_withdraw/rfq endpoint if the combination of the spread and all fees (excluding the network fee), as a percentage of the total_notional, exceeds a certain threshold. This threshold depends on the current jurisdiction that the end customer resides in. In the United States (the only country that this feature is enabled for), the initial max thresholds are as follows:
    • New York (NY): 7.5% or 750 bps
    • All other states: No limit

Flow

Get Quote

Example request

POST /convert_withdraw/rfq

{
  "side": "buy",
  "participant_code": "CUST01",
  "underlying": "ETH",
  "quoted_currency": "USD",
  "total": "100",
  "withdrawal_address": "0x6E0C18D71f470cc5076A74FE34c19Ab51129C6F7",
  "fee_inclusive": true,
  "spread": "200"
}

Example Response

{
  "message": {
    "request_id": "1367f818-bc3e-4f44-9248-3b609df3ba44",
    "participant_code": "PLAT01",
    "quoted_currency": "USD",
    "side": "buy",
    "quantity": "0.045139334192361",
    "price": "2213.8120064897038273",
    "quote_id": "111cee26-f351-44c6-a82d-a132d6b4e3f5",
    "expire_ts": 1701630113828,
    "account_group": "00SCXM",
    "account_label": "general",
    "obo_participant": {
      "participant_code": "CUST01",
      "account_group": "PLAT01",
      "account_label": "general"
    },
    "network_fee_notional": "0.07",
    "network_fee_quantity": "0.0000315000003024",
    "total_notional": "100",
    "underlying": "ETH",
    "asset_cost_notional": "99.93",
    "spread_notional": "1.9986",
    "spread_bps": "200"
  }
}

Execute Quote

Example request

POST /convert_withdraw/execute

{
  "quote_id": "111cee26-f351-44c6-a82d-a132d6b4e3f5"
}

Example response

{
  "message": {
    "request_id": "0b357995-2450-48e2-8ca7-eb62ebf106bd",
    "quote": {
      "request_id": "79def6a9-895f-4ae8-a9fa-59d7137000a3",
      "participant_code": "PLAT01",
      "quoted_currency": "USD",
      "side": "buy",
      "quantity": "0.045139334192361",
      "price": "2213.8120064897038273",
      "quote_id": "af2b747e-1f1c-44e7-a3b1-9fedc903897c",
      "expire_ts": 1701630128565,
      "account_group": "00SCXM",
      "account_label": "general",
      "obo_participant": {
        "participant_code": "CUST01",
        "account_group": "PLAT01",
        "account_label": "general"
      },
      "network_fee_notional": "0.07",
      "network_fee_quantity": "0.0000315000003276",
      "total_notional": "100",
      "underlying": "ETH",
      "asset_cost_notional": "99.93",
      "spread_notional": "1.9986",
      "spread_bps": "200",
      "transaction_timestamp": 1701630125757
    },
    "trade_id": "7de4d374-1d99-4eef-b0ec-29299291935c",
  }
}

Updated 5 months ago