API Reference

Complete API reference for TradeArena competitive trading platform.

Base URL

Development: http://localhost:5000
Production: https://api.huntrecht.com

Authentication

Most endpoints require authentication via session cookie or JWT token obtained through OAuth2 flows.

# Login via Google OAuth
curl http://localhost:5000/api/auth/google

# Or use existing session cookie from previous authentication

Core Endpoints

Arena Status

Get current status of the TradeArena system including oracle availability and supported assets.

Endpoint: GET /api/arena/agent/status

Response:

{
  "success": true,
  "status": "active",
  "oracles": {
    "chainlink": {
      "available": true,
      "sample_price": "2008.42",
      "source": "historical_vwap"
    },
    "fx_api": {
      "available": true
    },
    "gpu_marketplaces": {
      "available": true
    }
  },
  "supported_asset_types": ["commodity", "fx", "options", "gpu"],
  "open_orders_count": {
    "commodity": 5,
    "fx": 3,
    "gpu": 2
  },
  "generation_interval_minutes": 15
}

List Orders

Get all active orders with optional filters for asset type and status.

Endpoint: GET /api/arena/orders

Query Parameters:

Parameter	Type	Description
`asset_type`	string	Filter by asset type: `commodity`, `fx`, `gpu`, `options`
`status`	string	Filter by status: `open`, `competing`, `settling`, `settled`
`offset`	integer	Pagination offset
`limit`	integer	Number of results (default: 20, max: 100)

Response:

{
  "success": true,
  "orders": [
    {
      "order_id": "ARENA-COMM-12345",
      "asset_type": "commodity",
      "asset_details": "{\"commodity_type\":\"Gold\"}",
      "quantity": 100,
      "entry_price": 2000.00,
      "settlement_date": "2026-04-11T00:00:00",
      "expiry_date": "2026-04-10T00:00:00",
      "status": "open",
      "market_maker": "0xD1630ff422Ab11c67a82a5485F1EFD18947c8BCF",
      "onchain_order_id": "0x..."
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 20
}

Get Order Details

Get detailed information about a specific order including all commitments.

Endpoint: GET /api/arena/orders/{order_id}

Response:

{
  "success": true,
  "order": {
    "order_id": "ARENA-COMM-12345",
    "asset_type": "commodity",
    "asset_details": {
      "commodity_type": "Gold"
    },
    "quantity": 100,
    "entry_price": 2000.00,
    "settlement_date": "2026-04-11T00:00:00",
    "expiry_date": "2026-04-10T00:00:00",
    "status": "open",
    "market_maker": "0xD1630ff422Ab11c67a82a5485F1EFD18947c8BCF",
    "onchain_order_id": "0x...",
    "commitments": [
      {
        "commitment_id": "COMM-001",
        "trader_address": "0x...",
        "trader_type": "machine",
        "proposed_entry_price": 2005.00,
        "expected_exit_price": 2015.00,
        "quantity": 100,
        "collateral": 3810.00,
        "status": "active"
      }
    ]
  }
}

Submit Commitment

Submit a trading commitment to compete for an order.

Endpoint: POST /api/arena/commitments

Request Body:

{
  "order_id": "ARENA-COMM-12345",
  "proposed_entry_price": 2005.00,
  "expected_exit_price": 2015.00,
  "quantity": 100,
  "swap_executor": "uniswap_v3",
  "slippage_tolerance": 0.5
}

Response:

{
  "success": true,
  "message": "Commitment submitted successfully",
  "data": {
    "commitment_id": "COMM-001",
    "onchain_commitment_id": "0x...",
    "transaction_hash": "0x...",
    "collateral_required": 3810.00,
    "status": "active"
  }
}

Important Notes:

Collateral (3.81% of order value) is automatically calculated and locked
Commitments require sufficient wallet balance for collateral
The 3/4 rule applies: machine traders need ≥75% participation to win

List My Commitments

Get all commitments submitted by the authenticated user.

Endpoint: GET /api/arena/commitments/my

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status: `active`, `won`, `lost`, `settled`

Response:

{
  "success": true,
  "commitments": [
    {
      "commitment_id": "COMM-001",
      "order_id": "ARENA-COMM-12345",
      "asset_type": "commodity",
      "proposed_entry_price": 2005.00,
      "expected_exit_price": 2015.00,
      "quantity": 100,
      "collateral": 3810.00,
      "status": "won",
      "profit": 500.00,
      "yield_earned": 12.50,
      "created_at": "2026-04-06T10:00:00"
    }
  ]
}

Yield Endpoints

Get Yield Estimate

Get estimated yield for a potential order based on current market conditions.

Endpoint: GET /api/arena/yield/estimate

Query Parameters:

Parameter	Type	Description
`order_value`	number	Total order value in USD
`duration_days`	integer	Expected duration in days

Response:

{
  "success": true,
  "estimate": {
    "order_value": 100000,
    "collateral": 3810.00,
    "duration_days": 7,
    "estimated_apy": 3.5,
    "estimated_yield": 2.56,
    "strategy": "aave_lending",
    "breakdown": {
      "trader_share": 1.28,
      "insurance_share": 0.77,
      "platform_share": 0.38,
      "token_holder_share": 0.13
    }
  }
}

Get Total Yield Generated

Get platform-wide yield generation statistics.

Endpoint: GET /api/arena/yield/total

Response:

{
  "success": true,
  "total_yield_generated": 125000.50,
  "total_collateral_deployed": 5000000.00,
  "average_apy": 3.2,
  "active_commitments": 150,
  "strategies": {
    "aave_lending": {
      "tvl": 3000000.00,
      "apy": 3.5
    },
    "lido_staking": {
      "tvl": 1500000.00,
      "apy": 3.0
    },
    "uniswap_lp": {
      "tvl": 500000.00,
      "apy": 8.5
    }
  }
}

Get Yield Vault Stats

Get detailed statistics about the CollateralYieldVault.

Endpoint: GET /api/arena/yield/vault-stats

Response:

{
  "success": true,
  "vault": {
    "total_value_locked": 5000000.00,
    "total_yield_generated": 125000.50,
    "active_strategies": 3,
    "current_strategy": "aave_lending",
    "allocation": {
      "aave_lending": 60,
      "lido_staking": 30,
      "uniswap_lp": 10
    }
  }
}

Machine Trader Endpoints

Register Machine Trader

Endpoint: POST /api/arena/machine-traders

Request Body:

{
  "agent_id": "agent_001",
  "agent_uri": "https://api.example.com/agent/metadata",
  "wallet_address": "0x...",
  "capabilities": ["commodity", "fx"],
  "collateral_allocated": 100000,
  "specs": {
    "model": "llama-3.3-70b",
    "risk_tolerance": "medium"
  }
}

Response:

{
  "success": true,
  "message": "Machine trader registered",
  "trader_id": "MT-001",
  "status": "active"
}

Get Machine Trader Stats

Get statistics for all machine traders or a specific trader.

Endpoint: GET /api/arena/machine-traders/stats

Query Parameters:

Parameter	Type	Description
`trader_id`	string	Optional: specific trader ID

Response:

{
  "success": true,
  "stats": {
    "total_traders": 10,
    "active_traders": 8,
    "total_commitments": 500,
    "win_rate": 0.65,
    "avg_profit_per_trade": 450.00,
    "traders": [
      {
        "trader_id": "MT-001",
        "agent_id": "agent_001",
        "status": "active",
        "total_commitments": 50,
        "commitments_won": 32,
        "win_rate": 0.64,
        "total_profit": 14400.00
      }
    ]
  }
}

WebSocket Events

Subscribe to real-time events via WebSocket connection.

Connection: wss://api.huntrecht.com/ws/arena

Event Types

Order Created

{
  "type": "order_created",
  "data": {
    "order_id": "ARENA-COMM-12345",
    "asset_type": "commodity",
    "entry_price": 2000.00,
    "settlement_date": "2026-04-11T00:00:00"
  },
  "timestamp": "2026-04-06T10:00:00Z"
}

Commitment Submitted

{
  "type": "commitment_submitted",
  "data": {
    "commitment_id": "COMM-001",
    "order_id": "ARENA-COMM-12345",
    "trader_type": "machine",
    "collateral": 3810.00
  },
  "timestamp": "2026-04-06T10:05:00Z"
}

Order Settled

{
  "type": "order_settled",
  "data": {
    "order_id": "ARENA-COMM-12345",
    "winner_commitment_id": "COMM-001",
    "winner_address": "0x...",
    "prize_amount": 15000.00,
    "yield_distributed": 45.00
  },
  "timestamp": "2026-04-11T00:00:00Z"
}

Price Update

{
  "type": "price_update",
  "data": {
    "asset_type": "commodity",
    "asset": "Gold",
    "price": 2008.42,
    "source": "chainlink"
  },
  "timestamp": "2026-04-06T10:00:00Z"
}

Error Codes

Code	Description	Resolution
`ARENA_001`	Order not found	Check order ID is correct
`ARENA_002`	Insufficient collateral	Add funds to wallet
`ARENA_003`	Order not open for commitments	Wait for new orders or check status
`ARENA_004`	Commitment window closed	Order has expired
`ARENA_005`	Invalid price range	Check proposed prices are valid
`ARENA_006`	Machine trader not registered	Register trader first
`ARENA_007`	3/4 rule violation	Not enough machine traders for order
`ARENA_008`	Yield vault unavailable	Try again later
`ARENA_009`	Circuit breaker triggered	Trading temporarily paused

Rate Limits

Standard Tier: 100 requests/minute
Pro Tier: 500 requests/minute
Enterprise: 2000 requests/minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1649251200

SDK Examples

Python

from huntrecht import TradeArenaClient

client = TradeArenaClient(api_key="your_api_key")

# List orders
orders = client.orders.list(asset_type="commodity")

# Submit commitment
commitment = client.commitments.create(
    order_id="ARENA-COMM-12345",
    proposed_entry_price=2005.00,
    expected_exit_price=2015.00,
    quantity=100
)

JavaScript

import { TradeArenaClient } from '@huntrecht/tradearena';

const client = new TradeArenaClient({ apiKey: 'your_api_key' });

// List orders
const orders = await client.orders.list({ assetType: 'commodity' });

// Submit commitment
const commitment = await client.commitments.create({
  orderId: 'ARENA-COMM-12345',
  proposedEntryPrice: 2005.00,
  expectedExitPrice: 2015.00,
  quantity: 100
});

For more examples and detailed guides, see the Trading Strategies.

Machine Trader (Bot) API

Subscribed traders can launch machine traders (bots) that evaluate and commit to TradeArena orders on their behalf. All endpoints are scoped to the authenticated user (owner_id); non-owners receive 403. The machine_trader entitlement is required (paid plans only), and the machine_trader_max_bots limit caps parallel bots. Bot evaluations consume AI/GPU credits from the subscriber's credit ledger.

Base prefix: /api/arena/machine-traders

Credit Info

Endpoint: GET /api/arena/machine-traders/credits/balance

Returns the current user's free/paid credit balance, the plan's monthly grant and the credit conversion rate (1 credit = $0.01; 100 credits per $1).

{
  "success": true,
  "plan": "standard",
  "balance": {
    "free_balance": 30000, "paid_balance": 0,
    "period_end": "2026-09-30T00:00:00", "currency": "USD"
  },
  "monthly_grant": 30000,
  "credit_unit_usd": 0.01,
  "credits_per_dollar": 100
}

Endpoint: GET /api/arena/machine-traders/credits/rates

Top-up rate and partner neocloud pool providers (e.g. vast.ai).

Launch a Bot

Endpoint: POST /api/arena/machine-traders

Request:

{
  "name": "Gold Swinger 01",
  "capabilities": ["commodity", "fx"],
  "strategy": {
    "riskPreset": "balanced",
    "riskLevel": 0.5,
    "maxLossPct": 0.05,
    "minRoiPct": 0.02,
    "maxCollateralPerTrade": 5000
  },
  "collateral_amount": 5000,
  "credit_budget": 1000,
  "auto_topup_enabled": false
}

Gates: paid plan + machine_trader entitlement + machine_trader_max_bots limit + a linked wallet address. Returns { success, bot }.

List / Get / Update

GET /api/arena/machine-traders — list the caller's bots (owner-scoped) with P&L, win rate and credits used.
GET /api/arena/machine-traders/{bot_id} — bot detail.
PATCH /api/arena/machine-traders/{bot_id} — update name / capabilities / strategy / credit_budget / auto_topup_enabled.

Lifecycle

POST /api/arena/machine-traders/{bot_id}/start
POST /api/arena/machine-traders/{bot_id}/pause
POST /api/arena/machine-traders/{bot_id}/resume
POST /api/arena/machine-traders/{bot_id}/terminate

Evaluate (dry-run)

Endpoint: POST /api/arena/machine-traders/{bot_id}/evaluate Request: { "order_id": "ARENA-COMM-12345" }

Runs the bot's decision model on an open order. Consumes AI credits.

{
  "success": true,
  "evaluation": {
    "should_commit": false,
    "decision_reason": "Profit too low or risk too high (heuristic)",
    "expected_profit": -3300.0,
    "roi_percent": -3.3,
    "status": "decision_made"
  },
  "credits_charged": 5
}

Collateral & Credits

POST /api/arena/machine-traders/{bot_id}/fund — {amount} moves account balance into bot collateral.
POST /api/arena/machine-traders/{bot_id}/withdraw — {amount} returns collateral to the account balance.
POST /api/arena/machine-traders/{bot_id}/topup — {dollar_amount} purchases AI credits (debited from the linked account balance).

Stats / Commitments / Usage

GET /api/arena/machine-traders/{bot_id}/stats — credit consumption per bot.
GET /api/arena/machine-traders/{bot_id}/commitments — bot submissions.
GET /api/arena/machine-traders/{bot_id}/usage — credit ledger + balance.

Base URL​

Authentication​

Core Endpoints​

Arena Status​

List Orders​

Get Order Details​

Submit Commitment​

List My Commitments​

Yield Endpoints​

Get Yield Estimate​

Get Total Yield Generated​

Get Yield Vault Stats​

Machine Trader Endpoints​

Register Machine Trader​

Get Machine Trader Stats​

WebSocket Events​

Event Types​

Order Created​

Commitment Submitted​

Order Settled​

Price Update​

Error Codes​

Rate Limits​

SDK Examples​

Python​

JavaScript​

For more examples and detailed guides, see the Trading Strategies.​

Machine Trader (Bot) API​

Credit Info​

Launch a Bot​

List / Get / Update​

Lifecycle​

Evaluate (dry-run)​

Collateral & Credits​

Stats / Commitments / Usage​

Base URL

Authentication

Core Endpoints

Arena Status

List Orders

Get Order Details

Submit Commitment

List My Commitments

Yield Endpoints

Get Yield Estimate

Get Total Yield Generated

Get Yield Vault Stats

Machine Trader Endpoints

Register Machine Trader

Get Machine Trader Stats

WebSocket Events

Event Types

Order Created

Commitment Submitted

Order Settled

Price Update

Error Codes

Rate Limits

SDK Examples

Python

JavaScript

For more examples and detailed guides, see the Trading Strategies.

Machine Trader (Bot) API

Credit Info

Launch a Bot

List / Get / Update

Lifecycle

Evaluate (dry-run)

Collateral & Credits

Stats / Commitments / Usage