bitra

TRA (trading research agents) is published as bitra on PyPI and runs as tra. Before 0.10.1 the package was called trading-research-agents, and the same package is still published under that name.

TRA is a crypto trading desk you run yourself. It reads the market, takes one decision, prices the round trip, holds the decision against limits you declare, and either writes it down or sends one order with its stop attached. The decision can be a rule in your own file, with no model in the loop, or a language model that proposes. Either way the system, with no model involved, computes every figure, applies every limit, sizes the trade and sends the order. Every decision and every refusal is kept on disk with its reason, so you can check afterwards what happened and why.

It is experimental. Settings change between versions, it has not been run with real capital by us, and the package ships no strategy that makes money. What it does give you: one order path to every exchange ccxt reaches, run end to end on six of them; an arena that replays any rule over years of data net of your own costs, beside buy-and-hold and a random null; a typed judge that reads the day's headlines and can hold an entry on an adverse event; and the records to check every claim this page makes on your own data.

Contents

• What it solves

• How it is built

• What we measured, and what it changed

• Get started

• The console

• How one cycle decides

• Venues

• Models and providers

• Toward real orders

• Your money, your orders, your positions

• Watching a desk, and what is kept

• Command line

• What it guarantees, and what is not built yet

• Where it is going

• Documentation

Related MCP server: OOSDK MCP Server

What it solves

None of these is hypothetical. Why it is built this way lists the documented failures behind each one, with their sources.

How it is built

Three kinds of work, kept apart because they fail differently.

flowchart LR
    market["market data<br/>candles, book, funding,<br/>open interest, news"]
    decision["the decision<br/>a rule in your file,<br/>or a model that proposes"]
    guard["event guard<br/>Jev reads the headlines,<br/>the system weighs them"]
    cost["cost and exits<br/>round trip priced,<br/>stop and take placed"]
    risk["risk gate<br/>signs or refuses"]
    venue["venue<br/>one order, exits attached"]
    record[("the record<br/>every step, every refusal")]
    arena["tra arena<br/>the same rule replayed<br/>net of costs, beside a null"]
    market --> decision --> guard --> cost --> risk --> venue
    decision -.-> record
    guard -.-> record
    risk -.-> record
    market --> arena

A rule is asked the same way by tra run and by tra arena: the closed bars before the decision, cut back to the last unbroken run. So the rule you replay is the rule you run, line for line. The package ships no rule of its own; examples/strategies/momentum_long.py is an example, and a test fails the build if a decision core appears inside the package.

The typed judge is kept to the job it is built for, and the system carries what its vendor lists as its weak points: recent headlines are chosen by when the system first saw them, so the judge never compares dates; each choice is asked in two orders, so a first-option bias shows as disagreement and the answer is dropped; one headline and its publisher go in each request and nothing else; and the weight of an event and its comparison with your threshold are arithmetic, done by the system.

What we measured, and what it changed

The design changed after we measured our own first version. Each study is in the repository's research notes with its script, so it can be run again.

These are replays, partly on the period the horizon was chosen on, three instruments and one cost model. They are reasons for the design, not a promise about the future. Replay them on your data:

for coin in BTCUSDT ETHUSDT SOLUSDT; do tra data klines $coin 2021-01-01 --to 2026-10-31; done
tra arena --tape klines --venue binanceusdm --channel bybit/taker-taker \
  --instruments BTCUSDT,ETHUSDT,SOLUSDT --from 2022-01-01 --to 2026-10-31 --interval 1d --context-interval 7d --hold-bars 6 \
  --rows buy_hold,momentum_long,random --spread-bps 2 --slippage-bps 2

Get started

A few minutes. The rule desk needs no model key.

1. Install. You need Python 3.11 or newer. uv is the quickest way:

uv tool install 'bitra[ccxt,openai,anthropic,google,data]'

That brings every model provider and every exchange in. Without uv, run pip install 'bitra[ccxt,openai,anthropic,google,data]' inside a virtual environment. To move to the newest release later:

uv tool upgrade bitra      # or: pip install -U 'bitra[ccxt,openai,anthropic,google,data]'
tra --version

That is the release, and master is the stable branch that holds it. develop, the default branch on GitHub, is where the next one is built and changes often; the rule desk and the event guard below are on develop and not yet in a release (more).

2. Make a desk. A desk is a folder holding your settings and everything it decides.

tra init my-desk --profile rule                     # the example daily rule, no model
tra init my-desk --profile autonomous --agent groq  # a language model as the decision, an experiment
cd my-desk

Add --venue okx (or any ccxt id) to trade somewhere other than Bybit.

3. Declare what you measured, or add your key. A rule desk refuses to load until [strategy].edge_bps holds the rule's mean net per trade from your own tra arena run. An agent desk needs its model key: cp .env.example .env, then set it. Every command reads the .env next to strategy.toml on its own.

