TradingView Webhook to OKX: The Passphrase Trap and the Right Setup
OKX has one trap that costs people their whole automation: the API passphrase. You set it yourself, OKX stores only a hash, and if you forget it, it's gone — the only fix is deleting the key and starting over.
This walks through wiring a TradingView alert to OKX through a receiving service, with the three OKX-specific things that bite: the passphrase, the permission model, and the way idle keys quietly die.
The passphrase is yours, and it's unrecoverable
An OKX API credential is three values: the API key, the secret key, and a passphrase you choose. Every signed private request headers it. OKX's FAQ is blunt: you fill it in yourself, it's never shown after creation, and there's no recovery — forget it and you create a new key.
Permissions that are exactly right
OKX splits permissions into Read, Trade and Withdraw. Automation needs Read and Trade. Withdraw should stay off permanently — a leaked key with trade-only permission can be abused to trade, but a key with withdraw permission can be drained.
- Enable Read and Trade. Never withdraw.
- IP-allowlist to your server's egress (up to 20 addresses per key).
- A key with trade or withdraw permission but no IP binding is auto-deleted after 14 days of inactivity.
Wiring the alert to the receiving service
The webhook URL and the JSON template are the two halves. The template uses the strategy placeholders; the receiving service maps them to the fields its API expects, then signs the OKX order with your key, secret and passphrase.
- Create the bot and copy its webhook URL and template.
- In TradingView, paste the URL into the alert's Webhook URL and the JSON into the message box.
- Send one test signal and confirm the direction, quantity and price land as expected in OKX.
- Verify your position in OKX, not just in your bot's log.
The rest of the gotchas
- TradingView cancels requests that take over ~3 seconds — persist then process async.
- Only ports 80/443; no IPv6.
- Webhooks are paid-plan only and require 2FA.
When signatures fail: the error messages and what they mean
OKX signature errors are terse, but they map to a short list of causes. Here's what to check, in order:
| Symptom | Likely cause | Fix |
|---|---|---|
| Signature invalid | Timestamp, method, path or body mismatch; clock skew | Re-derive the signature over the exact request; sync server time |
| Passphrase header missing/wrong | The passphrase isn't the one from the key you're signing with | Confirm API key, secret and passphrase all belong to the same credential |
| Permission denied | Key lacks Trade permission, or IP not allowlisted | Enable Read+Trade; add the server's egress IP |
| Key not found / expired | Auto-deleted after 14 idle days, or deleted manually | Create a new key and update every bot |
The most subtle one is clock skew: OKX requests include a timestamp in the signature, and a server clock that's off by more than the allowed window fails every single call, even with a correct key and passphrase.
Frequently asked questions
Can I recover a forgotten OKX passphrase?
No. OKX stores only a salted hash for validation. The official answer is that a forgotten passphrase cannot be retrieved — delete the key and create a new one, then update it everywhere.
Do I need Withdraw permission for automated trading?
No. Placing orders, querying balances and closing positions only need Read and Trade. Withdraw exists to move funds out, and enabling it only widens the blast radius if the key leaks.
Why did my OKX key stop working after two weeks?
OKX auto-deletes keys with trade or withdraw permission that aren't IP-bound and are idle for 14 days. Reading a balance or placing an order counts as activity; bind an IP to avoid the window entirely.
What does the passphrase actually do?
It's an extra signing input on every private request. The signature covers timestamp, method, path and body, keyed by the secret, with the passphrase sent alongside. Missing it, and calls fail.
Put the pipeline to work
Run your first TradingView signal to a live exchange, then verify it in your exchange — not just in the bot's log.
References
- OKX: API FAQ (passphrase, permissions, key expiry)
- OKX: API docs — API key security
- TradingView: How to configure webhook alerts
Exchange and platform rules change. Links above point to official pages; always follow their latest guidance.
Related guides
Found an inaccuracy or a broken link? Let us know via Telegram and we'll verify and update it.