§ 00 / products / apigtbot

apigtbot. A trading bot that shows its work.

Two strategies — a buy-low-sell-high grid and a breakout trend follower — running as always-on daemons against live market data, with every fill, refit and kill written to a journal you can read. One shared wallet funds them all, capital moves to wherever the opportunity is, and every decision is scored against what actually happened. Paper mode by default: real prices, simulated fills, no exchange keys. Risk caps are enforced on the server, not in the strategy, and an AI agent can tune the grid every hour — but never touch the caps.

what it is
self-hosted crypto trading bot platform
status
paper trading · real money behind a go-live gate
licence
MIT · open source
platform
self-hosted PHP 8.4 · Binance
built with
GoatCheese
strategies
grid · trend · optional core, per symbol
default mode
paper — real prices, no keys
AI
MCP server · hourly agent routine
§ 01 / strategies

Two engines, one run, one switch.

Markets range and markets trend; a bot that only knows one of them is wrong half the time. Both engines sit behind the same seam, so a run can change its mind without changing its wallet.

01/grid

Grid — mean reversion

A ladder of buy and sell levels across a price range: geometric or arithmetic spacing, configurable levels and per-level allocation. Buys the dips, sells the bounces, re-anchors itself when the geometry changes and never abandons inventory on a refit. Geometry is set by the agent or runs in mechanical mode: a fixed ±% band, re-centred on a timer.

02/trend

Trend — breakout follower

Long-only entries when price closes above the recent high with the fast average over the slow one; exits on a ratcheting trailing stop sized by volatility with a hard floor. Regime activation is machine-scaled from 4h and 1d ADX and efficiency ratio, with hysteresis so it doesn't flap: the arm deploys its whole slice when the regime turns up and exits cleanly when it fades.

03/core

Core — optional inventory

A 1d EMA-cross core position built in staggered tranches, bought on a pullback or after a time limit — the long book beside the trade book, so a grid never sells the last of what you meant to keep.

04/switch

One switch per run

Flip a live run between grid and trend from the dashboard. The daemon restarts and hands over cleanly: open entries cancelled with partial fills booked, working exits carried as legacy orders, unguarded positions taken over at cost.

§ 02 / capital follows opportunity

One wallet. Capital goes where the move is.

A budget pinned to a symbol sits idle while the move happens somewhere else. Here every run draws from one shared wallet, and an allocator moves the slices — inside limits it enforces on itself.

01/arms

Arms per symbol

No fixed budget splits. Each symbol declares its grid and trend arms; a trend arm is funded when its regime turns up and released when it fades.

02/allocator

An allocator every 15 minutes

Rebalances the pool toward wherever the opportunity is, and keeps a reserve it refuses to spend — gtbot_pool_reserve_pct is headroom the allocators cannot touch.

03/invariant

Never overcommit

The shared-budget invariant is enforced in three layers — when you save, in the allocator, and in the daemon — so a slip in one is caught by the next.

04/lifecycle

Run lifecycle

Retire and purge finished runs, seal a wallet, or let the cap follow account value in "use all funds" mode. One wallet, multi-asset seeded, funds everything.

05/why

It tells you why

An arm sitting idle names its cause. A silent grid raises an alert. An arm with nothing running has to explain itself to the watchdog, or it pages you.

06/hold

Never panic-sell

By default a position is never sold below cost unless the ladder has nothing left to trade with. Liquidating is a decision, not a reflex.

§ 03 / trading modes

Paper first. Real money is opt-in, twice.

01/paper

Paper — the default

Live market data, fills simulated locally, balances in a simulated wallet. No exchange account, no keys. Every strategy, chart, alert and risk rail behaves exactly as it would with money on the line.

  • no keys
  • real prices
02/testnet

Real — testnet

Orders go to the exchange's sandbox with testnet keys. Same code path as live, so what you see here is what you will get there.

  • sandbox keys
03/live

Real — live

Mainnet orders with your own keys. Gated on purpose: the run's own switch and the server's environment flags must all agree; a mismatch is refused at boot, and the daemon fast-fails without credentials. The go-live gate (gtbot-golive) reads the ledgers and passes only when every check does; the account audit (gtbot-audit) checks that the real exchange account backs them, and a finding pages you only if it survives two consecutive audits.

  • your keys
  • gated
§ 04 / risk rails

The strategy proposes. The rails decide.

A bot is only as safe as the thing that can say no to it. Every rail below applies identically in paper, testnet and live mode.

