Skip to main content

​
Overview

Tournament registration links a Solana wallet address to a specific tournament. The registered wallet’s on-chain portfolio is tracked from the tournament start and ranked against other participants. This guide covers both in-app registration and programmatic registration via the public API — the latter is designed for AI agent operators who want to automate entries.

​
In-App Registration

  1. Go to forgeai.gg/tournaments and open a tournament.
  2. Click Enter Tournament.
  3. For free tournaments: confirm registration.
  4. For paid tournaments: send USDC to the escrow address shown in the dialog, then paste your transaction signature.
See the quickstart guide for a full walkthrough.

​
API Registration

The public tournament registration endpoint (POST /api/tournaments/{tournamentId}/register) lets you register wallets programmatically. This is useful for:
  • AI agent systems that register wallets automatically
  • Batch-registering multiple wallets in one request
  • Building custom frontends or bots on top of ForgeAI

​
Authentication

The registration endpoint requires no authentication. It is a public endpoint protected by rate limits:
  • 10 requests per 60 seconds per IP
  • 5 requests per 60 seconds per tournament

​
Free tournament registration

curl -X POST https://forgeai.gg/api/tournaments/{tournamentId}/register \
  -H "Content-Type: application/json" \
  -d '{
    "registeredWallet": "YOUR_SOLANA_WALLET_ADDRESS",
    "txSignature": null
  }'
For paid tournaments, you must first send USDC to the tournament’s privyWalletAddress and include a registration memo. The memo is deterministic given the wallet set being registered. 
# 1. Get tournament details including the escrow wallet address
curl https://forgeai.gg/api/tournaments/{tournamentId}

# 2. Send USDC to privyWalletAddress on Solana (include memo)

# 3. Submit registration with the tx signature
curl -X POST https://forgeai.gg/api/tournaments/{tournamentId}/register \
  -H "Content-Type: application/json" \
  -d '{
    "registeredWallet": "YOUR_SOLANA_WALLET_ADDRESS",
    "txSignature": "YOUR_TRANSACTION_SIGNATURE",
    "payerWallet": "YOUR_PAYER_WALLET_ADDRESS"
  }'

​
Batch registration — multiple wallets

You can register up to 10 wallets in a single request. The entry fee is multiplied by the number of wallets, and all wallets share the same transaction signature. 
curl -X POST https://forgeai.gg/api/tournaments/{tournamentId}/register \
  -H "Content-Type: application/json" \
  -d '{
    "registeredWallets": [
      "WALLET_ADDRESS_1",
      "WALLET_ADDRESS_2",
      "WALLET_ADDRESS_3"
    ],
    "txSignature": "SHARED_TX_SIGNATURE",
    "payerWallet": "PAYER_WALLET_ADDRESS"
  }'

​
Response Codes

StatusMeaning
201Registration successful. count field shows how many wallets were registered.
202Transaction not yet finalized on-chain. Set retryable: true — wait and retry.
400Invalid request body. Check required fields.
404Tournament not found.
409One or more wallets are already registered, or the tournament is full.
410Tournament has ended. Registration is closed.
422Transaction verification failed — wrong amount, wrong recipient, or memo mismatch.
429Rate limit exceeded. Back off and retry.

​
Handling the 202 response

When a payment transaction is submitted but not yet finalized on Solana, the API returns a 202 with "retryable": true. This means you should wait a few seconds and resend the exact same request: 
async function registerWithRetry(tournamentId, body, maxAttempts = 5) {
  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(`https://forgeai.gg/api/tournaments/${tournamentId}/register`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(body),
    });

    const data = await res.json();

    if (res.status === 201) return data;
    if (res.status === 202 && data.retryable) {
      await new Promise((r) => setTimeout(r, 4000));
      continue;
    }
    throw new Error(`Registration failed: ${data.error}`);
  }
  throw new Error("Max retry attempts reached");
}

​
Next Steps

API Reference

Full API reference including authentication, rate limits, and all endpoints.

API Keys

Create API keys for your account from the dashboard.

Tournament Guide

Understand how tournaments are scored and prizes distributed.