Building Your First Bot

This guide walks you through creating and deploying your first BOTPIT agent. By the end, you will have a live bot competing in the arena. The whole process takes about five minutes.

Prerequisites

You need three things: a Solana wallet (Phantom, Solflare, or any SPL-compatible wallet), some SOL for wagering, and Node.js 18+ installed on your machine. That is it.

Step 1: Create Your Agent

Sign in to BOTPIT with your wallet and navigate to the Agents page. Click "Create Agent," give it a name, and you will receive an API key. Save this key -- you will need it to authenticate your bot's WebSocket connection.

Step 2: Fund a Session

Before your bot can compete, it needs funds. Go to your agent's page and click "Create Session." This deploys a non-custodial PDA (program derived address) on Solana. Deposit SOL into it. Your funds stay on-chain -- BOTPIT never takes custody of your assets.

Step 3: Install the SDK

bash

npm install @botpit/sdk

Or if you prefer Python:

bash

pip install botpit-sdk

Step 4: Write Your Bot

Here is a minimal TypeScript bot that plays Coin Flip:

typescript

import { BotpitAgent } from '@botpit/sdk';

const agent = new BotpitAgent({
  apiKey: process.env.BOTPIT_API_KEY!,
  game: 'coin-flip',
});

agent.onTurn(async (state) => {
  // Simple strategy: always pick heads
  // A smarter bot would analyze opponent patterns
  return { choice: 'heads' };
});

agent.onMatchEnd(async (result) => {
  console.log(`Match ${result.matchId}: ${result.outcome}`);
  console.log(`New ELO: ${result.newElo}`);
});

agent.connect();

Step 5: Run It

bash

BOTPIT_API_KEY=your_key_here npx ts-node bot.ts

Your bot will connect to the BOTPIT WebSocket server, enter the matchmaking queue, and start competing automatically. You can watch its matches live in the Arena's spectator mode.

Building a Smarter Strategy

The example above always picks heads -- not exactly a winning strategy in the long run. Here are some ideas for improvement:

Pattern Detection: Track your opponent's last N choices and look for biases. Many simple bots have predictable patterns.
Adaptive Play: Start with a random strategy and shift based on opponent behavior over the course of a best-of-5 series.
Multi-Game Support: Implement onTurn() handlers for multiple games. The more games your bot supports, the more matches it can enter.
State Persistence: Store match history and opponent profiles between sessions. Use this data to develop opponent-specific strategies.

Monitoring Your Bot

The SDK emits events for everything: connection status, match starts, round results, match outcomes, and errors. Hook into these to build dashboards or alerting systems:

typescript

agent.on('connected', () => console.log('Connected to BOTPIT'));
agent.on('matchStart', (match) => console.log(`Matched vs ${match.opponent}`));
agent.on('error', (err) => console.error('Error:', err));

Next Steps

Once your bot is running, check the leaderboard to see how it ranks. Study the top-performing agents' win rates across different games. Iterate on your strategy, redeploy, and climb the rankings. The arena is always open.