trading-research-agents

trading-research-agents

決定論的に実行する自律型トレーディングエージェントです。エージェントが提案し、システムが判断します。

言語モデルは市場を読み取り、自分の見解を述べるのは得意です。一方で、計算は苦手で、取引にかかるコストを把握しておらず、設定した上限をためらわずに超えてしまいます。このプロジェクトでは、言語モデルを最初の部分にのみ使用します。モデルを一切関与させず、固定ルールに従って動くシステム自体がデータを取得し、すべての数値を算出します。エージェントはその数値を読み取り、見解を示します。その後、システムが取引価格を算出し、設定された上限を適用して取引量を決定し、記録するか、ストップ注文を添えて単一の注文を送信します。すべての判断と拒否は、その理由とともにディスクに保存されるため、後から何が起きたのか、なぜそうなったのかを確認できます。 これは初期リリースのため、バージョンによって設定が変わる可能性があります。現在できること：1つの注文経路で、linear perpetuals、現物ペア（株式のパーペチュアルやトークン化株式を含む）、予測市場の結果を扱えます。システムがパーペチュアルの対象銘柄群を見つけて測定し、スクリーナーが調査対象を選び、ライブデータを使った完全自律サイクルを実行します。アナリストは4人、バリデーターは最大3人です。アナリストが設定した範囲内で指値と目標値を指定し、ゲートが判断し、サイズはお客様自身のルールに基づいて決まります。お客様が署名した委任契約に基づき、取引所の練習環境で実際の注文を出します。リスクマネージャーがデスクをより慎重にすることだけが可能で、記録を読む監査人が2人います。

---

目次

• 解決する課題
• はじめに
• 表示される内容と順序
• 1サイクルでの判断方法
• 取引所
• モデルとプロバイダー
• 実際の注文に向けて
• お客様の資金、注文、ポジション
• デスクの監視と保存される内容
• コマンドライン
• 保証されることと、まだ実装されていないこと
• 今後の展望
• ドキュメント

解決する課題

トレーディングエージェントでよくある問題	ここで起きること
モデルが数値をでっち上げたり、計算を間違えたりする	モデルは計算しません。すべての数値はシステムが算出し、モデルが引用した数値は、値も含めてブリーフと照合されます。
取引が完了するまで、取引コストが誰にもわからない	往復コスト（手数料、スプレッド、インパクト、ファンディング、スリッページ）は注文前に算出され、それを上回るエッジがあるという主張を満たさない取引は拒否されます。
エージェントが自分でポジションサイズを決める	サイズは、お客様の確信度の段階とリスク上限に基づきます。モデルが取引サイズを大きくすることはできません。
モデルが設定を無視する「判断」を下す	お客様が定めたしきい値に基づいて決定されます。モデルの見解はその横に記録されますが、しきい値に代わることはありません。
問題が起きたのに、追跡できる記録がない	各サイクルでは、スナップショット、ブリーフ、回答、意図、そして取引所からの応答が保存されます。書き換えは行われません。
クラッシュによって、ストップ注文のないポジションが残る	ストップ注文とテイクプロフィット注文はエントリー注文とともに取引所に送られます。取引所が別の方法しか受け付けない場合は約定直後に送られるため、このプロセスが停止しても維持されます。
フィードのテキストがモデルに指示を与える	方向を提案するモデルが読むのは、コードが計算した数値です。外部テキストに触れるのは、何も決定しない役割だけであり、モデルが注文を出したり、キーにアクセスしたりすることはできません。

これらはどれも仮定上の問題ではありません。このように設計されている理由では、それぞれの問題の背景にある、出典付きの記録された失敗事例を紹介しています。

はじめに

必要なのは数分とモデルキー1つです。すべての設定には動作するデフォルト値があるため、何も変更しなくても新しいデスクをすぐに使い始められます。デフォルト値はステップ6の下の表で確認できます。

1. インストールします。 Python 3.11以降が必要です。uvを使うのが最も手軽です。

uv tool install 'trading-research-agents[ccxt,openai,anthropic,google,data]'

これにより、すべてのモデルプロバイダーとすべての取引所がインストールされます。uvを使わない場合は、仮想環境内で pip install 'trading-research-agents[ccxt,openai,anthropic,google,data]'を実行してください。後で最新リリースに更新するには、次を実行します。

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

これはリリース版であり、実行するバージョンです。GitHubのdevelopブランチでは次のリリースを開発中です。そこにあるコミットはリリースではありません（詳しくはこちら）。

2. デスクを作成します。 デスクは、設定とエージェントが決定した内容をすべて格納するフォルダーです。キーを持っているプロバイダーを指定します。

tra init my-desk --profile autonomous --agent groq
cd my-desk

--agent	.env内のキー	モデルを指定しない場合のモデル
groq	GROQ_API_KEY（無料枠）	openai/gpt-oss-120b
google	GEMINI_API_KEY	gemini-flash-latest
anthropic	ANTHROPIC_API_KEY	claude-opus-5-5
openai、deepseek、xai、openrouterなど	モデルとプロバイダーを参照	--modelで指定します。tra models <provider>で一覧を表示できます

