### Start Backend Servers (Bash, Go, Node.js, C#, C++)

Source: https://context7.com/to-nexus/cross-ramp-integration-sample/llms.txt

Provides commands to build and run the sample backend server across different programming languages. It includes Go using Gin, TypeScript using Express, C# with .NET, and C++ with CMake. All examples default to running on port 8080, enabling CrossRamp frontend integration.

```bash
# Go server startup
cd golang
go mod tidy
go run main.go
# Server starts on http://localhost:8080

# TypeScript server startup
cd typescript
npm install
npm run dev
# Server starts on http://localhost:8080

# C# server startup
cd csharp/SampleGameBackend
donet restore
donet run
# Server starts on configured port

# C++ server build and run
cd cpp
mkdir build && cd build
cmake ..
make
./sample_game_backend_cpp
```

--------------------------------

### API: Asset Information Query Example

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/README.md

Example using curl to query asset information from the backend. Requires authentication headers and specifies the language parameter.

```bash
curl -X GET "http://localhost:8080/api/assets?language=ko" \
  -H "Authorization: Bearer test_cross_auth_jwt_token" \
  -H "X-Dapp-Authorization: Bearer test_dapp_access_token" \
  -H "X-Dapp-SessionID: test_session_id"
```

--------------------------------

### Install Dependencies - Bash

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/golang/README.md

Installs project dependencies using Go modules. Requires Go 1.21 or higher.

```bash
go mod tidy
```

--------------------------------

### Clone and Run C# Backend

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/README.md

Steps to clone the repository, navigate to the C# backend directory, restore dependencies, and run the server. This is the primary setup for the C# implementation.

```bash
git clone <repository-url>
cd sample-game-backend/csharp/SampleGameBackend
dotnet restore
dotnet run
```

--------------------------------

### API: Order Validation Example

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/README.md

Example using curl to send an order validation request to the backend. This POST request includes a JSON payload with user signature, address, project ID, and intent details.

```bash
curl -X POST "http://localhost:8080/api/validate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer test_cross_auth_jwt_token" \
  -H "X-Dapp-Authorization: Bearer test_dapp_access_token" \
  -H "X-Dapp-SessionID: test_session_id" \
  -d '{
    "user_sig": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "user_address": "0xB777C937fa1afC99606aFa85c5b83cFe7f82BabD",
    "project_id": "acjviwejsi",
    "intent": {
      "method": "mint",
      "from": [
        { "type": "asset", "id": "asset_money", "amount": 1000 }
      ],
      "to": [
        { "type": "asset", "id": "item_gem", "amount": 1000 }
      ]
    }
  }'
```

--------------------------------

### Reclaim API Request Example (Bash)

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/GUIDE.md

Example cURL command to demonstrate a POST request to the Reclaim API. It includes necessary headers like Content-Type, X-HMAC-SIGNATURE, X-Dapp-Authorization, and X-Dapp-SessionID, along with a JSON request body containing account, asset_id, and uid.

```bash
curl -X POST "https://api.yourgame.com/reclaim" \
  -H "Content-Type: application/json" \
  -H "X-HMAC-SIGNATURE: <HMAC_SIGNATURE>" \
  -H "X-Dapp-Authorization: Bearer <DAPP_ACCESS_TOKEN>" \
  -H "X-Dapp-SessionID: <DAPP_SESSION_ID>" \
  -d '{
      "account": "0x1234567890123456789012345678901234567890",
      "asset_id": "asset_fire_bow",
      "uid": "asset_fire_bow_uid"
  }'
```

--------------------------------

### API: Health Check Example

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/README.md

Example using curl to perform a health check on the backend server. This is a simple GET request to the /health endpoint.

```bash
curl -X GET "http://localhost:8080/health"
```

--------------------------------

### Run Server - Bash

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/golang/README.md

Starts the Golang sample game backend server. The server will listen on port 8080. Requires Go 1.21 or higher.

```bash
go run main.go
```

--------------------------------

### Clone Repository - Bash

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/golang/README.md

Clones the project repository and navigates into the project directory. Requires Git to be installed.

```bash
git clone <repository-url>
cd sample-game-backend
```

