🔌API Reference

REST API & WebSocket Documentation

This document provides complete API reference for integrating with the Robot Fighting Championship platform.

🌐 Base URLs

Production:

REST API: https://api.robotfight.io/v1
WebSocket: wss://ws.robotfight.io

Authentication: Most endpoints require an API key or wallet signature.

🔐 Authentication

Admin Endpoints

Admin endpoints require Bearer token authentication:

Authorization: Bearer <ADMIN_TOKEN>

User Endpoints

User endpoints require wallet signature verification:

// Generate signature
const message = `robotfight:${timestamp}:${walletAddress}`;
const signature = await wallet.signMessage(message);

// Send in header
Authorization: Signature ${walletAddress}:${timestamp}:${signature}

📡 REST API Endpoints

Fights

GET /fights

Get all fights (past and upcoming).

Query Parameters:

status (optional): open, live, closed
limit (optional): Number of results (default: 50)
offset (optional): Pagination offset

Response:

{
  "fights": [
    {
      "fight_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "left_fighter": "Morpheus",
      "right_fighter": "NeoNode",
      "status": "closed",
      "winner": "Left",
      "left_pool": 100000000000,
      "right_pool": 50000000000,
      "total_bets": 47,
      "stream_url": "https://pump.fun/fight/7c9e6679",
      "created_at": "2024-10-30T12:00:00Z"
    }
  ],
  "total": 10,
  "limit": 50,
  "offset": 0
}

GET /fights/:fight_id

Get specific fight details.

Response:

{
  "fight_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "left_fighter": "Morpheus",
  "right_fighter": "NeoNode",
  "status": "closed",
  "winner": "Left",
  "left_pool": 100000000000,
  "right_pool": 50000000000,
  "total_bets": 47,
  "left_odds": 1.5,
  "right_odds": 3.0,
  "stream_url": "https://pump.fun/fight/7c9e6679",
  "created_at": "2024-10-30T12:00:00Z",
  "started_at": "2024-10-30T12:05:00Z",
  "ended_at": "2024-10-30T12:06:23Z"
}

POST /admin/fight/create

[Admin Only] Create a new fight.

Request Body:

{
  "fight_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "left_fighter": "Morpheus",
  "right_fighter": "NeoNode"
}

Response:

{
  "success": true,
  "fight_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "message": "Fight created successfully"
}

POST /admin/fight/:fight_id/close

[Admin Only] Close a fight and declare winner.

Request Body:

{
  "winner": "Left"
}

Response:

{
  "success": true,
  "winner": "Left",
  "payouts_processed": 23
}

Bets

GET /bets

Get bet history for authenticated user.

Query Parameters:

status (optional): pending, won, lost
limit (optional): Number of results (default: 50)

Response:

{
  "bets": [
    {
      "bet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "fight_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "wallet_address": "5xWL7...9fXq",
      "amount": 5000000000,
      "fighter_side": "Left",
      "odds": 1.5,
      "status": "won",
      "payout": 7142857143,
      "created_at": "2024-10-30T12:03:00Z"
    }
  ],
  "total": 15
}

POST /bet/create

Place a new bet.

Request Body:

{
  "fight_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "side": "Left",
  "amount": 5000000000,
  "wallet_address": "5xWL7...9fXq",
  "signature": "..."
}

Response:

{
  "success": true,
  "bet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transaction": {
    "blockhash": "...",
    "instructions": [...],
    "feePayer": "..."
  }
}

GET /bet/:bet_id

Get specific bet details.

Response:

{
  "bet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fight_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "wallet_address": "5xWL7...9fXq",
  "amount": 5000000000,
  "fighter_side": "Left",
  "odds": 1.5,
  "status": "won",
  "payout": 7142857143,
  "transaction_signature": "3Jk...",
  "created_at": "2024-10-30T12:03:00Z"
}

POST /bet/:bet_id/claim

Claim payout for winning bet.

Response:

{
  "success": true,
  "payout": 7142857143,
  "transaction_signature": "4Km...",
  "message": "Payout claimed successfully"
}

Fighters

GET /fighters

Get all fighter profiles.

Response:

{
  "fighters": [
    {
      "fighter_id": 1,
      "name": "Morpheus",
      "combat_style": "Strategic Mastermind",
      "win_rate": 0.521,
      "total_fights": 156,
      "wins": 81,
      "losses": 75,
      "avg_fight_duration": 72,
      "signature_move": "Counter-rush into combo",
      "training_focus": {
        "aggression": 0.85,
        "patience": 0.45,
        "adaptability": 0.72
      }
    }
  ]
}

GET /fighters/:fighter_name

Get specific fighter details.

Response:

{
  "fighter_id": 1,
  "name": "Morpheus",
  "combat_style": "Strategic Mastermind",
  "win_rate": 0.521,
  "total_fights": 156,
  "wins": 81,
  "losses": 75,
  "avg_fight_duration": 72,
  "signature_move": "Counter-rush into combo",
  "training_focus": {
    "aggression": 0.85,
    "patience": 0.45,
    "adaptability": 0.72
  },
  "recent_fights": [
    {
      "fight_id": "...",
      "opponent": "NeoNode",
      "result": "win",
      "date": "2024-10-30T12:00:00Z"
    }
  ],
  "matchup_stats": {
    "vs_aggressive": 0.67,
    "vs_defensive": 0.54,
    "vs_balanced": 0.51
  }
}

Statistics

GET /stats/platform

Get platform-wide statistics.

Response:

{
  "total_fights": 10,
  "total_bets": 523,
  "total_volume": 1250000000000,
  "unique_bettors": 187,
  "avg_bet_size": 2390057361,
  "largest_payout": 45000000000,
  "active_fights": 0,
  "upcoming_fights": 0
}

GET /stats/fighter/:fighter_name

Get detailed fighter statistics.

Response:

{
  "name": "Morpheus",
  "performance": {
    "win_rate": 0.521,
    "total_fights": 156,
    "wins": 81,
    "losses": 75
  },
  "betting_stats": {
    "total_bets_on": 234,
    "total_volume": 567000000000,
    "avg_odds": 1.87,
    "roi_for_bettors": 0.12
  },
  "combat_metrics": {
    "avg_damage_dealt": 127.3,
    "avg_damage_taken": 89.7,
    "avg_fight_duration": 72,
    "knockout_rate": 0.34,
    "comeback_rate": 0.23
  }
}

🔌 WebSocket API

Connection

const ws = new WebSocket('wss://ws.robotfight.io');

ws.onopen = () => {
  console.log('Connected to Robot Fight WS');
};

Authentication

ws.send(JSON.stringify({
  type: 'auth',
  wallet_address: '5xWL7...9fXq',
  signature: '...',
  timestamp: Date.now()
}));

Events

Client → Server

Subscribe to Fight

ws.send(JSON.stringify({
  type: 'subscribe',
  fight_id: '7c9e6679-7425-40de-944b-e07fc1f90ae7'
}));

Unsubscribe from Fight

ws.send(JSON.stringify({
  type: 'unsubscribe',
  fight_id: '7c9e6679-7425-40de-944b-e07fc1f90ae7'
}));

Server → Client

Fight Started

{
  "type": "fight:start",
  "fight_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "left_fighter": "Morpheus",
  "right_fighter": "NeoNode",
  "timestamp": 1730289900000
}

Fight State Update (60Hz during live fights)

{
  "type": "fight:state",
  "fight_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "left_position": { "x": 450, "y": 0 },
  "right_position": { "x": 1200, "y": 0 },
  "left_health": 12,
  "right_health": 14,
  "timestamp": 1730289905234
}

Hit Event

{
  "type": "fight:hit",
  "fight_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "attacker": "Left",
  "defender": "Right",
  "damage": 1,
  "remaining_health": 13,
  "timestamp": 1730289905234
}