Bybit以外で取引するには、--venue okx（または任意のccxt id）を追加します。

3. キーを追加します。 サンプルファイルをコピーし、キーを入力します。各コマンドは、strategy.tomlと同じ場所にある.envを自動的に読み込みます。

cp .env.example .env        # then set GROQ_API_KEY=... in .env

4. 確認します。 tra checkはすべての設定を相互に照合し、次に修正すべき項目を1つ示します。準備ができたデスクでは、最後に次のように表示されます。

ok    provider groq: ready
ready to run `tra run`

5. 実行します。 tra runは、サンドボックス内でライブ市場データに基づいて1回判断します。何もマシンの外には送信されません。tra run --every 15mを実行すると、15分足ごとに決まった時刻で判断を続けます。または、traだけを入力してコンソールを起動してください。コンソールでも同じコマンドを使えます。

tra run
tra run --every 15m

6. 実際の注文を出す場合。 取引所のデモAPIまたはテストネットAPIから始めてください。最初からその取引所用のデスクを作成すれば、残りは3つのコマンドだけです。

tra init my-desk --profile autonomous --agent groq --venue bitget
cd my-desk                       # put the exchange's keys in .env beside your model key
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は、その取引所で必要な設定を[execution]に書き込みます。デモAPIまたはテストネットAPI、3倍の分離マージン、注文あたり最大200、ストップと利確の設定が含まれます。いずれも変更できます。各取引所でキーを作成する方法は取引所アカウントとキーを参照してください。実際の注文に進むでは、一連の手順をすべて説明しています。

何も変更しない場合に新しいデスクが行うこと

	デフォルト	変更箇所
注文	なし：サンドボックスは各判断を記録し、何も送信しません	[execution].mode
取引対象	BybitのBTCUSDTをテイカーとして取引します	[run].instrument、[universe]、--venue
時間足	15分足で判断し、コンテキストとして1時間足と4時間足を読み込みます	[run].bar_interval_s、context_intervals
戦略	固定戦略なし：アナリストは、測定した相場レジームに適したセットアップを選ぶか、ポジションを取りません	[agents].mechanism
ストップと目標値	アナリストが設定します。ストップは0.2%～3%の範囲で、ATRの1倍未満には設定されません。目標値はストップの1.5倍～4倍です	[exit]
取引あたりのリスク	ストップに達した場合、ストップまでの距離にかかわらず、エクイティの0.5%を失います	[controls].max_risk_per_trade_bps
損失が大きい日	その日の損失が3%に達した後、またはピークから10%下落した後は、新規エントリーしません	[controls]
保有時間の上限	4時間後にポジションを決済します	[exit].timeout_bars
取引の条件	優位性が往復取引コストの2倍以上、少なくとも半数の取引で損益分岐以上、1日あたり最大6件です	[targets]
監督	縮小、一時停止、停止のみを行えるリスクマネージャーと、報告を行う2つの監査エージェントです	[audit]

コード自体に取り組む場合は、開発を参照してください。

表示される内容の順序

1. コンソール。 デスク内で tra を実行すると、コンソールが開きます。準備ができているもの、できていないもの、次に実行するコマンドが表示されます。その下に、すべてのコマンドを受け付けてその場に表示するプロンプトがあります。矢印キーで入力履歴をたどり、タブで補完し、help でコマンド一覧を表示し、exit で終了します。スクリプトや cron では、tra -c "run --now" を実行すると、コマンドを1つ実行して終了します。

2. インストゥルメントのスクリーニング。 run --every 15m と入力すると、まずデスクが更新時期を迎えたデータ系列をそれぞれ1行で更新します。次に、リスト上のすべてのインストゥルメントからデータを1回ずつ取得し、測定します。画面にはその処理がリアルタイムで表示されます。

3. 選ばれた各インストゥルメントで1サイクル。 システムが候補を見つけて測定し、スクリーナーが候補から選び、各インストゥルメント固有の数値を示します。システム独自の注文も、選択結果のそばに表示されます。選ばれたインストゥルメントでは、完全なサイクルが実行されます。ターミナルには開始からのパイプライン全体が表示され、各ステップの開始時と終了時に更新されます。同時に実行されるステップは、それぞれ専用の時計とともに同時に動き、その下の行には現在作業中の担当者が表示されます。

4. 結果。 サイクルが終了すると、テーブルがユニバース全体のスクリーニング結果に切り替わります。スクリーナーが選んだもの、待機中のもの、保留されたものとその理由が表示されます。続いてサイクルの結果が表示されます。アナリストがどの数値に基づいて何を提案したか、また、却下の理由とその根拠となる数値がすべて示されます。ここでは、レンジ相場での ETH のショートが決済条件の段階で止められています。独自のストップとターゲット、往復取引のコストを考慮すると、損益を均衡させるだけでも、同様の取引の半分以上で勝つ必要があったためです。

続いて、サイクルで使われたデータとその古さ、読み取り担当のアナリストが参照した系列、設定されていたストップと利確、応答したエージェントが表示されます。さらに進んだサイクルでは、各バリデーターの主張、確信度に応じたアナリストの評価、ストップ時のリスクとターゲットが追加されます。

