OKX API

This skill should be used when the user asks to "query OKX account balance", "place an order on OKX", "get OKX market data", "check OKX positions", "cancel O...

Security Scan

The skill appears to implement an OKX API client correctly, but registry metadata omits required credentials and the SKILL.md recommends placing API keys into a global env that OpenClaw will inject into every agent session—this mismatch and credential-exposure guidance are concerning and worth review before installing.

Purpose & Capability

The files and SKILL.md implement the stated purpose (OKX REST/WebSocket access, signing, example scripts). However, the registry metadata lists no required environment variables or primary credential even though the code and documentation require OKX_API_KEY, OKX_SECRET_KEY, and OKX_PASSPHRASE. That metadata omission is an inconsistency (likely an oversight) that reduces transparency.

Instruction Scope

Runtime instructions explicitly direct the agent (and the user) to store API credentials in ~/.openclaw/openclaw.json under the top-level env field so OpenClaw will inject them into agent environments. This grants broad exposure of sensitive keys to every agent session and to other skills. Other than that, the SKILL.md stays within scope (describes endpoints, signing, demo header, and uses only OKX endpoints).

Install Mechanism

No install specification or remote downloads are present (instruction-only plus local Python scripts), and all code files are bundled. No external installers, URL downloads, or archive extraction steps were found.

Credentials

The skill legitimately needs OKX_API_KEY, OKX_SECRET_KEY, and OKX_PASSPHRASE for private endpoints and OKX_DEMO for sandbox use; those are used directly by the code. But the registry metadata does not declare these required env vars. More importantly, the recommended placement (top-level env in ~/.openclaw/openclaw.json) causes the credentials to be injected into every agent session, which is broader than strictly necessary and raises risk of unintended credential access by other skills or agent actions.

Persistence & Privilege

The skill is not set to always:true and is user-invocable; it does not request elevated platform privileges or modify other skills. However, because OpenClaw will inject top-level env variables into every agent session (per the SKILL.md guidance), the combination of autonomous skill invocation (default) with broadly scoped credentials increases the blast radius if an agent or another skill is compromised. Consider restricting autonomous actions or credential scope.

What to consider before installing

This skill is functionally coherent for interacting with OKX, but review these before installing: (1) The registry metadata omits the required OKX_API_KEY / OKX_SECRET_KEY / OKX_PASSPHRASE variables — expect to supply them. (2) The SKILL.md recommends adding those keys to the top-level ~/.openclaw/openclaw.json env field, which causes OpenClaw to inject the keys into every agent session — consider using per-skill or per-agent scoped secrets instead, or limit which agents/skills can access them. (3) Use sandbox/demo keys (OKX_DEMO=1) while testing and restrict API key permissions (no withdrawal, IP whitelist, minimal trading permissions) and rotate keys regularly. (4) Because the skill can place/cancel orders, ensure you (a) require explicit confirmations for any real-trading actions, (b) review the example scripts (they include a prompt for real orders), and (c) audit the code or prefer installing from a trusted repository. If you need higher assurance, ask the publisher to update registry metadata to declare required env vars and to document safer credential storage options.

OKX API v5 Skill

Overview

OKX API v5 provides REST and WebSocket interfaces for spot trading, derivatives (perpetual swaps, futures, options), market data, and account management.

• Base URL: https://www.okx.com
• API version prefix: /api/v5/
• Demo/sandbox: same base URL, add header x-simulated-trading: 1
• Auth: HMAC SHA256 signature (private endpoints only)
• Rate limits: public endpoints by IP; private endpoints by User ID

All examples use scripts/okx_auth.py — a reusable helper that handles credential loading, signing, and response parsing.

---

Configuration Setup

Store credentials in ~/.openclaw/openclaw.json under the top-level env field. OpenClaw automatically injects these into the agent environment:

{
  "env": {
    "OKX_API_KEY": "your-api-key",
    "OKX_SECRET_KEY": "your-secret-key",
    "OKX_PASSPHRASE": "your-passphrase",
    "OKX_DEMO": "1"
  }
}

Set OKX_DEMO=1 to use sandbox mode (paper trading). Remove or set to 0 for live trading.

You can also export these in your shell:

export OKX_API_KEY="your-api-key"
export OKX_SECRET_KEY="your-secret-key"
export OKX_PASSPHRASE="your-passphrase"
export OKX_DEMO="1"

---

Authentication

Private endpoints require four request headers:

Header	Value
OK-ACCESS-KEY	Your API key
OK-ACCESS-SIGN	Base64(HmacSHA256(pre-sign, secret))
OK-ACCESS-TIMESTAMP	ISO 8601 UTC timestamp with milliseconds
OK-ACCESS-PASSPHRASE	Your passphrase
Content-Type	application/json (POST only)

Signature formula:

pre_sign = timestamp + METHOD + path_with_query + body
signature = base64(hmac_sha256(pre_sign, secret_key))

• timestamp: e.g. 2024-01-15T10:30:00.123Z
• METHOD: uppercase GET or POST
• path_with_query: e.g. /api/v5/account/balance or /api/v5/market/ticker?instId=BTC-USDT
• body: JSON string for POST, empty string "" for GET

Use scripts/okx_auth.py — it handles all of this automatically. See references/authentication.md for edge cases and error codes.

---

Common Operations Quick Reference

Intent	Method	Endpoint
Get account balance	GET	/api/v5/account/balance
Get positions	GET	/api/v5/account/positions
Get ticker (spot price)	GET	/api/v5/market/ticker?instId=BTC-USDT
Get candlestick data	GET	/api/v5/market/candles?instId=BTC-USDT&bar=1H
Get order book	GET	/api/v5/market/books?instId=BTC-USDT&sz=20
Get recent trades	GET	/api/v5/market/trades?instId=BTC-USDT
Place order	POST	/api/v5/trade/order
Amend order	POST	/api/v5/trade/amend-order
Cancel order	POST	/api/v5/trade/cancel-order
Get open orders	GET	/api/v5/trade/orders-pending
Get order history	GET	/api/v5/trade/orders-history
Get instruments	GET	/api/v5/public/instruments?instType=SPOT
Get funding rate	GET	/api/v5/public/funding-rate?instId=BTC-USDT-SWAP

---

Response Handling

All REST responses follow this envelope:

{
  "code": "0",
  "msg": "",
  "data": [...]
}

• code: "0" — success
• Any other code — error; check msg for details
• data is always an array (even for single objects)

Common error codes:

Code	Meaning
50011	Rate limit exceeded — back off and retry
50111	Invalid API key
50113	Invalid signature
50114	Timestamp out of range (±30s tolerance)
51000	Parameter error — check required fields
51008	Insufficient balance

The make_request() function in scripts/okx_auth.py raises a RuntimeError when code != "0", so you can catch errors cleanly.

---

Rate Limits

OKX enforces rate limits per endpoint group:

Category	Limit
Public market data	20 req/2s per IP
Account endpoints	10 req/2s per UID
Trade order placement	60 req/2s per UID
Order cancellation	60 req/2s per UID

If you hit 50011, sleep 2 seconds and retry. For bulk operations, use batch endpoints:

• POST /api/v5/trade/batch-orders — place up to 20 orders
• POST /api/v5/trade/cancel-batch-orders — cancel up to 20 orders

---

Place Order — Key Parameters

{
  "instId": "BTC-USDT",
  "tdMode": "cash",
  "side": "buy",
  "ordType": "limit",
  "px": "42000",
  "sz": "0.001"
}

Field	Values
instId	BTC-USDT (spot), BTC-USDT-SWAP (perp), BTC-USD-241227 (futures)
tdMode	cash (spot), cross (cross margin), isolated
side	buy or sell
ordType	limit, market, post_only, fok, ioc
px	Price (required for limit orders)
sz	Size in base currency (spot) or contracts (derivatives)

See examples/place-order.py for a complete working example.

---

WebSocket

For real-time data (prices, order updates, position changes), use WebSocket instead of polling REST.

• Public: wss://ws.okx.com:8443/ws/v5/public
• Private: wss://ws.okx.com:8443/ws/v5/private

Subscribe to channels by sending JSON messages. Private channels require a login operation first using the same HMAC signature scheme.

See references/websocket.md and examples/websocket-ticker.py.

---

References

• references/authentication.md — Signature details, edge cases, auth error troubleshooting
• references/market-data-endpoints.md — All public REST endpoints with params and response fields
• references/trading-endpoints.md — All private REST endpoints, order types, instrument types
• references/websocket.md — WebSocket URLs, subscription format, private channel auth, common channels
• examples/get-balance.py — Fetch and display account balance
• examples/get-market-data.py — Ticker and candlestick data
• examples/place-order.py — Place a limit buy order
• examples/websocket-ticker.py — Real-time price subscription
• scripts/okx_auth.py — Reusable auth/request helper (import in your scripts)