On-Chain Copy Trading

Copy page

🎯 Goal

Follow smart-money addresses or on-chain signals continuously, and have every entry placed with stop-loss and take-profit orders already on-chain — while you write the strategy and the scaffold handles the plumbing.

⚠️ This scaffold ships no strategy. It gives you a running pipeline and three hooks where your own strategy goes. The hooks that come with it filter almost nothing and carry no evidence of positive expectancy — they exist to prove the pipeline runs, not to make money. Every risk control below is a suggestion, not a safeguard. On-chain transactions are irreversible and the risk is yours.

✅ Prerequisites

• Agentic Wallet installed and signed in, on a chain that supports both market-order and limit-order (without limit orders you cannot place on-chain protection).

• A CLI at or above the floor the Skill declares in its frontmatter as requiredCliVersion (1.9.1 at the time of writing) — that field is the single source of truth, so read it rather than this sentence. Below the floor the real-time connection has no keepalive and no reconnect, and the scaffold refuses to start:

  Code
  baw cli-check --required-version <the Skill's requiredCliVersion> --json

• These Skills, from binance-skills-hub: binance-onchain-copy-trader plus binance-agentic-wallet, binance-wallet-tracker, binance-leaderboard, binance-trading-signal, query-token-audit.

• Python 3 on Linux or macOS — the single-instance lock uses flock, so Windows is not supported.

• A machine that stays awake, and process-level supervision you set up yourself (launchd, systemd, or a container restart policy). The scaffold restarts its own child processes, but nothing restarts the scaffold.

Check the environment before anything else:

Code
baw --version
baw wallet status --json      # must be CONNECTED
baw wallet chains --json      # which chains are supported right now
baw wallet balance --binanceChainId <chain> --json   # quote token + native (gas)

Note that no cheap check proves a protective order will actually place. Treat a chain as unverified until you have seen a real stop-loss reach WORKING on it, and do that first run at the smallest size you are willing to hold unprotected.

Step 1 · Install the Skill

"Install the on-chain copy trader Skill and check whether its dependencies are all present"

The Agent installs binance-onchain-copy-trader, confirms the five dependency Skills are available, and verifies the CLI version floor.

Step 2 · Pick your trigger sources

Two peer real-time subscriptions. Use either, or both.

Source	What it follows	How you choose
Address	Trades made by specific wallets you list	Up to 100 addresses, one per line, in $COPYTRADER_HOME/addrs.txt
Signal	The platform's own smart-money signals, all chains	No configuration needed

"Find candidate addresses to copy on BSC, ranked by win rate, and score the top ones"

The Agent uses binance-leaderboard to list candidates and then scores each on six dimensions — follow_friendly is the one that matters most here. Note that single dimensions saturate: over a short window many addresses tie at 100% win rate, so add your own secondary criteria.

Step 3 · Write the config

The first run writes an empty template to $COPYTRADER_HOME (default ~/.local/copytrader) and refuses to start until every required field is filled, listing exactly which are missing.

There are no default values for anything that touches capital. A stop-loss distance you never thought about is as dangerous as a position size you never thought about. The single exception is mode, which defaults to dry-run — an omission can never turn into live trading.

Key	Meaning
chain / quote_token	Chain ID and quote-token address (lowercase)
sources	["address"], ["signal"], or both
budget_usd	Cumulative deployment cap. Decide whether losing all of it is acceptable
position_usd	Per-trade size
max_positions	Concurrent position cap
gas_floor_native	Native-token floor; also stops if the balance cannot be read
policy.*	Your strategy parameters — passed to your hooks verbatim

Leave mode as dry-run.

Step 4 · Dry-run with the bundled hooks unchanged

Code
cd <skill-dir>/scripts && python3 copytrader.py
tail -f $COPYTRADER_HOME/copytrader.log

Do not edit the hooks yet. What ships filters almost nothing, which makes it a poor strategy but a good instrument: it lets through a broad sample so you can see what the stream actually contains before you start rejecting things.