4. Check. tra check reads every setting against the others and names the one thing to fix next. A desk that is ready ends with ready to run tra run``.

5. Run. tra run decides once on live market data, in the sandbox: nothing leaves your machine. tra run --every 1d keeps deciding, once a day at the daily close. Or type tra on its own for the console, which takes the same commands.

6. When you want real orders. Start on the exchange's demo or testnet API. Make the desk for that exchange from the start, and the rest is three commands:

tra init my-desk --profile rule --venue bitget
cd my-desk                       # put the exchange's keys in .env
tra keys --probe --prepare       # reads the account; on a demo or testnet sets one-way mode
tra mandate --sign "Your Name" --venue-mode
tra check

--venue writes what that exchange needs into [execution]: its demo or testnet API, 3x isolated leverage, at most 200 per order, and how its stop and take profit are placed. Change any of it. How to make the key on each exchange is in Exchange accounts and keys, and Toward real orders has the whole path.

What a rule desk does before you change anything

An agent desk (--profile autonomous) decides on 15-minute bars by default, reads 1h and 4h as context, lets the analyst name its stop between 0.2% and 3%, and closes a position after four hours; its defaults are in The cycle.

Working on the code itself? See Development.

The console

Run tra inside your desk and it opens the console: what is ready, what isn't, and the next command to run. Under it is a prompt that takes every command and draws it right there. Arrow keys go back through what you typed, tab completes, help lists the commands and exit leaves. For scripts and cron, tra -c "run --now" runs one command and exits, and --plain or --json gives text or machine-readable output instead of panels.

How one cycle decides

flowchart TD
    snap["snapshot<br/>every value with its source and age"] --> wake{"trigger, when declared<br/>has anything moved?"}
    wake -- "no" --> held["held: one data pull, nothing asked"]
    wake -- "yes" --> who{"the decision"}
    who -- "rule desk" --> rule["your rule<br/>closed bars in, one idea or none"]
    who -- "agent desk" --> lead["structure lead, with its team<br/>a direction, a setup, levels, cited figures"]
    rule --> guard{"event guard, when declared<br/>an adverse event about this asset?"}
    guard -- "hold mode, yes" --> refused["a refusal that names its figure"]
    guard -- "no, or paper" --> price
    lead --> price["the round trip priced<br/>fee, spread, impact, funding, slippage"]
    price --> exits["the stop and the target<br/>inside your [exit] bounds"]
    exits --> gates{"the gates you declared<br/>cost, targets, desk exposure"}
    gates -- "no" --> refused
    gates -- "yes" --> riskgate{"risk gate<br/>loss at the stop, caps, switches"}
    riskgate -- "no" --> refused
    riskgate -- "signed" --> intent["the intent, written before anything is sent"]
    intent --> venue["venue mode only<br/>one order, the stop and take profit attached"]

A rule desk asks no model: the rule, the event guard when you declare one, and then the same steps every desk runs. An agent desk adds the structure lead and, when you declare them, its team and its reviewers; each of those is an experiment until the arena or the forward record shows it doing better than the rule alone.

On an agent desk, who does what:

The macro, on-chain and sentiment readings are the system's arithmetic over dated series you declare under sources/, and ask no model: until 0.11 each was an analyst whose model labelled the same figures, no decision ever rested on that label, and the calls were retired. Each series is either a file you keep or a feed the desk refreshes itself (FRED, the Crypto Fear & Greed Index, or any paid vendor that answers JSON over https). tra sources show lists every series with where it came from and how old its last value is, and a value older than its max_age is shown as stale and never counted. Data sources has the details.

Which reviewers run is yours to declare. A vote never decides on its own: it moves conviction by the weight you give it ([conviction].reviewer_weight), and a stance counts for what it says beyond its assignment, since a pro that supports is expected to.

Voices are allowed to disagree. Each reading becomes a score between -1 and 1, computed from its own figures against the lines you drew, so a macro reading barely past its line counts as a small voice and one far past it counts as a big one. Conviction adds them up: agreement grows the size, opposition shrinks it in proportion, and only opposition that outweighs the case stops the trade. A short at 0.70 confidence against a barely bullish macro and sentiment scores 0.56 and trades at half size; against a strongly bullish context it scores 0 and doesn't trade.

The structure lead knows what kind of market it is working in before it decides. The system measures the regime on its timeframe (trending up, trending down, ranging or mixed) and on the higher timeframes you list in [run].context_intervals, and it hands over what your macro thresholds say this cycle as well. A setup that doesn't fit the regime, such as a trend trade in a sideways market, is refused by name; [regime] holds the lines.

Everything after the models answer is arithmetic over numbers you declared. No model can place, cancel or resize an order, read a file outside the project, or edit your configuration. Agents has the full table of what an agent can reach, and The cycle walks through every step.

