取引所のAPIキーを追加すると、Freyaは保存する前にキーを検証します — 問題があれば、何を直すべきかを教えてくれます。このガイドでは、その結果の読み方と対処法をご説明します。（キーの接続自体は成功したのに、後からボットが停止した場合は別の問題です — ボットが一時停止・停止したのはなぜ？をご覧ください。）
初回セットアップの手順については、まず取引所を接続する方法をご覧ください。この記事は、その接続が失敗したときに何をすべきかについて解説します。
要点
- キーを追加すると、Freyaは保存前に接続可否と権限が正しいかを検証します — 失敗した場合、エラーメッセージが何を直すべきかを示します。
- 「APIキー/シークレットが無効」は通常、コピー＆ペーストのミスか、キーが再生成されたことを意味します。「IP」関連のエラーは、キーのIP制限がFreyaの要件と一致していないことを意味します。
- キーには読み取り権限と取引権限（出金権限は絶対に不要）が必要で、ボットに合わせて正しい市場 — 現物または先物 — で有効になっている必要があります。
- OKXのキーにはパスフレーズが必要で、完全に一致していなければなりません。先物キーの場合、ボットが正しく取引できるようFreyaが自動でアカウントを準備します。
- 原因が示されない「接続に失敗しました」は、一時的なネットワークや取引所の不調であることが多く、もう一度お試しいただければ解決します。
キーが接続できないとき
キーの追加は、そのまま保存するだけの処理ではありません。Freyaはキーが機能し、正しい権限を持っていることを検証してから、暗号化して保存します。問題があれば、エラーは原因を直接指し示します — 多くの場合、キーかシークレット、IP制限、または不足している権限です。以下のセクションでは、各エラーとその修正方法を順にご説明します。
「APIキーが無効」または「シークレットキーが無効」
最も多い接続エラーであり、たいていは最も単純な原因です。
- コピー＆ペーストのミス — 余分なスペースが入っている、あるいは文字が抜けている。キーとシークレットの両方を慎重にコピーし直してください。
- シークレットは一度しか表示されません。 取引所はキーを作成した際に一度だけシークレットキーを表示します。保存していなければ復元できません — 新しいキーを作成してください。
- キーが取引所側で削除または再生成されたため、もう一致しなくなっている。
対処法： キーとシークレットを正確に入力し直すか、新しいキーを作成してもう一度お試しください。
IP制限のエラー
Freyaは自社のサーバーから接続するため、キーのIP設定が重要になります。ここには2つの異なるケースがあります。
- 「IPアドレスがホワイトリストに登録されていません」 — キーにIP制限がかかっているものの、Freyaのサーバーアドレスが許可リストに入っていません。APIキー追加画面に追加すべきIPアドレスが表示されます（コピーボタン付き） — それを取引所側でキーのホワイトリストに追加してください。
- 「制限なし」 — キーにIP制限がまったく設定されていません。安全のため、FreyaはIP制限を有効にして表示されたアドレスを追加してから、もう一度お試しいただくようお願いしています。
いずれの場合も、対処法の考え方は同じです。モーダルにFreyaが表示するIPにキーを制限してください。
権限のエラー
キーは接続できたものの、ボットが必要とする操作を実行できない状態です。
- 読み取りが無効 — キーの読み取り／閲覧権限を有効にしてください。
- 取引権限がない — 取引権限（ボットに合わせて現物および／または先物）を有効にしてください。
- 現物と先物の不一致 — 先物ボットには先物取引が有効なキーが、現物ボットには現物取引が有効なキーが必要です。先物ボットに現物専用のキーを追加した場合（またはその逆）、Freyaがそれを検知して知らせます。キーで有効になっている市場が、構築しようとしているボットと一致していることをご確認ください。
覚えておいてください：Freyaが必要とするのは読み取りと取引の権限だけです — 出金権限は決して必要ありません。出金権限のないキーこそが、まさに望ましい状態です。
取引所ごとの注意点
- OKXにはパスフレーズが必要です。 OKXでキーを作成する際にパスフレーズを設定します — 設定したものとまったく同じパスフレーズをFreyaに入力してください。パスフレーズの誤りは、OKXでよくある接続失敗の原因です。
- OKXの先物セットアップ。 OKXの先物取引には特定のアカウントモードが必要ですが、Freyaが自動で設定します — 手動で構成する必要はありません。
- ヘッジモード（先物）。 Freyaは先物アカウントでヘッジモードを使用します。すでに競合する一方向（ワンウェイ）ポジションを保有している場合、失敗ではなく警告が表示されることがあります — キーは保存され、既存のポジションを決済すればボットは取引できるようになります。
- BinanceとBybitはパスフレーズを使用しないため、パスフレーズの入力欄はありません。
明確な原因が示されない「接続に失敗しました」
原因が示されない接続失敗は、あなたのせいではないことがよくあります — 一時的なネットワークの不調や、取引所が一時的に混雑しているだけです。少し待ってからもう一度お試しください。数回試しても失敗が続く場合は、上記のキー／シークレットとIP設定を改めてご確認ください。
それでも解決しない場合：かんたんチェックリスト
- キーを作り直す — 取引所で読み取り＋取引のみ（出金権限は決して付けない）で作成する。
- IPに制限をかける — APIキー追加画面にFreyaが表示するIPに制限する。
- 市場を合わせる — 現物ボットには現物キー、先物ボットには先物キー。
- OKX： パスフレーズを正確に入力する。
- それでも失敗する場合は、[email protected] までご連絡ください。
よくある質問
正しくコピーしたはずなのにFreyaが「APIキーが無効」と表示します — 何が問題ですか？
たいていの場合、キーかシークレットに見えない文字やスペースが紛れ込んでいるか、取引所側でキーが再生成・削除されて一致しなくなっています。両方の項目を慎重にコピーし直してください。またシークレットは作成時に一度しか表示されないことをお忘れなく — 手元にない場合は、新しいキーを作成してください。
「IPアドレスがホワイトリストに登録されていません」と「制限なし」の違いは何ですか？
「IPアドレスがホワイトリストに登録されていません」は、キーにIP制限がかかっているものの、Freyaのサーバーアドレスがまだ許可されていない状態です — Freyaが表示するアドレスをキーのホワイトリストに追加してください。「制限なし」は、キーにIP制限がまったくない状態です。安全のため、Freyaは保存前にIP制限を有効にして、表示されるアドレスを追加していただくようお願いしています。
OKXのキーが接続できません — パスフレーズは必要ですか？
はい。OKXのキーには、作成時に設定するパスフレーズがあります。そのパスフレーズをFreyaに正確に入力する必要があります — パスフレーズの誤りや未入力は、OKXでよくある接続失敗の原因です。BinanceとBybitではパスフレーズは使用しません。
Freyaが「キーで取引を発注できない」と表示します — どう直せばよいですか？
ボットが使用する市場に対して、キーの取引権限が有効になっていません。取引所で取引権限を有効にしてください — 現物ボットなら現物取引、先物ボットなら先物取引です — そのうえで再接続してください。Freyaに必要なのは読み取りと取引の権限であり、出金権限は決して必要ありません。
先物キーに追加のセットアップ（アカウントモード／ヘッジモード）が必要と出ました — 問題ですか？
いいえ。先物取引には特定のアカウントモードとヘッジモードが必要ですが、Freyaが自動で設定します。既存の一方向ポジションがある場合は、エラーではなくヘッジモードの警告が表示されることがあります — キーは保存され、それらのポジションを決済すればボットは取引できるようになります。
現物キーを追加したのに先物ボットが使ってくれません（またはその逆）— なぜですか？
キーは特定の市場に対して有効になっています。先物ボットには先物取引が有効なキーが、現物ボットには現物取引が有効なキーが必要です。これらが一致しない場合、Freyaがそれを検知して知らせます。作成しようとしているボットと、有効な市場が一致するキーを接続してください。
明確な原因もなく接続が「失敗」しました — 私の問題ですか、取引所の問題ですか？
多くの場合、設定の問題ではなく、一時的なネットワークや取引所の不調です。少し待ってからもう一度お試しください。それでも失敗が続く場合は、キーとシークレットにコピーミスがないか確認し、IP制限がFreyaの表示するアドレスと一致していることをご確認ください。