New Awards Endpoints

API Updates

We have launched a duo of new Awards endpoints that are closely related and are designed to be used sequentially. The primary use case is to facilitate crypto awards payments as part of a promotional program, prize pool, bonus pool, giveaway, etc. This endpoint has built-in liquidity- the purchasing and then the distribution/settlement both take place within the Zero Hash ecosystem.

New Endpoints

POST /awards/fund

Purpose: This endpoint allows the client to specify the amount, quoted currency, and asset that will ultimately be distributed to their customers. The resulting purchase will reside in a float account instantly.
Other Notes:

• Similar to Liquidity and Rewards endpoints, clients can specify a quantity (amount of BTC, for example) or a total (US Dollar amount of BTC).
• This endpoint is functional for all assets supported by ZHLS, described here.

Payload example:

{
  "underlying": "BTC",
  "quoted_currency": "USD",
  "quantity": "1"
}

POST /awards/distribute

Purpose: After the initial fund, this endpoint is used to evenly distribute the purchased crypto among the participants that you specify in the payload. The exact amount will be specified by the client in this call as well.
Payload example: In this example, let's say you want to distribute the 1 BTC among 4 of your customers.

{
  "asset": "BTC",
  "quantity": ".25",
  "participant_codes": ["CUST01","CUST02", "CUST03", "CUST04"]
}

Other Considerations

API Key Permissions

There is a new API Key Permission for "Awards". You will need to enable this when you create new API keys in order to interact with the above endpoints:

Confirmation

To validate that the fund or distribute transactions have fully settled, you can take the trade_id's from the response and then poll GET /trades:trade_id endpoint. If trade_state = "terminated", then you can be confident that your customer has received the funds in their account. Response examples:

POST /awards/fund

{
"message": {
   "request_id": "9d355b88-b2e3-4272-8ec4-352e1c7618a1",
     "quote": {
        "request_id": "9d355b88-b2e3-4272-8ec4-352e1c7618a1",
        "participant_code": "CJC9I7",
        "quoted_currency": "USD",
        "side": "buy",
        "quantity": "1",
        "price": "50000.00",
        "quote_id": "902654fc-c43e-426e-85f8-d9484b1ae382",
        "expire_ts": 1633024897781,
        "account_group": "00SCXM",
        "account_label": "awards",
        "underlying": "BTC"
               },
        "trade_id": "e629906c-76c3-4aec-8b28-5a536e00ec23",
        "status": "Completed",
        "trade_ids_list": [
        "e629906c-76c3-4aec-8b28-5a536e00ec23"
                          ]
            }
}

POST /awards/distribute

{
"message": {
      "confirms_list": [
             {
                "participant_code": "NEPBSH",
                "trade_id": "9958af6e-1bcc-4325-b1b4-02206792692b"
             },
             {
                "participant_code": "O70IOW",
                "trade_id": "bf16b834-0c4c-41b2-b991-00da3d1bed2f"
             }
        ]
    }
}

Limits

It is quite possible that your platform's promotional campaign has a large number of entrants, say 100,000. The internet has its limits, and 100,000 participant_codes do not fit within a single POST /awards/distribute request. We recommend breaking these into chunks to ensure that all distributions can be made successfully.