--------------------------------

### Reclaim API Response Example (JSON)

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/GUIDE.md

Example JSON response from the Reclaim API upon successful item claim. It includes a success status and data pertaining to the claimed item, such as account, session ID, asset ID, and transfer details.

```json
{
  "success": true,
  "data": {
    "account": "0x1234567890123456789012345678901234567890",
    "session_id": <DAPP_SESSION_ID>,
    "asset_id": "asset_fire_bow",
    "uid": "asset_fire_bow_uid",
    "from": "Luis",
    "to": "Theo"
  }
}
```

--------------------------------

### Webhook Error Examples (JSON)

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/GUIDE.md

Illustrative examples of JSON error responses for various HTTP status codes and error codes. These examples show specific error messages for internal server errors, bad request parameters, and unauthorized access.

```json
{
  "errorCode": 1001,
  "errorMessage": "character not exists"
}

{
  "errorCode": 2001,
  "errorMessage": "param1 is required"
}

{
  "errorCode": 2002,
  "errorMessage": "invalid JSON"
}

{
  "errorCode": 3001,
  "errorMessage": "session id is required"
}
```

--------------------------------

### HMAC-Signature Generation

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/GUIDE.md

Details on how to generate the HMAC-SHA256 signature required for secure requests, with examples in Golang and Javascript.

```APIDOC
## HMAC-Signature

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

### Golang Example
```go
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:     "user@example.com",
		Role:      "admin",
		CreatedAt: 1234567890,
	}
)

func TestSha256(t *testing.T) {
	bodyBytes, err := json.Marshal(body)
	require.NoError(t, err)
	t.Log(string(bodyBytes))

	saltByte, _ := base64.URLEncoding.WithPadding(base64.NoPadding).DecodeString(salt)
	hmac := hmac.New(sha256.New, saltByte)
	hmac.Write(bodyBytes)
	hashBytes := hmac.Sum(nil)
	hashString := hex.EncodeToString(hashBytes)
	t.Log("hashString", hashString) 
	// expected X-HMAC-Signature: f96cf60394f6b8ad3c6de2d5b2b1d1a540f9529082a8eb9cee405bfbdd9f37a1
}
```

### Javascript Example
```javascript
const crypto = require('crypto');

// Base64 URL decoding
function base64UrlDecode(str) {
    // Convert URL safe base64 to standard base64
    str = str.replace(/-/g, '+').replace(/_/g, '/');
    // Add padding (if needed)
    while (str.length % 4) {
        str += '=';
    }
    return Buffer.from(str, 'base64');
}

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

// Define JSON object request body
const requestBody = {
    userId: 1234,
    username: '홍길동',
    email: 'user@example.com',
    role: 'admin',
    createdAt: 1234567890,
};

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

console.log('JSON string:', jsonString);
// Output result
console.log('HMAC-SHA256:', hmacSha256(jsonString, salt)); 
// expected X-HMAC-Signature: f96cf60394f6b8ad3c6de2d5b2b1d1a540f9529082a8eb9cee405bfbdd9f37a1
```
```

--------------------------------

### GET /api/assets

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/typescript/README.md

Retrieves user assets. This endpoint requires authentication.

```APIDOC
## GET /api/assets

### Description
Retrieves user assets. This endpoint requires authentication.

### Method
GET

### Endpoint
/api/assets

### Parameters
#### Query Parameters
- **Authorization** (string) - Required - Bearer <CROSS_AUTH_JWT>
- **X-Dapp-Authorization** (string) - Required - Bearer <DAPP_ACCESS_TOKEN>
- **X-Dapp-SessionID** (string) - Required - <DAPP_SESSION_ID>

### Request Example
```bash
curl -X GET \
  http://your-api-url/api/assets \
  -H 'Authorization: Bearer <CROSS_AUTH_JWT>' \
  -H 'X-Dapp-Authorization: Bearer <DAPP_ACCESS_TOKEN>' \
  -H 'X-Dapp-SessionID: <DAPP_SESSION_ID>'