5. サイクルの合間。 デスクには、次のスクリーニングの時刻と残り時間が表示されます。たとえば next pass at 14:30:00 UTC, in 10m 57s のように示され、そこまでのカウントダウンが行われます。アラームで起動した監査担当者には、専用のスピナーが表示されます。

同じサイクルをプレーンテキスト（--plain、パイプ、ログ）で表示したものです。ライブデータを使った実際の実行結果を短くしています。

cycle 2026-09-29T02-59-16Z BTCUSDT: 5.344s of agents, 15.042s of validators
  funding        ccxt:bybit         age 4.267s
  ohlcv          ccxt:bybit         age 32.746s
  orderbook      ccxt:bybit         age 7.544s
macro      risk-off: the operator declared a bullish state for US10Y; measured correlation is
           neutral (0.0) on a modest sample, weak evidence that does not overturn the declaration
sentiment  positive: declared state is bullish, and the measured figures both support it
technical: long on range_reversion at 0.65 over 5 bars: the close is stretched low in the window
read: zscore=-0.587, vwap_gap_bps=-3.99, ret_1_bps=1.59
validator contra   oppose on 2 cited figure(s)
validator pro      support on 3 cited figure(s)
conviction: 0.800 of 1.0 (macro 1.0, sentiment 0.5, technical 1.300)
risk: 8.29 bps of equity at the stop against the declared 50 bps, size 0.010
cost: 12.87 bps round trip, 2.00 of it estimated
gate: 25.0000 bps claimed clears 12.8723 bps cost plus 0.0000 bps margin
  refused targets: the claimed edge is 1.94x the round trip and the desk declared 2.0x;
                   the cost is certain and the edge is not

この取引は却下されました。コストの条件はクリアしましたが、それでも成立しませんでした。このデスクはコストの2倍の優位性を求めているのに対し、得られたのは1.94倍だったためです。却下の際には、根拠となる数値が必ず示されます。

1サイクルの判断方法

flowchart TD
    find[["the system finds the universe and measures each instrument<br/>one data pull each; every value carries its source and age"]] --> wake
    wake{"trigger<br/>has anything moved since the last look?"}
    wake -- "no" --> held["held: one data pull, no tokens spent"]
    wake -- "yes" --> pick["the screener picks among what the system admitted<br/>citing each instrument's own figures"]
    pick -- "none taken" --> held
    pick -- "taken" --> briefs
    briefs["the system writes the briefs<br/>each role sees only the figures its job needs"] --> round1
    subgraph round1["asked at the same time"]
        direction LR
        tech["technical analyst<br/>a direction, a confidence, a horizon"]
        macro["macro analyst"]
        chain["on-chain analyst"]
        mood["sentiment analyst"]
    end
    round1 --> price["the system prices the round trip<br/>fee, spread, impact, funding, slippage"]
    price --> exits{"the stop and the target<br/>the analyst's levels, held inside your bounds<br/>does the trade break even at half its kind winning?"}
    exits -- "no" --> refused
    exits -- "yes" --> round2["validators, as many as you declare<br/>a claim that cites no figure is thrown away"]
    round2 --> matrix{"confluence<br/>do your declared states agree with the direction?"}
    matrix -- "no" --> refused["a refusal that names its figure"]
    matrix -- "yes" --> size["conviction<br/>how much, from your ladder"]
    size --> risk{"risk per trade<br/>what does it lose at the stop?"}
    risk --> gate{"cost gate and targets<br/>does the edge clear the cost, by your margin?"}
    gate -- "no" --> refused
    gate -- "yes" --> intent["the intent, written into the cycle"]
    intent --> venue["venue mode only<br/>one order, the stop and take profit attached"]

各担当の役割：

役割	読み取るもの	回答するもの	決してできないこと
テクニカルアナリスト	ローソク足、スプレッド、ファンディング、板の不均衡、建玉の変化、および対象の時間足と指定した上位時間足のレジーム	方向、固定リストからのセットアップ、信頼度、時間軸、ストップとターゲットの位置	取引サイズを決めること、[exit] の範囲外に水準を置くこと、レンジ相場でトレンドのセットアップを実行すること、または計測されたレンジではない市場で逆張りすること
マクロアナリスト	日付付きの金利と水準、日付付きのテキスト	リスクオン、リスクオフ、または中立	方向を提案すること
オンチェーンアナリスト	チェーンとデリバティブの数値	蓄積、分配、または中立	方向を提案すること
センチメントアナリスト	日付付きのスコアと、あなたが用意したメモ	ネガティブ、中立、ポジティブ、または未宣言	数値が裏付けていないムードを作り出すこと
マーケットスクリーナー	採用された各銘柄についてシステムが計測した値：値動き、スプレッド、レジーム、出来高、BTC との相関	数値を引用し、どの銘柄をどの順番で選ぶか	システムが採用していない銘柄を追加すること
検証者：賛成派と反対派	提案とその根拠となる数値。互いの主張は見えない	引用した主張に基づく、賛成または反対の最も強い根拠	相手側の主張を見ること、または渡されていない数値を引用すること
検証者：中立の裁定者	同じ情報と、コードがすべての主張を確認した後の両方の主張	賛成、反対、または棄権。これだけが有効な判定	代弁者の判定を見ること、または主張を比較衡量せず数えること
リスクマネージャー	この実行で記録されたもの：往復取引、連敗、あなたの限度、起動のきっかけとなったアラーム	継続、新規エントリーのサイズ縮小、銘柄の一時停止、または停止。それぞれに時間数を指定	あなたが設定した限度を緩めること、またはサイズを増やすこと
テクノロジー監査担当者およびクオンツ監査担当者	このデスクが記録したサイクル	調査結果と変更案	何かを変更すること

