API Interaction

How the game server communicates with Monsuta Core for off-chain to on-chain settlement.

Purpose

The API interaction layer defines how a game server submits gameplay results to the blockchain. It exists because:

Game servers must not interact with smart contracts directly from gameplay code
There must be a standardized interface between off-chain game logic and on-chain settlement
The communication model must handle failures, retries, and authorization
Multiple games using Monsuta Core need a consistent integration pattern

Communication Model

┌──────────────────────────────────────────────────────────────┐
│                       GAME SERVER                            │
│                                                              │
│  ┌────────────┐  ┌────────────┐  ┌─────────────────────────┐ │
│  │ Match      │  │ Reward     │  │ Monsuta Core            │ │
│  │ Engine     │──►│ Calculator │──►│ API Client              │ │
│  │            │  │            │  │                          │ │
│  │ gameplay   │  │ determines │  │ • signs requests         │ │
│  │ logic      │  │ who earned │  │ • batches transactions   │ │
│  │            │  │ what       │  │ • handles retries        │ │
│  └────────────┘  └────────────┘  │ • tracks tx status      │ │
│                                  └──────────┬──────────────┘ │
└─────────────────────────────────────────────┼────────────────┘
                                              │
                                    signed API requests
                                              │
                                 ┌────────────▼────────────┐
                                 │  Monsuta Core Gateway   │
                                 │  (optional middleware)   │
                                 │                          │
                                 │  • validates signatures  │
                                 │  • rate limiting         │
                                 │  • queue management      │
                                 │  • nonce management      │
                                 └────────────┬────────────┘
                                              │
                                    smart contract calls
                                              │
                                 ┌────────────▼────────────┐
                                 │     AVALANCHE C-CHAIN   │
                                 │                          │
                                 │  Prize Pool Contract     │
                                 │  Identity Contract       │
                                 │  Crafting Contract       │
                                 │  THC Token Contract      │
                                 └─────────────────────────┘

Interaction Patterns

Pattern 1: Server-Signed, Player-Submitted

The server generates a signed attestation. The player submits the transaction.

Server signs attestation:
  "Player 0x1234 won match #567 and earned 100 THC"
       │
       ▼
Signature sent to player's game client
       │
       ▼
Player submits claim() transaction with signature
       │
       ▼
Contract verifies server signature, processes claim

When to use:

Player claims rewards
Player crafts items
Player mints achievements

Advantages:

Player pays gas (server has no gas costs)
Player controls timing of claim
No server-to-chain dependency for routine claims

Disadvantages:

Player needs AVAX for gas
Claim UX requires wallet interaction

Pattern 2: Server-Submitted (Push)

The server submits transactions directly.

Server detects economic event (season end, tournament complete)
       │
       ▼
Server submits transaction to contract
       │
       ▼
Contract processes event (distributes rewards, mints NFTs)

When to use:

Season finalization (submitting final rankings)
Tournament result submission
Batch operations affecting many players

Advantages:

Players don't need gas
Immediate finality
Suitable for batch operations

Disadvantages:

Server pays gas
Server key must be funded and secured
Server downtime blocks settlements

Pattern 3: Hybrid (Server Signs, Relayer Submits)

Server signs payload
       │
       ▼
Payload stored (database or queue)
       │
       ▼
Relayer service picks up pending payloads
       │
       ▼
Relayer submits transactions to chain
       │
       ▼
Relayer monitors confirmations

When to use:

High-volume operations
When separating signing authority from gas payment
When using a third-party relayer service (e.g., OpenZeppelin Defender, Gelato)

API Endpoints

Result Submission

POST /api/v1/results/submit

Authorization: Bearer <server_api_key>

Body:
{
  "competition_id": "season_1",
  "competition_type": "season",      // "season" | "tournament" | "event"
  "results": [
    {
      "player": "0x1234...",
      "rank": 1,
      "stats": {
        "wins": 87,
        "losses": 23,
        "elo": 2150
      }
    },
    {
      "player": "0x5678...",
      "rank": 2,
      "stats": {
        "wins": 80,
        "losses": 30,
        "elo": 2050
      }
    }
  ],
  "timestamp": 1777420800,
  "nonce": 42
}

Response:
{
  "tx_hash": "0xABCD...",
  "status": "pending",
  "confirmation_url": "/api/v1/tx/0xABCD..."
}

Reward Claim Generation

POST /api/v1/claims/generate

Authorization: Bearer <server_api_key>

Body:
{
  "player": "0x1234...",
  "reward_type": "season_thc",
  "amount": 5000,
  "season_id": 1,
  "nonce": 12345
}

Response:
{
  "claim_data": {
    "player": "0x1234...",
    "amount": 5000,
    "nonce": 12345,
    "expiry": 1778020800
  },
  "signature": "0x9876...ABCD",
  "contract": "0xTHC_CONTRACT...",
  "method": "claim(address,uint256,uint256,uint256,bytes)"
}

Achievement Minting

POST /api/v1/achievements/mint

Authorization: Bearer <server_api_key>

Body:
{
  "player": "0x1234...",
  "achievement_type_id": 42,
  "season_id": 1,
  "competition_id": 0,
  "metadata": {
    "league": "Diamond",
    "final_rank": 3,
    "wins": 87,
    "win_rate": "79%"
  }
}

Response:
{
  "mint_data": { ... },
  "signature": "0xSIG...",
  "token_id": null,    // assigned on mint
  "status": "ready_to_mint"
}

Crafting Authorization

POST /api/v1/crafting/authorize

Authorization: Bearer <server_api_key>

