NEXUS

CROSS RAMP

1. Overview

CrossRamp is a platform that supports easy implementation of exchanges between in-game currencies and tokens without requiring separate understanding of blockchain technology. This manual provides a step-by-step guide to help onboarding developers quickly and efficiently apply CrossRamp.

CrossRamp can be applied in two ways:

  • UI Integration Version: Integrated solution including both UI and backend

  • API Only Version: Method utilizing only backend API - In preparation

Below is the overall flow diagram of CrossRamp (hereinafter referred to as ramp).

sequenceDiagram
    participant User as User
    participant Game as game backend
    participant WF as cross-ramp frontend
    participant WB as cross-ramp backend
    participant TF as token-forge-api

    User->>WF: Access webshop link<br/>(JWT(ingame), sessionId, projectId)
    WF->>WB: Request additional information<br/>needed for rendering<br/>(item information)
    WB-->>WF: Deliver item information
    WF->>Game: (1) Assets, in-game currency<br/>balance inquiry,<br/>character name<br/>and wallet mapping<br/>status inquiry<br/>(JWT(ingame or cross auth))
    Note over WF,Game: 🔴 Important API call
    Game-->>WF: Deliver in-game<br/>currency balance<br/>(standardized spec required)
    WF-->>User: Deliver item information<br/>(screen rendering)
    User->>WF: Click mint/burn (minting/purchase)<br/>request button and sign

    WF->>WB: Deliver user request information<br/>- product, quantity,<br/>user signature (permit), etc.

    WB->>Game: (2) Validate, Buy Or Sell information delivery<br/>- product, quantity, etc.<br/>(JWT(ingame or cross auth), userSignature)
    Note over WB,Game: 🔴 Important API call

    Game->>Game: Validate user request and<br/>reduce in-game currency<br/>for minting cases
    Game->>Game: validator sign

    Game-->>WB: validator sig<br/>(detailed content below refers to token forge flow)
    WB->>TF: Transaction request
    WB-->>TF: Deliver transaction result
    WB-->>WF: Deliver user request result<br/>(success/failure)
    WB-->>Game: (3) Result, deliver user request result<br/>(success/failure) webhook
    Note over WB,Game: 🔴 Important Webhook call
    Game->>Game: Restore in-game currency when<br/>minting failure result is received
    WF-->>User: Deliver user request result<br/>(success/failure)

2. Prerequisites

2.1. UI Integration Version

2.1.1. Item Registration

Until developer console support is available, share item information with Nexus using the form below, and Nexus will proceed with information registration.

Download Form

2.1.2. Access Link Example

https://ramp.crosstoken.io/catalog?projectId=nexus-ramp-v1&sessionId=demo-session-1754029744441&accessToken=demo-access-1754029744441&lang=zh&platform=web&timestamp=1754029746

2.1.3 UI Parameter Description

Parameter NameDescriptionRequired
projectIdProject ID issued by NexusRequired
sessionIdUnique ID that can identify characterRequired
accessTokenIn-game user authentication tokenRequired
langLanguage selection (zh,en,zh-Hant)-
platformweb-

2.1.4 Game Server Implementation Description

ItemDescriptionNote
hmac keyX-HMAC-SIGNATURE verification key used for mutual trust in API requests and responses between ramp backend and game backend. Will be provided by Nexus and stored by both Nexus and game companies. Can be generated and replaced in developer console in the futurekey
validator keyWhen order information verification request comes to game server through verification API, signs with this key after verification if it's a valid order. Key is stored by game company and Nexus only stores public key. Can be generated and replaced in developer console in the futurekeystore
Assets Query APIUsed to query user's in-game assets in ramp UIAPI(v1)
Validate APIUsed to validate user's orders in ramp UIAPI
Result APIProcess on-chain result transmissionAPI
CORSCORS registration required for https://ramp.crosstoken.io site

2.2. API Only Version

In preparation.

3. Implementation Interface

Please refer to the sample code by language at the link below.

GitHub - to-nexus/cross-ramp-integration-sample

3.1. Game Asset Inquiry API

API for displaying in-game currency on ramp page.

  • Provide in-game currency of character identifiable by DAPP_ACCESS_TOKEN and DAPP_SESSION_ID
  • If DAPP_ACCESS_TOKEN and DAPP_SESSION_ID are not available, verify CROSS_AUTH_JWT and provide in-game currency mapped to sub (wallet address) in payload (implementation planned)

Request Example

curl -X GET "https://api.yourgame.com/assets?language=ko" \
  -H "Authorization: Bearer <CROSS_AUTH_JWT>" \
  -H "X-Dapp-Authorization: Bearer <DAPP_ACCESS_TOKEN>" \
  -H "X-Dapp-SessionID: <DAPP_SESSION_ID>"

Response Example (v1)

{
  "success": true,
  "errorCode": null,
  "data": {
    "v1": {
      "player_id": "C1",
      "name": "CharacterName01",
      "wallet_address": "0xaaaa",
      "server": "",
      "assets": [
        {
          "id": "1",          // fixed item index in game data
          "balance": "2000",    // if uid exists, balance is fixed to "1"
          "uid": "sdf238fnsd",              // optional, unique value of the item from user database
          "attributes": [
            {
              "traity_type": "rarity",
              "value": 0
            },
            {
              "traity_type": "rarity_string",
              "value": "common"
            },
            {
              "trait_type": "damage",   // string
              "value": 255  // can be number
            }, 
            {
              "trait_type": "class",   // string
              "value": "sword"  // can be string
            }
          ]
        }
      ]
    }
  }
}

Response Example (v2, to be provided later)