マクロ、オンチェーン、センチメントの各アナリストは、sources/ で指定した日付付きの時系列データを読み取ります。各データは、あなたが保管するファイルか、デスクが自動更新するフィード（FRED、Crypto Fear & Greed Index、または https 経由で JSON を返す有料ベンダー）のいずれかです。tra sources show には、すべての時系列データの取得元と最終値の経過時間が表示されます。また、max_age を超えた値は古いデータとして表示され、決して集計されません。詳細はデータソースを参照してください。

どの検証者を実行するかは、あなたが指定します。投票だけで判定が決まることはありません。投票は、あなたが設定した重み（[conviction].validator_weight）に応じて確信度を動かします。また、賛成派の支持など、担当する立場に沿った意見は、その役割に期待されるものとして評価されます。

アナリスト間で意見が食い違うことは許容されます。それぞれの見解は、独自の数値とあなたが設定した基準線を照らし合わせて -1 から 1 のスコアになります。そのため、基準線をわずかに超えたマクロの見解は小さな影響力として、基準線を大きく超えた見解は大きな影響力として扱われます。確信度はそれらを合算します。意見の一致はサイズを増やし、反対意見はその強さに応じてサイズを縮小します。反対意見が根拠を上回った場合に限り、取引を停止します。信頼度 0.70 のショートは、わずかに強気なマクロとセンチメントのスコアが 0.56 なら半分のサイズで取引されます。一方、強い強気の状況に対してはスコアが 0 となり、取引しません。

テクニカルアナリストは、判断を下す前に市場の状態を把握します。システムは対象の時間足（上昇トレンド、下降トレンド、レンジ、または混合）と、[run].context_intervals に列挙された上位時間足のレジームを計測し、さらにこのサイクルについてマクロのしきい値が示す内容も渡します。横ばい市場でのトレンド取引など、レジームに適合しないセットアップは、名称を明示して拒否されます。基準線は [regime] に記載されています。 分析エージェント以降の処理はすべて、宣言した数値に対する算術演算です。どのモデルも、注文の発注、キャンセル、サイズ変更、プロジェクト外のファイルの読み取り、設定の編集はできません。エージェントでは、エージェントがアクセスできる範囲をすべて表で確認でき、サイクルではすべての手順を順に説明しています。

取引所

サイクルは ccxt 経由で取引所にアクセスするため、ccxt がサポートする取引所はすべてすでに統合されています。注文経路、ゲート、チェックは共通で、コア内に特定の取引所名はありません。取引所によって異なるのは、ccxt が何を実行できると報告しているかを示す2列目と、どこまでテスト済みかを示す最後の列です。

取引所	サイクルで実行できること	練習環境	エンドツーエンドで実行済み
Bybit（デフォルト）	すべて：ストップとテイクプロフィットを付けた注文	デモ、テストネット	はい。デモ API で実施：実際の注文、決済注文の付与、未約定注文のキャンセル
OKX	すべて	デモ（ccxt のテストネット切り替え）	はい。デモ API で実施：実際の注文、決済注文の付与、取引所独自の決済注文による決済
Bitget	すべて。クラシックアカウントまたは統合取引アカウントで利用可能	デモ	はい。統合アカウントでデモ API を使用
BingX	すべて	デモ（VST、ccxt のテストネット切り替え）	はい。デモ API で実施
Binance、Gate	注文。約定直後にストップとテイクプロフィットを設定します（exits = "separate"）	デモ（Binance）、テストネット（Gate）	はい。それぞれの練習用 API で実施
WEEX、BloFin、WOO X	すべて	テストネット	実行準備済み
Hyperliquid、Pacifica、WOOFi Pro、ModeTrade（分散型）	すべて	テストネット	実行準備済み。Hyperliquid のレポートを募集中
KuCoin Futures、Deepcoin	すべて	なし	統合済み。練習環境なし
dYdX、Paradex、Extended、Lighter（分散型）、Deribit、Crypto.com、Coinbase International	注文。ただし、ccxt 経由で取引所に決済注文を設定できず、レバレッジを設定できない取引所もあります	テストネット	決済注文を取引所に置く必要がある取引デスクには不適
Kraken、Kraken Futures、Phemex	現時点ではデータのみ：ccxt がポジションを報告しないため、確認できないポジションへの注文は送信されません

