👨‍💻API Integration for Devs

Web3 Mini App Platform

Our platform enables developers to publish mini apps with integrated Web3 features. Users can play games and purchase in-app items using cryptocurrency.

Features:

• Publish and monetize mini apps

• Engage users familiar with Web3

• Enable in-app purchases with crypto

Our API is designed for easy integration via iframes, allowing you to seamlessly connect your apps to Sociogram with minimal additional code. All Web3-related aspects (such as authentication, purchases, payments, etc.) are managed by Sociogram.

---

Overview

To use our API, first obtain a MiniAppToken by registering your app. Every request to the Sociogram API must include this token in the header.

Currently, your app will not appear in the Sociogram apps list, and you can develop and test it by: https://sociogram.org/games/{your_mini_app._id}

After you have implemented all the necessary code, contact the official Sociogram representative to publish your app in the public app list. Please note that manual validation by the Sociogram team may take some time to verify that your app functions correctly.

---

Register Mini App

At present, you cannot register an app by yourself. To do so, contact the Sociogram team and provide a JSON object with the required app information:

{
  // your_app name (required)
  "name": "FunGame",
  // public name shown to users (required)
  "displayName": "Fun Game",
  // your_app description (required)
  "description": "super cool and funny game"
  // your_app icon (required)
  "avatar": "https://i.pinimg.com/736x/50/b3/60/50b36082867693a6a0b69196aa208a30.jpg"
  // url to your_app website (required)
  "clientUrl": "https://example.com/game",
  // url to your_app website api (required)
  "apiUrl": "https://example.com/api",
  // extra social urls, that will be visible in your app card in app list (optional)
  "socials": {
    "twitter": "https://x.com/VitalikButerin", // (optional)
    "telegram": "https://t.me/sociogram_channel", // (optional)
    "website": "https://coinmarketcap.com/en/currencies/dogecoin/" // (optional)
    "sociogram": "https://sociogram.org/vitalik.eth" // (optional)
  }
}

After registration, the Sociogram team will provide your MiniAppToken, which you can use to interact with the Sociogram API.

{
"miniAppKey": "1d9fd41dfda1b48c976f7fe1ae01bdf6566cda54d483be601e00b77303198ccf",
}

Until your_app is published in the app list, it will be accessible via: https://sociogram.org/games/{your_app.name}

---

User Login Process

This section describes how your app should handle and identify Sociogram users. When a user opens your app, Sociogram will request your website and include the user’s data in the GET request query parameters. For example:

GET https://{your_app.clientUrl}?address={user_wallet_address}&avatar={user_avatar_url}&domain={user_name_service}&provider=sociogram&startApp={additional_param}&hash={secret_user_app_hash}

Query Parameters:

• address (string): User wallet address (EVM or Solana)

• avatar (string): URL of the user's avatar

• domain (string): User's domain name from services such as ENS, SpaceID, or Unstoppable

• provider (string): Indicates that login data is sourced from Sociogram

• startApp (string): Passed along for referral links when the app is opened with this parameter

• hash (string): Used to verify the validity of the login data

Login Validation Process:

1. Validate the user data and the hash from the query parameters using your MiniAppToken.

2. Create an HMAC (SHA-256) using your_app_token.

3. Generate a userString by JSON-stringifying an object containing the user’s address, avatar, and domain.

4. Update the HMAC with this userString and convert the result to a hexadecimal value.

5. Compare this value with the hash received; if they match, the login is valid. Otherwise, it is considered fraudulent.

Example:

private checkAuthHash(query: SociogramAuthDto) {
    const {address, domain, avatar} = query
    query.user = {address, domain, avatar}    

    const token = this.configService.get('YOUR_APP_TOKEN')

    const keyBuffer = Buffer.from(token, 'hex')
    const userString = JSON.stringify(query.user)
    
    const hmacHex = crypto.createHmac('sha256', keyBuffer).update(userString).digest('hex')

    return hmacHex === query.hash
  }

---

In-App Purchases

This section explains how your app should handle in-app purchases using USDT tokens.

• When you create an app, it is immediately linked to your Sociogram account, and all funds from in-app purchases are credited to your account’s internal balance. You can later withdraw these funds to blockchains such as BSC, ARB, or ETH.

• To process user purchases correctly, implement the following REST endpoints along with an invoice object.

The Sociogram API will always call your endpoints with the x-app-key header whose value will be your MiniAppToken. So, you have to secure these endpoints so that only Sociogram can call them by validating this token.

Endpoints:

• create-invoice: Create an invoice for an in-app purchase. Include the price, a description of the purchase, and any payload data required to validate the purchase in later steps. This invoice object must be delivered to Sociogram via an iframe event.

• purchase-validate: After the user confirms their purchase on Sociogram, this endpoint is called with a confirmed invoice. Your system should validate the payload to ensure the invoice is genuine and that the purchase can be processed (e.g., checking item availability).

• purchase-confirmed: Once payment is successful and funds are delivered to your account, Sociogram calls this endpoint with the paid invoice. After validating the payload, your app should deliver the purchased item to the user.

Example Invoice Payload:

{
      // if you create purchases with different providers - you can name them
      provider_token: null
      title: `Burger Pack L`, // purchase title 
      description: `Buy 1000 tasty burgers`, // purchase description
      // array of prices, if you item can be sold for different currencies (gold, gem)
      prices: [ { label: `10 Usd`, amount: 10, currency: 'usd' } ], 
      // string created by you, so you can verify is invoice data valid and not fraud
      payload: invoicePayload, 
}

To send the invoice via the iframe, use:

window.parent.postMessage({ action: 'OPEN_INVOICE', { invoicePayload } }, '*')

Purchase Validate Request:

• Endpoint: POST {your_app.api_url}/purchase-validate

• Headers: x-app-token: [MiniAppToken] (string)

• Body:

  • invoice.payload (string): Purchase identifier

  • invoice.prices (array): Array of price objects confirmed by the user

    Array <{

    label: string

    price: number

    currency: string

    }>

• Response: Return true if valid; otherwise, return false.

Purchase Confirmed Request:

• Endpoint: POST {your_app.api_url}/purchase-confirmed

• Headers: x-app-token: [MiniAppToken] (string)

• Body:

  • payload (string): Purchase identifier

• Response: Return HTTP status 200 with true on success.

Once the purchase-confirmed endpoint is triggered and the payload is validated, deliver the item to the user. The purchase process is then complete.