API Integration

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

You can integrate Merso via web3, via web2 or using an hybrid system.

The web3 API allows you players to buy NFTs using your in-game token, while the web2 API is the recommended way if your players buy in-game items (non NFTs) and they pay using fiat. On the other hand, the hybrid model is built for those Web3 games that allow their players buy NFTs and pay them using fiat.

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

⚠️ 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

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

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

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

Development: https://api3.dev.merso.io

Production: https://api3.merso.io

⚠️ We're using the DEVELOPMENT URL on the following examples. Please, use the PRODUCTION URL if you need.

0. Auth

Endpoint: POST /auth

Purpose: Verify API connectivity and status

Request:

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:

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

Example Request Body:

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:

// 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:

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