AgentBroker API Reference

REST + WebSocket API for autonomous AI agents. HTTP for operations. WebSocket for real-time data. Base URL: https://agentbroker.polsia.app

REST API

All REST endpoints are under /v1/. Authenticated endpoints require an X-API-Key header.

MethodPathAuthDescription
POST/v1/agents/register—Create agent account, get API key
POST/v1/deposit✓Deposit simulated USDC
POST/v1/strategy/select✓Select trading strategy
POST/v1/trade/execute✓Execute a trade
GET/v1/account✓Account info + balance
GET/v1/strategies—List available strategies
GET/v1/pairs—Current market prices
GET/v1/trades✓Trade history
GET/v1/deposits✓Deposit history

Authentication

Pass your API key in the X-API-Key header on every authenticated request.

HTTP
X-API-Key: ab_your_api_key_here

Register

POST /v1/agents/register

Creates a new agent account and returns an API key. Save the key immediately — it cannot be retrieved again.

Request
{ "name": "my-trading-agent-v1" }
Response 201
{ "agent_id": 42, "name": "my-trading-agent-v1", "api_key": "ab_a1b2c3d4e5f6...", "balance_usdc": "0.000000", "created_at": "2026-03-14T20:00:00.000Z" }

Deposit

POST /v1/deposit

Deposit simulated USDC into your balance. Min: any positive amount. Max: 10,000,000 USDC per deposit. Triggers a balance WebSocket event on connected clients.

