Blockscout
SupportWebsiteGithubDiscord
  • Blockscout Open-Source Explorer
  • ๐Ÿ’กAbout BlockScout
    • Features
      • Ethereum Bytecode Database Microservice
      • Blockscout Redesign
    • Chains Using Blockscout
    • Partners & Integrations
      • RaaS Providers
      • Vera: Verifier Alliance
        • Adding your chain to the Vera database
        • Programmatic verification via the API
    • News & Media
      • Newsletter & Blog
    • Funding
      • L2 Funding Proposal
        • Aux Funding Images
    • Roadmap
  • ๐Ÿ™ŽUsing Blockscout
    • Getting Started
      • Glossary of Terms
      • Main Menu
      • Blocks
      • Transaction Types
      • Beacon Chain Withdrawal Views
    • My Account
      • Watch list
      • Private tags
      • Public tags
      • API keys
      • Custom ABI
      • Verified addresses
        • Copy and Sign Message
      • For developers
    • Dappscout Apps Marketplace
      • DApp Integration
    • Swapscout
      • Earn Merits when using Swapscout
    • Revokescout
    • Autoscout Explorer Launchpad
    • CSV Exports
    • Token Support
      • ERC-1155 Support
    • Merits
      • Streak rewards
      • Activity Pass
      • Leaderboard
      • Badges
      • FAQs
  • ๐Ÿ‘ฉโ€๐Ÿ’ปDeveloper Support
    • For Web3 Developers
    • Link to Blockscout
    • Blockscout APIs
      • Requests & Limits
      • REST API Endpoints
        • Stats API
        • Interpreter API
      • JSON RPC & ETH Compatible RPC Endpoints
        • Account
        • Block
        • Contract
        • Logs
        • Stats
        • Token
        • Transaction
        • ETH RPC API
      • GraphQL in Blockscout
    • Smart Contract Verification
      • Blockscout UI
      • Blockscout smart-contract verification API
      • Hardhat Verification Plugin
        • Sourcify Plugin for Hardhat
      • Foundry Verification
      • Sourcify Verification
      • OpenZeppelin Contract Verification
      • Automate verifications with Catapulta
      • Verification via thirdweb
      • Interacting with Smart Contracts
    • Integrate Merits
    • Chainscout chains list
  • ๐Ÿƒโ€โ™‚๏ธSetup and Run Blockscout
    • General Overview
      • Separate Indexer, Web App, and API
      • Umbrella Project Organization
      • Indexer Architecture Overview
      • ShareLock
      • EVM Version Information
    • Requirements
      • General Backend Requirements / Blockscout Backend Prerequisites
      • Backend/Frontend Compatibility Matrix
      • Hardware & Hosting Requirements
      • Database Storage Requirements
      • Client Setting Requirements
      • Node Tracing / JSON RPC Requirements
      • L2 -> L1 JSON-RPC Method Requests
    • โ˜‘๏ธENV Variables
      • Backend ENVs: Common
      • Backend ENVs: Chain-Specific
      • Backend ENVs: Integrations
      • Frontend ENVs: Common
        • ENVs
        • Deprecated ENVs
      • Deprecated Backend ENVs
        • Previous ENV Variable Home Page
    • Deployment
      • โญManual Deployment Guide
        • Ubuntu Setup
        • MacOS setup
      • โญDocker-compose Deployment
      • โญKubernetes Deployment
      • Rollup Deployment
      • ๐ŸŒŸCosmos-based chains
      • ๐Ÿ€Upgrade Guide (v7.0 & v8.0)
      • Frontend Migration
        • All-In-One Container
        • Separate Frontend
        • Customized Backend
        • Proxy Setup
        • FAQs
      • Manual Deployment (backend + old UI)
        • Manual cleaning an instance from the previous deployment
      • Terraform Deployment
      • Ansible Deployment (AWS Cloud)
        • Overview
        • Prerequisites
        • AWS Permissions & Settings
          • Creating a Secret Key Pair
          • Login with AWS CLI
          • Creating an AWS certificate for SSL
          • Manually Cleaning Terraform Related Instances
        • Variables
        • Deploying the Blockscout Infrastructure
        • Deploying Blockscout
        • Destroying Provisioned Infrastructure
        • Common Additional Tasks
        • Common Errors and Questions
        • AWS Marketplace (deprecated)
          • Overview
          • CloudFormation Template
          • Prerequisites & Install Parameters
          • Install from AWS Marketplace
          • AWS EC2 archive node setup with OpenEthereum (formerly Parity)
          • Updating & Redeploying in AWS
          • Customizing CSS
    • Microservices
      • Blockscout ENS (BENS) Name Service Integration
      • Smart Contract Verification
    • Configuration Options
      • Automating Restarts
      • Branding Configs
      • Circle CI Updates
      • Charts and Stats
      • CSS Configuration & Presets
      • Exchange Rates
      • Front-end Config Files
      • haproxy Settings for Blockscout.com
      • Internationalization
      • Logger Configs
      • Memory Usage
      • Metrics
      • My Account Settings
      • Sorting and Pagination
      • Tracing
      • Reown Project ID for contract Read/Write
    • Indexing
      • How do I fix indexer timeouts?
      • How do I update memory consumption to fix indexer memory errors?
    • Testing
    • DB schema
  • FAQs
    • User FAQs
    • Developer FAQs
  • ๐ŸงฉResources
    • EaaS: Hosting with Blockscout
    • Contributing to Blockscout
    • Bug Bounty Program
    • Media kit
    • Release Notes
      • v5.3.0: 10/23/23
      • v5.2.0: 6/20/23
      • v5.1.0: 2/13/23
      • v5.0.0: 1/11/23
    • Discord Channel
    • Discussion
    • GitHub Repo