```

### Response
#### Success Response (200)
- **assets** (array) - An array of user's assets.

#### Response Example
```json
{
  "assets": [
    {
      "id": "asset-123",
      "name": "Sword",
      "quantity": 1
    }
  ]
}
```
```

--------------------------------

### GET /api/assets

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/README.md

Retrieves asset information. Supports filtering by language.

```APIDOC
## GET /api/assets

### Description
Asset information query endpoint. Allows specifying a language for the returned asset information.

### Method
GET

### Endpoint
/api/assets

#### Query Parameters
- **language** (string) - Optional - The language code for the asset information (e.g., 'ko').

### Request Example
```bash
curl -X GET "http://localhost:8080/api/assets?language=ko" \
  -H "Authorization: Bearer test_cross_auth_jwt_token" \
  -H "X-Dapp-Authorization: Bearer test_dapp_access_token" \
  -H "X-Dapp-SessionID: test_session_id"
```

### Response
#### Success Response (200)
- **asset_data** (object) - Contains detailed information about the assets.

#### Response Example
```json
{
  "asset_data": {
    "asset_id_1": {
      "name": "Example Asset",
      "description": "This is a sample asset."
    }
  }
}
```
```

--------------------------------

### GET /api/assets

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/README.md

Retrieves asset information for a player. This endpoint is used to query the player's current in-game assets and their balances. It supports language selection for the response.