{
  "success": true,
  "errorCode": null,
  "data": {
    "v2": {
      "common": [
        {
          "id": "0x9",
          "balance": "19999"
        }
      ],
      "characters": [
        {
          "character_id": "C1",
          "name": "CharacterName01",
          "image_url": "CharacterImagePath",
          "wallet_account": "0xaaaa",
          "server": "",
          "inventory": [
            {
              "id": "0x1",
              "balance": "2000"
            }
          ]
        }
      ]
    }
  }
}

3.2. Validation API

Validates user's in-game currency ↔ token exchange request.

Request Example

curl -X POST "https://api.yourgame.com/validate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <CROSS_AUTH_JWT>" \
  -H "X-HMAC-SIGNATURE: <HMAC_SIGNATURE>" \
  -H "X-Dapp-Authorization: Bearer <DAPP_ACCESS_TOKEN>" \
  -H "X-Dapp-SessionID: <DAPP_SESSION_ID>" \
  -d '{
    "user_sig": "0xabcdef",
    "user_address": "0xB777C937fa1afC99606aFa85c5b83cFe7f82BabD",
    "project_id": "acjviwejsi",
    "digest": "0x123456789...",
    "uuid": "c8ab8d7b-3fe7-....",
    "intent": {
      "type":"assemble", // assemble || disassemble
      "method": "mint",
      "from": [{ "type": "erc20", "id": "0x1234", "amount": 1000 }],
      "to": [{ "type": "asset", "id": "ITEM01", "amount": 1000 }]
    }
  }'

Response Example

{
  "success": true,
  "errorCode": null,
  "data": {
    "userSig": "0xabcdef",
    "validatorSig": "0xabcdef"
  }
}

3.3. Exchange Result Delivery API

API for receiving exchange results between game assets and tokens.

Request Example

curl -X POST "https://api.yourgame.com/result" \
  -H "X-HMAC-SIGNATURE: <HMAC_SIGNATURE>" \
  -d '{
    "session_id": "<DAPP_SESSION_ID>",
    "uuid": "4fec342b-8ad7-4e...",
    "tx_hash": "0x123456789.....",
    "receipt": {},
    "intent": {
      "type":"assemble", // assemble || disassemble
      "method": "mint",
      "from": [{ "type": "erc20", "id": "0x1234", "amount": 1000 }],
      "to": [{ "type": "asset", "id": "ITEM01", "amount": 1000 }]
    }
  }'

Response Example

{
  "success": true,
  "errorCode": null,
  "data": null
}

3.4 Wallet-Game Account Connection API

API for connecting wallet address and game account.

Request Example

curl -X POST "https://api.yourgame.com/enroll?address=0x1234567890..." \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <CROSS_AUTH_JWT>" \
  -H "X-HMAC-SIGNATURE: <HMAC_SIGNATURE>" \
  -H "X-Dapp-Authorization: Bearer <DAPP_ACCESS_TOKEN>" \
  -H "X-Dapp-SessionID: <DAPP_SESSION_ID>"

3.5 Contract Interface

Interface definition required for ramp integration

interface IERC721Forge {
    function mint(address to, uint256 tokenID) external returns (uint256);
    function burnFrom(address from, uint256 tokenID) external;
}

interface IERC1155Forge {
    function mint(address to, uint256 tokenID, uint256 amount, bytes calldata data) external;
    function mintBatch(address to, uint256[] memory tokenIDs, uint256[] memory amounts, bytes calldata data) external;
    function burnFrom(address from, uint256 tokenID, uint256 amount) external;
    function burnFromBatch(address from, uint256[] memory tokenIDs, uint256[] memory amounts) external;
}

4. HMAC-Signature

For security requests requiring mutual trust, HMAC is used and signature value is required in header with X-HMAC-SIGNATURE key.

Below are examples for signature generation by language.

4.1. Golang

package router

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"testing"
	"github.com/stretchr/testify/require"
)

const (
	salt = "my_secret_salt_value_!@#$%^&*" // hmac key
)

type Body struct {
	UserID    int    `json:"userId"`
	Username  string `json:"username"`
	Email     string `json:"email"`
	Role      string `json:"role"`
	CreatedAt int    `json:"createdAt"`
}

var (
	body = Body{
		UserID:    1234,
		Username:  "홍길동",
		Email:     "[email protected]",
		Role:      "admin",
		CreatedAt: 1234567890,
	}
)

func TestSha256(t *testing.T) {
	bodyBytes, err := json.Marshal(body)
	require.NoError(t, err)
	t.Log(string(bodyBytes))
	hmac := hmac.New(sha256.New, []byte(salt))
	hmac.Write(bodyBytes)
	hashBytes := hmac.Sum(nil)
	hashString := hex.EncodeToString(hashBytes)
	t.Log("hashString", hashString) // expected X-HMAC-Signature: f96cf60394f6b8ad3c6de2d5b2b1d1a540f9529082a8eb9cee405bfbdd9f37a1
}

4.2 Javascript

const crypto = require('crypto');

function hmacSha256(data, salt) {
    return crypto.createHmac('sha256', salt).update(data).digest('hex');
}

// JSON object definition request body
const requestBody = {
    userId: 1234,
    username: '홍길동',
    email: '[email protected]',
    role: 'admin',
    createdAt: 1234567890,
};

const salt = 'my_secret_salt_value_!@#$%^&*'; // hmac key
const jsonString = JSON.stringify(requestBody);
console.log('JSON string:', jsonString);

// Result output
console.log('HMAC-SHA256:', hmacSha256(jsonString, salt)); // expected X-HMAC-Signature: f96cf60394f6b8ad3c6de2d5b2b1d1a540f9529082a8eb9cee405bfbdd9f37a1

© 2025 NEXUS Co., Ltd. All Rights Reserved.