Powered by GitBook
LogoLogo

Privacy and Terms

  • Privacy Notice
  • Terms and Conditions

Copyright ยฉ Blockscout Limited 2023-2024

On this page

Was this helpful?

Export as PDF
  1. Developer Support

Integrate Merits

Last updated 20 days ago

Was this helpful?

Attention EthGlobal Hackathon Participants. We have a $1000 Bounty available for best integration of Merits. The basic requirement is to incorporate Merits into your application in some way. Users can earn Merits through different activities in your app and you can distribute them via the API Below you will find more info on the program and the API for checking user Merits, distribution, and login processes.


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 .

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.

  • Blockscout activity pass: The activity pass allows you to earn Merits for additional Blockscout activities like verifying and interacting with contracts.

  • Telegram mini app. The telegram Blockscout Merits Bot allows for direct communication with subscribers. Users who download the bot receive extra Merits ->

  • Swapscout swapping app. Merits are incorporated in the app so that users can view their balance and earn Merits for their swaps. . 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

  1. Request your API key at:

Get Basic Merit Info for a User

Get Leaderboard ranking for a user

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.

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.

Login and Registration Flow - Get User Token

Use the following flow to get a User Token

  1. Get Nonce from Backend

  1. 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
  1. Send data to get a user token

API Calls Requiring a User Token

*Requires User Token: put the user token in the Authorization header

API hostname (and test merits dashboard):

๐Ÿ‘ฉโ€๐Ÿ’ป
Merits section of the docs
https://t.me/blockscout_merits_bot
https://swap.blockscout.com/
https://merits-staging.blockscout.com
get

Returns user information by address

Path parameters
addressstringRequired

The blockchain address of the user

Responses
200
User information
application/json
get
GET /api/v1/auth/user/{address} HTTP/1.1
Host: merits-staging.blockscout.com
Accept: */*
200

User information

{
  "exists": true,
  "user": {
    "address": "0x813399e5b08Bb50b038AA7dF6347b6AF2D161338",
    "total_balance": "981",
    "referrals": "5",
    "registered_at": "2024-10-21T13:21:20.529Z"
  }
}
get

Returns the leaderboard information for a specific user

Path parameters
addressstringRequired

The blockchain address of the user

Responses
200
User leaderboard information
application/json
get
GET /api/v1/leaderboard/users/{address} HTTP/1.1
Host: merits-staging.blockscout.com
Accept: */*
200

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
}
get