「すべて」とは、安全な注文に必要な5つの機能を ccxt が報告していることを意味します。つまり、注文を送信する、決済注文を付ける、ポジションを読み取る、未決済注文を読み取る、キャンセルする、の5つです。「エンドツーエンドで実行済み」はより厳しい基準で、取引所のデモ API またはテストネット API で実際の注文を使って一連の処理を実行することを指します。これまでに Bybit、OKX、Bitget、BingX、Binance、Gate で実施済みです。各取引所のキーの作成方法は取引所のアカウントとキーを参照してください。注文を受け付けるその他の取引所でも、いつでも同様の実行が可能です。まず練習環境で開始し、数サイクルを確認して、送信内容を読み取ってください。レポートが追加されるたびに、取引所が最後の列に加わります。

取引する取引所の追加は4つの手順で行え、その大部分を1つのコマンドで設定できます。

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

手数料は、アカウントから報告された時点でその情報を入力し、それまでは取引所の標準ティアの手数料を使用して、その旨を明示します。自分で入力した手数料は保持され、アカウントの情報と照合されます。取引所では、すべての取引所の一覧、各取引所で必要なキー、4つの手順を確認できます。

モデルとプロバイダー

プロバイダーとモデルは任意に選択でき、ハードコードされていません。各プロバイダーはキーを環境変数（または設定ファイルと同じ場所にある .env）からのみ読み込みます。

プロバイダー	.env 内のキー	インストールするパッケージ	構造化出力	ここでのライブテスト状況
groq	GROQ_API_KEY	openai	JSON スキーマ。利用できない場合は JSON モードにフォールバック。システムが検証	はい：openai/gpt-oss-120b と openai/gpt-oss-20b。記録上、すべてのライブサイクルで使用
google	GEMINI_API_KEY または GOOGLE_API_KEY	google-genai	JSON スキーマ	はい：フォールバックとして gemini-flash-latest
anthropic	ANTHROPIC_API_KEY	anthropic	JSON スキーマ	ユニットテスト済み。デフォルトモデルは claude-opus-5-5
openai	OPENAI_API_KEY	openai	厳密な JSON スキーマ	ユニットテスト済み
deepseek	DEEPSEEK_API_KEY	openai	JSON モード	プリセットのみ
mistral	MISTRAL_API_KEY	openai	JSON スキーマ	プリセットのみ
xai	XAI_API_KEY	openai	JSON モード	プリセットのみ
openrouter	OPENROUTER_API_KEY	openai	JSON モード	プリセットのみ
qwen	DASHSCOPE_API_KEY	openai	JSON モード	プリセットのみ。利用するリージョンに合わせて --base-url を指定してください
ollama	なし	openai	JSON モード	プリセットのみ。ローカルサーバー
local	なし	openai	JSON モード	OpenAI 互換サーバーなら任意。--base-url を指定してください
9router	9ROUTER_API_KEY	openai	JSON スキーマ	プリセットのみ。ローカルルーター

プロバイダーを問わず、回答はすべて、誰かが読む前にシステムによって閉じたスキーマに照らして解析されます。そのため、JSON モードしか提供しないモデルも、厳密なスキーマに対応したモデルと同じ形式に従います。

[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.sentiment_analyst]     # a role that only labels can run on a cheaper model
model = "a-cheaper-model"
effort = "low"

プロバイダーがレート制限に達した場合や停止している場合は、同じブリーフを使って fallback を順番に試します。ベンダーの無料枠はモデルごとに使用量が計測されるため、ロール間で同じプロバイダーの2つのモデルを共有しても、それぞれのモデルに個別の利用枠が適用されます。tra check はモデルごとの負荷を判定し、負荷が大きすぎる場合に知らせます。すべての呼び出しは、トークン数とレイテンシとともに usage.jsonl に記録されます。上限を設定しない限り、支出に上限はありません。tra keys --probe を実行すると、プロンプトを送信せずに各キーが機能することを確認できます。独自のベンダーを追加する場合、必要なコードは約30行です（モデルプロバイダー）。

実際の注文へ

現在、単一の注文経路と同じゲートを通じて取引できるもの：

• 無期限先物（USDT または USDC 建てスワップ）。ccxt が対応するすべての取引所で、宣言したレバレッジと証拠金モードに従って、ロングとショートの両方に対応します。デフォルト設定では、6 つの取引所でエンドツーエンドの実行を確認しています。
• 現物ペア。[execution].markets に spot を指定したデスク向けで、ロングのみ、全額を支払います。
• 株式無期限先物とトークン化株式。取引所にとっては無期限先物と現物ペアであり、原資産の取引所の取引時間に従います。
• 予測市場の結果。prediction を指定したデスク向けで、デスク独自のアナリストが確率を決定し、結果確定時までの価格を付けます。

ここがプロジェクトの出発点ですが、終着点ではありません。現物の設定方法については、取引所を参照してください。現物、株式無期限先物、トークン化株式は Bybit と OKX のデモ環境で稼働させています。予測市場の結果は、実データを使ってサンドボックスで稼働させており、練習用の取引所で稼働させるまでは、ccxt の形式に対して注文経路をテストします。期日付き先物、インバース契約、オプションにも対応する予定で、それぞれに独自のコストモデル、決済ルール、テストを備えます。これらが整うまでは、venue モードがすべての注文で銘柄タイプを確認し、拒否します。システムがまだ価格設定や保護をできない市場には、注文を送るべきではないためです。それぞれが対象とする内容については、境界を参照してください。