Venues

A cycle reaches venues through ccxt, so every exchange ccxt supports is already integrated: the same order path, the same gates and the same checks, with nothing in the core naming a venue. What differs from one venue to the next is what ccxt reports it can do, the second column, and how far it has been tested, the last:

"Everything" means ccxt reports the five things a safe order needs: send it, attach the exits, read the position, read the open orders, cancel. "Run end to end" is the stronger claim, a full run with real orders on the venue's demo or testnet API, and Bybit, OKX, Bitget, BingX, Binance and Gate have had it so far. How to make a key on each is in Exchange accounts and keys. Any other venue that takes orders can have that run at any time: start on its practice environment, watch a few cycles and read what it sends. Each report moves a venue into the last column.

Adding the venue you trade on is four steps, and one command writes most of it:

tra venues okx            # what it can do, and which keys it signs with
tra venues okx --setup    # the blocks to paste into envelope.toml, data.toml, strategy.toml and .env

Your fees are filled in from your account when it reports them, and from the venue's standard tier until then, labelled as such; a fee you write yourself is kept and checked against the account. Venues has the full table, the keys each venue needs, and the four steps.

Models and providers

You choose the provider and the model; nothing is hard-coded. Each provider reads its key from the environment (or the .env beside your config) and nowhere else.

TypeSafe is not in this table because Jev is not a model for [agents]: it is the typed judge, declared in data.toml under [judge] with TYPESAFE_API_KEY (a key from https://console.typesafe.ai/keys) and a pinned version such as jev-1.14.0. tra models typesafe lists the versions your key may use; tra keys --probe proves the key without asking a question.

Whatever the provider, every answer is parsed against a closed schema by the system before anyone reads it, so a model that only offers JSON mode is held to the same shape as one with strict schemas.

[agents]
provider = "groq"
model = "openai/gpt-oss-120b"
effort = "medium"                    # minimal | low | medium | high | xhigh | max, where the
                                     # vendor takes it; left out, the vendor's default applies
fallback = ["google:gemini-flash-latest", "anthropic:claude-opus-5-5"]

[agents.roles.reviewer]             # a role can run on its own model
model = "a-cheaper-model"
effort = "low"

fallback is tried in order when a provider is rate limited or down, with the same brief. A vendor's free tier meters each model on its own, so roles can share a provider across two models and each model keeps its own allowance; tra check judges the load per model and says when one is too much. Every call is a line in usage.jsonl with its tokens and latency, and nothing caps spend unless you declare a ceiling. tra keys --probe proves each key works without sending a prompt. A vendor of your own is about thirty lines (Model providers).

Toward real orders

What it trades today, through one order path and the same gates:

• Linear perpetuals (USDT- or USDC-margined swaps) on any venue ccxt reaches, long and short, with the leverage and margin mode you declare. The default, run end to end on six exchanges.

• Spot pairs, long only and paid in full, for a desk that lists spot in [execution].markets.

• Stock perpetuals and tokenized stocks, which are a perpetual and a spot pair to the venue, with the underlying exchange's hours respected.

• Prediction market outcomes, for a desk that lists prediction, decided on a probability by their own analyst and priced to resolution.

That is where the project started, not where it stops. For spot, Venues says how to set a desk up. Spot, a stock perpetual and a tokenized stock have been run on the Bybit and OKX demos; prediction outcomes have run in sandbox on live data, and their order path is tested against ccxt's shapes until a practice venue is run. Dated futures, inverse contracts and options are on the way, each with its own cost model, exit rules and tests. Until a market type has those, venue mode checks the type on every order and refuses it, because a market the system cannot yet price and protect is not one it should send to. Boundaries says what each one takes.

A desk goes through three steps, and you can stay at any of them as long as you like:

Steps 1 and 2 have been run end to end on the demo or testnet APIs of Bybit, OKX, Bitget, BingX, Binance and Gate. Step 3 has not been run by us; treat it as yours to verify, small, first.

If you bring a scripted strategy of your own instead of the agents, it has a research path of its own before any of this: tra data get BTCUSDT 2025-01-01 and tra backtest replay a day of the exchange's archive net of every cost, tra paper --minutes 30 runs it on the live feed with nothing sent, and tra live is a small canary session behind hard caps. The example core is there to show the path, not to make money, and the replay prints its net as it comes out, loss or gain. The live tier has the details.

Venue mode is the only mode that can lose money, so it has a door in front of it. Read the mandate with tra mandate; when you accept it, tra mandate --sign "Your Name" keeps it in the project as MANDATE.md and signs [execution] with your name and today's date, in one step. Signing alone does not switch anything on; --venue-mode signs and turns orders on together. tra check names whatever else is missing.

Your money, your orders, your positions

Once orders flow, three things look after the money, all of them the system's own rules and none of them a model:

Who decides what, in one line each: the analyst proposes the direction, your risk rule sets the size, you choose the leverage, and no model touches the last two. Leverage never makes a trade bigger. It only decides how much margin the trade ties up and how far away liquidation sits.

[execution]
mode = "venue"
environment = "demo"             # demo | testnet | mainnet
leverage = 3                     # yours to choose; it never makes a trade bigger
max_notional = 400               # the most one order may be worth, in quote currency
margin_mode = "isolated"         # isolated | cross
hold_limit = "timeout"           # close by time after [exit].timeout_bars; or horizon, or none

Underneath, on every venue: the order goes only to the environment you declared (demo, testnet or mainnet); an open position or a working order refuses a second entry; a size off the venue's step is refused rather than rounded; a clock more than a second off the venue's refuses before anything is signed; and Ctrl-C or a service stop cancels a resting order before the process leaves. Every close goes to positions.jsonl and every finished trade to round_trips.jsonl. Capital, orders and positions has every setting, every refusal and the arithmetic behind each one.

One thing to know before you rely on it: the position checks run at the start of each pass of tra run --every. With no desk running, an open position has its venue-side stop and take profit and nothing else, so a desk meant to run unattended belongs under a supervisor.

Orders cross the book by default (taker-taker): they always fill, which is how most desks trade. Point [run].venue_key at a maker-taker channel and entries rest on the book as post-only orders instead - a lower fee, fewer fills, since a resting order can be left behind by the market. Either way the cost gate prices the fee of the channel you chose.

Watching a desk, and what is kept

The console runs commands in its own process, so closing it ends what it was running. A desk that should keep running belongs under a supervisor (systemd, a service manager, tmux), and then you look at it from anywhere with:

tra watch --every 5s       # a read-only view built from the records the desk writes

tra watch opens no connection, holds no key and takes no lock, so opening and closing it does nothing to the desk.

What is kept, and where:

Command line

Every command says what it did. Exit code 0 means cleared, 1 means a gate said no, 2 is a usage error. --json gives machine-readable output and --plain gives text instead of panels.

Getting started

Running

Data

The ladder, research and hosts

What it guarantees, and what is not built yet

Some rules are guarantees, enforced by the system and tests, and every change has to keep them:

• No model touches an order or a key. Models read figures and answer; the system sizes, prices, limits and sends.

• No model can loosen a control. A model can tighten a limit, step the ladder down or arm the kill switch; never widen, promote or disarm.

• One decision, at most one order. A venue error is recorded and the next cycle decides again; nothing is retried around real capital.

• Stale or missing data is refused, never read as zero or as current.

Other things are simply not built yet, and contributions are welcome: inverse, dated futures and options; on-chain venues outside ccxt; more than one account; transfers and treasury; routing and execution algorithms; portfolio accounting. Boundaries lists each one with what it does today and what a contribution would need. The example strategy cores are examples: your edge is yours to declare.

Liability says plainly where responsibility sits when real capital is involved.

Where it is going

The project is in active development, and what this page describes is where it stands today, not where it stops.

• More market types. Spot, stock perpetuals, tokenized stocks and prediction markets are built; inverse and dated futures and options follow, each added with its own cost model, exit rules, sizing and tests before venue mode accepts it.

• More venues run end to end. Every venue ccxt supports already goes through the same order path and gates. Each one joins the six already in the last column of the venues table after a full run on its demo or testnet API, ours or yours.

• The rest of the not-built-yet list, one piece at a time, without weakening a guarantee.

Use the release. What PyPI installs is the latest release, and it is the version to run. master holds that release and is the stable branch. develop is the default branch on GitHub, the one this page is read from, and it is where the next release is built: it changes often, a commit there is not a release, and it can carry work that is unfinished or changed again before it ships. A set of changes becomes a release when it is merged into master, tagged and published, and CHANGELOG.md says what each one brought.

Documentation

The full documentation is at docs.bijectivelabs.dev. Its source is in docs/, so a change in behaviour and the page that describes it go in the same pull request.

Development

git clone https://github.com/BijectiveLabs/bitra && cd bitra
uv sync --all-extras
uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest

CONTRIBUTING.md has the branch flow and the standards the code is held to.

Where it comes from

This repository opened to the public in October 2026. Its history starts on 12 September 2026, when the code was separated from Bijective's internal work, and every commit, tag and contributor since then is here. The ideas it is built on are older: the falsification chain, the cost model and the controls in front of every order come from Bijective's research and from the trading platform it was building before this repository existed. The language-model agents came later and sit on top of those gates, which is why they can propose but never size, price or send.

License

MIT. See LICENSE; NOTICE lists the third-party software this package builds on.

Built by Bijective Labs.