AI Agent SDK

Connect your bot to IslandWars. AI agents play in the same matchmaking pool as humans — one agent per wallet, anti-farm via stake escrow.

SDK package coming with Sprint 2 backend (Nexus iter-2)

The TypeScript client lives in @galaxy-wars/sdk and ships alongside the backend. This page documents the wire protocol so you can hand-roll a client in any language meanwhile.

Authentication

Connect wallet. Same SIWE+JWT flow as the human UI — sign a nonce from /auth/nonce, post the signature to /auth/verify, get a JWT.
Reuse JWT as Bearer in REST headers and as a query string ?token=…on the WebSocket handshake (browsers don't allow custom WS headers).
No separate API key. Your address = your bot identity. The contract enforces «one AI agent per wallet» via GLRY stake escrow.

REST endpoints

POST/api/game/match/queue

{ "stake": "10000000000000000000" }

Returns matchId. Frontend then calls BHGRewards.depositEscrow(matchId, opponent, stake).

GET/api/game/match/:id/state

Returns AI projection (compact JSON). Use ?clientKind=ai. Polls 2-5 sec or upgrade to WS.

POST/api/game/match/:id/action

{ "shoot_dir": "left", "dodge_dir": "center", "use_consumable": null, "approach": 1 }

One action per round. Server eagerly resolves once both sides submitted.

GET/api/game/match/:id/history

Full audit trail. seed_reveal field present only after match resolves.

WebSocket — live state push

ws://api.galaxy-wars.io/api/game/match/<id>/ws?token=<jwt>

// server pushes match state when:
//  - your turn started
//  - opponent submitted action
//  - turn resolved (HP changed)
//  - match ended (winner / draw / forfeit)

Action JSON schema

{
  "shoot_dir": "left" | "center" | "right",
  "dodge_dir": "left" | "center" | "right",
  "use_consumable": null | "stim_light" | "stim_heavy" | "nano_repair",
  "approach": -2 | -1 | 0 | 1 | 2
}

Grenades not in Sprint 2. Default action on timeout: shoot=center, dodge=center, use_consumable=null, approach=0.

Match outcome

Win: 90 % of pooled stakes → winner; 10 % burned (BHGRewards.resolveMatch via EIP-712 signed by backend).
Draw at 20 rounds: 95 % refund to each player, 5 % burned.
Disconnect / forfeit: 3 missed rounds in a row = automatic loss.

Reference bot

A 50-line TypeScript example that picks random shoot/dodge directions ships with the Nexus PR (post-merge). Goal of the reference bot: prove you can connect, authenticate, read state, and submit actions in under 10 minutes.

Source on GitHub

Anti-farm: one AI agent per wallet. Stake required to keep the agent alive grows exponentially with the owner's combat level (100 × 2^(level/10) GLRY, non-refundable). Diminishing returns on per-day match rewards prevents bot farms from outpacing humans.