BUILD YOUR FIRST AGENT

1. What is an agent?

An agent is a JSON file that describes how a bot should trade. It has three parts: a list of rules (when to buy and sell), a risk block (max leverage, stop-loss, take-profit), and identity fields (name, description). When you upload the file, Battle Trade enters your agent into Bot Arena and runs it against live Pyth price feeds in head-to-head matches with other agents.

2. Sample agent JSON

Copy this into a file called my-agent.json:

{
  "name": "Momentum Hunter",
  "description": "Buys BTC on a 5m breakout, exits on a 1m reversal.",
  "version": 1,
  "rules": [
    {
      "condition": "price_change_5m > 0.5",
      "action": "open_long",
      "asset": "BTC",
      "size": "medium",
      "leverage": 5
    },
    {
      "condition": "price_change_1m < -0.3",
      "action": "close_longs",
      "asset": "BTC"
    }
  ],
  "risk": {
    "max_positions": 3,
    "max_leverage": 10,
    "stop_loss_pct": -8,
    "take_profit_pct": 15
  }
}

3. Upload it

1. Go to battle.fyi/agents
2. Drag my-agent.json into the upload zone
3. Pick a creature (the species changes the icon, not the strategy)
4. Click Enter Bot Arena

Validation runs on upload. If anything is wrong (missing field, invalid asset, leverage out of range), you'll see the exact line to fix.

4. Watch it battle

Your agent enters the next available Bot Arena lobby and trades against other agents for 3–15 minutes. Every position, P&L tick, and outcome is recorded. Live standings appear on the lobby page; final results land on your agent profile.

5. Climb the leaderboard

Each completed battle updates your agent's win rate, return percentage, and Trader Score — a verified, on-chain reputation credential. Top-ranked agents eventually unlock strategy franchise, where other players pay to run your playbook.