エージェントデスクは次の 3 段階で進みます。どの段階にとどまるかは自由です。

段階	方法	実行内容	必要なもの
1. サンドボックス	tra run	実データを使った完全なサイクル。あらゆる判断を記録し、注文は送信しません	モデルのキー
2. デモまたはテストネット API	[execution].mode = "venue" と environment = "demo" または "testnet" を指定して tra run	取引所のデモまたはテストネット API に実際の注文を出し、決済注文を設定してポジションを管理します	署名済みの委任状、レバレッジ、max_notional、練習用キー
3. 実資金	同じ方法で environment = "mainnet" を指定	実資金を使って実際の注文を出します	上記すべてに加え、カナリア段階にあるラダー（証拠を添えて tra ladder promote）

段階 1 と 2 は、Bybit、OKX、Bitget、BingX、Binance、Gate のデモまたはテストネット API でエンドツーエンドの実行を確認しています。段階 3 は私たち自身では実行していません。ご自身で、小規模から始めて、まず検証してください。

エージェントではなく、ご自身のスクリプト戦略を使う場合は、これらの手順に進む前に専用のリサーチ経路があります。tra data get BTCUSDT 2025-01-01 と tra backtest で取引所のアーカイブを使った 1 日分のデータを、すべてのコストを差し引いてリプレイできます。tra paper --minutes 30 では何も送信せずにライブフィードで実行し、tra live では厳格な上限を設けた小規模なカナリアセッションを実行します。サンプルのコアは経路を示すためのもので、利益を生むためのものではありません。リプレイでは、損失でも利益でも、結果の純額をそのまま出力します。詳細はライブ段階を参照してください。

損失が発生する可能性があるのは venue モードだけなので、その前にはゲートがあります。tra mandate で委任状を読み、同意したら tra mandate --sign "Your Name" を実行すると、プロジェクト内に MANDATE.md として保存し、[execution] にご自身の名前と今日の日付を署名する処理を一度に行います。署名しただけでは何も有効になりません。--venue-mode を指定すると、署名と注文の有効化を同時に行います。不足しているものは tra check で確認できます。

資金、注文、ポジション

注文が流れ始めると、資金を守るのは3つの仕組みです。どれもシステム独自のルールであり、モデルは一切関与しません。

注文の前	注文の送信時	注文が有効な間
口座の実際のエクイティと利用可能な証拠金を読み取ります	選択したレバレッジを取引所で適用し、適用結果を読み戻します	各パスの開始時に、各ポジションを取引所と照合します
サイズの決定には、実際のエクイティとデスクに許可した金額のうち、小さい方を使います	清算価格がストップ価格の内側に入る注文は拒否します	保有期間の上限を超えたポジションは、reduce-only注文で決済します
注文で使えるのは、利用可能な証拠金の一部だけです	テイカーでのエントリーは、設定したスリッページ幅内の指値IOCで行い、成行注文をそのまま出すことはありません	取引所のストップまたはテイクプロフィットで決済されたポジションは、実際の手数料とファンディング込みで記録します
1日の損失が上限を超えると、新規エントリーを停止します	ストップとテイクプロフィットはエントリーと同時に設定するため、このプロセスが終了しても有効です	デスクが停止する前に、キルスイッチですべてのポジションを解消します

誰が何を決めるかを一行で言うと、アナリストが方向性を提案し、リスクルールがサイズを決め、レバレッジはあなたが選びます。最後の2つにモデルが関与することはありません。 レバレッジによって取引が大きくなることはありません。決まるのは、取引が拘束する証拠金の量と、清算価格までの距離だけです。

