Integrate Your Game with Sverse and Mint NFTs via API

Developer Guide

1. Overview

This guide explains how to integrate your game with Sverse in a multi-chain environment and mint NFTs via the Sverse Developer Platform API.

By integrating with Sverse, your game can:

authenticate and manage your application/project,
provision wallets (custodial or linked external addresses),
create chain-aware NFT collections,
mint NFTs to players,
and receive real-time events through webhooks.

2. Prerequisites

Before starting, you should have:

A Sverse developer account (via SDeveloper Portal)
A project/application created in Sverse (or permission to create one)
A target chain selected (via /v1/chains)
A server backend (recommended) to store secrets and call the API securely

Important:

Do not call privileged endpoints directly from the client.
Keep API keys and client secrets server-side.

3. Choose Environment and Base URL

Use Sandbox during development:

Sandbox: https://sandbox.sverse.io

Switch to Production for launch:

Production: https://open.sverse.io

All endpoint paths remain the same between environments.

4. Authenticate (Get Access Token)

Request

curl -X POST "https://sandbox.sverse.io/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grantType": "client_credentials",
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "scopes": ["projects:write","wallets:write","nfts:write","transactions:write","webhooks:write"]
  }'

Response (example)

{
  "accessToken": "eyJhbGciOi...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "scope": "projects:write wallets:write nfts:write transactions:write webhooks:write"
}

Use the returned accessToken as:

Authorization: Bearer <token>

5. Create or Select Your Project (Game/App)

A “project” represents your game/application in Sverse.

Create Project

curl -X POST "https://sandbox.sverse.io/v1/projects" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Game",
    "description": "Sverse-integrated game experience"
  }'

Save the returned projectId.

6. Select Supported Chains

List available chains in the current environment:

curl -X GET "https://sandbox.sverse.io/v1/chains" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Pick a chainKey for your NFT collection and mint flow, for example:

ton-mainnet / ton-testnet
eth-mainnet / eth-sepolia

7. Create or Link Player Wallets

Sverse supports a logical wallet that can have addresses on multiple chains.

7.1 Create a Wallet for a Player (Logical Wallet)

curl -X POST "https://sandbox.sverse.io/v1/wallets" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerType": "member",
    "ownerId": "MEMBER_ID"
  }'

You will receive walletId.

Where do you get MEMBER_ID? Your game should maintain a mapping between your user identity and the Sverse app member (see Section 8).

7.2 Create or Link a Chain Address

Option A: Custodial address (Sverse-managed)

curl -X POST "https://sandbox.sverse.io/v1/wallets/WALLET_ID/addresses" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chainKey": "ton-testnet",
    "custodyType": "custodial"
  }'

Option B: External address (player-managed)

curl -X POST "https://sandbox.sverse.io/v1/wallets/WALLET_ID/addresses" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chainKey": "eth-sepolia",
    "custodyType": "external",
    "address": "0xABCDEF..."
  }'

8. Register Players as App Members

To track participation in your game, create or update app members.

curl -X POST "https://sandbox.sverse.io/v1/projects/PROJECT_ID/members" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "SVR_USER_ID",
    "externalId": "YOUR_GAME_USER_ID",
    "displayName": "PlayerOne",
    "metadata": {
      "region": "VN",
      "platform": "telegram"
    }
  }'

This creates/updates the “membership” record that your game can query later.

9. Create an NFT Collection (Chain-Aware)

An NFT collection is tied to a chain and token standard.

curl -X POST "https://sandbox.sverse.io/v1/nfts/collections" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "PROJECT_ID",
    "chainKey": "ton-testnet",
    "tokenStandard": "jetton",
    "name": "My Game Items",
    "description": "In-game item NFTs for My Game",
    "metadata": {
      "category": "game-items"
    }
  }'

Save the returned collectionId.

Note:

If your platform uses ERC-721/1155, set tokenStandard accordingly.
contractAddress may be optional depending on whether Sverse deploys it or you provide it.

10. Mint an NFT to a Player Wallet

Minting happens in the context of the collection.

curl -X POST "https://sandbox.sverse.io/v1/nfts/collections/COLLECTION_ID/items" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerWalletId": "WALLET_ID",
    "metadataUri": "ipfs://YOUR_METADATA_URI",
    "attributes": {
      "itemType": "sword",
      "rarity": "epic",
      "attack": 12
    },
    "idempotencyKey": "mint_player_123_item_456"
  }'

Response (example)

