Run Your Bot
The last step of the dreamBot Builder, Deploy bot, gives you a config file and two ways to run it: on Railway, or on your own machine. This page covers both for a bot kit strategy, then going live and the extra setup a Perps bot needs. DreamFly has its own run lines, covered on the DreamFly page.
Your config
Copy the config or press Download to save it as .env. For a Starter bot at its defaults, it reads:
NETWORK=testnet
DRY_RUN=true
STRATEGY=starter
PRIVATE_KEY=0x...
SYMBOL=SOMI:USDso
STARTER_SPREAD_BPS=10
STARTER_SIZE_USDSO=20
STARTER_TICK_MS=5000
The first four lines are the same for every kit bot:
| Line | What it does |
|---|---|
NETWORK | The network you chose on the Network step: testnet or mainnet |
DRY_RUN | true logs the orders the bot would place and sends nothing. false sends real orders |
STRATEGY | The kit strategy to start on Railway. On your own machine you name it in the run command instead |
PRIVATE_KEY | The key the bot signs with. The builder leaves a 0x... placeholder for you to replace |
The lines after the gap are the strategy's settings from the Tune step.
Only you ever see this key. Replace
0x...with the key of a wallet made just for the bot, keeping the0xprefix (MetaMask exports keys without it, so add it in front). Never use your main wallet's key, and never share or commit this file.
Option A: 24/7 on Railway
Railway keeps the bot running around the clock without your computer on, with no server to set up. Railway charges by usage, so check its pricing before you leave a bot running.
- On the Deploy step, click Deploy on Railway. It opens the bot kit's one-click template.
- In the new Railway service, open Variables → RAW Editor and paste your whole
.env. - On the
PRIVATE_KEY=0x...line, replace0x...with your key, then deploy.
The service can show Crashed until you paste your config. That's expected: it starts as soon as your variables are set.
Your bot's output appears in the service's logs on Railway. Stopping the service stops the bot.
Option B: on your own machine
Free, and the same steps work on any server you control. You need Node.js 20 or later and git. The builder prints these lines with your strategy filled in:
git clone https://github.com/somnia-chain/dreamdex-bot-kit
cd dreamdex-bot-kit
npm install
# save the .env from the builder into this folder, then:
npm run dev -w starter
npm install also builds the kit, so the first run takes a little longer. Stop the bot with Ctrl+C.
From dry run to live
- Dry run on testnet. Let the bot run and read its log. Are these orders you would place yourself?
- Live on testnet. Set
DRY_RUN=false. The bot's wallet needs test tokens to trade and STT for gas: the Quick Start lists the testnet faucets. - Live on mainnet. Set
NETWORK=mainnet. Fund the bot's wallet with only what you are ready to lose, plus SOMI for gas, and keep sizes small until it has proved itself.
Change these lines in your .env (on Railway, in the service's variables), or go back through the builder and download a new config.
Perps bots: link the bot to a wallet
A Perps bot runs on the testnet and keeps its own key, which trades one of your app wallets for you. Before its first run, on app.testnet.dreamdex.io:
- Make a key just for the bot, for example with
cast wallet new, and put it on thePRIVATE_KEYline. Not your account's key: the bot's key only signs orders and pays their gas. - Pick the wallet it trades. Open your wallet (top right) and switch to Wallet 2 or 3 rather than your main trading wallet, so the bot's risk stays in that wallet. The builder's DreamDEX account wallet address follows the wallet you switch to.
- Link the bot to that wallet. Choose Link a bot, paste the bot's address, keep Perps ticked, leave the option to send it STT for gas on, and press Add bot. Step by step: Link a Bot.
- Fund the wallet's perps margin. On the perps page, open Perps ⇆ Spot and move USDso from Spot wallet to Perps account. The bot only trades margin that is already there.
- Check before the first order. From the kit's folder,
npm run perp:doctorreads the link, the bot's gas and the margin in one go, and sends nothing.
The bot can then place, cancel and reduce orders for that wallet, and every fill lands in it. It can't withdraw, and the wallet's leverage stays the setting you chose in the app.
Leave the account address blank and the bot trades its own key's perps account instead. Then send the bot's key STT for gas and deposit USDso into its own perps margin before the first run.
When something goes wrong
| What you see | What to do |
|---|---|
| The Railway service shows Crashed | Paste your .env into Variables → RAW Editor. The bot starts once the variables are set |
| The bot runs but no orders reach the book | Check DRY_RUN. In a dry run the bot only logs what it would send |
| The builder won't go past Tune | A setting would stop the bot from starting. The message under it says which one and why |
| A Perps bot's orders fail | Check its perps margin on the perps page, and the bot's STT on the wallet's Bots tab. npm run perp:doctor reads both |
Still stuck? See Get help.