Integrate Merits
Merits for incentives testing
This guide features APIs for integrating test Merits into your application.
What are Blockscout Merits?
Merits are digital rewards collected by interacting with Blockscout and Blockscout-related apps and by participating in various activities (like contests, X participation, telegram participation, app participation and more). Merits are chain agnostic and can be incorporated into any application. For more details see the Merits section of the docs.
Using Merits as an activity incentive
Merits are used to incentivize different activities within the Blockscout universe. For example:
Blockscout explorer basics: Earn Merits by signing up for the program. Once you are signed up, you can earn additional Merits by completing a daily claim. You can also share your referral code and earn Merits when new users sign up with that code.
Telegram mini app. The telegram Blockscout Merits Bot allows for direct communication with subscribers. Users who download the bot receive extra Merits -> https://t.me/blockscout_merits_bot
Swapscout swapping app. Merits are incorporated in the app so that users can view their balance and earn Merits for their swaps. https://swap.blockscout.com/. This is a good example of an external app that incorporates Merits.
Revokescout app. Merits are used to incentivize users but there is no sign in or interface. We simply check addresses that use the application and distribute Merits to those addresses.
Blockscout campaigns. Participants in time-gated campaigns such as rating Dapps or Twitter(X) contests receive additional Merits. We collect the Ethereum addresses of winners and distribute Merits manually.
Partner campaigns. Merits are allocated to users of other protocols as an additional incentive for use. Partners provide us with a list of addresses and tasks they completed and we distribute accordingly.
Integrating Test Merits into your application
Merits can be integrated in different ways into your application. Ideas may be to include Merits as a reward for user interactions with your app or a general reward for any activity. Merits can be distributed to users via the API.
Users can have the ability to sign up for Merits through your app and/or login to their Merits account. You can also display individual Merits balances and leaderboard balances within your application. However, these are optional integrations.
To qualify for the bounty, you simply need to provide Merit incentives for certain activities, and then distribute those merits appropriately. As long as you have the participant's Ethereum address you can distribute Merits.
Note: You can retrieve basic data without an API key, but for interactivity purposes you will need to request one via our Discord channel. See below.
Getting started
Request your API key at: https://ethglobal.com/discord in the #partner-blockscout channel
API hostname (and test merits dashboard): https://merits-staging.blockscout.com
Get basic Merit info for a user
Returns user information by address
The blockchain address of the user
GET /api/v1/auth/user/{address} HTTP/1.1
Host: merits-staging.blockscout.com
Accept: */*
User information
{
"exists": true,
"user": {
"address": "0x813399e5b08Bb50b038AA7dF6347b6AF2D161338",
"total_balance": "981",
"referrals": "5",
"registered_at": "2024-10-21T13:21:20.529Z"
}
}
Get leaderboard ranking for a user
Returns the leaderboard information for a specific user
The blockchain address of the user
GET /api/v1/leaderboard/users/{address} HTTP/1.1
Host: merits-staging.blockscout.com
Accept: */*
User leaderboard information
{
"address": "0x813399e5b1102950b038AA7dF6347b6AF21102828",
"total_balance": "981",
"referrals": "5",
"registered_at": "2024-10-21T13:21:20.529Z",
"rank": "1",
"users_below": "71569",
"top_percent": 0.01
}
Partner balance and distribution information
When you request an API key you become a partner! You will receive a balance of test Merits which can then be distributed to your users. * Requires API Key - Add the assigned API KEY in the Authorization header to see your information.
Returns the balance and distribution information for a partner
GET /partner/api/v1/balance HTTP/1.1
Host: merits-staging.blockscout.com
Accept: */*
Partner balance information
{
"name": "partner-1",
"api_key": "4VF6LDF7RC64CNGWXOECF8J1LJ62W5HS",
"valid_since": "2025-05-01T00:00:00.000Z",
"valid_until": "2025-06-01T00:00:00.000Z",
"rate": "0.1",
"balance": "1234.5",
"total_distributed": "100",
"updated_at": "2025-04-16T11:26:31.757Z"
}
Distribute Merits
* Requires API Key - Add the assigned API KEY in the Authorization header to add your distribution information.
Notes:
id
must be unique per each API KEY, so it’s recommended to include date or time period describing the distribution period.distributions
Max
1000
wallets per distribution.Amounts less than
0.01
per address are not allowed.Amounts can be in decimals, max 2 decimal digits precision is recommended.
create_missing_accounts
true
: allows distributions to not yet registered Merits accounts.false
: only allow distributions to users that are already registered.
Distributes merits to specified addresses
Unique ID for the distribution
ethglobal_rewards-2025/05/01
Human readable description of the distribution
Extra rewards from ProjectX for using Blockscout during ETH Global
Allow distribution for non-registered accounts if true
false
Total distribution amount (must equal sum of all amounts)
100.00
POST /partner/api/v1/distribute HTTP/1.1
Host: merits-staging.blockscout.com
Content-Type: application/json
Accept: */*
Content-Length: 270
{
"id": "ethglobal_rewards-2025/05/01",
"description": "Extra rewards from ProjectX for using Blockscout during ETH Global",
"distributions": [
{
"address": "0x813399e5b08Bb50b038AA7dF6347b6AF2D161338",
"amount": "10.50"
}
],
"create_missing_accounts": false,
"expected_total": "100.00"
}
Distribution results
{
"accounts_distributed": "1",
"accounts_created": "0"
}
Login and Registration Flow - Get User Token
Use the following flow to get a User Token
Get Nonce from Backend
Returns a nonce for authentication
GET /api/v1/auth/nonce HTTP/1.1
Host: merits-staging.blockscout.com
Accept: */*
Authentication nonce
{
"nonce": "4MCWIDlddqsmJAAAZ",
"merits_login_nonce": null
}
Ask for a signature from a user with a predefined message
// Formatted message example
merits.blockscout.com wants you to sign in with your Ethereum account:
0x813399e5b08Bb50b038AA7dF6347b6AF2D163328
Sign-In for the Blockscout Merits program.
URI:
https://merits-staging.blockscout.com
Version: 1
Chain ID: 1
Nonce: 4MCWIDlddqsmJAZOZ
Issued At: 2025-03-18T12:23:51.549Z
Expiration Time: 2026-03-18T12:23:51.549Z
Send data to get a user token
Authenticates a user with a signed message
Authentication nonce received from the server
4MCWIDlddqsmJAAAZ
The message that was signed
merits.blockscout.com wants you to sign in with your Ethereum account: 0x813399e5b08Bb50b038AA7dF6347b6AF2D161338 Sign-In for the Blockscout Merits program. URI: https://merits.blockscout.com Version: 1 Chain ID: 1 Nonce: 4MCWIDlddqsmJAAAZ Issued At: 2025-03-18T12:23:51.549Z Expiration Time: 2026-03-18T12:23:51.549Z
The signature of the message
0xb11b582a6ef196a3f20fa9c84443a92c9f456c9da2ce8ceea2bcf4ce2b936e35767ac2ff56a1de635b7a5f4bcb5da89c4297efb2b4ce559123891202731752661c
POST /api/v1/auth/login HTTP/1.1
Host: merits-staging.blockscout.com
Content-Type: application/json
Accept: */*
Content-Length: 518
{
"nonce": "4MCWIDlddqsmJAAAZ",
"message": "merits.blockscout.com wants you to sign in with your Ethereum account:\n0x813399e5b08Bb50b038AA7dF6347b6AF2D161338\n\nSign-In for the Blockscout Merits program.\n\nURI: https://merits.blockscout.com\nVersion: 1\nChain ID: 1\nNonce: 4MCWIDlddqsmJAAAZ\nIssued At: 2025-03-18T12:23:51.549Z\nExpiration Time: 2026-03-18T12:23:51.549Z",
"signature": "0xb11b582a6ef196a3f20fa9c84443a92c9f456c9da2ce8ceea2bcf4ce2b936e35767ac2ff56a1de635b7a5f4bcb5da89c4297efb2b4ce559123891202731752661c"
}
Authentication result
{
"created": false,
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3NzM4MzY2MzEsImlhdCI6MTc0MjMwMDYzMSwibmJmIjoxNzQyMzAwNjMxLCJzdWIiOiIweDgxMzM5OWU1YjA4QmI1MGIwMzhBQTdkRjYzNDdiNkFGMkQxNsadasdasdasdsajE4MjgiLCJqdGkiOiI0TUNXSURsZGRxc21KQVpPWiIsImNoYWluX2lkIjoxLCJkb21haW4iOiJtZXJpdHMuYmxvY2tzY291dC5jb20ifQ.QQj-dn3ZmHhusq7cvtohF72yxF-605lP7WxVuVZ7BfQ"
}
API Calls Requiring a User Token
*Requires User Token: put the user token in the Authorization header
Returns the detailed balance information for the authenticated user
GET /api/v1/user/balances HTTP/1.1
Host: merits-staging.blockscout.com
Accept: */*
User balance details
{
"total": "2426.61",
"staked": "0",
"unstaked": "2426.61",
"total_staking_rewards": "0",
"total_referral_rewards": "20",
"pending_referral_rewards": "0"
}
Returns activity logs for the authenticated user
Number of items to return per page
Token for pagination
GET /api/v1/user/logs HTTP/1.1
Host: merits-staging.blockscout.com
Accept: */*
User activity logs
{
"items": [
{
"action": "daily_reward",
"details": {
"streak": 1,
"amount": "10",
"date": "2025-03-18"
},
"timestamp": "2025-03-18T12:13:20.110Z"
}
],
"next_page_params": {
"page_token": "1732067538792818,984727",
"page_size": 50
}
}
Last updated
Was this helpful?