Khi bạn thêm một API key exchange, Freya sẽ kiểm tra nó trước khi lưu — và nếu có gì đó không ổn, nó sẽ cho bạn biết cần sửa gì. Hướng dẫn này giúp bạn đọc kết quả đó và khắc phục. (Nếu key của bạn đã kết nối tốt nhưng sau đó một bot ngừng lại, đó là một vấn đề khác — xem Vì sao Bot của Tôi Tạm dừng hoặc Dừng lại?.)
Đối với các bước thiết lập lần đầu, hãy bắt đầu với Cách Kết nối Exchange của Bạn; bài viết này nói về việc phải làm gì khi kết nối đó thất bại.
Điểm chính
- Khi bạn thêm một key, Freya kiểm tra rằng nó kết nối được và có đúng quyền hạn trước khi lưu — nếu có gì đó thất bại, thông báo lỗi sẽ cho bạn biết cần sửa gì.
- “Invalid API Key/Secret” thường có nghĩa là lỗi copy/paste hoặc key đã bị tạo lại; lỗi “IP” nghĩa là hạn chế IP của key không khớp với những gì Freya cần.
- Key của bạn phải có quyền đọc và trade (không bao giờ có quyền rút tiền) và được bật cho đúng thị trường — spot hoặc futures — để khớp với bot của bạn.
- Key OKX cần một passphrase phải khớp chính xác; đối với key futures, Freya tự động chuẩn bị tài khoản của bạn để bot có thể trading đúng cách.
- Lỗi chung chung “Connection Failed” thường chỉ là trục trặc mạng hoặc exchange nhất thời — chỉ cần thử lại.
Khi một Key Không chịu Kết nối
Thêm một key không phải là lưu một cách mù quáng — Freya xác minh rằng key hoạt động và có đúng quyền hạn trước khi nó được lưu trữ, mã hóa. Nếu có gì đó không ổn, thông báo lỗi sẽ chỉ thẳng cho bạn nguyên nhân — thường là key hoặc secret, hạn chế IP, hoặc một quyền còn thiếu. Các phần dưới đây sẽ đi qua từng lỗi và cách khắc phục.
"Invalid API Key" hoặc "Invalid Secret Key"
Lỗi kết nối phổ biến nhất, và thường là đơn giản nhất:
- Lỗi copy/paste — một khoảng trắng dư thừa hoặc một ký tự bị thiếu. Hãy copy lại cẩn thận cả key lẫn secret.
- Secret chỉ hiển thị một lần duy nhất. Exchange chỉ để lộ secret key một lần khi bạn tạo nó. Nếu bạn không lưu lại, bạn không thể khôi phục — hãy tạo một key mới.
- Key đã bị xóa hoặc tạo lại trên exchange, nên nó không còn khớp nữa.
Cách sửa: nhập lại chính xác key và secret, hoặc tạo một key mới rồi thử lại.
Lỗi Hạn chế IP
Freya kết nối từ máy chủ của riêng nó, nên cài đặt IP của key rất quan trọng. Có hai trường hợp khác biệt:
- "IP Not Whitelisted" — key của bạn bị hạn chế IP, nhưng địa chỉ máy chủ của Freya chưa nằm trong danh sách cho phép của nó. Màn hình Thêm API Key hiển thị cho bạn (các) địa chỉ IP cần thêm (kèm nút copy) — hãy thêm chúng vào whitelist của key trên exchange.
- "Unrestricted" — key của bạn hoàn toàn không có hạn chế IP nào. Vì sự an toàn của bạn, Freya yêu cầu bạn bật hạn chế IP và thêm địa chỉ mà nó hiển thị, rồi thử lại.
Trong cả hai trường hợp, cách khắc phục cùng chung một ý tưởng: hạn chế key vào đúng IP mà Freya hiển thị trong modal.
Lỗi Quyền hạn
Key đã kết nối được, nhưng nó không thể làm điều mà bot của bạn cần:
- Quyền đọc bị tắt — hãy bật quyền đọc/xem trên key.
- Thiếu quyền trade — hãy bật trading (spot và/hoặc futures, khớp với bot của bạn).
- Không khớp Spot với Futures — một bot futures cần một key được bật trading futures; một bot spot cần trading spot. Nếu bạn thêm một key chỉ có spot cho một bot futures (hoặc ngược lại), Freya sẽ gắn cờ báo. Hãy đảm bảo thị trường được bật của key khớp với bot bạn đang xây dựng.
Hãy nhớ: Freya chỉ bao giờ cần các quyền đọc và trade — không bao giờ có quyền rút tiền. Một key không có quyền rút tiền chính xác là điều bạn muốn.
Những Điểm Cần Lưu ý Riêng theo Từng Exchange
- OKX cần một passphrase. Khi bạn tạo một key OKX, bạn đặt một passphrase — hãy nhập đúng passphrase đó vào Freya, chính xác như bạn đã đặt. Passphrase sai là một nguyên nhân thất bại kết nối phổ biến của OKX.
- Thiết lập futures OKX. Trading futures của OKX cần một chế độ tài khoản cụ thể, mà Freya thiết lập cho bạn tự động — bạn không cần cấu hình nó thủ công.
- Hedge mode (futures). Freya sử dụng hedge mode cho các tài khoản futures. Nếu bạn đã có các vị thế one-way mở đang xung đột, bạn có thể thấy một cảnh báo thay vì một lỗi — key vẫn được lưu, và bot của bạn có thể trading một khi các vị thế hiện có đó được đóng.
- Binance và Bybit không dùng passphrase — không có trường passphrase cho chúng.
"Connection Failed" Không có Lý do Rõ ràng
Một lỗi kết nối chung chung thường không phải lỗi của bạn — chỉ là một trục trặc mạng nhất thời hoặc exchange đang bận trong chốc lát. Hãy chờ một lát và thử lại. Nếu nó vẫn liên tục thất bại sau vài lần thử, hãy kiểm tra lại key/secret và cài đặt IP ở trên.
Vẫn Bế tắc? Một Danh sách Kiểm tra Nhanh
- Tạo lại key trên exchange chỉ với read + trade (không bao giờ có quyền rút tiền).
- Hạn chế nó vào đúng IP mà Freya hiển thị trong màn hình Thêm API Key.
- Khớp thị trường — key spot cho bot spot, key futures cho bot futures.
- OKX: nhập chính xác passphrase.
- Vẫn thất bại? Liên hệ [email protected].
Các Câu hỏi Thường gặp
Freya báo "Invalid API Key" nhưng tôi chắc chắn đã copy đúng — có gì sai vậy?
Thường là một ký tự ẩn hoặc khoảng trắng đã lọt vào key hoặc secret, hoặc key đã bị tạo lại/xóa trên exchange nên nó không còn khớp nữa. Hãy copy lại cẩn thận cả hai trường, và nhớ rằng secret chỉ được hiển thị một lần lúc tạo — nếu bạn không có nó, hãy tạo một key mới.
Sự khác biệt giữa "IP Not Whitelisted" và "Unrestricted" là gì?
"IP Not Whitelisted" nghĩa là key của bạn bị hạn chế IP nhưng địa chỉ máy chủ của Freya chưa được cho phép — hãy thêm địa chỉ mà Freya hiển thị vào whitelist của key. "Unrestricted" nghĩa là key hoàn toàn không có hạn chế IP nào; vì sự an toàn, Freya yêu cầu bạn bật hạn chế IP và thêm địa chỉ của nó trước khi lưu.
Key OKX của tôi không chịu kết nối — tôi có cần passphrase không?
Có. Key OKX có một passphrase mà bạn đặt khi tạo key. Bạn phải nhập chính xác passphrase đó vào Freya — một passphrase sai hoặc thiếu là nguyên nhân thất bại kết nối phổ biến của OKX. Binance và Bybit không dùng passphrase.
Freya báo key của tôi không thể đặt lệnh trade — tôi khắc phục thế nào?
Key của bạn chưa được bật trading cho thị trường mà bot của bạn sử dụng. Trên exchange, hãy bật quyền trade — trading spot cho một bot spot, trading futures cho một bot futures — rồi kết nối lại. Freya cần các quyền đọc và trade, không bao giờ có quyền rút tiền.
Key futures của tôi cần thiết lập thêm (chế độ tài khoản / hedge mode) — có phải vấn đề không?
Không. Trading futures cần một chế độ tài khoản và hedge mode cụ thể, mà Freya thiết lập cho bạn tự động. Nếu bạn có các vị thế one-way hiện có, bạn có thể thấy một cảnh báo hedge-mode thay vì một lỗi — key vẫn được lưu, và bot của bạn có thể trading một khi các vị thế đó được đóng.
Tôi đã thêm một key spot nhưng bot futures của tôi không dùng nó (hoặc ngược lại) — tại sao?
Một key được bật cho một thị trường cụ thể. Một bot futures cần một key được bật trading futures, và một bot spot cần trading spot. Nếu chúng không khớp, Freya sẽ gắn cờ báo. Hãy kết nối một key có thị trường được bật khớp với bot bạn đang tạo.
Kết nối chỉ đơn giản "thất bại" mà không có lý do rõ ràng — là lỗi của tôi hay của exchange?
Thường đó là một trục trặc mạng hoặc exchange nhất thời chứ không phải cài đặt của bạn. Hãy thử lại sau một lát. Nếu nó vẫn liên tục thất bại, hãy kiểm tra lại key và secret xem có lỗi copy không và xác nhận hạn chế IP khớp với địa chỉ mà Freya hiển thị.