Add Exchange API
API Keys connect your exchange account to CopySonar. Live copy trading requires an API Key that has passed all permission checks; paper copy does not require any key binding. The current interface supports Binance and OKX; available scope is determined by your account page.
Binding an API Key deserves careful attention: Key permissions dictate what CopySonar can do in your account, and also define what an unauthorized party could do in the event of a leak. This page covers the four steps — Create, Authorize, Bind, and Revoke — with checkpoints for each.
Before Binding: Confirm Whether You Truly Need It
| Your Current Goal | Need to Bind a Key? |
|---|---|
| Browsing signal rankings, radar, and reports | No |
| Creating paper copy tasks | No |
| Creating live copy tasks | Yes, and must pass permission verification |
| Just want to preview parameter inputs | No, paper mode also runs full pre-flight checks |
If the page indicates "The current deployment is paper-only", the host has disabled live trading. In this case, binding is neither required nor possible. Such notices reflect server policy, not an issue with your account.
Creating a Key on the Exchange
Create a dedicated API Key for CopySonar inside your official exchange account's API Management console. Navigation paths and labels may change with exchange updates; follow their current official UI. Keep your API Key and Secret safe; OKX also requires the Passphrase created at key generation.
Never copy these credentials into chat apps, support tickets, screenshots, or code repositories. This documentation does not provide real credential examples.
General Steps
- Log in to the official exchange website and go to "API Management". Only access via the official site or official app; do not click search ads or third-party links.
- Create a new API Key and give it a recognizable label (e.g.
copysonar-main). The label will appear in CopySonar's key list for easy identification. - In permission settings, only check Read and Futures Trading. Leave Withdrawal, Universal Transfer, and Internal Transfer strictly unchecked.
- Set IP whitelisting to only the platform egress IP shown on CopySonar's binding form. Never leave IP restrictions blank, and never enter
0.0.0.0/0. - Complete exchange security verification (email, SMS, authenticator, or Passkey), then immediately paste the Key and Secret (plus Passphrase for OKX) into the CopySonar form.
Critical Point: Secret and Passphrase are often only displayed in full once upon creation. Paste them immediately; do not save screenshots in photo albums or chat histories.
Differences Between the Two Exchanges
| Item | Binance (USDⓈ-M Futures) | OKX (Perpetual Futures) |
|---|---|---|
| Required Fields | API Key + Secret | API Key + Secret + Passphrase |
| Permission Labels | Enable Reading, Enable Futures | Read, Trade |
| Withdrawal Switches | "Enable Withdrawals" must be OFF | "Withdrawal" must be OFF |
| Transfer Switches | "Enable Universal Transfer" & "Enable Internal Transfer" must be OFF | "Transfer" must be OFF |
| Position Mode | Hedge Mode (dual-side) | Hedge Mode (dual-side) |
| IP Whitelist | Mandatory | Mandatory |
The Passphrase is a passphrase you set yourself during key creation, not your account login password, nor your 2FA code. If you forget your Passphrase, it cannot be recovered; you must delete the Key on the exchange and create a new one.
TODO 素材：此处补「交易所 API 创建入口及用途选择，不展示任何凭据」截图
Permissions & IP Whitelisting
Enable only Read and Futures Trading permissions; disable withdrawals, universal transfers, and internal transfers. Enable IP restrictions and only input the platform egress IP shown on the management page after signing in; do not guess or reuse outdated addresses.
The server validates permissions upon binding. Keys with non-compliant permissions are rejected. If you modify permissions or IP settings on the exchange, return to CopySonar to re-verify status.
Permission Comparison Matrix
The platform checks each switch below. Any violation will reject binding with an explicit notice:
| Check Item | Required State | Meaning of Failure Notice |
|---|---|---|
| Read Permission | Enabled | Without read access, balance and position sizing cannot be calculated |
| Futures Trading | Enabled | Without futures trading, orders cannot be placed; live trading blocked |
| Withdrawal | Disabled | Enabling withdrawals grants fund egress to a third party; strictly rejected |
| Universal Transfer | Disabled | Allows moving funds between sub-wallets; risk is equivalent to withdrawal |
| Internal Transfer | Disabled | Same as above; fund movement capability |
| IP Whitelist | Bound & Platform IP Only | Without an IP whitelist, anyone possessing the key could invoke it |
| Position Mode | Hedge Mode | One-way mode cannot manage long and short positions independently |
About Egress IPs
- The platform egress IP is displayed only on the binding form after sign-in; this guide does not list specific addresses (which may vary across deployments).
- Include only this single IP in the key's whitelist. Adding company IPs, home networks, or obsolete addresses expands your attack surface.
- If the platform has not yet configured a fixed egress IP, binding will state that it is temporarily unavailable. This is a safeguard, not a malfunction.
- When an egress IP changes: update whitelist on exchange → return to CopySonar and click "Check Permissions" to re-verify. Changing only the exchange without re-verifying will leave tasks blocked.
Verification Validity Window
Permission checks are not one-and-done. Successful check results remain valid for 24 hours. Once expired, the system halts new risk additions (reduce-only and closures remain allowed). You must return to the Key Management page and trigger a manual recheck, then explicitly resume the task.
TODO 素材：此处补「读取与合约交易开启、提现与划转关闭、出口 IP 白名单位置」截图
Validating & Binding in CopySonar
Open API Key Management, select the exchange, and fill in the account label and credentials; OKX requires an additional Passphrase. Confirm permissions and IP whitelist before submitting for verification. Only proceed to select an account for live copy after the page explicitly shows successful binding.
Form Field Descriptions
| Field | Required? | Notes & Constraints |
|---|---|---|
| Exchange | Required | Binance or OKX; form fields adapt upon selection |
| Account Label | Optional | Max 128 characters, no control characters; defaults to "Unnamed Account" if blank |
| API Key | Required | Paste complete string, at least 8 characters; form will not echo full value |
| Secret | Required | Masked by default; click "Show" to double check before submission |
| Passphrase | Required for OKX | The phrase set during OKX key creation; not needed for Binance |
Before submitting, you must check the confirmation acknowledging that you have disabled withdrawals and transfers, enabled only read and futures trading, and restricted IP to the platform egress IP. This checkbox is your formal confirmation of authorization scope.
What Happens During Binding
- Credentials are encrypted and transmitted to the server; the frontend never stores plain text.
- The server sends a read-only probe to the exchange to inspect permission flags and IP restriction state.
- Upon passing all checks, key status becomes "Verified" and records the timestamp.
- The list displays masked key suffixes, permission summaries, associated tasks, and last check time.
Only when the list shows "Permissions Valid" can this key be selected as a live execution account. If marked "Pending Check · Blocked", "Permissions Invalid · Blocked", or "Expired or Unconfirmed · Blocked", please recheck first.
Diagnostic Flow for Binding Failures
Follow this sequence to resolve most issues:
- Do Key and Secret belong to the same pair? Mixing keys from different generations is the #1 cause.
- Did you miss the Passphrase on OKX? Or accidentally use your account password.
- Are both permissions enabled? Read + Futures Trading are both required.
- Are withdrawal and transfer switches completely off? Universal transfer and internal transfer are often overlooked.
- Does the IP whitelist contain only the platform IP? Empty whitelists or multiple IPs will fail.
- Is position mode set to Hedge Mode? One-way mode will be rejected.
- Has the Key expired or been disabled on the exchange? Some exchanges apply auto-expiration to keys.
Fix the root cause and resubmit. Do not repeatedly retry without making adjustments. See API Binding Failures for detailed error mappings.
TODO 素材：此处补「绑定表单字段与权限校验结果，凭据字段全程遮挡」录屏
Multi-Account & Quota
- Each live task binds to exactly one execution account; one account (Key) can only run one live task at any given time.
- The number of bound keys is constrained by your plan quota; once reached, unbind unused keys first.
- The key list supports filtering by All / Normal / Action Required, as well as name search and exchange filter.
- Each key displays active associated tasks and allocated capital to help identify quota usage.
Unbinding & Revoking
When a key has active associated tasks, review and handle the tasks before attempting to unbind. Unbinding in CopySonar does not delete or revoke the key on the exchange. To completely revoke access, delete the key in the exchange's API Management.
Revocation may affect ongoing position management. Verify exchange orders and open positions before revoking, and read Incident Response.
Two Very Different Actions
| Action | Where to Perform | Effect | Affects Existing Positions? |
|---|---|---|---|
| Unbind Key | CopySonar · API Keys · Unbind | Platform deletes credentials; cannot place further orders | Does not close positions; tasks cannot manage them automatically |
| Revoke Key | Exchange · API Management · Delete | Key becomes completely invalid for all callers | Does not close positions; unclosed positions remain in account |
Many users assume "unbinding = 100% safe", but the key remains valid on the exchange. If you suspect credential compromise, you must delete the Key on the exchange, not just unbind.
Pre-Unbinding Checklist
- [ ] This key has no active associated tasks (the page will block unbinding if any exist).
- [ ] You have confirmed open positions and orders on the exchange, closing manually if necessary.
- [ ] You understand tasks can no longer automatically manage positions after unbinding.
- [ ] If your goal is complete revocation, remember to delete the Key on the exchange.
When to Revoke Immediately
If any of the following occur, delete the key on the exchange immediately before addressing tasks:
- Credentials might have been captured in screenshots, chats, logs, or repositories.
- The exchange alerts you to unfamiliar logins, unusual API calls, or modified permissions.
- You observe unauthorized orders in your account.
- You no longer plan to use CopySonar, but positions remain open.
See How to Handle Anomalies for full emergency procedures.
Next Steps
- Bound successfully, start task configuration: Create Copy · Parameters
- Understand why permissions are designed this way: Safety & Funds · Least Privilege
- Binding failed: FAQ · API Binding Failures