risk profiles
One dropdown — NoLoss, Cautious, Balanced, Aggressive, Max — drives every cap as a live ratio of the run's budget: daily-loss limit, unrealised-loss stop, position and order caps, breakout policy, trailing-stop multipliers. NoLoss structurally refuses every loss-realising path.
shared wallet
All runs draw slices from one budget pool. Over-commitment is refused when you save, and halts entries at the daemon if it slips through. A wallet-level drawdown floor kills every run when equity falls below it and stays there for three ticks.
sell at loss
A per-run switch, off by default. Until you turn it on, the bot will hold inventory rather than realise a loss — a deliberate choice, not a forgotten one. sell_when_starved sells below cost only when the ladder has nothing left to trade with, and Flatten takes the bids and chases the price until the position is flat.
server-side
The caps live outside the strategy and outside the agent. A strategy bug or an over-eager AI proposal cannot raise a limit, clear a kill switch or liquidate a position.
evidence
Walk-forward sweeps over collected candle history — spacing, width, deployment policy, trend parameters — validate a setting before it is trusted with a live run. Sixteen sections of refit evidence and counting; ideas the data refuted stay refuted and are written up as such. Guardrails derived from them are computed into every refit proposal.
alerts
Kills, breakout halts, drawdown stops and stranded inventory go to your phone immediately; closed cycles the moment they book, with realised P/L; routine fills batched into digests so a burst is one message, not ten. A stop alert is never held back by the throttle.
§ 05 / an agent in the loop

Tuned by an AI. Bounded by the server.

Grid geometry is tedious to tune by hand and markets move. So an assistant like Claude does it on a schedule — inside limits it cannot change, with a scoreboard it cannot hide from.

01/mcp

MCP server

The whole system is drivable by an AI agent over the Model Context Protocol, as a logged-in user: status, the hourly routine brief, grid preview and set, refit proposals, market and backtest, P/L report, decisions and events, budget and allocation mode, create, start, stop, kill, retire and purge a run.

  • gtbot_routine_brief
  • gtbot_refit_proposal
  • gtbot_alloc_mode
  • +15
02/routine

Hourly refit routine

Once an hour an agent takes one compact brief of every run — signal digest, regime and gates, a candidate grid, track record, a "material change" bit — and re-fits the flagged runs' range, levels and deployment, reallocating budget slices where it helps.

  • gtbot_routine_brief
  • 1 read / hour
03/scored

Decisions that get graded

Every agent decision is journaled with its reasoning, then scored by the server against what the market actually did: each decision records its clamps and candidate delta and gets a counterfactual verdict computed from intra-bar OHLC. The agent reads its own track record in the next brief and learns from it.

  • gtbot_decisions
  • scored
04/rails

Advisory, with guardrails

The agent may re-fit geometry and move slices. It cannot raise a risk cap, clear a kill switch or liquidate inventory — those stay human. A dead-man's-switch cron takes over with quantile refits if the routine goes quiet for two hours.

  • caps untouchable
  • dead-man switch
§ 06 / in the box

Built to be operated, not just started.

01

Dashboard

Per-run charts — trades, price history, trend line, grid band, lifecycle markers — holdings, the shared-wallet tile with an inline budget editor, hold / release funds, start / pause / reload per run. A wallet NAV ledger and a P&L report benchmarked against HODL and USDT.

02

Always-on daemons

One process per active run, kept alive by a watchdog; market data collected every ten minutes; a nightly backup. No root, no service manager required.

03

Decision journal

Every fill, refit, switch, halt and kill is an event with an id. Alerts carry the id, so a genuine repeat is distinguishable from a double-send. Regime episodes and engagement tracking show how long each arm was eligible and how much of that time it was actually working. Fills are booked at the price they traded at.

04

Market outlook

A long-horizon 1d / 1w regime detector with hysteresis and scored 7-day and 30-day outcomes, with an optional daily Telegram digest. A detector, not a predictor: the predictor version was tested and refuted.

05

Backtests & sweeps

Backtest a candidate grid or trend setting from the dashboard or the agent; walk-forward sweep scripts for the parameters that matter.

06

REST API

Runs, orders, events, market data and wallet as documented endpoints with role checks and an audit log — the same surface the dashboard and the MCP server use.

07

Go-live & audit

gtbot-golive reads the ledgers and exits 0 only when every check passes; gtbot-audit checks that the real exchange account backs them. The BNB fee float is handled, and exchange switches belong to the host, so a deploy never pushes them.

08

Runbook

Going live, incident recovery, alerts, the agent routine's prompt and design, the evidence behind the guardrails — written down, in the repo.

Built on GoatCheese: the admin, API and MCP server are generated from the data model; the strategy engines and daemons are the custom part.

§ 07 / next step

Run it yourself, or have one built.

Clone it, run the installer, create a paper run and watch it work. Want a strategy of your own, another exchange, or an agent routine tuned to your rules? Send a brief.

Experimental software for research and paper trading. Nothing here is financial advice; if you connect real funds, you do so at your own risk.