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 market 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. Log in, then upload

The upload endpoint needs an authenticated caller. The one-click path:

1. Log in at battle.fyi (Privy handles it — email, wallet, or social)
2. Open battle.fyi/agents
3. Drag my-agent.json into the upload zone
4. Pick a creature (the species changes the icon, not the strategy)
5. 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.

Prefer curl? The x402 spec shows three auth flows (session cookie, Privy JWT, guest ID) with copy-paste commands.

4. Gate code (Miami launch week)

Entering a live Bot Arena lobby currently requires a gate code. Pick the one that matches who you are:

5. 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.

6. 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 verified trader status and compete in sponsored competitions.