거래소 API 키를 추가하면 Freya는 저장하기 전에 키를 검증합니다 — 문제가 있으면 무엇을 고쳐야 하는지 알려줍니다. 이 가이드는 그 결과를 읽고 문제를 해결하는 방법을 안내합니다. (키는 정상적으로 연결되었는데 이후에 봇이 멈춘 경우라면 다른 문제입니다 — 봇이 왜 일시정지되거나 중지되었나요?를 참조하세요.)
처음 설정하는 단계는 거래소 연결 방법부터 시작하세요. 이 글은 그 연결이 실패했을 때 무엇을 해야 하는지에 관한 내용입니다.
핵심 요약
- 키를 추가하면 Freya는 저장하기 전에 연결 여부와 올바른 권한 보유 여부를 검증합니다 — 실패하면 오류 메시지가 무엇을 고쳐야 하는지 알려줍니다.
- “유효하지 않은 API 키/시크릿”은 대개 복사·붙여넣기 실수이거나 재생성된 키를 의미합니다. “IP” 오류는 키의 IP 제한이 Freya가 필요로 하는 설정과 맞지 않는다는 뜻입니다.
- 키에는 읽기와 거래 권한이 있어야 하며(출금 권한은 절대 안 됩니다), 봇에 맞는 시장 — 현물 또는 선물 — 이 활성화되어 있어야 합니다.
- OKX 키에는 정확히 일치해야 하는 패스프레이즈가 필요합니다. 선물 키의 경우 Freya가 봇이 올바르게 거래할 수 있도록 계정을 자동으로 준비해 줍니다.
- 원인이 불분명한 “연결 실패”는 대개 일시적인 네트워크나 거래소 문제입니다 — 다시 시도해 보세요.
키가 연결되지 않을 때
키 추가는 무작정 저장하는 과정이 아닙니다. Freya는 키가 작동하고 올바른 권한을 가지고 있는지 검증한 뒤에야 암호화하여 보관합니다. 문제가 있으면 오류 메시지가 원인을 곧바로 짚어줍니다 — 대개 키나 시크릿, IP 제한, 또는 누락된 권한입니다. 아래 섹션에서 각 오류와 해결 방법을 하나씩 살펴봅니다.
“유효하지 않은 API 키” 또는 “유효하지 않은 시크릿 키”
가장 흔한 연결 오류이며, 보통 가장 단순합니다.
- 복사·붙여넣기 실수 — 공백이 끼어들었거나 문자가 하나 빠진 경우입니다. 키와 시크릿을 모두 다시 꼼꼼히 복사하세요.
- 시크릿은 단 한 번만 표시됩니다. 거래소는 키를 생성할 때 시크릿 키를 한 번만 보여줍니다. 저장해 두지 않았다면 복구할 수 없으니 새 키를 만드세요.
- 거래소에서 키가 삭제되었거나 재생성된 경우 — 더 이상 일치하지 않습니다.
해결: 키와 시크릿을 정확히 다시 입력하거나, 새 키를 만들어 다시 시도하세요.
IP 제한 오류
Freya는 자체 서버에서 연결하기 때문에 키의 IP 설정이 중요합니다. 두 가지 경우가 있습니다.
- “IP 주소가 화이트리스트에 없음” — 키에 IP 제한이 걸려 있지만 Freya의 서버 주소가 허용 목록에 없는 경우입니다. API 키 추가 화면에 추가해야 할 IP 주소가 표시됩니다(복사 버튼 포함) — 거래소에서 해당 키의 화이트리스트에 추가하세요.
- “제한 없음” — 키에 IP 제한이 전혀 없는 경우입니다. 안전을 위해 Freya는 IP 제한을 켜고 표시된 주소를 추가한 뒤 다시 시도하도록 요청합니다.
두 경우 모두 해결의 핵심은 같습니다. 모달에 표시된 Freya의 IP로 키를 제한하는 것입니다.
권한 오류
키는 연결되었지만 봇에 필요한 작업을 수행할 수 없는 경우입니다.
- 읽기 비활성화 — 키에 읽기/조회 권한을 활성화하세요.
- 거래 권한 누락 — 거래 권한을 활성화하세요(봇에 맞게 현물 및/또는 선물).
- 현물과 선물 불일치 — 선물 봇에는 선물 거래가 활성화된 키가 필요하고, 현물 봇에는 현물 거래가 필요합니다. 선물 봇에 현물 전용 키를 추가했다면(또는 그 반대라면) Freya가 이를 알려줍니다. 키에 활성화된 시장이 만들려는 봇과 일치하는지 확인하세요.
기억하세요. Freya에게 필요한 것은 읽기와 거래 권한뿐이며, 출금 권한은 절대 필요하지 않습니다. 출금 권한이 없는 키야말로 바람직한 키입니다.
거래소별 주의사항
- OKX에는 패스프레이즈가 필요합니다. OKX 키를 생성할 때 패스프레이즈를 설정하는데, 설정한 것과 똑같이 Freya에 입력해야 합니다. 잘못된 패스프레이즈는 OKX 연결 실패의 흔한 원인입니다.
- OKX 선물 설정. OKX 선물 거래에는 특정 계정 모드가 필요한데, Freya가 자동으로 설정해 줍니다 — 직접 구성할 필요가 없습니다.
- 헤지 모드(선물). Freya는 선물 계정에 헤지 모드를 사용합니다. 이미 충돌하는 One-Way 포지션이 열려 있다면 실패가 아니라 경고가 표시될 수 있습니다 — 키는 그대로 저장되며, 기존 포지션이 종료되면 봇이 거래할 수 있습니다.
- Binance와 Bybit는 패스프레이즈를 사용하지 않습니다 — 해당 입력란 자체가 없습니다.
원인이 불분명한 “연결 실패”
원인이 명확하지 않은 연결 실패는 당신의 잘못이 아닌 경우가 많습니다 — 일시적인 네트워크 문제이거나 거래소가 잠시 바쁜 상태일 수 있습니다. 잠시 기다렸다가 다시 시도하세요. 몇 번 시도해도 계속 실패한다면 위에서 설명한 키/시크릿과 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가 자동으로 설정해 줍니다. 기존 One-Way 포지션이 있다면 오류 대신 헤지 모드 경고가 표시될 수 있습니다 — 키는 그대로 저장되며, 해당 포지션이 종료되면 봇이 거래할 수 있습니다.
현물 키를 추가했는데 선물 봇이 사용하지 않습니다(또는 그 반대) — 왜 그런가요?
키는 특정 시장에 대해 활성화됩니다. 선물 봇에는 선물 거래가 활성화된 키가 필요하고, 현물 봇에는 현물 거래가 필요합니다. 서로 맞지 않으면 Freya가 이를 알려줍니다. 만들려는 봇과 활성화된 시장이 일치하는 키를 연결하세요.
뚜렷한 이유 없이 그냥 “실패”했습니다 — 제 문제인가요, 거래소 문제인가요?
설정 문제라기보다 일시적인 네트워크나 거래소 문제인 경우가 많습니다. 잠시 후 다시 시도하세요. 계속 실패한다면 키와 시크릿에 복사 오류가 없는지 다시 확인하고, IP 제한이 Freya가 표시하는 주소와 일치하는지 확인하세요.