Boomerang AI
EN PT Try the demo
Documentation

What Boomerang AI is

Boomerang AI is an autonomous trading agent. Instead of you watching charts all day, it does that for you: it observes the market, decides with artificial intelligence, and executes trades on its own on the BNB Chain (Binance's network), following rules you set.

The name "boomerang" comes from the core idea: capital is thrown into a trade and always returns to your wallet with the result. You are always in control and the money never leaves your reach.

💡

In one sentence: it turns spikes of market attention into disciplined trades, automatically, around the clock.

Concept

How it works

When a coin goes viral, people rush first to sites like CoinMarketCap to research it. That interest shows up there before the money actually reaches the chain. There is a small window of opportunity in that gap, and that is where the agent acts.

Every decision passes through three checks in sequence (we call them "the three shields"). If any one fails, the trade does not happen.

1. The analytical shield (the eyes)

The agent reads attention and momentum signals on CoinMarketCap. An AI weighs those numbers and only approves a buy if confidence clears a threshold you adjust. Never on impulse.

2. The on-chain shield (the reality check)

Before spending anything, the agent simulates the trade on the chain itself: it checks whether there is real liquidity to buy and, above all, to sell later. It rejects coins with hidden taxes or abnormal prices. The golden rule: if it cannot exit cleanly, it does not enter.

3. The execution shield (the hands and the vault)

Once approved, the agent signs and sends the transaction using the Trust Wallet Agent Kit. The agent itself signs, with the key that moves the money kept encrypted in the agent's own environment. It never appears in the browser, the site, or the code. This is called self-custody.

🪃

The cycle in short: signal, checks, trade, and the capital returns to you. Like a boomerang.

Trust

Security and privacy

The money is yours, the rules are yours, and the key is yours. These are the principles:

  • Self-custody. The wallet belongs to the agent itself (it is not held on an exchange). The private key (the "master password" that moves funds) is stored encrypted and never appears in the browser, the site, or the code.
  • Isolation. The part that "thinks" (reads the market) has no access to the key; the part that "holds" the money is not exposed to the internet.
  • Manipulation-proof. The AI only receives structured numbers, never loose text someone could use to trick it.
  • Owner lock. Only you command the agent, confirmed by your wallet signature.
  • Withdrawal lock. Funds can only be sent back to your personal wallet, never to an unknown address.

And when it becomes a product, with many users?

Today this is a prototype with a single wallet (the demo one). In a real product with many users and larger amounts, the planned architecture is non-custodial: each user keeps ownership of their own money, the agent only gets permission to trade (never to withdraw elsewhere), and each person sees only their own wallet, protected by wallet login. There will never be a model where the operator holds everyone's keys.

⚠️

A wallet address is public by nature (anyone can see it on the chain) and is not a risk. What must never leak is the private key / recovery phrase. Keep it offline and never type it into websites.

Hands on

Installation

The steps below take you from zero to a ready-to-run agent. You do not need to be a programmer: just follow them in order.

1

Install the prerequisites. Download from each official site and install with default options:

  • Python 3.12 or newer, at python.org/downloads. The agent's engine. On Windows, tick the "Add Python to PATH" box during install (easy to forget, and it causes headaches later).
  • Node.js LTS version, at nodejs.org. Required for Trust Wallet.
  • Git, at git-scm.com. Used to download the project (or grab the ZIP, in step 2).

After installing, open a new terminal (called "PowerShell" on Windows, "Terminal" on Mac) and check everything responds:

python --version node --version
💡

Always open a new terminal after installing something. Otherwise it may not "see" the program you just installed.

2

Get the project and enter the folder:

git clone https://github.com/deegalabs/boomerang-ai cd boomerang-ai

No Git? On the project's GitHub page, click Code then Download ZIP, extract it, and open the folder in the terminal.

3

Install the dependencies in an isolated environment (so nothing messes with the rest of your computer):

python -m venv .venv # Windows: .venv\Scripts\activate # macOS / Linux: source .venv/bin/activate pip install -r requirements.txt
4

Get the access keys. The agent talks to four services. Create an account in each and save the keys (they are free to start):

  • Telegram. Message @BotFather, use /newbot and save the bot token. Also get your ID from @userinfobot (this is the lock that lets only you command it).
  • Claude (Anthropic). At console.anthropic.com, create an API key. It is the agent's "brain".
  • CoinMarketCap. At coinmarketcap.com/api, get your API key. The "eyes".
  • Trust Wallet (TWAK). At portal.trustwallet.com, create an app and copy the Access ID and HMAC Secret (the secret is shown only once). The "hands".
🔒

Never share these keys or put them in screenshots. They live in your .env file (explained next), which is never committed (it does not go to Git or the site). When you host the agent, you set them as protected environment variables on the provider.

5

Install the Trust Wallet tool (TWAK). With Node.js already installed, install the TWAK CLI following the instructions at portal.trustwallet.com. To confirm it worked, run:

twak --version

If a version number shows up, you are ready to create the wallet.

The heart

The agent wallet

The agent needs its own wallet on the BNB Chain, with a little money to trade. You create this wallet in seconds and keep full control of it.

1

Create the wallet (choose a strong password and keep it):

twak wallet create --password "YOUR_STRONG_PASSWORD"

Use exactly the same password in every command below and in the .env file. If they do not match, the agent cannot open the wallet.

📝

Write down the recovery phrase (seed) shown and keep it offline, somewhere safe. With it you can always recover access, even if you lose the computer. Never type it into websites.

2

See the address of the agent wallet on the BNB Chain:

twak wallet address --chain bsc
3

Add a little money. From your personal Trust Wallet app (or any wallet), send to the address above, over the BNB Smart Chain (BEP-20) network:

  • A small test bankroll in USDC (suggestion: 10 to 20 dollars to start).
  • A little BNB to pay network fees (around 2 dollars is plenty; each trade costs cents).
⚠️

Double-check two things before sending: that the network is BNB Smart Chain (BEP-20) and that the address is correct. Sending on the wrong network or to the wrong address can make you lose the money, with no way back. That is why you start small.

4

Check the balance to make sure it arrived:

twak wallet portfolio --chains bsc --password "YOUR_STRONG_PASSWORD"
✅

Done. You keep full control: by importing the recovery phrase into the Trust Wallet app, you can withdraw manually at any time.

Almost there

Configure and run

1

Set up the config file. Copy the template and fill it with your keys:

# Windows: copy .env.example .env # macOS / Linux: cp .env.example .env

Open .env with a plain text editor (Notepad on Windows works fine) and fill each line in the format NAME=value: the wallet password, the Telegram, Claude, CoinMarketCap and Trust Wallet keys, and the address of your personal wallet (where withdrawals return). Paste each value right after the =, with no spaces or quotes.

2

Start the agent:

python run_agent.py

It starts up, connects to Telegram and is ready. (To just test without real money, use python run_agent.py --paper, which simulates trades.) To run 24/7 without keeping your computer on, the agent runs hosted in the cloud; the official instance runs on Railway, with the key kept encrypted in the agent's environment.

3

Configure via Telegram. In your bot, send /start and use the three-step wizard:

  • Focus token. Which coin (or all liquid ones) the agent should focus on.
  • Stop-loss. How much you accept losing per trade before selling (2%, 4% or 5%).
  • Take-profit. When to realize the gain (+5%, +10%, +15% or "let it run").

Confirm with Activate and that is it: the agent starts trading and notifies you on every action.

4

Keep it running 24/7 (in the cloud). So the agent works without keeping your computer on, host it on Railway (that is where the official instance runs). In four steps:

  • Create the Railway account, install the CLI and log in: npm i -g @railway/cli then railway login.
  • In the project folder: railway init and create a volume for the state: railway volume add -m /app/state.
  • Send your secrets and the (encrypted) wallet to Railway without exposing values: python scripts/railway_setvars.py. Also set SESSION_SECRET and OWNER_WALLET_ADDRESS.
  • Publish and get the link: railway up and railway domain.

Done: the bot and the site stay up around the clock. The full walkthrough (what each command does) is in the project's DEPLOY.md.

🔒

When hosted, the key (encrypted) and the password live as protected variables on the provider, not on your PC. This is how any 24/7 bot works, so start with a small bankroll. And do not run the agent from your PC alongside the cloud one: two agents on the same wallet conflict.

📊

At any time, send /status to see equity, positions and live PnL, or /dashboard to open the live panel. In an emergency, /panic liquidates everything and halts the agent.

Discipline

Risk management

The agent is built to protect capital. The safeguards work in layers, all automatic:

  • Per-trade stop-loss. Cuts a small loss before it grows.
  • Trailing stop. When a trade rises, it protects part of the gain already made.
  • Take-profit. Realizes the gain when it hits the target you set.
  • Global circuit breaker. If the whole account loses beyond a limit, it sells everything and stops, avoiding a large loss.

The philosophy is simple: small positions, contained losses, survival first.

⚠️

Trading crypto involves risk. No tool guarantees profit. Only use what you are willing to risk. This is not financial advice.

The future

Roadmap

  • Non-custodial multi-user. Each person with their own wallet and private panel, keeping ownership of their funds.
  • Automatic boomerang return. On hitting the target, return the capital to the personal wallet and pause ("goal met, rest" mode).
  • More coins and more networks. Expand the universe as liquidity allows.
  • Public proof panel. Real-time tracking, verifiable on-chain by anyone.

This project was built for the BNB Hack (Track 1), bringing together CoinMarketCap, Trust Wallet and BNB Chain.