API Integration (EVM) - Business Onboarding

📋 Overview

This guide covers the technical implementation of Merso System API integration for game companies.

You can integrate Merso via Web3 or using a Hybrid system.

🌐

Web3 API

Allows your players to buy NFTs using your in-game token.
🔗

Hybrid API

Built for Web3 games that allow players to buy NFTs and pay using fiat.

💡 Important

In every case, you must modify your game UX/UI by adding a button to communicate with the Merso API.

🌐

Web3 API

Full decentralized integration using Web3 libraries. Players pay with in-game tokens for NFT purchases.

Learn more →

🔗

Hybrid API

Combines Web3 NFT purchases with fiat payment processing.

Learn more →

⚠️ Before Starting

Prior to integrating the Merso System API into your game, follow these preliminary steps:

When a company expresses the desire to integrate Merso into their game, we generate an API Key and a Game ID for them. These are unique identifiers for your project and should be kept confidential to prevent unauthorized access.

The JWT is generated when you first authenticate with the /auth endpoint and will expire every 12 hours, requiring you to re-authenticate to continue making requests.

To call the /auth endpoint, the client needs to send the following parameters in the request body:

→

gameId
→

apiKey

💡 Note

We provide both parameters to the companies once they decide to implement Merso in their games.

🌍 Environments

In addition, we have two different environments in order to allow you to integrate the Merso Protocol safely in your system.

You will have to use one of these URLs depending on the integration phase:

Environment	URL
Development	`https://api3.dev.merso.io`
Production	`https://api3.merso.io`

⚠️ Important

We're using the DEVELOPMENT URL in the following examples. Please use the PRODUCTION URL when you're ready to go live.

0️⃣ Auth

Endpoint: POST /auth
Purpose: Verify API connectivity and status

Request

cURL

curl -X POST https://api3.dev.merso.io/auth \
  -H "Content-Type: application/json" \
  -d '{
    "game_id": "YOUR_GAME_ID",
    "api_key": "YOUR_API_KEY"
  }'

Response

JSON

{
    "authResult": {
        "token": "YOUR_NEW_JWT_TOKEN",
        "expires_at": "2025-08-05T21:21:13.000Z"
    }
}

Example Request Body

JavaScript

const axios = require('axios');

async function authenticateGame() {
  try {
    const response = await axios.post('/auth', {
      gameid: 'exampleGameId',
      apikey: 'exampleApiKey'
    });
    console.log('Authentication successful:', response.data.authResult);
  } catch (error) {
    if (error.response) {
      console.error('Error:', error.response.data.error);
    } else {
      console.error('Failed to authenticate game. Error Message:', error.message);
    }
  }
}

🔐 Authentication

JWT Token Setup

During onboarding, you'll receive a custom Game ID token for API access:

JavaScript

// Your custom GameID (provided during onboarding)
const GAME_ID = 'YOUR_GAME_ID';

// API base URL for your game
const API_BASE_URL = 'https://api3.merso.io/game/YOUR_GAME_ID';

Request Headers

All API requests require these headers:

JavaScript

const headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${JWT_TOKEN}`
};