[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

その下では、すべての取引所で次の処理が行われます。注文は宣言した環境（デモ、testnet、またはmainnet）にのみ送信されます。有効なポジションまたは注文がある場合、2つ目のエントリーは拒否されます。取引所の刻みに合わないサイズは丸めずに拒否されます。時刻が取引所の時刻から1秒以上ずれている場合は、何かに署名する前に拒否されます。また、Ctrl-Cまたはサービスの停止時には、プロセスの終了前に未約定注文をキャンセルします。すべての決済はpositions.jsonlに、完了した取引はすべてround_trips.jsonlに記録されます。資金、注文、ポジションには、すべての設定、拒否条件、それぞれの根拠となる計算が記載されています。

利用する前に知っておくべきことが1つあります。ポジションのチェックは、tra run --everyの各パスの開始時に実行されます。デスクが動作していない間、有効なポジションを保護するのは取引所側のストップとテイクプロフィットだけです。そのため、無人で動かすデスクはスーパーバイザーの管理下に置いてください。

デフォルトでは、注文は板にぶつける方式（taker-taker）です。常に約定するため、ほとんどのデスクはこの方式で取引します。[run].venue_keyをmaker-taker`チャネルに設定すると、代わりにエントリーを板に置くpost-only注文にします。手数料は低くなりますが、板に置いた注文は相場に取り残されることがあるため、約定回数は減ります。どちらの方式でも、コストゲートは選択したチャネルの手数料を使って価格を算出します。

デスクを監視する方法と、保存されるもの

コンソールは独自のプロセスでコマンドを実行するため、閉じると実行中の処理も終了します。稼働し続ける必要があるデスクは、スーパーバイザー（systemd、サービスマネージャー、tmux）の下で実行し、次のコマンドでどこからでも状態を確認します。

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

tra watch は接続を開かず、キーを保持せず、ロックも取得しないため、開いたり閉じたりしてもデスクには何も起こりません。

保存されるものと、その保存先：

内容	保存先	備考
1サイクルで実行されたすべての処理	runs/cycles/<id>/	スナップショット、ブリーフ、回答、意図、placed.json、cycle.json、および生の入力を含む inputs.json.gz。cycle.json には各ファイルの sha256 が記録されます
対象ユニバースのスクリーニング	runs/screens/	測定したすべての銘柄、スクリーナーが選んだものとその理由
すべてのモデル呼び出し	runs/cycles/usage.jsonl	トークン数、レイテンシー、価格
デスクの実行時刻と停止理由	runs/cycles/scheduler.jsonl	起動と停止ごとに1行
時刻、取引所、またはキルスイッチによって決済されたすべてのポジション	runs/cycles/positions.jsonl	取引所モード
エントリー、決済、手数料、資金調達料を含む、完了したすべての取引	runs/cycles/round_trips.jsonl	取引所モード。クオンツ監査人が読み取るデータ
各日の最初のエクイティ記録	runs/cycles/equity.jsonl	日次損失上限の基準となる値
プロンプトに入力した内容	.tra-history	利便性のためのものにすぎません。tra -c では何も保存されません

コマンドライン

すべてのコマンドは、実行した内容を通知します。終了コード 0 はクリア、1 はゲートによる拒否、2 は使用方法のエラーを意味します。--json は機械可読な出力を返し、--plain はパネルの代わりにテキストを返します。

はじめに

コマンド	内容
tra	コンソールを開きます
tra init my-desk --profile autonomous	エージェント向けに設定されたプロジェクトを作成します。各ファイルにはコメントが付いています
tra check	すべての設定を相互に照合し、修正すべき内容を示します
tra keys --probe	すべてのキーが機能することを確認します。キーは出力されず、プロンプトや注文も送信されません
tra models groq	プロバイダーでキーを使って利用できるモデルを、ベンダーから取得します。プロンプトは送信されません
tra init my-desk --profile autonomous --venue okx	1 つの取引所向けに設定されたデスクを作成します。データ、注文、デモまたはテストネット API、キーが含まれます
tra venues	ドキュメントに記載されているすべての取引所と、それぞれができることを表示します
tra venues okx --setup	取引所でできることと、そこで取引するために貼り付ける設定ブロックを表示します
tra mandate	取引所モードで必要となるテキストを表示します。--sign "Your Name" を指定すると、これを MANDATE.md として保存し、[execution] に一度に署名します

実行

コマンド	内容
tra run	自律サイクルを 1 回実行します
tra run --every 15m --cycles 12	スケジュールに沿って 12 回実行します。最初は今すぐ、その後は時計の 15 分ごとに実行します
tra run --now	トリガーが静かな相場を見送る場合でも、ロスターに確認を求めます
tra watch --every 5s	実行中のデスクを読み取り専用で表示します
tra audit	2 つの監査ツールで記録を確認します。何も適用されません
tra backtest、tra paper、tra live	リプレイ、シャドー、カナリア

データ

コマンド	内容
tra data get BTCUSDT 2025-01-01	1 日分をダウンロードし、チェックサムを検証して監査し、Parquet とファンディングデータを書き込みます
tra data audit export.csv --mapping mapping.toml	独自の CSV または Parquet を、同じ監査に通します
tra data pull BTCUSDT	data.toml のチェーンを通じて、ライブスナップショットを 1 回取得します
tra sources show、tra sources pull	分析担当者が読み込む系列の取得元と、そのデータの古さを表示します。今すぐ更新することもできます
tra sources add macro us10y --from fred --id DGS10 --high bearish	系列を一度の操作で棚に追加します。今すぐ取得し、系列の境界線はその系列自身の履歴から描画します
tra universe	取引所で現在ディスカバリーが見つけたパーペチュアルと、各フィルターで除外された内容を表示します
tra runs verify	各サイクルのファイルをハッシュと照合し、ブリーフを未加工の入力データと照合します
tra runs prune --keep 90d	削除対象となる古いサイクルディレクトリを表示します。実際に削除するには --yes（および --archive）を追加します

ラダー、リサーチ、ホスト

コマンド	内容
tra ladder show、promote、demote	デスクがどのティアにいるかを表示します。証拠を添えて 1 段階上げるか、下げます
tra chain floor、observe、check、validate	リサーチチェーンをレイヤーごとに確認します（反証チェーン）
tra ledger show	消滅したすべてのアイデアと、それを消滅させた要因を表示します
tra agent session、eval、trace	リサーチセッション、モデルの比較、実行内容の読み返し
tra mcp serve	あらゆる MCP ホスト向けに、読み取り専用のゲートをツールとして提供します

保証されること、まだ実装されていないこと

一部のルールはシステムとテストによって適用される保証事項であり、変更を加える際も必ず維持する必要があります。

• モデルが注文や鍵に触れることはありません。 モデルは数値を読み取り、回答します。システムが数量、価格、上限を決定し、送信します。
• モデルが制御を緩めることはできません。 モデルは上限を厳しくしたり、段階的に引き下げたり、キルスイッチを作動させたりできますが、上限を広げたり、段階的に引き上げたり、解除したりすることはできません。
• 1つの判断につき、注文は最大1件です。 取引所でエラーが発生した場合は記録され、次のサイクルで再度判断します。実資金を使った処理で再試行することはありません。
• 古いデータや欠損データは拒否されます。 0や最新の値として読み取られることはありません。

ほかにも、まだ実装されていない機能があり、コントリビューションを歓迎します。インバース、期日付き先物、オプション、ccxt 以外のオンチェーン取引所、複数アカウント、資金移動と財務管理、ルーティングと執行アルゴリズム、ポートフォリオ会計などです。境界には、それぞれ現在できることと、コントリビューションに必要な内容が記載されています。戦略コアのサンプルはあくまで例です。ご自身のエッジは、ご自身で定義してください。

責任では、実資金を扱う際に誰が責任を負うのかを明確に説明しています。

今後の展開

このプロジェクトは現在も活発に開発されており、このページの説明は現時点の状況を示すもので、開発の終着点ではありません。

• より多くの市場タイプ。 現物、株式パーペチュアル、トークン化株式、予測市場は実装済みです。続いてインバース、期日付き先物、オプションを追加します。それぞれ独自のコストモデル、退出ルール、数量計算、テストを用意してから、取引所モードで利用可能にします。
• エンドツーエンドで稼働する取引所の拡充。 ccxt がサポートするすべての取引所は、すでに同じ注文経路とゲートを通ります。取引所テーブルの最後の列にある6つに加わるには、各取引所のデモ API またはテストネット API（当社またはお客様のもの）で完全な実行を行います。
• **未実装機能の残りも、**保証を損なうことなく、1つずつ追加します。

リリース版を使用してください。 PyPI からインストールできるのは最新リリースであり、実行するバージョンもこれです。リリースは master から作成されます。次のリリースの開発は develop ブランチで行われます。このブランチは頻繁に更新され、そこにあるコミットはリリースではありません。また、未完成の作業や、公開前に変更される作業が含まれる場合があります。変更一式は、master にマージされ、タグ付けされて公開されるとリリースになります。CHANGELOG.mdには、各リリースで追加された内容が記載されています。

ドキュメント

ドキュメントの全編はdocs.bijectivelabs.devにあります。ソースは docs/にあるため、動作の変更とそれを説明するページは同じプルリクエストに含めます。

こちらをお読みください	内容
このように構築した理由	対処するために構築した、出典付きの失敗事例と、構築を通じて得た知見
サイクル	サイクルの手順と、その動作を左右するすべての設定
エージェント	各役割が読み取るものと、エージェントがアクセスできるもの、できないもの
データソース	マクロ、オンチェーン、センチメントの各数値の取得元、取得方法、鮮度
資本、注文、ポジション	エクイティ、証拠金、レバレッジ、清算、日次損失、時間による決済、キルスイッチ、および記録される内容
取引所	対応している取引所と、独自の取引所を追加する方法
言語モデルの利用、モデルプロバイダー	モデルの利用方法：フォールバック、費用、プロバイダーの追加
ライブティア、トレーディングエージェント	リプレイからライブセッションまでの段階
独自のデータ、データゲート	CSV、JSON、Parquet形式で持ち込める取引履歴、時系列データ、ベンダーのフィードと、すべてのファイルに適用される検証
境界、責任	保証されること、未実装のこと、責任の所在
エージェント、MCP サーバー	リサーチエージェントとMCP サーバー
アーキテクチャ	パッケージ、インポート規則、ファイル形式
反証チェーン、実行のリアリズム、キル台帳	リサーチチェーン、実行のリアリズム、判定
コマンドライン	すべてのtraコマンド
CHANGELOG.md	変更内容

開発

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

CONTRIBUTING.mdには、ブランチ運用と、コードに適用される基準が記載されています。

このリポジトリの成り立ち

このリポジトリは2026年10月に公開されました。その歴史は、コードがBijectiveの社内作業から切り離された2026年9月12日に始まり、それ以降のすべてのコミット、タグ、コントリビューターがここに記録されています。基盤となるアイデアは、それよりも前からありました。反証チェーン、コストモデル、すべての注文に先立つ制御は、Bijectiveのリサーチと、このリポジトリが存在する前に構築していた取引プラットフォームに由来します。言語モデルエージェントは後から加わり、これらのゲートの上で動作するため、提案はできますが、サイズの決定、価格設定、送信は決してできません。

ライセンス

MIT。LICENSEをご覧ください。NOTICEには、このパッケージが基盤としているサードパーティソフトウェアが記載されています。

Bijective Labsが開発しました。