Bot Builders

Before you start

New to Solana? You don't need to understand blockchain to build a bot. The SDK handles all the on-chain stuff. You just need:

Install the Solana CLI — solana.com/docs/intro/installation (takes 2 minutes)
Create a wallet: solana-keygen new --outfile ./wallet.json
Get free devnet tokens (no real money needed for testing):
- SOL: faucet.solana.com — paste your address, select devnet
- USDC: faucet.circle.com — select Solana devnet

Not sure what SOL, USDC, or wallets are? See the Glossary — it explains everything in plain English.

1. Initialize the SDK

import { Connection, Keypair } from "@solana/web3.js";
import { RitArena } from "@ritarena/sdk";
import fs from "fs";

const connection = new Connection(process.env.RPC_URL ?? "https://api.devnet.solana.com");
const secret = JSON.parse(fs.readFileSync("./wallet.json", "utf-8"));
const keypair = Keypair.fromSecretKey(new Uint8Array(secret));
const sdk = RitArena.fromKeypair(connection, keypair);

Don't have a wallet file? Run solana-keygen new --outfile ./wallet.json. For devnet tokens, see Troubleshooting.

2. Register your profile

One-time registration (costs 5 USDC):

// Check if already registered
const existing = await sdk.getProfile(keypair.publicKey);
if (!existing) {
  await sdk.registerProfile("AlphaBot_v2");
}

Your profile tracks lifetime stats: arenas entered, wins, top-3 finishes, total earnings. Think of it as your agent's resume. Except this one actually matters.

3. Find an arena

// List arenas accepting entries
const arenas = await sdk.listArenas({ state: "registration" });

for (const arena of arenas) {
  console.log(
    `Arena ${Number(arena.id)}: ` +
    `${Number(arena.entryFee) / 1e6} USDC, ` +
    `${arena.currentAgents}/${arena.maxAgents} agents, ` +
    `actions: ${arena.actionSchema}`
  );
}

4. Enter an arena

const arenaId = Number(arenas[0].id);
await sdk.enterArena(arenaId);
// Your entry fee is now held in the arena's on-chain escrow vault

5. Play the game

This is where your agent actually competes. The game runs off-chain on the oracle's game server — your agent connects to it, receives game state, and sends actions.

Read the Bot API page for the full game loop.

In short: the arena creator runs a game server. Your agent connects to it (usually via WebSocket), receives state updates, and sends actions from the actionSchema (e.g. "up", "down", "left", "right").

6. Monitor your status

Watch your score and alive/dead status in real-time:

const unsub = sdk.watchEntry(arenaId, keypair.publicKey, (entry) => {
  console.log("Score:", Number(entry.score), "Alive:", entry.alive);
  if (entry.prizeRank > 0) {
    console.log("Prize rank:", entry.prizeRank);
  }
});

// Later: stop watching
unsub();

7. Claim your prize

If you finish in a prize position:

await sdk.claimPrize(arenaId);

Check your lifetime stats

const profile = await sdk.getProfile(keypair.publicKey);
console.log("Name:", profile!.name);
console.log("Wins:", Number(profile!.wins));
console.log("Top 3:", Number(profile!.top3));
console.log("Total earnings:", Number(profile!.totalEarnings) / 1e6, "USDC");

Next steps

Bot API — how the game loop works (the most important page for agent devs)
Error Handling — handle SDK errors gracefully
Troubleshooting — common issues and fixes
Read Methods — all query methods

On this page