Fight Ended

{
  "type": "fight:end",
  "fight_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "winner": "Left",
  "duration": 83,
  "final_health": { "left": 8, "right": 0 },
  "timestamp": 1730289983000
}

Bet Placed (real-time betting updates)

{
  "type": "bet:placed",
  "fight_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "side": "Left",
  "amount": 5000000000,
  "new_odds": { "left": 1.45, "right": 3.10 },
  "total_pool": 155000000000,
  "timestamp": 1730289870000
}

Odds Update

{
  "type": "odds:update",
  "fight_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "left_odds": 1.45,
  "right_odds": 3.10,
  "left_pool": 105000000000,
  "right_pool": 50000000000,
  "timestamp": 1730289870000
}

🛠️ SDK & Libraries

JavaScript SDK

npm install @robotfight/sdk

import { RobotFightClient } from '@robotfight/sdk';

const client = new RobotFightClient({
  apiKey: 'your-api-key',
  network: 'mainnet'
});

// Get fights
const fights = await client.fights.list({ status: 'open' });

// Place bet
const bet = await client.bets.create({
  fightId: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
  side: 'Left',
  amount: 5 * 1e9 // 5 SOL
});

// Subscribe to live updates
client.ws.on('fight:state', (data) => {
  console.log('Fight update:', data);
});

Python SDK

pip install robotfight

from robotfight import RobotFightClient

client = RobotFightClient(api_key='your-api-key')

# Get fights
fights = client.fights.list(status='open')

# Get fighter stats
morpheus = client.fighters.get('Morpheus')
print(f"Win rate: {morpheus.win_rate}")

🔍 Rate Limits

Public endpoints: 100 requests/minute per IP
Authenticated endpoints: 1000 requests/minute per user
WebSocket: 1000 messages/minute per connection
Betting: 10 bets/minute per wallet

⚠️ Error Codes

Code

Message

Description

400

Bad Request

Invalid request parameters

401

Unauthorized

Missing or invalid authentication

403

Forbidden

Insufficient permissions

404

Not Found

Resource not found

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server error

503

Service Unavailable

Maintenance mode

Error Response Format:

{
  "error": {
    "code": 400,
    "message": "Invalid fight_id format",
    "details": "fight_id must be a valid UUID"
  }
}

📚 Examples

Complete Betting Flow

// 1. Connect wallet
const wallet = await connectPhantomWallet();

// 2. Get open fights
const fights = await fetch('https://api.robotfight.io/v1/fights?status=open')
  .then(res => res.json());

// 3. Select fight
const fight = fights.fights[0];

// 4. Place bet
const betRequest = {
  fight_id: fight.fight_id,
  side: 'Left',
  amount: 5000000000,
  wallet_address: wallet.publicKey.toString()
};

const betResponse = await fetch('https://api.robotfight.io/v1/bet/create', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(betRequest)
});

const { transaction } = await betResponse.json();

// 5. Sign transaction
const signedTx = await wallet.signTransaction(transaction);

// 6. Send to blockchain
const txid = await connection.sendRawTransaction(signedTx.serialize());

// 7. Subscribe to updates
const ws = new WebSocket('wss://ws.robotfight.io');
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    fight_id: fight.fight_id
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'fight:end') {
    console.log('Winner:', data.winner);
    // Claim payout if won
  }
};

PreviousBetting System NextLive Streaming on Pump.fun

Last updated 1 month ago

Good night

REST API & WebSocket Documentation

🌐 Base URLs

🔐 Authentication

Admin Endpoints

User Endpoints

📡 REST API Endpoints

Fights

Bets

Fighters

Statistics

🔌 WebSocket API

Connection

Authentication

Events

🛠️ SDK & Libraries

JavaScript SDK

Python SDK

🔍 Rate Limits

⚠️ Error Codes

📚 Examples

Complete Betting Flow