At this point you are answering one question only — does the plumbing work? Check that the startup log matches what you intended, that events are arriving from every source you configured, and that the decision distribution in events.jsonl shows each gate rejecting what you expect.

Do not read a dry-run pass rate as a live fill rate. Dry-run records no positions, so the budget and concurrency guardrails never fire — it will always pass more than live would open.

Step 5 · Score the decisions before spending anything

Every decision that would have opened a position — dry-run included, where nothing is bought — re-reads the price at outcome_horizons_min (default [5, 15, 60]) and appends it to outcomes.jsonl. Join it with events.jsonl on the event key and you get one row per decision carrying both its features and its forward return:

"Read my outcomes.jsonl and tell me which event features actually separated winners from losers"

These numbers are marks, not fills — no slippage, fees, token tax or gas, and a horizon is an instant rather than a path, so a good reading at 60 minutes says nothing about whether a stop-loss would have been touched first. Treat them as an upper bound, and let sample size govern how much you conclude.

Step 6 · Write your strategy

Three functions at the top of scripts/copytrader.py. The mechanism layer never touches them:

Code
should_enter(ev, ctx)  -> (bool, reason)
size_position(ev, ctx) -> float          # USD
exit_plan(ev, ctx, entry_price, qty) -> [(trigger_price, sell_qty, slippage_pct), ...]

should_enter is called twice — once before anything has been spent on audit and market data, and once after both are ready. Put cheap judgements in the first call and anything needing audit data in the second.

Build your thresholds from your own dataset from step 5. Numbers copied from someone else's run describe their sample, their sources and their window — not yours.

Step 7 · Go live

Switch mode to live. The run refuses to start unless $COPYTRADER_HOME/I_UNDERSTAND_THE_RISK contains the current budget_usd:

Code
echo <budget_usd> > $COPYTRADER_HOME/I_UNDERSTAND_THE_RISK

Requiring the amount rather than mere existence means the acknowledgement cannot be inherited by copying someone else's runtime directory, and that raising budget_usd invalidates it — more money at risk deserves a fresh decision. An Agent may write this file once you have confirmed the number; what matters is that the decision was made about this specific amount.

Start with an amount whose total loss is acceptable.

Operating a live run

Action	Command
Stop opening new positions	touch $COPYTRADER_HOME/STOP
Exit the process	touch $COPYTRADER_HOME/KILL
Restore the live gate	rm $COPYTRADER_HOME/I_UNDERSTAND_THE_RISK

"Summarize my copy-trading run: open positions, realized P&L, and what the gates rejected most"

Process exit does not cancel protective orders already on-chain. Stopping the runner leaves your stop-loss and take-profit orders working; cancelling them is a separate, explicit action.

Known limitations

Limitation	What it means for you
Structural lag	Your fill is necessarily later than the address you copy. If they are the issuer or hold a private execution path, their gains are not reproducible while their losses copy in full
Market orders fill at market	A stop-loss trigger price is a trigger, not a fill price. In a fast drop the fill can be well below it
There is an unprotected window	Time passes between the buy filling and the protective order being placed. The position has no downside protection in that window — it can be shortened, not eliminated
No protection without limit orders	On a chain where limit-order is unavailable, protection depends entirely on the process staying alive
The scaffold has no supervisor	It restarts its own child processes, but if the scaffold itself exits nothing brings it back. That is your job to configure
Version coupling is hard	Below CLI 1.9.1 a dropped connection goes permanently silent, and silence is indistinguishable from a quiet market

What's next

• Automated Strategies — conversational strategies that need no long-running process.
• Skills Reference — full capability reference for all Skills modules.
• Security Settings — wallet-level limits that apply regardless of strategy.

⚠️ Risk warning: Nothing here is investment advice. The scaffold guarantees only that it will run the checks you configure — not that those checks are sufficient to protect your funds.