AGENT JSON SPEC

Top-level shape

{
  "name":         "string  (2-40 chars, required)",
  "description":  "string  (max 200 chars, required)",
  "species":      "string  (creature id, optional — picker handles it)",
  "version":      "number  (1, required)",
  "rules":        "AgentRule[]  (1-20 rules, required)",
  "risk":         "AgentRisk    (required)",
  "x402_metadata": "object  (preserved if uploaded via x402 envelope)"
}

AgentRule

Each rule is one if/then trading decision:

{
  "condition": "price_change_5m > 0.5",
  "action":    "open_long",
  "asset":     "BTC",
  "size":      "medium",
  "leverage":  5
}

Conditions

Built-in expressions you can use without quoting:

• price_change_1m > 0.5 — 1-minute price change in percent
• price_change_5m > 0.5 — 5-minute price change in percent
• price_change_15m > 0.5 — 15-minute price change in percent
• price_change_1m < -0.3 — negative thresholds work too
• unrealized_pnl_pct > 5 — exit when up 5%
• unrealized_pnl_pct < -3 — exit when down 3%
• position_count > 2 — gate on how many positions you hold

Actions

Sizes

Position size is bucketed into four tiers, scaled to your starting balance:

Supported assets

Battle Trade supports 16 spot tickers natively. Use the bare symbol (no USDT suffix):

BTC, ETH, SOL, AVAX, DOGE, LINK, ARB, OP,
SUI, APT, MATIC, DOT, ADA, XRP, BNB, NEAR

AgentRisk

{
  "max_positions":   3,
  "max_leverage":    10,
  "stop_loss_pct":   -8,
  "take_profit_pct": 15
}

Limits

• Max 10 agents per profile
• Each agent: name 2–40 chars, description ≤200 chars
• 1–20 rules per agent
• Rule evaluation order = array order (first match wins per tick)

Validation errors

Uploads run through validateAgentConfig on the server before being accepted. If anything fails, you get the full list of issues with field paths so you can fix them inline. Common errors:

• rules[0].asset must be one of: BTC, ETH, SOL, ...
• risk.max_leverage exceeds 50
• condition not parseable — check spelling of the metric name