Background
Using the light-weight and singular API endpointPOST /rewards; Zero Hash-connected platforms can offer crypto rewards products.
The end-result of this endpoint being called and executed is the customer receives a crypto balance of the specified amount.
Use Cases
- Credit/Debit card rewards
- Round-ups
How it Works
High Level
USD can be replace with any fiat currency supported by Zero Hash here.
Detailed Flow
1. If your organization is interested in using this feature, please get in touch with a Zero Hash representative to enable the rewards product.
2. Platforms will need to pre-fund the float account. Although the only responsibility of the platform is to send funds to Zero Hash, here are the technical details of the float account in case the platform wishes to query the balances via GET /accounts:
| Field | Value |
| Participant | Zero Hash Liquidity Services (00SCXM) |
| Asset | USD |
| Account Type | available |
| Account Group | [Platform Code] |
| Account Label | rewards |
Executing a Rewards call is technically a purchase event. If the float account balance is insufficient when compared to the purchase amount, Zero Hash will reject the call and return an error.
3. POST /rewards
You can use quantity or total. All other fields are required.
Using quantity- "I want to give my customer, CUST01, .002 BTC"
{
"participant_code":"CUST01",
"underlying_currency":"BTC",
"quoted_currency":"USD",
"quantity":".002"
}
Using total- "I want to give my customer, CUST01, $60 worth of BTC"
{
"participant_code":"CUST01",
"underlying_currency":"BTC",
"quoted_currency":"USD",
"total":"60"
}
A status of 'Completed' for this endpoint means that you successfully post crypto rewards to the participant. For any HTTP errors, you can refer to our API error handling page here API Error Handling.
4. These transactions will settle instantly. The platform can then query GET /accounts and view the balance for CUST01. In this example, the Platform (PLAT01), is making the call:
{
"asset": "BTC",
"account_owner": "CUST01",
"account_type": "available",
"account_group": "PLAT01",
"account_label": "general",
"balance": ".002",
"account_id": "14a147e8-6d71-42a2-832c-4d45d4b50d55",
"last_update": 1616428235111
},
How to view the current rewards float balance
To view the current float balance for the rewards account, you can use GET /accounts endpoint and search for the account matching the following descriptions:
|
account_owner |
00SCXM |
|
account_type |
available |
|
account_group |
your platform |
|
account_label |
rewards |
How to deal with the ‘Insufficient credit’ error message
When executing a rewards trade, you might be getting the below error message:
{"error":"Insufficient credit: insufficient credit"}
‘Insufficient credit’ means you do not have enough funds in your rewards float account to cover the buy trade. To resolve this issue, you will need to top up your rewards account in the usual way and then try to execute the buy trade afterwards.
You can refer to the above section on how to view your current rewards float balance.