봇이 대신 거래하려면 먼저 Freya가 자금이 있는 거래소 — Binance, OKX, Bybit — 에 연결되어야 합니다. 이를 위해 자금을 옮기거나 거래소 비밀번호를 공유할 필요는 없습니다. 대신 API 키를 발급합니다. API 키는 Freya가 사용자를 대신해 주문을 넣을 수 있게 해주는 제한된 자격 증명이며, 자금은 사용자 본인의 거래소 계정에 그대로 머무릅니다.
이 가이드에서는 어떤 권한을 부여해야 하는지(그리고 절대 부여하면 안 되는 권한은 무엇인지), 키를 Freya에 추가하는 방법, 연결이 검증되지 않을 때 어떻게 해야 하는지를 정확히 설명합니다. 이것이 왜 안전한지 큰 그림을 먼저 이해하고 싶다면 Freya Finance에서 내 자금은 안전한가요?를 먼저 읽어보세요.
핵심 요약
- 거래소 연결은 자금을 옮기거나 거래소 비밀번호를 공유하는 것이 아니라, 제한된 자격 증명인 API 키로 이루어집니다.
- 키에는 읽기 권한과 현물 및/또는 선물 거래 권한이 필요합니다. 출금 권한은 절대 부여해서는 안 됩니다.
- OKX 키는 생성 시 직접 설정하는 패스프레이즈가 필요합니다. Binance와 Bybit는 필요하지 않습니다.
- Freya에서 설정 → API 키 → API 키 추가 경로로 키를 등록하면 Freya가 즉시 검증합니다.
- 검증에 실패하면 Freya가 그 이유를 정확히 알려줍니다 — 유효하지 않은 키, 화이트리스트에 없는 IP, 누락된 권한 — 각각 간단한 해결책이 있습니다.
전체 단계 한눈에 보기
- 거래소에서 API 키를 생성합니다 — 읽기와 거래 권한은 부여하되, 출금 권한은 부여하지 않습니다.
- 자격 증명을 복사합니다 — API 키, 시크릿, 그리고 (OKX의 경우) 패스프레이즈.
- Freya에 키를 추가합니다 — 설정 → API 키 → API 키 추가 경로로 이동해 거래소를 선택합니다.
- Freya가 검증하도록 둡니다 — Freya가 연결과 권한을 즉시 확인합니다.
- 오류가 보고되면 수정합니다 — 검증에 실패하면 Freya가 무엇이 잘못되었는지 정확히 알려줍니다.
API 키란 무엇이며 — Freya에는 어떤 권한이 필요한가
API 키는 하나의 애플리케이션이 제한된 방식으로 거래소 계정과 통신할 수 있게 해주는 자격 증명 쌍(키와 시크릿)입니다. 그 키가 무엇을 할 수 있는지는 사용자가 직접 결정합니다. Freya에는 다음 권한만 활성화하세요.
- 읽기 권한 — Freya가 잔액, 포지션, 주문 상태를 확인할 수 있도록 합니다.
- 현물 거래 및/또는 선물 거래 — 봇이 필요한 주문을 넣을 수 있도록 합니다. 운영할 봇에 맞는 유형을 활성화하세요.
Freya는 주문을 넣을 뿐, 계정에서 자금을 옮길 필요가 전혀 없습니다. 연결하는 키에서 출금 권한은 항상 비활성화 상태로 두세요. 이는 거래소에서 사용자가 직접 통제하는 권한입니다. 이 권한이 꺼져 있으면 Freya도, 혹시라도 그 키를 입수한 누군가도 자금을 출금할 수 없습니다. 어떤 봇 플랫폼을 연결하든 가장 중요한 습관입니다.
1단계: 거래소에서 API 키 생성하기
거래소의 API 관리 메뉴에서 새 API 키를 생성하세요.
- Binance — API Management에서 키를 생성하고, 읽기와 현물 및/또는 선물 거래를 활성화하되 출금은 꺼둡니다.
- OKX — 키를 생성하면서 패스프레이즈를 설정하세요(Freya에서 입력해야 합니다). 읽기와 거래는 활성화하고, 출금은 활성화하지 않습니다.
- Bybit — 사용할 상품에 맞춰 읽기와 거래 권한으로 키를 생성하고, 출금은 꺼둡니다.
거래소가 IP 화이트리스트를 지원한다면 키를 Freya의 IP 주소로 제한하는 것이 좋은 습관입니다. 다만 이 경우 Freya의 IP를 반드시 화이트리스트에 등록해야 하며, 그렇지 않으면 연결이 거부됩니다(아래 오류 표 참조).
키를 생성할 때 거래소는 시크릿을 딱 한 번만 보여줍니다. 즉시 복사해 안전하게 보관하세요. 분실하면 복구할 수 없으며, 키를 삭제하고 새로 생성해야 합니다.
2단계: Freya에 키 추가하기
Freya에서 설정 → API 키로 이동해 API 키 추가를 선택하세요. 그런 다음:
- 거래소를 선택합니다 (Binance, OKX, Bybit).
- API 키와 시크릿을 붙여넣습니다. OKX의 경우 직접 설정한 패스프레이즈도 입력합니다.
- 키에 이름을 지정합니다 — 나중에 알아볼 수 있도록 합니다.
여러 거래소를 연결할 수 있으며, 언제든지 같은 페이지에서 키를 관리하거나 삭제할 수 있습니다.
3단계: Freya가 키를 검증합니다
키를 추가하는 즉시 Freya가 연결과 권한을 확인합니다 — 추측할 필요가 없습니다. 모든 것이 올바르면 키가 검증되어 바로 사용할 수 있습니다. 문제가 있으면 Freya가 무엇을 고쳐야 하는지 명확한 메시지로 알려줍니다.
검증 오류 이해하기
검증에 실패하면 Freya가 표시하는 메시지를 아래 해결책과 대조해 보세요.
| Freya가 표시하는 내용 | 의미 | 해결 방법 |
|---|---|---|
| 유효하지 않은 API 키 | 키가 잘못 복사되었거나 거래소에서 삭제됨 | API 키를 정확히 다시 복사하거나 새로 생성하세요 |
| 유효하지 않은 시크릿 키 | 시크릿이 키와 일치하지 않음 | 시크릿을 다시 복사하세요. 분실했다면 새 키를 생성하세요 |
| IP 주소가 화이트리스트에 없음 | 키에 IP 제한이 걸려 있고 Freya의 주소가 허용되지 않음 | 키에 Freya의 IP를 화이트리스트로 등록하거나 IP 제한을 해제하세요 |
| 권한 누락 | 키에 읽기 또는 거래 권한이 없음 | 키에서 읽기와 현물/선물 거래를 활성화하세요 |
| 읽기 권한 비활성화됨 | Freya가 계정을 읽을 수 없음 | 키에서 읽기/조회 권한을 활성화하세요 |
| 현물/선물 권한 비활성화됨 | 키가 봇에 필요한 주문을 넣을 수 없음 | 봇에 맞는 거래 유형(현물 또는 선물)을 활성화하세요 |
| 연결 실패 | 일시적인 네트워크 또는 거래소 문제 | 잠시 후 키를 다시 추가해 보세요 |
Freya는 “제한 없음” 모드로 설정된 키, 즉 IP 제한이 없는 키도 표시합니다. 보안을 위해 Freya는 키를 저장하기 전에 IP 제한을 켜고 화면에 표시된 주소를 추가하도록 요청합니다. 읽기와 거래만 활성화하고(출금은 절대 안 됩니다), 키를 Freya의 IP로 제한하세요. (연결 오류에 대한 자세한 내용은 거래소 연결이 안 되나요?를 참조하세요.)
보안에 관한 참고 사항
이 연결은 설계상 안전하지만, 몇 가지 습관이 그 상태를 유지해 줍니다.
- 출금은 항상 끄기 — Freya에는 전혀 필요하지 않습니다.
- IP 화이트리스트 사용하기 — 거래소가 지원한다면 활용하세요.
- 하나의 키에 하나의 용도 — 그리고 더 이상 사용하지 않는 키는 삭제하세요.
자금과 키가 어떻게 보호되는지 전체 그림을 보려면 Freya Finance에서 내 자금은 안전한가요?와 거래소 API 보안 및 리스크 완화를 참조하세요.
자주 묻는 질문
Freya는 내 API 키에 어떤 권한이 필요한가요?
읽기 권한(잔액, 포지션, 주문을 확인하기 위해)과 현물 및/또는 선물 거래 권한(봇의 주문을 넣기 위해)입니다. 운영할 봇에 맞는 거래 유형을 활성화하세요. Freya에는 출금 권한이 전혀 필요하지 않으므로 항상 비활성화 상태로 두세요.
Freya가 내 자금을 출금할 권한이 필요한가요?
아니요. Freya는 거래를 넣고 관리할 뿐이며, 거래소에서 자금을 옮길 수 없고 그럴 수 있어서도 안 됩니다. 연결하는 키에서 출금 권한은 항상 꺼두세요 — 이는 거래소에서 사용자가 직접 통제하는 권한입니다.
Freya가 왜 “IP 주소가 화이트리스트에 없음”이라고 표시하나요?
API 키가 특정 IP 주소로 제한되어 있는데 Freya의 주소가 목록에 없기 때문입니다. 거래소에서 키의 화이트리스트에 Freya의 IP 주소를 추가하거나, 키의 IP 제한을 해제하세요. 수정한 뒤 Freya에서 키를 다시 추가하면 됩니다.
왜 “유효하지 않은 API 키” 또는 “유효하지 않은 시크릿 키”라고 표시되나요?
대개 키나 시크릿이 잘못 복사되었거나, 거래소에서 키가 삭제 또는 재발급되었기 때문입니다. 두 값을 정확히 다시 복사하세요. 시크릿은 키를 생성할 때 단 한 번만 표시되므로, 더 이상 가지고 있지 않다면 거래소에서 키를 삭제하고 새로 생성하세요.
패스프레이즈란 무엇이며, OKX는 왜 요구하나요?
OKX API 키에는 키를 생성할 때 사용자가 직접 설정하는 패스프레이즈가 포함됩니다 — 키와 시크릿에 더해지는 추가 자격 증명입니다. OKX 키를 추가할 때 Freya에 동일한 패스프레이즈를 입력하세요. Binance와 Bybit는 패스프레이즈를 사용하지 않습니다.
거래소를 두 개 이상 연결할 수 있나요?
네. Binance, OKX, Bybit의 API 키를 추가할 수 있으며, 설정 → API 키에서 언제든지 관리하거나 삭제할 수 있습니다.
Freya에 내 API 키를 제공해도 안전한가요?
키를 올바르게 설정했다면 그렇습니다 — 읽기와 거래만 허용하고, 출금은 허용하지 않으며, 가능한 경우 IP 화이트리스트를 적용하세요. 자금은 본인의 거래소에 그대로 머무르며, 공유하는 키로는 자금을 옮길 수 없습니다. 자세한 설명은 Freya Finance에서 내 자금은 안전한가요?를 참조하세요.
Freya는 어떤 거래소를 지원하나요?
Freya는 현재 Binance, OKX, Bybit(현물 및 선물)에 연결됩니다. 시간이 지나면서 더 많은 거래소가 추가될 수 있습니다. 연결한 거래소에서 거래하게 되며, 자금과 이용 가능한 시장은 해당 거래소에 그대로 남아 있습니다.
어떤 코인이나 거래쌍을 거래할 수 있나요?
이용 가능한 거래쌍은 Freya의 별도 목록이 아니라 연결된 거래소 자체의 상장 목록에서 가져옵니다 — 따라서 거래소에 어떤 거래쌍(예: BTC/USDT, ETH/USDT)이 상장되어 있다면 그 위에 봇을 만들 수 있습니다. 대부분의 거래는 USDT를 기준 통화로 이루어집니다. 거래소가 거래쌍을 상장 폐지하면 해당 거래소에서는 더 이상 거래할 수 없게 됩니다.