End Point

Interfaces are required for integration between the developer's server and the RAMP platform server.

Retrieve UUID

Retrieve the UUID required to open the RAMP F/E Webview from the application (dApp).

(ex : https://ramp.crosstoken.io/exchange?uuid={{uuid}}&accessToken={{userAccessToken}}&sessionId={{userSessionId}}&network=testnet)

Request / Response

Request Sample

POST https://cross-ramp-api.crosstoken.io/api/v2/initialize
Content-Type: application/json
X-HMAC-SIGNATURE: {{}}
X-Dapp-Authorization: Bearer {{accessToken}}
X-Dapp-SessionID: {{sessionId}}

{
    "player_id": "player_id_01",
    "name": "character_name_01",
    "wallet_address": "0xwalletaddresss",
    "server": "server_01",
    "intent": {
        "network": "testnet",
        "project_id": "79bc87b18d7941caee2fb2f5226d1736",
        "token": "0xFFF6dCEa241a974283C0ECEea8ED81b478062AF1",
        "mint_fee_bps": 2000,
        "burn_fee_bps": 0,
        "mint_method": "mint",
        "burn_method": "burn-permit",
        "materials": [
            {
                "id": "item_gold",
                "amount": 100,
                "icon_url": "https://console-contents.crosstoken.io/studios/projects/assets/019ac48c-ed97-7a09-be8e-2fdb499e3c11.png",
                "is_non_fungible": false
            }
        ],
        "outputs": [
            {
                "id": "item_gold",
                "amount": 80,
                "icon_url": "https://console-contents.crosstoken.io/studios/projects/assets/019ac48c-ed97-7a09-be8e-2fdb499e3c11.png",
                "is_non_fungible": false
            }
        ]
    }
}

Request Header Field Description

Field Name	Description
X-HMAC-SIGNATURE	HMAC signed value of Request Raw Data using the HMAC-Key generated in the RAMP Console.
X-Dapp-Authorization	accessToken generated by the developer's server. Uses the `accessToken` value added to the Query when loading RAMP F/E.
X-Dapp-SessionID	Character identification ID of the user managed by the developer. Uses the `sessionId` value added to the Query when loading RAMP F/E.

Request Field Description

Field Name	Type	Description
Basic Info
player_id	string	Unique Player ID in the game
name	string	Character Name
wallet_address	string	Player Wallet Address
server	string	Game Server Identifier accessed by the player
intent
intent	object	Token Mint/Burn Information
intent.network	string	Network (`mainnet`, `testnet`)
intent.project_id	string	CROSS RAMP Project ID
intent.token	string	Token Contract Address
intent.mint_fee_bps	number	Mint Fee (bps based, 100 = 1%)
intent.burn_fee_bps	number	Burn Fee (bps based) `0 fixed`
intent.mint_method	string	Contract method name used for Token Mint `mint fixed`
intent.burn_method	string	Contract method name used for Token Burn
intent.materials[]		`burn-permit fixed`
intent.materials	array	Game currency information used during `Token Minting`
intent.materials[].id	string	Item ID
intent.materials[].amount	number	Amount of items consumed
intent.materials[].icon_url	string	Item Icon Image URL
intent.materials[].is_non_fungible	boolean	NFT Status (`true` = NFT, `false` = FT)
intent.outputs[]
intent.outputs	array	Game currency information provided during `Token Burn`
intent.outputs[].id	string	Item ID
intent.outputs[].amount	number	Amount of items provided
intent.outputs[].icon_url	string	Item Icon Image URL
intent.outputs[].is_non_fungible	boolean	NFT Status (`true` = NFT, `false` = FT)

Response Sample

{
    "code": 200,
    "message": "OK",
    "data": {
        "uuid": "9cf3a7e5-7d2c-4ef3-ba6f-911d5078416b"
    }
}

Response Field Description

Field Name	Type	Description
data.uuid	string	UUID used to load the RAMP F/E page in the application (dApp). The generated UUID is valid for only `5 minutes`.

User Game Asset Inquiry API

Implementation of an API to query the game assets held by the user for token issuance is required. The retrieved game assets are displayed on the RAMP F/E page.

When RAMP B/E calls the Game Asset Inquiry API, it transmits the accessToken and sessionId contained in the query parameters of the RAMP F/E URL loaded for token issuance or burning within the game, including them in the Request Header.
Therefore, the developer server must verify the accessToken and return an appropriate Response based on the verification result.

Requests will be made to the Get Assets Endpoint configured in the CROSS-RAMP Console project.

Request / Response

RAMP B/E requests user asset information from the Endpoint implemented by the developer.

Request Sample

GET /api/assets
Host: https://your-server.com
Content-Type: application/json
X-Dapp-Authorization: Bearer {{accessToken}}
X-Dapp-SessionID: {{sessionId}}

Request Header Field Description

Field Name	Description
X-Dapp-Authorization	accessToken generated by the developer's server. Uses the `accessToken` value added to the Query when loading RAMP F/E.
X-Dapp-SessionID	Character identification ID of the user managed by the developer. Uses the `sessionId` value added to the Query when loading RAMP F/E.

Response Sample

Success Response (200 OK)

{
  "success": true,
  "errorCode": null,
  "data": {
    "v1": {
      "player_id": "player_id_allen",
      "name": "name_allen",
      "wallet_address": "0x62c5a30a90d3c3032dfb0fe4ea05e9c454c56707",
      "server": "test",
      "assets": [
        {
          "id": "item_gold",
          "balance": "1000.123"
        }
      ]
    }
  }
}

Response Field Description

Field Name	Type	Description
success	boolean	Request success status
errorCode	string	Error code (null if successful)
data	object	Response data (null if failed)
data.v1	object	API version 1 data
data.v1.player_id	string	User character unique ID
data.v1.name	string	User character name
data.v1.wallet_address	string	User wallet address
data.v1.server	string	User character connection server info
data.v1.assets	array	List of game assets held by the user
data.v1.assets[].id	string	`Game asset unique identifier` The game asset ID configured in the RAMP Console must be entered.
data.v1.assets[].balance	string	`Quantity of game assets held by the user` The quantity of assets held by the user in the game must be entered.

User Signature Verification Query API

❗️
Important
Developers must verify the game asset values included in the Request parameters requested by RAMP B/E.

In the token issuance process, implementation of an API is required to verify whether the user's signature value matches the transaction request data sent by the developer.

To verify data integrity, data signed with HMAC-SHA256 generated in the CROSS-RAMP Console is included in the Request Header.
Therefore, the developer server must use the HMAC value from the CROSS-RAMP Console to verify integrity.

A response is required after verifying whether the user's token issuance/burning request violates the developer's policy (authentication, game asset quantity, etc.).

Requests will be made to the Validate Order Endpoint configured in the CROSS-RAMP Console project.

Request / Response

Request sample

POST /api/validate
Host: https://your-server.com
Content-Type: application/json
x-dapp-authorization: Bearer {{accessToken}}
x-dapp-sessionid: {{sessionId}}
x-hmac-signature: {{hmac_signature}}

{
  "user_sig": "0x58ea88cc20a571d2bc4f4a7ab687158e1924887c005a8a2ccce9a7c8f669adbb222932f9e760b923b6f359870169d58a171d47516ee71167313d5068dbd84c631c",
  "user_address": "0x6de346a7333d97fe0d39a49178ac65918c257b28",
  "project_id": "3a4----------------------2d7",
  "digest": "0x6d196d0881bb8e322c194fbf53518089b240055134044491a78b14920098e395",
  "uuid": "86b555dd-e622-43fe-a799-c5c4536dd8c6",
  "intent": {
    "method": "mint",
    "type": "assemble",
    "from": [
      {
        "type": "asset",
        "id": "item_gold",
        "amount": 100
      }
    ],
    "to": [
      {
        "type": "ERC20",
        "id": "0x14f6f0057274c3519d6258EB66F5d01D79821D81",
        "amount": 1
      }
    ],
    "target_candidate": {}
  }
}

POST /api/validate
Host: https://your-server.com
Content-Type: application/json
x-dapp-authorization: Bearer {{accessToken}}
x-dapp-sessionid: {{sessionId}}
x-hmac-signature: {{hmac_signature}}

{
  "user_sig": "0xb1378a978b5e77d750c44d4b9bdf4d883d2e2bad8e09c8928e8d83176359cc9376a959c3576c82f2214c9fece66c73417669bf667734ec8f94880885c5d1b82a1c",
  "user_address": "0x6de346a7333d97fe0d39a49178ac65918c257b28",
  "project_id": "3a4f5838f7cdfe31873a43ca021a92d7",
  "digest": "0x7bd721630a8c7e6b1c1050934fc3bf69cadaef0253c46f92f1b03242c5f2e733",
  "uuid": "d7360515-8547-427e-acb5-6556c8376fd4",
  "intent": {
    "method": "burn-permit",
    "type": "disassemble",
    "from": [
      {
        "type": "ERC20",
        "id": "0x14f6f0057274c3519d6258EB66F5d01D79821D81",
        "amount": 1
      }
    ],
    "to": [
      {
        "type": "asset",
        "id": "item_gold",
        "amount": 50
      }
    ],
    "target_candidate": {}
  }
}

Request Header Field Description

Field Name	Description
X-HMAC-SIGNATURE	HMAC signed value of Request Raw Data using the HMAC-Key generated in the RAMP Console.
X-Dapp-Authorization	accessToken generated by the developer's server. Uses the `accessToken` value added to the Query when loading RAMP F/E.
X-Dapp-SessionID	Character identification ID of the user managed by the developer. Uses the `sessionId` value added to the Query when loading RAMP F/E.

Request Body Field Description

Field Name	Type	Description
user_sig	string	Data signed through CROSSx for user's token issuance/burning.
user_address	string	User's CROSSx address
project_id	string	Project ID generated in RAMP Console
digest	string	Hash digest of transaction data The original text to be signed using the Validator Key generated by the developer.
uuid	string	Request Unique Identifier
intent	object	Token Issuance/Burning Information
intent.method	string	Execution Method (mint, burn)
intent.type	string	Transaction Type (assemble, disassemble) assemble : Token Issuance disassemble : Token Burning
intent.from	array	List of source asset information
intent.from[].type	string	Asset Type (asset, ERC20) asset : Game Asset ERC20 : Game Token
intent.from[].id	string	Game asset ID registered in CROSS-RAMP Console.
intent.from[].amount	number	Quantity of game assets used for token issuance
intent.to	array	List of target asset information
intent.to[].type	string	Asset Type (ERC20, NFT)
intent.to[].id	string	Token Contract Address
intent.to[].amount	number	Quantity of tokens to issue
intent.target_candidate	object	Target candidate information (additional option)

Response Sample

Success Response (200 OK)

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

Response Field Description

Field Name	Type	Description
success	boolean	Request success status
errorCode	string	Error code (null if successful)
data	object	Response data (null if failed)
data.userSig	string	Data signed by the user through CROSSx for token issuance/burning.
data.validatorSig	string	Data signed with ECDSA using the Validator Key generated by the developer. The Validator Key's address must be registered in the CROSS-RAMP Console.

User Token Issuance / Burning Result API

Transmits the blockchain transaction result for the user's token issuance/burning request to the game server via Webhook.

The transaction result is delivered to the Endpoint registered in the CROSS-RAMP Console, and the developer server must respond with an HTTP status value of 200 after receiving the result.

If RAMP B/E does not receive a response or receives an HTTP 500 code, RAMP B/E will attempt to resend.
An HTTP 200 code must be returned for normal processing.

📘
Retry Information
After the first Webhook delivery attempt, up to 20 retries are attempted over 12 hours.

2 attempts at 5-minute intervals

7 attempts at 15-minute intervals

10 attempts at 60-minute intervals

Webhook request / response

If receipt.status is not 0x1, the transaction request on the blockchain network has failed, so game currency must be restored.

Request Sample

POST /api/result
Host: https://your-server.com
Content-Type: application/json
x-dapp-authorization: Bearer {{accessToken}}
x-dapp-sessionid: {{sessionId}}
x-hmac-signature: {{hmac_signature}}

{
    "session_id": "{{dappSessionId}}",
    "uuid": "b6d3976b-36b1-48d6-974b-da1471aa94de",
    "tx_hash": "0x17def972330f874dcfbc8099ada5da777c4273e3c0aa6faebb103e09615f5784",
    "receipt": {
        "type": "0x2",
        "root": "0x",
        "status": "0x1",
        "cumulativeGasUsed": "0x1f531",
        "logsBloom": "0x00000000080040000000200a00000000000000000000000000000000000000000000010000000000002000100000000000000000000000000000000000000000000000100820000400000008000000000000000000000000000000000000110000040000020000000000000000000800000040000000000000000010000000000000000008000000000000080000000000000000000000000000000000100000000000000000000000000400000002000000000000000000000000000000000000000002000000000000000000020800000002000000000000000000000020400000000000000000000200000000000000000000000000000800000000000000",
        "logs": [
            {
                "address": "0x14f6f0057274c3519d6258eb66f5d01d79821d81",
                "topics": [
                    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
                    "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "0x0000000000000000000000006de346a7333d97fe0d39a49178ac65918c257b28"
                ],
                "data": "0x0000000000000000000000000000000000000000000000003e73362871420000",
                "blockNumber": "0xaa3d8f",
                "transactionHash": "0x17def972330f874dcfbc8099ada5da777c4273e3c0aa6faebb103e09615f5784",
                "transactionIndex": "0x0",
                "blockHash": "0x5b62d0387e2f37ea7c76cde2b08b1a36648aca277c76152fdf0da59e6ee63733",
                "blockTimestamp": 0,
                "logIndex": "0x0",
                "removed": false
            },
            {
                "address": "0x7189d67b9ded72e9f1dcfce1c23ea3af418f4a57",
                "topics": [
                    "0x9612604afba70e4cf03261d7d86ca03d08911d9887aa41621dea929e34cfd7b1",
                    "0x3361346635383338663763646665333138373361343363613032316139326437",
                    "0x171ac396aacce04a8c32ecd6322f384796a2a5e15224316a78c9358a8cea809b",
                    "0x0000000000000000000000006de346a7333d97fe0d39a49178ac65918c257b28"
                ],
                "data": "0x00000000000000000000000014f6f0057274c3519d6258eb66f5d01d79821d810000000000000000000000000000000000000000000000004563918244f40000",
                "blockNumber": "0xaa3d8f",
                "transactionHash": "0x17def972330f874dcfbc8099ada5da777c4273e3c0aa6faebb103e09615f5784",
                "transactionIndex": "0x0",
                "blockHash": "0x5b62d0387e2f37ea7c76cde2b08b1a36648aca277c76152fdf0da59e6ee63733",
                "blockTimestamp": 0,
                "logIndex": "0x2",
                "removed": false
            }
        ],
        "transactionHash": "0x17def972330f874dcfbc8099ada5da777c4273e3c0aa6faebb103e09615f5784",
        "contractAddress": "0x0000000000000000000000000000000000000000",
        "gasUsed": "0x1f531",
        "effectiveGasPrice": "0xee6b2800",
        "blockHash": "0x5b62d0387e2f37ea7c76cde2b08b1a36648aca277c76152fdf0da59e6ee63733",
        "blockNumber": "0xaa3d8f",
        "transactionIndex": "0x0"
    },
    "intent": {
        "method": "mint",
        "type": "assemble",
        "from": [
            {
                "type": "asset",
                "id": "item_gold_n",
                "amount": 500
            }
        ],
        "to": [
            {
                "type": "ERC20",
                "id": "0x14f6f0057274c3519d6258EB66F5d01D79821D81",
                "amount": 5
            }
        ],
        "target_candidate": {}
    }
}

response sample

POST /api/result
Host: https://your-server.com
Content-Type: application/json

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

HMAC Signature and Validator Signature Samples

HMAC Signature Sample

import { ethers } from "ethers";

/**
 * generateValidatorSignature
 * 
 * Signs the given digest using the validator's private key.
 * The digest must be a 32-byte hash (e.g. "0xabc123...").
 * 
 * @param {string} userSig - (optional) user's signature
 * @param {string} digest  - 32-byte digest to sign
 * @returns {Promise<{ success: boolean, signature?: string, error?: string }>}
 */
export async function generateValidatorSignature(userSig, digest) {
  try {
    // Load validator private key (from env or default)
    const privateKey =
      process.env.VALIDATOR_PRIVATE_KEY;

    // Create an Ethers.js Wallet instance
    const wallet = new ethers.Wallet(privateKey);

    // Convert digest (hex) to byte array
    const digestBytes = ethers.getBytes(digest);

    // Sign the digest (must be 32 bytes)
    const rawSignature = await wallet.signingKey.sign(digestBytes);

    // Serialize signature (r + s + v)
    const signature = ethers.Signature.from(rawSignature).serialized;

    // Return success response
    return {
      success: true,
      signature,
    };
  } catch (error) {
    console.error("Error generating validator signature:", error);

    // Return failure response
    return {
      success: false,
      error: error.message,
    };
  }
}