Web3 API

This page shows you how to integrate Merso using Web3. This means that your players with pay the NFT using tokens or cryptocurrencies.

🎯 Integration Overview

The Merso API provides three core endpoints for game integration:

• /health - API health check

• /merso-user-approval - Approve ERC20 token spending

• /merso-buy-token - Purchase NFT using Merso System

📋 Web3 API Endpoints

1. Health Check

Endpoint: GET /health

Purpose: Verify API connectivity and status

Request:

curl -X GET "https://api3.dev.merso.io/health"

Response:

{
  "success": true,
  "message": "Merso Backend is running",
}

JavaScript Example:

async function checkAPIHealth() {
  try {
    const response = await fetch(`https://api3.dev.merso.io/health`, {
      method: 'GET',
      headers: headers
    });
    
    const data = await response.json();
    console.log('API Status:', data.status);
    return data;
  } catch (error) {
    console.error('Health check failed:', error);
  }
}

2. User Approval

Endpoint: POST /merso-user-approval

Purpose: Approve Merso System to spend user's ERC20 tokens. You can choose between PNPL or Upfront approve. New optional params added.

Request :

curl -X POST "https://api3.dev.merso.io/merso-user-approval" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "userAddress": "VALID_USER_ADDRESS",
    "userEmail": "[e-mail]",
    "tokenPrice": "ERC721_PRICE_IN_WEI",
    "collectionAddress": "YOUR_GAME_ERC721_ADDRESS",
    "paymentMode": "DESIRED_PAYMENT_MODE",
    "tokenAddress": "DESIRED_ERC20_TOKEN_ADDRESS",
    "chainId: "YOUR_CHAIN_ID"
}'

Parameters:

• userAddress (string): User's wallet address.

• userEmail (string): User's in-game email.

• tokenPrice (string): Amount to approve (in wei).

• collectionAddress (string): NFT collection contract address.

Optionals:

• paymentMode (string): Desired way to pay the asset. Values must be: "BNPL" or "UPFRONT". Default in case you don't want/need it to send is set as "BNPL"

• chainId (int): EVM chain ID used to process the payment. If not provided, the protocol will use the default chain configured during the game’s registration process.

• tokenAddress (string): ERC-20 token contract address used for the payment. If not provided, the protocol will use the default payment token configured during the game’s registration process.

Response:

{
  "success": true,
  "txData": {
    "to": "YOUR_GAME_ERC20_ADDRESS",
    "from": "VALID_USER_ADDRESS",
    "data": "0xa9059cbb000000000000000000000000...",
    "gasPrice": "20000000000",
    "nonce": 5,
    "value": "0"
  },
}

JavaScript Example:

async function approveTokens(userAddress, userEmail, tokenPrice,
                             collectionAddress, paymentMode, tokenAddress, chainId) {
  try {
	const approvalResponse = await fetch(
        `https://api3.dev.merso.io/merso-user-approval`,
        {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            Authorization: `Bearer ${jwtToken}`,
          },
          body: JSON.stringify({
            userAddress: userAddress,
            userEmail: userEmail,
            tokenPrice: tokenPrice,
            collectionAddress: collectionAddress,
            paymentMode: paymentMode,
            tokenAddress: tokenAddress,
            chainId: chainId
          }),
        }
      );
    
      if (!approvalResponse.ok) {
        throw new Error("Approval API request failed");
      }
      const approvalData: ApiResponse = await approvalResponse.json();
      
      // Execute approval transaction
      const approvalTx = await signer.sendTransaction({
        to: approvalData.txData.to,
        from: approvalData.txData.from,
        data: approvalData.txData.data,
        gasPrice: approvalData.txData.gasPrice,
        nonce: approvalData.txData.nonce,
        value: approvalData.txData.value,
      });

      // Wait for approval transaction to be mined
      await approvalTx.wait();

  } catch (error) {
    console.error('Approval failed:', error);
    throw error;
  }
}

3. Buy Token with Merso

Endpoint: POST /merso-buy-token

Purpose: Purchase NFT using Merso functionality. You can choose between PNPL or Upfront payment. New optional params added.

Request:

curl -X POST "https://api3.dev.merso.io/merso-buy-token" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "userAddress": "VALID_USER_ADDRESS",
    "tokenId": "1",
    "tokenPrice": "ERC721_PRICE_IN_WEI",
    "collectionAddress": "YOUR_GAME_ERC721_ADDRESS",
    "paymentMode: "DESIRED_PAYMENT_MODE",
    "tokenAddress": "DESIRED_ERC20_TOKEN_ADDRESS",
    "chainId: "YOUR_CHAIN_ID"
}'

Parameters:

• userAddress (string): User's wallet address.

• tokenId (string): NFT token ID to purchase.

• tokenPrice (string): Total price in wei.

• collectionAddress (string): NFT collection contract address.

Optionals:

• paymentMode (string): Desired way to pay the asset. Values must be: "BNPL" or "UPFRONT". Default in case you don't want/need it to send is set as "BNPL"