Returns the balance and distribution information for a partner

Responses
200
Partner balance information
application/json
get
GET /partner/api/v1/balance HTTP/1.1
Host: merits-staging.blockscout.com
Accept: */*
200

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"
}
get

Returns a nonce for authentication

Responses
200
Authentication nonce
application/json
get
GET /api/v1/auth/nonce HTTP/1.1
Host: merits-staging.blockscout.com
Accept: */*
200

Authentication nonce

{
  "nonce": "4MCWIDlddqsmJAAAZ",
  "merits_login_nonce": null
}
get

Returns the detailed balance information for the authenticated user

Responses
200
User balance details
application/json
get
GET /api/v1/user/balances HTTP/1.1
Host: merits-staging.blockscout.com
Accept: */*
200

User balance details

{
  "total": "2426.61",
  "staked": "0",
  "unstaked": "2426.61",
  "total_staking_rewards": "0",
  "total_referral_rewards": "20",
  "pending_referral_rewards": "0"
}
get

Returns activity logs for the authenticated user

Query parameters
page_sizeinteger ยท int32Optional

Number of items to return per page

page_tokenstringOptional

Token for pagination

Responses
200
User activity logs
application/json
get
GET /api/v1/user/logs HTTP/1.1
Host: merits-staging.blockscout.com
Accept: */*
200

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
  }
}
  • What are Blockscout Merits?
  • Using Merits as an activity incentive
  • Integrating Test Merits into your application
  • Getting Started
  • Get Basic Merit Info for a User
  • GET/api/v1/auth/user/{address}
  • Get Leaderboard ranking for a user
  • GET/api/v1/leaderboard/users/{address}
  • Partner balance and distribution information
  • GET/partner/api/v1/balance
  • Distribute Merits
  • POST/partner/api/v1/distribute
  • Login and Registration Flow - Get User Token
  • GET/api/v1/auth/nonce
  • POST/api/v1/auth/login
  • API Calls Requiring a User Token
  • GET/api/v1/user/balances
  • GET/api/v1/user/logs
post

Distributes merits to specified addresses

Body
idstringRequired

Unique ID for the distribution

Example: ethglobal_rewards-2025/05/01
descriptionstringRequired

Human readable description of the distribution

Example: Extra rewards from ProjectX for using Blockscout during ETH Global
create_missing_accountsbooleanRequired

Allow distribution for non-registered accounts if true

Example: false
expected_totalstringRequired

Total distribution amount (must equal sum of all amounts)

Example: 100.00
Responses
200
Distribution results
application/json
post
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"
}
200

Distribution results

{
  "accounts_distributed": "1",
  "accounts_created": "0"
}
post

Authenticates a user with a signed message

Body
noncestringRequired

Authentication nonce received from the server

Example: 4MCWIDlddqsmJAAAZ
messagestringRequired

The message that was signed

Example: 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
signaturestringRequired

The signature of the message

Example: 0xb11b582a6ef196a3f20fa9c84443a92c9f456c9da2ce8ceea2bcf4ce2b936e35767ac2ff56a1de635b7a5f4bcb5da89c4297efb2b4ce559123891202731752661c
Responses
200
Authentication result
application/json
post
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"
}
200

Authentication result

{
  "created": false,
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3NzM4MzY2MzEsImlhdCI6MTc0MjMwMDYzMSwibmJmIjoxNzQyMzAwNjMxLCJzdWIiOiIweDgxMzM5OWU1YjA4QmI1MGIwMzhBQTdkRjYzNDdiNkFGMkQxNsadasdasdasdsajE4MjgiLCJqdGkiOiI0TUNXSURsZGRxc21KQVpPWiIsImNoYWluX2lkIjoxLCJkb21haW4iOiJtZXJpdHMuYmxvY2tzY291dC5jb20ifQ.QQj-dn3ZmHhusq7cvtohF72yxF-605lP7WxVuVZ7BfQ"
}