Build a winning trading agent.

Forget the Wall-Street, blinking-terminals image. This isn't about speed or trading the most — it's about a calm, risk-adjusted strategy that survives, the kind you'd actually trust with real money.

Why these rails? So the winner is the best idea— not the fastest box or the biggest wallet — and so the winning bot is something a person could genuinely run with real money. That's the whole design.

You implement decide(market_state, portfolio_state, cash) and return a list of orders. You get ~220 trading days of daily bars per ticker (about 10 months, enough for a 200-day SMA); you return [{"ticker": "SMH", "side": "buy", "quantity": 40}]. That's it. We run it across hidden historical regimes (admission) then live for 30 days — Round 1, June 2 – July 2 (the ranking).

Fork the template → — it ships with 4 working reference bots you can read, run, and beat.

Building with an AI assistant? Paste the build brief into Claude / ChatGPT / Cursor and describe your idea — it has the contract, rules, and goal baked in, so your AI writes a valid bot with you.

The whole loop, copy-pasteable. No install, no keys, ~5 minutes to your first admitted bot:

git clone https://github.com/builderr-ai/builderr-trading-template
cd builderr-trading-template
cp baseline.py agent.py     # rename: a valid, admittable bot
python preview.py           # runs locally in ~10s, prints PASS/FAIL

1. Fork the template and open it. Don't write anything yet.
2. Rename baseline.py to agent.py — that alone is a valid, admittable submission. Run python preview.py and watch it clear the safety bar in ~10 seconds (no install, no keys).
3. Now read example_sector_rotation.py— it's the heavily-commented version of exactly the bot most people build (momentum + risk-off). Copy its ideas into your agent.py.
4. Re-run python preview.py after each change. Green safety bar = very likely admitted.
5. Push, email the link, done. You can revise up to 4 times during Round 1 — we run your latest. Your first try isn't your last.

The blank page is the hard part. Pick a thesis you believe in, paste it into your AI along with the build brief, and you've got a working bot in minutes — then improve it. (Markets move; none of these is a sure thing.)

Want the full breakdown? Anatomy of a strong bot → — plain English: what a strong bot actually does, the one rule that matters, and a complete copy-paste recipe you can hand to your AI.

Write a decide() that each day ranks NVDA, AMD, MU, MRVL, AVGO, SMH by 3-month return, holds the top 4 equally (max 20% each) — but only the ones above their 50-day average; rest in cash.

Write a decide() that holds QQQ when its latest price is above its 100-day moving average, and holds 100% cash otherwise.

Write a decide() that every 5 trading days ranks XLK, XLF, XLE, XLV, XLI, XLY, XLP, XLU, SMH by 3-month return and holds the top 3 equally — only if positive, else cash.

Write a decide() that holds QQQ when it's above its 50-day average, but switches to an equal mix of XLP, XLU, XLE and cash whenever QQQ's 5-day return is below -5%.

Write a decide() that holds ~25% QLD + 25% QQQ in calm uptrends (QQQ above its 100-day average, low recent volatility) but sells the leverage into QQQ/cash when volatility spikes. Keep beta-adjusted gross under 1.4x and every position under 25%.

Still not sure which to pick? Drop your idea in the Discord → and someone will help you shape it.

A few directions builders take. None is “the answer” — each links to a working example in the repo or some reading. Borrow what makes sense and make it your own.

You don't have to fly blind. Backtest locally, sweep parameters, sanity-check — then submit. A few well-worn, free tools:

• awesome-quant — a curated index of basically every quant library worth knowing. Start here.
• backtrader / vectorbt — backtest a strategy on years of data; vectorbt is fast for parameter sweeps (just don't overfit on them).
• pandas-ta — 100+ technical indicators in one import, if you want signals beyond moving averages.

• Change every parameter ±20%. If performance collapses, you overfit — it won't survive the live test or the rerun.
• A risk-off switch beats a clever entry. A 50/200-day SMA gate does more for your score than any fancy signal.
• Size by volatility, not fixed dollars. Cut size as vol rises; lean in (within the 1.5× cap) when calm.
• Leveraged ETFs decay in chop. TQQQ/SOXL reset daily — −10%/+10% nets a loss, and TQQQ hit −82% in 2022. Tactical only, never buy-and-hold.
• Keep it simple. Fewer parameters = fewer ways to fool yourself.
• The prettiest backtest is usually the most overfit. Distrust perfection.

• Lookahead bias — using data your bot couldn't have had in real time. We catch it (code review + held-out rerun) and it's an instant DQ.
• Curve-fitting — tuning until history looks perfect. Dies live.
• Over-leverage — sizing for max return, not survival. The 1.5× cap auto-flattens you.
• No drawdown management — no risk-off, no vol scaling. One bad regime ends your run.
• Ignoring costs & fills — a frictionless backtest lies. We model slippage; so should you.

• alpacahq/alpaca-backtrader-api — official Alpaca ↔ Backtrader bridge; backtest then paper-trade the same code.
• Alpaca + VectorBT tutorial — fast vectorized backtesting over years of data (and the overfit trap it creates).
• Quantopian Lectures (archived) — the canonical free quant curriculum: momentum, mean-reversion, bias avoidance.