Request
{ "amount": 10000, "tx_hash": "0xabc123..." // optional }

Strategy Select

POST /v1/strategy/select
StrategySlippageDescription
momentum-0.05% / +0.05%Trend-following. Slightly favorable fills.
grid±0.02%Grid levels. Minimal slippage.
mean_reversion+0.1% / -0.1%Counter-trend. Slight adverse selection.

Execute Trade

POST /v1/trade/execute

Executes a simulated trade. Fee: 0.4% of trade value. Triggers trades and balance WebSocket events on connected clients.

Request
{ "pair": "ETH/USDC", "side": "buy", // "buy" | "sell" "quantity": 1.5 // in base asset units }

Supported pairs: BTC/USDC, ETH/USDC, SOL/USDC, AVAX/USDC, LINK/USDC, DOGE/USDC, ARB/USDC, MATIC/USDC

WebSocket API

The WebSocket endpoint provides real-time streaming for prices, your trades, and balance changes — without polling. Prices update every 2 seconds. Trade and balance events fire immediately after each operation.

Endpoint: wss://agentbroker.polsia.app/ws?apiKey=<your_api_key>

Connecting

Pass your API key as a query parameter. The connection is rejected with close code 4001 if the key is missing or invalid.

JavaScript
const ws = new WebSocket( 'wss://agentbroker.polsia.app/ws?apiKey=ab_your_key' ); ws.onopen = () => { // Server sends a "connected" message immediately }; ws.onmessage = (event) => { const msg = JSON.parse(event.data); console.log(msg); };

On successful connection the server sends:

Server → Client
{ "type": "connected", "agent_id": 42, "name": "my-trading-agent-v1", "channels": ["prices", "trades", "balance"], "message": "Connected. Subscribe to channels..." }

Subscribe / Unsubscribe

Send a JSON message to subscribe or unsubscribe from any channel.

Client → Server
// Subscribe to price updates for specific pairs { "action": "subscribe", "channel": "prices", "pairs": ["BTC/USDC", "ETH/USDC"] } // Subscribe to your own trade executions { "action": "subscribe", "channel": "trades" } // Subscribe to balance change notifications { "action": "subscribe", "channel": "balance" } // Unsubscribe { "action": "unsubscribe", "channel": "prices" }
FieldTypeDescription
actionstringsubscribe or unsubscribe
channelstringprices, trades, or balance
pairsstring[]Required for prices channel. Which pairs to stream.

WS prices channel

Subscribe with specific pairs. Prices update every 2 seconds. On subscribe you also receive an immediate snapshot.

Subscribe

Client → Server
{ "action": "subscribe", "channel": "prices", "pairs": ["BTC/USDC", "ETH/USDC", "SOL/USDC"] }

Subscription confirmed (with snapshot)

Server → Client
{ "type": "subscribed", "channel": "prices", "pairs": ["BTC/USDC", "ETH/USDC", "SOL/USDC"], "snapshot": { "prices": { "BTC/USDC": "67312.450000", "ETH/USDC": "3487.220000", "SOL/USDC": "148.812000" }, "timestamp": "2026-03-14T20:34:00.000Z" } }

Recurring price update (every 2s)

Server → Client
{ "channel": "prices", "type": "update", "data": { "prices": { "BTC/USDC": "67298.120000", "ETH/USDC": "3484.875000", "SOL/USDC": "148.612000" }, "timestamp": "2026-03-14T20:34:02.000Z" } }

WS trades channel

Receive your own trade executions in real-time — fires immediately when POST /v1/trade/execute completes.

Execution event

Server → Client
{ "channel": "trades", "type": "execution", "data": { "trade_id": 1234, "agent_id": 42, "pair": "ETH/USDC", "side": "buy", "quantity": "1.50000000", "market_price": "3484.875000", "fill_price": "3483.132000", "slippage": "-0.0500%", "fee_usdc": "5.224698", "total_usdc": "5224.698000", "balance_usdc": "4770.077302", "strategy": "momentum", "status": "filled", "executed_at": "2026-03-14T20:34:05.123Z" } }

WS balance channel

Fires on deposits and trade settlements. Gives you the new balance immediately after each operation without polling GET /v1/account.

Deposit event

Server → Client
{ "channel": "balance", "type": "update", "data": { "event": "deposit", "amount_usdc": "10000.000000", "balance_usdc": "10000.000000", "deposit_id": 7, "timestamp": "2026-03-14T20:30:00.000Z" } }

Trade settlement event

Server → Client
{ "channel": "balance", "type": "update", "data": { "event": "trade_settlement", "trade_id": 1234, "pair": "ETH/USDC", "side": "buy", "balance_change_usdc": "-5229.922698", "balance_usdc": "4770.077302", "timestamp": "2026-03-14T20:34:05.123Z" } }

Heartbeat

The server sends a WebSocket ping frame every 30 seconds. The client must respond with a pong. Most WebSocket libraries do this automatically. Connections that don't respond within 10 seconds are terminated.

Built-in: Browser WebSocket and most Node.js ws clients handle ping/pong automatically. You don't need to implement this manually.

Errors

All errors are delivered as JSON messages over the connection before it's closed (if fatal).

ScenarioClose CodeMessage
Missing / invalid API key4001Authentication failed
Invalid JSON sent to server—Invalid JSON
Missing action or channel—action and channel are required
Unknown channel name—Invalid channel. Valid: prices, trades, balance
Unknown action—Unknown action: X. Valid: subscribe, unsubscribe

Full Example

A complete Node.js agent that connects, subscribes to all channels, and reacts to events:

Node.js
const WebSocket = require('ws'); const API_KEY = 'ab_your_api_key'; const ws = new WebSocket(`wss://agentbroker.polsia.app/ws?apiKey=${API_KEY}`); ws.on('open', () => { // Subscribe to all channels ws.send(JSON.stringify({ action: 'subscribe', channel: 'prices', pairs: ['BTC/USDC', 'ETH/USDC', 'SOL/USDC'] })); ws.send(JSON.stringify({ action: 'subscribe', channel: 'trades' })); ws.send(JSON.stringify({ action: 'subscribe', channel: 'balance' })); }); ws.on('message', (data) => { const msg = JSON.parse(data); if (msg.channel === 'prices' && msg.type === 'update') { // React to price ticks (every 2s) const eth = parseFloat(msg.data.prices['ETH/USDC']); if (eth > 3500) { // Trigger your trade logic } } if (msg.channel === 'trades' && msg.type === 'execution') { console.log(`Trade filled: ${msg.data.side} ${msg.data.quantity} ${msg.data.pair}`); } if (msg.channel === 'balance' && msg.type === 'update') { console.log(`Balance: ${msg.data.balance_usdc} USDC (${msg.data.event})`); } }); ws.on('close', (code, reason) => { console.log(`Disconnected: ${code} ${reason}`); // Reconnect logic here });