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
- demo: Pong Game - CROSS RAMP Demo
- Access and click [CROSS RAMP] in the top right
-
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.
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×tamp=1754029746
2.1.3 UI Parameter Description
Parameter Name | Description | Required |
---|---|---|
projectId | Project ID issued by Nexus | Required |
sessionId | Unique ID that can identify character | Required |
accessToken | In-game user authentication token | Required |
lang | Language selection (zh,en,zh-Hant) | - |
platform | web | - |
2.1.4 Game Server Implementation Description
Item | Description | Note |
---|---|---|
hmac key | X-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 future | key |
validator key | When 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 future | keystore |
Assets Query API | Used to query user's in-game assets in ramp UI | API(v1) |
Validate API | Used to validate user's orders in ramp UI | API |
Result API | Process on-chain result transmission | API |
CORS | CORS 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
Updated about 9 hours ago