• chainId (int): EVM chain ID used to process the payment. If not provided, the protocol will use the default chain configured during the game’s registration process.

• tokenAddress (string): ERC-20 token contract address used for the payment. If not provided, the protocol will use the default payment token configured during the game’s registration process.

Response:

{
  "success": true,
  "txData": {
    "to": "YOUR_BNPL_ADDRESS",
    "from": "VALID_USER_ADDRESS",
    "data": "0x...",
    "gasPrice": "20000000000",
    "nonce": 6,
    "value": "0"
  },
}

JavaScript Example:

async function buyNFTWithMerso(userAddress, tokenId, tokenPrice, collectionAddress, paymentMode, tokenAddress, chainId) {
  try {
    const buyResponse = await fetch(`https://api3.dev.merso.io/merso-buy-token`, {
      method: 'POST',
      headers: {
            "Content-Type": "application/json",
            Authorization: `Bearer ${jwtToken}`,
          },
      body: JSON.stringify({
        userAddress: userAddres,
        tokenId: tokenId,
        tokenPrice: tokenPrice,
        collectionAddress: collectionAddress,
        paymentMode: paymentMode,
        tokenAddress: tokenAddress,
        chainId: chainId
      })
    });
    
      if (!buyResponse.ok) {
        throw new Error("Buy API request failed");
      }

      const buyData: ApiResponse = await buyResponse.json();
      
      // Execute buy transaction
      const buyTx = await signer.sendTransaction({
        to: buyData.txData.to,
        from: buyData.txData.from,
        data: buyData.txData.data,
        gasPrice: buyData.txData.gasPrice,
        nonce: buyData.txData.nonce,
        value: buyData.txData.value,
      });

      // Wait for buy transaction to be mined
      await buyTx.wait();
      
  } catch (error) {
    console.error('NFT purchase failed:', error);
    throw error;
  }
}

🔄 Integration Flow

Complete Purchase Flow

  const handleBuy = async (tokenId: number, userEmail: string, price: string, paymentMode: string, tokenAddress: string, chainId: number) => {

	if (!window.ethereum || !walletAddress) return;
    setIsLoading(true);
    setError("");

	try {
      const provider = new ethers.BrowserProvider(window.ethereum as any);
      const signer = await provider.getSigner();
      const tokenPrice = ethers.parseEther(price).toString();

      // Step 1: Call your API for approval transaction
      const approvalResponse = await fetch(
        `https://api3.dev.merso.io/merso-user-approval`,
        {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
	    Authorization: `Bearer ${jwtToken}`
          },
          body: JSON.stringify({
            userAddress: walletAddress,
            userEmail: userEmail,
            tokenPrice: tokenPrice,
            collectionAddress: YOUR_ERC721_ADDRESS,
						tokenAddress: tokenAddress,
            chainId: chainId
          }),
        }
      );

      if (!approvalResponse.ok) {
        throw new Error("Approval API request failed");
      }

      const approvalData: ApiResponse = await approvalResponse.json();

      if (!approvalData.success) {
        throw new Error("Approval API returned error");
      }

      // Execute approval transaction
      const approvalTx = await signer.sendTransaction({
        to: approvalData.txData.to,
        from: approvalData.txData.from,
        data: approvalData.txData.data,
        gasPrice: approvalData.txData.gasPrice,
        nonce: approvalData.txData.nonce,
        value: approvalData.txData.value,
      });

      // Wait for approval transaction to be mined
      await approvalTx.wait();
      console.log("Approval transaction confirmed:", approvalTx.hash);

	  // Step 2: Call your API for buy transaction
      const buyResponse = await fetch(
        `https://api3.dev.merso.io/merso-buy-token`,
        {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
	    Authorization: `Bearer ${jwtToken}`
          },

          body: JSON.stringify({
            userAddress: walletAddress,
            tokenId: tokenId,
            tokenPrice: tokenPrice,
            collectionAddress: MOCK_ERC721_ADDRESS,
						paymentMode: paymentMode,
						tokenAddress: tokenAddress,
            chainId: chainId 
          }),
        }
      );

      if (!buyResponse.ok) {
        throw new Error("Buy API request failed");
      }

      const buyData: ApiResponse = await buyResponse.json();

      if (!buyData.success) {
        throw new Error("Buy API returned error");
      }

      // Execute buy transaction
      const buyTx = await signer.sendTransaction({
        to: buyData.txData.to,
        from: buyData.txData.from,
        data: buyData.txData.data,
        gasPrice: buyData.txData.gasPrice,
        nonce: buyData.txData.nonce,
        value: buyData.txData.value,
      });

      // Wait for buy transaction to be mined
      await buyTx.wait();
      console.log("Buy transaction confirmed:", buyTx.hash);

    } catch (err: any) {
      setError(
        "Transaction failed: " +
          (err?.reason || err?.message || "Unknown error")
      );
      console.error(err);
    }
    setIsLoading(false);
  };