Body:
{
  "player": "0x1234...",
  "recipe_id": 1,
  "input_nft_ids": [101, 102],      // if recipe requires NFT inputs
  "materials_verified": true,        // server confirms off-chain material balance
  "thc_amount": 500,
  "nonce": 67890
}

Response:
{
  "craft_data": { ... },
  "signature": "0xCRAFTSIG...",
  "contract": "0xCRAFTING...",
  "method": "craft(uint256,uint256[],uint256,bytes)"
}

Transaction Status

GET /api/v1/tx/{tx_hash}

Response:
{
  "tx_hash": "0xABCD...",
  "status": "confirmed",        // "pending" | "confirmed" | "failed" | "reverted"
  "block_number": 12345678,
  "confirmations": 5,
  "gas_used": 125000,
  "error": null                  // populated on failure/revert
}

Authorization Model

Server API Key

Used for server-to-gateway authentication
Not a blockchain key — just an API key
Rotatable without affecting on-chain state

Server Signing Key

EVM private key used to sign attestations
Must be registered in on-chain contracts as an authorized signer
Should be stored in a KMS, not in application config
Rotation requires updating contract registrations

Separation of Concerns

┌────────────┐     ┌──────────┐     ┌──────────────┐
│ API Key    │     │ Signing  │     │ Gas Wallet   │
│            │     │ Key      │     │              │
│ authenticates    │ signs    │     │ pays for     │
│ server to  │     │ payload  │     │ transactions │
│ gateway    │     │ data     │     │              │
│            │     │          │     │              │
│ not on-chain│     │ registered│    │ funded with  │
│             │     │ on-chain │     │ AVAX         │
└────────────┘     └──────────┘     └──────────────┘

Error Handling

Retry Strategy

Error Type	Retry?	Strategy
Network timeout	Yes	Exponential backoff (1s, 2s, 4s, 8s, 16s)
Nonce too low	Yes	Fetch current nonce, resubmit
Gas price spike	Yes	Wait for gas price to stabilize
Contract revert	No	Log error, investigate root cause
Signature invalid	No	Signing key mismatch, investigate
Already claimed	No	Skip — claim was already processed

Idempotency

All API calls must be idempotent. The nonce field prevents replay:

First call:   nonce=42 → success → claim processed
Replay:       nonce=42 → contract reverts "already used"

Queue Management

For high-volume operations (season end, batch minting):

┌─────────────┐     ┌──────────────┐     ┌──────────────┐
│ Game Server │     │ Transaction  │     │  Blockchain  │
│             │     │ Queue        │     │              │
│ enqueues    │────►│              │────►│ transactions │
│ 500 reward  │     │ • priority   │     │ submitted    │
│ claims      │     │ • rate limit │     │ sequentially │
│             │     │ • nonce mgmt │     │              │
│             │     │ • retry      │     │              │
└─────────────┘     └──────────────┘     └──────────────┘

Why a queue? Submitting 500 transactions simultaneously causes nonce conflicts and gas price bidding wars. A queue serializes submissions with proper nonce management and gas estimation.

Integration Guide for Other Games

Step 1: Choose Your Pattern

Your Situation	Recommended Pattern
Players have wallets and AVAX for gas	Server-signed, player-submitted
Players should not pay gas	Server-submitted (push)
High volume, need reliability	Hybrid with relayer
Mixed: some player-submitted, some push	Multiple patterns in parallel

Step 2: Implement the API Client

Wrap your on-chain interactions in an API client module
Handle signing, nonce management, and retries
Log all transactions for audit

Step 3: Secure Your Keys

API keys in environment variables
Signing keys in KMS (AWS KMS, GCP KMS, HashiCorp Vault)
Gas wallet funded with monitoring alerts
Key rotation plan documented

Step 4: Test on Testnet

Deploy contracts on Avalanche Fuji
Run all API flows end-to-end
Simulate failure cases (network timeout, gas spikes, double-submit)
Verify idempotency

Step 5: Monitor in Production

Track pending transactions and confirmation times
Alert on failed submissions or reverts
Monitor gas wallet balance
Log all signed payloads for audit and debugging

Purpose​

Communication Model​

Interaction Patterns​

Pattern 1: Server-Signed, Player-Submitted​

Pattern 2: Server-Submitted (Push)​

Pattern 3: Hybrid (Server Signs, Relayer Submits)​

API Endpoints​

Result Submission​

Reward Claim Generation​

Achievement Minting​

Crafting Authorization​

Transaction Status​

Authorization Model​

Server API Key​

Server Signing Key​

Separation of Concerns​

Error Handling​

Retry Strategy​

Idempotency​

Queue Management​

Integration Guide for Other Games​

Step 1: Choose Your Pattern​

Step 2: Implement the API Client​

Step 3: Secure Your Keys​

Step 4: Test on Testnet​

Step 5: Monitor in Production​

Purpose

Communication Model

Interaction Patterns

Pattern 1: Server-Signed, Player-Submitted

Pattern 2: Server-Submitted (Push)

Pattern 3: Hybrid (Server Signs, Relayer Submits)

API Endpoints

Result Submission

Reward Claim Generation

Achievement Minting

Crafting Authorization

Transaction Status

Authorization Model

Server API Key

Server Signing Key

Separation of Concerns

Error Handling

Retry Strategy

Idempotency

Queue Management

Integration Guide for Other Games

Step 1: Choose Your Pattern

Step 2: Implement the API Client

Step 3: Secure Your Keys

Step 4: Test on Testnet

Step 5: Monitor in Production