```APIDOC
## GET /api/assets

### Description
Retrieves asset information for a player. This endpoint is used to query the player's current in-game assets and their balances. It supports language selection for the response.

### Method
GET

### Endpoint
/api/assets

#### Query Parameters
- **language** (string) - Optional - Specifies the language for the response (e.g., 'ko').

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication (e.g., 'Bearer <CROSS_AUTH_JWT>').
- **X-Dapp-Authorization** (string) - Required - Bearer token for Dapp authorization (e.g., 'Bearer <DAPP_ACCESS_TOKEN>').
- **X-Dapp-SessionID** (string) - Required - Session ID for the Dapp.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **errorCode** (null) - Error code, null if successful.
- **data** (object) - Contains the asset information and guide details.
  - **v1** (object) - Player-specific asset data.
    - **player_id** (string) - Unique player identifier.
    - **name** (string) - Player's name.
    - **wallet_address** (string) - Mapped wallet address of the player.
    - **server** (string) - Game server identifier.
    - **assets** (array) - List of player's assets.
      - **id** (string) - Asset ID registered in the Ramp console.
      - **balance** (string) - Current balance of the asset.
  - **guide** (object) - Header information for reference (not provided to game companies).
    - **Authorization** (string) - Example Authorization header.
    - **X-Dapp-Authorization** (string) - Example X-Dapp-Authorization header.
    - **X-Dapp-SessionID** (string) - Example X-Dapp-SessionID.
    - **message** (string) - Explanation of the guide field.
    - **session_info** (object) - Session creation and update timestamps.
      - **created_at** (string) - ISO 8601 format timestamp.
      - **updated_at** (string) - ISO 8601 format timestamp.

#### Response Example
```json
{
  "success": true,
  "errorCode": null,
  "data": {
    "v1": {
      "player_id": "C1",
      "name": "playerName_C1",
      "wallet_address": "0xaaaa",
      "server": "test",
      "assets": [
        {
          "id": "asset_money",
          "balance": "2000"
        },
        {
          "id": "item_gem",
          "balance": "1500"
        }
      ]
    },
    "guide": {
      "Authorization": "Bearer <token>",
      "X-Dapp-Authorization": "Bearer <token>",
      "X-Dapp-SessionID": "<session_id>",
      "message": "The guide field displays header information at request time. It is for checking if the game company and protocol are correctly matched and is not provided to game companies. For ramp frontend developer reference.",
      "session_info": {
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    }
  }
}
```
```

--------------------------------

### GET /health

Source: https://context7.com/to-nexus/cross-ramp-integration-sample/llms.txt

A simple endpoint to check the health and responsiveness of the server.

```APIDOC
## GET /health

### Description
Simple endpoint to verify the server is running and responsive. Returns a basic status indicating the service is operational.

### Method
GET

### Endpoint
/health

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET "http://localhost:8080/health"
```

### Response
#### Success Response (200 OK)
- **status** (string) - Indicates the health status of the service (e.g., "ok").

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### Webhook Error Response Example (JSON)

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/GUIDE.md

JSON structure for error responses returned by webhooks. It includes an errorCode and an errorMessage to provide specific details about the nature of the error encountered during processing.

```json
{
    "errorCode"    int
    "errorMessage" string
}
```

--------------------------------

### Clone and Build C++ Backend

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/README.md

Instructions for cloning the repository and setting up the C++ backend. This includes creating a build directory, configuring with CMake, and compiling the project. Requires CMake 3.16+, a C++17 compiler, nlohmann/json, OpenSSL, and Git.

```bash
git clone <repository-url>
cd sample-game-backend/cpp
mkdir build && cd build
cmake ..
make
./sample_game_backend_cpp
```

--------------------------------

### Build Application - Bash

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/golang/README.md

Builds the Golang application into an executable file named 'sample-game-backend'. Requires Go 1.21 or higher.

```bash
go build -o sample-game-backend
```

--------------------------------

### Run Tests - Bash

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/golang/README.md

Executes all tests within the project. Requires Go 1.21 or higher.

```bash
go test ./...
```

--------------------------------

### Configure Go Server with Gin Framework

Source: https://context7.com/to-nexus/cross-ramp-integration-sample/llms.txt

Sets up a Go backend server using the Gin framework, including essential middleware for CORS and authentication. It initializes an in-memory database, registers API routes for asset handling, validation, and results, and includes a health check endpoint. The server is configured to run on port 8080.

```go
package main

import (
    "sample-game-backend/internal/database"
    "sample-game-backend/internal/handlers"
    "sample-game-backend/internal/middleware"

    "github.com/gin-gonic/gin"
)

func main() {
    // Initialize in-memory database
    database.InitDB()

    router := gin.Default()

    // Apply middleware
    router.Use(middleware.CORSMiddleware())
    router.Use(middleware.AuthMiddleware())

    // Register routes
    api := router.Group("/api")
    {
        api.GET("/assets", handlers.GetAssetsHandler)
        api.POST("/validate", handlers.ValidateUserActionHandler)
        api.POST("/result", handlers.ExchangeResultHandler)
    }

    router.GET("/health", func(c *gin.Context) {
        c.JSON(200, gin.H{"status": "ok"})
    })

    router.Run(":8080")
}
```

--------------------------------

### GET /health

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/typescript/README.md

Performs a health check on the API. No authentication is required.

```APIDOC
## GET /health

### Description
Performs a health check on the API. No authentication is required.

### Method
GET

### Endpoint
/health

### Parameters
No parameters are required for this endpoint.

### Request Example
```bash
curl -X GET http://your-api-url/health
```

### Response
#### Success Response (200)
- **status** (string) - The health status of the API (e.g., "ok").

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### Health Check Server Status (API GET)

Source: https://context7.com/to-nexus/cross-ramp-integration-sample/llms.txt

Performs a GET request to the /health endpoint to check if the server is running and responsive. A successful response returns a JSON object with a 'status' field set to 'ok', indicating the service is operational.

```cURL
# Check server health
curl -X GET "http://localhost:8080/health"

# Response (200 OK)
{
  "status": "ok"
}
```

--------------------------------

### Manage Session Assets with Go

Source: https://context7.com/to-nexus/cross-ramp-integration-sample/llms.txt

Demonstrates in-memory database operations for managing session-specific game assets using Go. It covers creating sessions with random asset balances, checking balances, deducting assets for mint operations, and adding assets from disassemble results. This functionality is crucial for tracking player inventory within a game session.

```go
package database

// Get or create session assets - auto-generates random balances for new sessions
sessionAssets, err := database.GetOrCreateSessionAssets("player_session_123")
// Returns: SessionAssets{
//   SessionID: "player_session_123",
//   Assets: map[string]string{
//     "asset_money": "50234567",
//     "asset_gold": "12345678",
//     "item_gem": "9876543",
//     ...
//   },
//   CreatedAt: "2024-01-15T10:30:00Z",
//   UpdatedAt: "2024-01-15T10:30:00Z"
// }

// Check and deduct assets for mint operations
fromAssets := []models.PairAsset{
    {Type: "asset", AssetID: "asset_money", Amount: 10000},
}
err := database.CheckAndDeductAssets("player_session_123", fromAssets)
// Returns error if insufficient balance

// Add assets after successful disassemble
toAssets := []models.PairAsset{
    {Type: "asset", AssetID: "item_gem", Amount: 500},
}
err := database.AddAssets("player_session_123", toAssets)
```

--------------------------------

### Query In-Game Assets - Bash

Source: https://context7.com/to-nexus/cross-ramp-integration-sample/llms.txt

Retrieves in-game currency balances for a user session. This API call demonstrates how to query assets by providing session and authorization headers. The response includes player details and a list of available assets with their balances.

```bash
# Query assets for a user session
curl -X GET "http://localhost:8080/api/assets?language=ko" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "X-Dapp-Authorization: Bearer dapp_token_abc123" \
  -H "X-Dapp-SessionID: session_player_001"

# Response (200 OK)
{
  "success": true,
  "errorCode": null,
  "data": {
    "v1": {
      "player_id": "session_player_001",
      "name": "playerName_session_player_001",
      "wallet_address": "0xaaaa",
      "server": "test",
      "assets": [
        { "id": "asset_money", "balance": "50234567" },
        { "id": "asset_gold", "balance": "12345678" },
        { "id": "item_gem", "balance": "9876543" },
        { "id": "item_banana", "balance": "5432100" }
      ]
    },
    "guide": {
      "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "X-Dapp-Authorization": "Bearer dapp_token_abc123",
      "X-Dapp-SessionID": "session_player_001",
      "message": "The guide field displays header information at request time...",
      "session_info": {
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    }
  }
}
```

--------------------------------

### Query Game Assets using cURL

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/GUIDE.md

This API retrieves in-game currencies for characters. It requires authentication via CROSS_AUTH_JWT and optionally DAPP_ACCESS_TOKEN and DAPP_SESSION_ID. The response includes player details and asset balances.

```bash
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>"
```

--------------------------------

### Asset Information Query API

Source: https://context7.com/to-nexus/cross-ramp-integration-sample/llms.txt

Retrieves in-game currency balances for a user session. The API returns asset information mapped to a player character, including their wallet address and all available in-game currencies. Session-specific assets are automatically created with random balances if the session doesn't exist.

```APIDOC
## GET /api/assets

### Description
Retrieves in-game currency balances for a user session. The API returns asset information mapped to a player character, including their wallet address and all available in-game currencies. Session-specific assets are automatically created with random balances if the session doesn't exist.

### Method
GET

### Endpoint
/api/assets

#### Query Parameters
- **language** (string) - Optional - Specifies the language for the response.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **X-Dapp-Authorization** (string) - Required - Bearer token for DApp authorization.
- **X-Dapp-SessionID** (string) - Required - The session ID of the player.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **errorCode** (string) - Null if successful, otherwise an error code.
- **data** (object) - Contains the asset information.
  - **v1** (object)
    - **player_id** (string) - The player's session ID.
    - **name** (string) - The player's name.
    - **wallet_address** (string) - The player's wallet address.
    - **server** (string) - The server name.
    - **assets** (array) - An array of asset objects.
      - **id** (string) - The asset ID.
      - **balance** (string) - The asset balance.
  - **guide** (object) - Contains information about the request headers and session.
    - **Authorization** (string) - Example Authorization header.
    - **X-Dapp-Authorization** (string) - Example X-Dapp-Authorization header.
    - **X-Dapp-SessionID** (string) - Example X-Dapp-SessionID header.
    - **message** (string) - Description of the guide field.
    - **session_info** (object) - Information about the session.
      - **created_at** (string) - Session creation timestamp.
      - **updated_at** (string) - Session update timestamp.

#### Response Example
```json
{
  "success": true,
  "errorCode": null,
  "data": {
    "v1": {
      "player_id": "session_player_001",
      "name": "playerName_session_player_001",
      "wallet_address": "0xaaaa",
      "server": "test",
      "assets": [
        { "id": "asset_money", "balance": "50234567" },
        { "id": "asset_gold", "balance": "12345678" },
        { "id": "item_gem", "balance": "9876543" },
        { "id": "item_banana", "balance": "5432100" }
      ]
    },
    "guide": {
      "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "X-Dapp-Authorization": "Bearer dapp_token_abc123",
      "X-Dapp-SessionID": "session_player_001",
      "message": "The guide field displays header information at request time...",
      "session_info": {
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    }
  }
}
```
```

--------------------------------

### Game Server Implementation Requirements

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/GUIDE.md

Requirements for game server implementation to support CrossRamp integration.

```APIDOC
## Game Server Implementation Requirements

### Description
This section outlines the essential components and APIs that game servers must implement to facilitate a smooth integration with the CrossRamp platform.

### Requirements
- **hmac key** (string) - X-HMAC-SIGNATURE verification key used for mutual trust between ramp backend and game backend for API requests and responses. Provided by Nexus, stored by both Nexus and game company. Future generation and replacement possible through developer console.
- **validator key** (string) - Used when the validation API receives an order information verification request to the game server. The game server signs with this key after validation if the order is normal. Key stored by the game company; Nexus only stores the public key. Future generation and replacement possible through developer console.
- **Assets Query API** (API v1) - Used for querying a user's in-game assets within the Ramp UI.
- **Validate API** (API) - Used for validating user orders within the Ramp UI.
- **Result API** (API) - Used for processing on-chain result transmissions.
- **CORS** (Configuration) - CORS registration is required for the `https://ramp.crosstoken.io` site.
```

--------------------------------

### Manage Session Assets with TypeScript

Source: https://context7.com/to-nexus/cross-ramp-integration-sample/llms.txt

Illustrates session asset management using TypeScript with an in-memory database. It shows how to store UUID to session ID mappings, retrieve session IDs using UUIDs (useful for webhook callbacks), and fetch session asset details. This is essential for correlating external events with internal game sessions.

```typescript
import { MemoryDatabase } from './database/memoryDb';

const db = new MemoryDatabase();

// Store UUID to session mapping for result correlation
db.storeUuidMapping('c8ab8d7b-3fe7-4a2b-9c1d-e5f6a7b8c9d0', 'player_session_123');

// Retrieve session by UUID (used in result webhook)
const sessionId = db.getSessionIdByUuid('c8ab8d7b-3fe7-4a2b-9c1d-e5f6a7b8c9d0');
// Returns: 'player_session_123'

// Get session assets
const assets = db.getSessionAssets('player_session_123');
// Returns: { sessionId: '...', assets: [{id: 'asset_money', balance: '50234567'}, ...] }
```

--------------------------------

### Process Failed Transaction (API POST)

Source: https://context7.com/to-nexus/cross-ramp-integration-sample/llms.txt

Sends a POST request to the /api/result endpoint to log a failed transaction. This example shows a failed 'assemble' intent where assets were not credited. The response indicates the transaction was logged, but no asset changes occurred due to the failure.

```cURL
curl -X POST "http://localhost:8080/api/result" \
  -H "Content-Type: application/json" \
  -H "X-HMAC-SIGNATURE: abc123..." \
  -d '{
    "uuid": "failed-tx-uuid-123",
    "tx_hash": "0xfailed...",
    "receipt": {
      "status": 0
    },
    "intent": {
      "type": "assemble",
      "method": "mint",
      "from": [{ "type": "asset", "id": "asset_money", "amount": 1000 }],
      "to": [{ "type": "erc20", "id": "0x1234", "amount": 1 }]
    }
  }'
```

--------------------------------

### Query Order Information using cURL

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/GUIDE.md

This API allows checking order information executed by users on Cross-Ramp. It requires chain network information and a user UUID for querying. The response includes details about the order status, type, and involved assets/tokens.

```bash
curl 
  -X GET 'https://cross-ramp-api.crosstoken.io/api/v1/order?network={chain_network}&uuid={user_uuid}' \
  -H 'accept: application/json'
```

--------------------------------

### CMake Build Configuration

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/cpp/CMakeLists.txt

This snippet defines the core CMake build configuration for the C++ project. It sets the minimum CMake version, project name, C++ standard, and required packages. It also includes directories for headers and source files, lists the source files to be compiled, and creates the final executable.

```cmake
cmake_minimum_required(VERSION 3.16)
project(sample_game_backend_cpp)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Find required packages
find_package(PkgConfig REQUIRED)
find_package(Threads REQUIRED)
find_package(nlohmann_json 3.2.0 REQUIRED)

# Find OpenSSL
find_package(OpenSSL REQUIRED)

# Add cpp-httplib (header-only library)
include_directories(/opt/homebrew/include)

# Include directories
include_directories(${CMAKE_SOURCE_DIR}/include)
include_directories(${CMAKE_SOURCE_DIR}/src)

# Add source files
set(SOURCES
    src/main.cpp
    src/config.cpp
    src/database.cpp
    src/handlers.cpp
    src/services.cpp
    src/server.cpp
    src/keystore.cpp
    src/hmac.cpp
)

# Create executable
add_executable(${PROJECT_NAME} ${SOURCES})

# Link libraries
target_link_libraries(${PROJECT_NAME}
    Threads::Threads
    nlohmann_json::nlohmann_json
    OpenSSL::SSL
    OpenSSL::Crypto
    ${CMAKE_DL_LIBS}
)

# Compiler flags
target_compile_options(${PROJECT_NAME} PRIVATE -Wall -Wextra)

# Install target
install(TARGETS ${PROJECT_NAME} DESTINATION bin)
```

--------------------------------

### UI Integration - Access Link Parameters

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/GUIDE.md

Parameters used in the CrossRamp UI integration access link.

```APIDOC
## UI Integration - Access Link Parameters

### Description
Parameters used in the CrossRamp UI integration access link to configure the user experience and project settings.

### Endpoint
`/catalog` (Example path)

### Query Parameters
- **projectId** (string) - Required - Project ID issued by Nexus.
- **sessionId** (string) - Required - Unique ID that can identify the character.
- **accessToken** (string) - Required - In-game user authentication token.
- **network** (string) - Optional - Specifies the network ('mainnet' or 'testnet'). Defaults to 'mainnet' if omitted.
- **lang** (string) - Optional - Language selection (e.g., 'zh', 'en', 'zh-Hant').
- **platform** (string) - Optional - Specifies the platform, typically 'web'.
```

--------------------------------

### Webhook Response Handling

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/GUIDE.md

Guidelines for responding to webhooks, including success and error codes, and details on the retry mechanism for failed transmissions.

```APIDOC
## Sending Response to Webhook

To confirm webhook reception, the server must return the following:
- ```200``` HTTP code for successful response
- ```400``` HTTP code with <span style="color:skyblue"><b>problem description</b></span> if not delivered as predefined request
- ```5xx``` HTTP code if temporary server problem occurs

If CROSS RAMP does not receive a response to the <b>*exchange order result*</b> webhook or receives a response containing ```5xx``` code, it will retransmit according to the following rules:
- 2 attempts at 5-minute intervals
- 7 attempts at 15-minute intervals
- 10 attempts at 60-minute intervals
According to these rules, webhook transmission will attempt retransmission up to 20 times within 12 hours after the first attempt.

### Error Response Structure
```json
{
    "errorCode": int,
    "errorMessage": string
}
```

#### Define Errors
| http status | error code | desc. |
|---|---|---|
| 500 | 1001 | internal server error |
| 400 | 2001 | bad request parameter (GET) |
|  | 2002 | bad request JSON (POST) |
| 401 | 3001 | unauthorized |

#### Error Example
```json
{
  "errorCode": 1001,
  "errorMessage": "character not exists"
}

{
  "errorCode": 2001,
  "errorMessage": "param1 is required"
}

{
  "errorCode": 2002,
  "errorMessage": "invalid JSON"
}

{
  "errorCode": 3001,
  "errorMessage": "session id is required"
}
```
```

--------------------------------

### Validate Exchange Order - Bash

Source: https://context7.com/to-nexus/cross-ramp-integration-sample/llms.txt

Validates user exchange requests, such as minting (in-game assets to tokens). This API verifies asset balances, deducts assets, and generates a validator signature for the on-chain transaction. It requires specific headers including HMAC signature for security.

```bash
# Validate a mint order (convert in-game assets to tokens)
curl -X POST "http://localhost:8080/api/validate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "X-Dapp-Authorization: Bearer dapp_token_abc123" \
  -H "X-Dapp-SessionID: session_player_001" \
  -H "X-HMAC-SIGNATURE: a1b2c3d4e5f6..." \
  -d '{
    "uuid": "c8ab8d7b-3fe7-4a2b-9c1d-e5f6a7b8c9d0",
    "user_sig": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "user_address": "0xB777C937fa1afC99606aFa85c5b83cFe7f82BabD",
    "project_id": "nexus-ramp-v1",
    "digest": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "intent": {
      "type": "assemble",
      "method": "mint",
      "from": [
        { "type": "asset", "id": "asset_money", "amount": 10000 }
      ],
      "to": [
        { "type": "erc20", "id": "0x1234567890abcdef1234567890abcdef12345678", "amount": 1 }
      ]
    }
  }'