{
  "transaction": {
    "id": "tx_01HXYZ...",
    "type": "mint",
    "status": "pending",
    "chainKey": "ton-testnet",
    "createdAt": "2026-01-10T04:20:00Z"
  },
  "nft": null
}

Minting may be async. You should confirm via:

transaction status polling, and/or
webhooks (recommended).

11. Track Mint Confirmation (Transactions)

List transactions to see status updates:

curl -X GET "https://sandbox.sverse.io/v1/transactions?type=mint&projectId=PROJECT_ID&chainKey=ton-testnet&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Once confirmed, the transaction may include:

onchainTxHash
confirmations
explorerUrl

12. Receive Webhooks (Recommended)

12.1 Create a Webhook Endpoint

curl -X POST "https://sandbox.sverse.io/v1/webhooks/endpoints" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "PROJECT_ID",
    "url": "https://your-server.com/sverse/webhooks",
    "events": [
      "transaction.confirmed",
      "transaction.failed",
      "nft.minted",
      "marketplace.order.fulfilled"
    ],
    "enabled": true,
    "secretMode": "auto"
  }'

Store the webhook secret securely.

12.2 Verify Webhook Signatures

Your webhook handler should:

read raw request body,
verify HMAC signature (based on the shared secret),
reject any invalid signatures,
then process the event idempotently.

Recommended properties:

eventId
eventType
createdAt
data payload with chainKey and references (txId, nftId, walletId)

13. Recommended Patterns (Production-Grade)

Idempotency

Always use idempotencyKey for:

minting
transfers
order creation

This prevents duplicate actions when retries occur.

Server-to-Server Calls

Keep these server-side:

authentication
minting
transfers
webhook endpoint management

Multi-chain Support

Treat chain as a first-class parameter:

always store chainKey with your assets and transactions,
do not assume a single network,
handle different confirmation times across chains.

Reconciliation

For any economic action:

rely on webhook confirmation,
and fall back to polling for resilience.

14. Minimal End-to-End Example Flow

A working mint flow for a game typically follows:

Player joins the game → upsert app member
Create or obtain player walletId
Ensure chain address exists (custodial or external)
Create (or reuse) NFT collectionId
Mint NFT to player walletId
Confirm via webhook transaction.confirmed / nft.minted
Update your game inventory state

15. Next Steps

After minting works, most games add:

Marketplace listing of minted NFTs
In-game utility rules for owned NFTs
Transfers/trades between players
Revenue sharing and fee configuration

PreviousIntroduction

Last updated 10 days ago

Good afternoon

hashtagDeveloper Guide

hashtag1. Overview

hashtag2. Prerequisites

hashtag3. Choose Environment and Base URL

hashtag4. Authenticate (Get Access Token)

hashtagRequest

hashtagResponse (example)

hashtag5. Create or Select Your Project (Game/App)

hashtagCreate Project

hashtag6. Select Supported Chains

hashtag7. Create or Link Player Wallets

hashtag7.1 Create a Wallet for a Player (Logical Wallet)

hashtag7.2 Create or Link a Chain Address

hashtag8. Register Players as App Members

hashtag9. Create an NFT Collection (Chain-Aware)

hashtag10. Mint an NFT to a Player Wallet

hashtagResponse (example)

hashtag11. Track Mint Confirmation (Transactions)

hashtag12. Receive Webhooks (Recommended)

hashtag12.1 Create a Webhook Endpoint

hashtag12.2 Verify Webhook Signatures

hashtag13. Recommended Patterns (Production-Grade)

hashtagIdempotency

hashtagServer-to-Server Calls

hashtagMulti-chain Support

hashtagReconciliation

hashtag14. Minimal End-to-End Example Flow

hashtag15. Next Steps

Developer Guide

1. Overview

2. Prerequisites

3. Choose Environment and Base URL

4. Authenticate (Get Access Token)

Request

Response (example)

5. Create or Select Your Project (Game/App)

Create Project

6. Select Supported Chains

7. Create or Link Player Wallets

7.1 Create a Wallet for a Player (Logical Wallet)

7.2 Create or Link a Chain Address

8. Register Players as App Members

9. Create an NFT Collection (Chain-Aware)

10. Mint an NFT to a Player Wallet

Response (example)

11. Track Mint Confirmation (Transactions)

12. Receive Webhooks (Recommended)

12.1 Create a Webhook Endpoint

12.2 Verify Webhook Signatures

13. Recommended Patterns (Production-Grade)

Idempotency

Server-to-Server Calls

Multi-chain Support

Reconciliation

14. Minimal End-to-End Example Flow

15. Next Steps