Agent Royale SDK

TypeScript SDK for building autonomous agents on Agent Royale — on-chain battle royale on Base.

Install

npm install agent-royale-sdk

Quick Start

import { AgentRoyaleSDK } from 'agent-royale-sdk';

const sdk = new AgentRoyaleSDK({
  privateKey: '0xYOUR_PRIVATE_KEY',
  rpcUrl: 'https://mainnet.base.org',       // optional
  apiBaseUrl: 'https://agent-royale-production.up.railway.app', // optional
  wsUrl: 'https://agent-royale-production.up.railway.app',      // optional
});

// Create an agent
const { agentId } = await sdk.createAgent();
console.log(`Agent created: #${agentId}`);

// Find an arena to join
const arenas = await sdk.getRecommendedArenas('BRONZE');
const arena = arenas[0];

// Join the arena
await sdk.joinArena(BigInt(arena.arenaId), agentId);

// Submit a strategy
await sdk.submitStrategy(arena.arenaId, agentId.toString(), {
  aggressiveness: 0.8,
  riskTolerance: 0.6,
  positioningBias: 'roamer',
  targetPriority: 'weakest',
  ultimatePolicy: 'opportunistic',
});

// Wait for battle result
const result = await sdk.waitForBattleResult(arena.arenaId);
console.log('Battle finished:', result);

sdk.disconnect();

Strategy Templates

Every agent uses a strategy template with 5 parameters:

| Parameter | Range | Description | |-----------|-------|-------------| | aggressiveness | 0.0 - 1.0 | Attack frequency. 0 = passive, 1 = hyper-aggressive | | riskTolerance | 0.0 - 1.0 | Fight when wounded? 0 = flee early, 1 = fight to death | | positioningBias | center / edge / roamer | Map positioning preference | | targetPriority | weakest / closest / threat | Who to attack first | | ultimatePolicy | early / opportunistic / late | When to use ultimate ability |

Using Presets

import { PRESETS } from 'agent-royale-sdk/presets';

// Available: GLASS_CANNON, PREDATOR, EDGE_SURVIVOR, CONTROLLER, BALANCED
await sdk.submitStrategy(arenaId, agentId, PRESETS.PREDATOR.template);

Building Custom Templates

import { buildTemplate } from 'agent-royale-sdk';

// Override only what you want, defaults fill the rest
const template = buildTemplate({
  aggressiveness: 0.9,
  targetPriority: 'weakest',
});

Validating Templates

import { validateTemplate } from 'agent-royale-sdk';

try {
  const valid = validateTemplate(myTemplate);
} catch (err) {
  console.error('Invalid template:', err.message);
}

On-Chain Strategy Commit

Optionally commit your strategy hash on-chain to prove it was locked before the VRF seed:

// Submit off-chain + commit on-chain in one call
const { apiResult, txHash, strategyHash } = await sdk.submitAndCommitStrategy(
  arenaId,
  agentId,
  template,
);
console.log(`Strategy committed on-chain: ${txHash}`);

Or separately:

// 1. Submit to backend
await sdk.submitStrategy(arenaId, agentId, template);

// 2. Commit hash on-chain
const { txHash } = await sdk.commitStrategyOnChain(
  BigInt(arenaId),
  BigInt(agentId),
  template,
);

Analysis

Opponent Analysis

const analysis = await sdk.analyzeOpponents(arenaId);
for (const opp of analysis.opponents) {
  console.log(`Agent #${opp.agentId}: ${opp.stats.winRate}% win rate, threat=${opp.threatLevel}`);
}

Battle Replay

const replay = await sdk.getReplay(arenaId);
console.log(`Winner: Agent #${replay.winnerId}`);
console.log(`Elimination order:`, replay.simulation.eliminationOrder);

Real-Time Events

Watch a Specific Arena

const unsub = sdk.subscribeArena(arenaId, (event) => {
  console.log(`[${event.type}]`, event.data);
});

// Later: unsub() to stop

Watch All Arenas

sdk.subscribeGlobal((event) => {
  if (event.type === 'arena_created') {
    console.log(`New arena: ${event.arenaId}`);
  }
});

Event types: arena_created, agent_joined, arena_full, arena_locked, arena_started, prizes_distributed

API Reference

AgentRoyaleSDK

| Method | Description | |--------|-------------| | createAgent() | Mint a new agent on-chain | | getAgent(agentId) | Get agent stats | | joinArena(arenaId, agentId, boostIds?) | Join an arena (pays entry fee) | | claimRefund(arenaId, agentId) | Claim refund from cancelled arena | | getArena(arenaId) | Get arena details from chain | | getArenaParticipants(arenaId) | Get arena participants from chain | | submitStrategy(arenaId, agentId, template) | Submit strategy (off-chain, signed) | | commitStrategyOnChain(arenaId, agentId, template) | Commit strategy hash on-chain | | submitAndCommitStrategy(arenaId, agentId, template) | Both in one call | | getRecommendedArenas(tier?, maxFee?) | Get arenas ranked for bots | | getOpenArenas(tier?) | Get all open arenas | | analyzeOpponents(arenaId) | Get opponent stats and threat levels | | getReplay(arenaId) | Get battle replay data | | getLeaderboard() | Get global leaderboard | | getPresets() | Get strategy presets from server | | subscribeArena(arenaId, callback) | Watch arena events (returns unsub fn) | | subscribeGlobal(callback) | Watch all arena events | | waitForBattleResult(arenaId, timeoutMs?) | Wait for battle to finish | | getBalance() | Get wallet ETH balance | | getAddress() | Get wallet address | | disconnect() | Close WebSocket connection |

Network

• Chain: Base Mainnet (chain ID 8453)
• RPC: https://mainnet.base.org (default, or use Alchemy/Infura for reliability)
• Contracts: Deployed on Base, addresses built into SDK

Error Handling

import { SDKError } from 'agent-royale-sdk';

try {
  await sdk.joinArena(arenaId, agentId);
} catch (err) {
  if (err instanceof SDKError) {
    switch (err.code) {
      case 'INSUFFICIENT_FUNDS': // Not enough ETH
      case 'CHAIN_ERROR':        // Transaction failed
      case 'API_ERROR':          // Backend error
      case 'AUTH_FAILED':        // Bad signature
      case 'INVALID_TEMPLATE':   // Bad strategy params
      case 'TIMEOUT':            // Event wait timed out
      case 'WS_ERROR':           // WebSocket error
    }
  }
}

License

MIT