# Response (200 OK)
{
  "success": true,
  "errorCode": null,
  "data": {
    "userSig": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "validatorSig": "0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba1c"
  }
}

# Error Response - Insufficient Balance (400)
{
  "success": false,
  "errorCode": "INSUFFICIENT_BALANCE",
  "message": "Insufficient balance for operation"
}
```

--------------------------------

### Deliver Exchange Results using cURL

Source: https://github.com/to-nexus/cross-ramp-integration-sample/blob/master/GUIDE.md

This API is used to receive the results of exchanges between game assets and tokens. It handles on-chain failures, triggers in-game asset refunds if necessary, and distributes in-game currency for disassemble intents. It uses UUID to prevent duplicate processing.

```bash
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": {
      "status" : 0x1,
      ...
    },
    "intent": {
      "type": "assemble", // assemble || disassemble
      "method": "mint",
      "from": [{ "type": "asset", "id": "material_01", "amount": 1000 }],
      "to": [{ "type": "erc20", "id": "0x1234", "amount": 1 }],
    }
  }'
```

--------------------------------

### Intent Validation Service

Source: https://context7.com/to-nexus/cross-ramp-integration-sample/llms.txt

Validates exchange intent structures, ensuring allowed methods and correct item types for mint operations.

```APIDOC
## Intent Validation Service

