Skip to main content

Distribute rewards

Distribute currency rewards and/or experience points to a list of users identified by their wallet address, social account, or e-mail address.

Use Cases​

  1. Reward users for one-off actions across your wider ecosystem, e.g., connecting their wallet to your website.

  2. Connect the On3 API to Zapier to create no-code automation's such as rewarding users for subscribing to your mailing list.

Request​

HTTP POST to /rewards with Content-Type: application/json and a JSON body of:

{
    "requestId": "876cc0af-8f20-4163-a8cd-e99674c5e0a4",
    "description": "Rewards for connecting wallets to our website",
    "message": "Well done!",
    "rewards": [
    {
        "recipient": {
            "identifierType": "WALLET_ADDRESS",
            "identifierValue": "0xd03ea8624C8C5987235048901fB614fDcA89b117"
        },
        "currencyReward": {
            "currencyId": "0681afdf-97bf-47f3-8569-731aeb6b2dd9",
            "amount": 50
        },
        "xpReward": 100
    },
    {
        "recipient": {
            "identifierType": "EMAIL",
            "identifierValue": "joe@bloggs.com"
        },
        "currencyReward": {
            "currencyId": "0681afdf-97bf-47f3-8569-731aeb6b2dd9",
            "amount": 50
        },
        "xpReward": 100
    }
    ]
}

Fields​

requestId​

Used to identify the request and ensures that no duplicates are processed in any subsequent requests. Must be generated by the client and must be unique to any previously sent requests.

Typestring
RequiredYes
LimitationsUnique to any previously sent Id. Alphanumeric characters only. No spaces. 128 characters maximum.
Examples"1"
"000005"
"88736db7-7f2d-44fc-8901-acaff1d95b72"
"testing"

description​

Generated by the client and provides context to the request for auditing purposes. Although not required it is recommended to provide a description, as this helps humans identify the request.

Typestring
RequiredNo but recommended
Limitations256 characters maximum.
Examples"Our top 10 customers this week."
"Our fanart competition winners."
"A special bonus for those being kind to others."

message​

Provided by the client and is used as the notification message to the reward recipients (note that the reward amount is automatically applied to the end of the message). If no message is provided, a generic notification is sent that tells the user they've received a reward and the amount.

Typestring
RequiredNo but recommended
Limitations256 characters maximum.
Examples"You reached the top 10 in this week's leaderboard!"
"Congratulations, you won the fanart competition!"
"Here's a special treat for being kind to your fellow community members."

rewards​

A list of rewards, containing at least one single customer identifier and the currency and/or XP rewards to distribute.

Typearray
RequiredYes
LimitationsMust contain at least one element.

rewards.recipient​

Contains the account identifying information required for sending the rewards.

rewards.recipient.identifierType​

An enum value of how to identify the account specified in rewards.recipient.identifierValue.

Typestring
RequiredYes
LimitationsMust be one of the following values (case sensitive): WALLET_ADDRESS | DISCORD_ID | TWITTER_ID | EMAIL

rewards.recipient.identifierValue​

The value of the account identifier, which must match the type specified in rewards.recipient.identifierType.

Typestring
RequiredYes
LimitationsValid wallet address for a WALLET_ADDRESS identifierType.
Valid Discord user ID for a DISCORD_ID identifierType.
Valid Twitter user ID for a TWITTER_ID identifierType.
Valid e-mail address for a EMAIL identifierType.
Examples"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
"11237863865923"
"pete@on3.one"

rewards.currencyReward​

Object containing the currency reward information.

rewards.currencyReward.currencyId​

Guid to identify the On3 currency you wish to reward.

Typestring
RequiredYes
LimitationsMust be a GUID format.
Examples"98cde5fa-d794-4a88-88bf-6622b50aaaa6"

rewards.currencyReward.currencyAmount​

The amount of currency points to reward. This can be a negative number if you want to deduct a currency, however an account's balance can not drop below zero.

Typenumber
RequiredYes
LimitationsIntegers only.
Examples1, 500, -100, 999999

rewards.xpReward​

The amount of XP points to reward.

Typenumber
RequiredNo
LimitationsPositive integers only.
Examples10, 20, 50

Response​

You should appropriately handle any failures when the failedCount is greater than 0. The failures.errors array will detail what went wrong but in 99% of cases it will be because we were unable to match the identifierType and identifierValue with a valid account or you passed an invalid currencyId. You should check your data or use a different identifier and re-send the request for any failed accounts, if appropriate.

note

A success response indicates that we were able to distribute rewards to at least one account, not all that were passed.

{
    "txId": "string",
    "requestId": "string",
    "timestamp": "string",
    "processedCount": 0,
    "failedCount": 0,
    "failures": [
        {
            "identifierType": "string",
            "identifierValue": "string",
            "errors": [
                "string"
            ]
        }
    ]
}

Codes​

CodeSuccessDescription
2XXYesThe transaction was successfully processed, with at least one reward being distributed. Any failures to distribute to rewards to a specific user is noted in the response.
4XXNoThe entire transaction failed due to a client-side error. Check the response body for details on what needs changing in the request. If the error continues and the request appears to be valid, please report this to the On3 support team.
5XXNoThe entire transaction failed due to a server-side error. If the error continues after several attempts, please report this to the On3 support team.