### Description
Validates exchange intent structures before processing. Ensures the method is allowed (mint, transfer, burn, burn-permit, transfer-from, transfer-from-permit) and that mint operations have valid asset-type source items.

### Method
N/A (This describes a service/logic, not a direct API endpoint)

### Endpoint
N/A

### Parameters
#### Request Body (for validation logic)
- **intent** (object) - Required - The exchange intent object to validate.
  - **type** (string) - Required - The type of intent (e.g., "assemble", "disassemble").
  - **method** (string) - Required - The method of the intent (e.g., "mint", "burn"). Must be one of the allowed methods.
  - **from** (array) - Required - Items originating from the transaction.
    - **type** (string) - Required - Type of the item (e.g., "asset", "erc20").
    - **id** (string) - Required - Identifier of the item.
    - **amount** (integer) - Required - Amount of the item.
  - **to** (array) - Required - Items destined for the transaction.
    - **type** (string) - Required - Type of the item (e.g., "asset", "erc20").
    - **id** (string) - Required - Identifier of the item.
    - **amount** (integer) - Required - Amount of the item.

### Request Example (for validation logic)
```json
{
  "type": "assemble",
  "method": "mint",
  "from": [{ "type": "asset", "id": "asset_money", "amount": 1000 }],
  "to": [{ "type": "erc20", "id": "0x1234", "amount": 1 }]
}
```

### Response
#### Success Response
- **boolean** - `true` if the intent is valid, `false` otherwise.

#### Response Example (Conceptual - return value of the validation function)
```go
// Go intent validation function returns a boolean
// return true // for valid intent
// return false // for invalid intent
```
```