Skill: aaronllee/easy-swap (version 1.0.0)

--- name: okx-dex-swap description: > Execute token swaps on-chain via OKX DEX Aggregator API (v6). Use this skill when a user wants to: 1. Build a complete swap flow: get swap calldata -> sign transaction -> broadcast to chain 2. Execute token-to-token swaps with slippage protection, MEV protection, and Jito tips (Solana) 3. Integrate OKX DEX swap + broadcast into applications, bots, or scripts This skill covers the FULL lifecycle: /swap endpoint (get tx data) + /broadcast-transaction endpoint (submit signed tx). For quote-only (no execution), use the okx-dex-quote skill instead. version: 1.0.0 allowed_tools: [bash_tool, create_file, str_replace, view] required_context: [api_key, secret_key, passphrase, user_wallet_address, private_key_or_signer] license: MIT author: Claude Assistant tags: [defi, dex, okx, swap, broadcast, web3, onchain, evm, solana, mev-protection] --- # OKX DEX Swap & Broadcast Skill ## Overview This skill generates production-ready code for the **complete on-chain swap flow** using the OKX DEX Aggregator: ``` ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │ Quote │ ──▶ │ Swap │ ──▶ │ Sign │ ──▶ │ Broadcast │ │ (optional│ │ API Call │ │ Tx │ │ to Chain │ │ preview)│ │ │ │ │ │ │ └─────────┘ └──────────┘ └──────────┘ └───────────┘ ``` **Two API endpoints involved:** | Step | Endpoint | Method | Purpose | |------|----------|--------|---------| | Swap | `/api/v6/dex/aggregator/swap` | GET | Get transaction calldata for the swap | | Broadcast | [REDACTED_SECRET] | POST | Submit signed transaction to the chain | **Key features:** - Full swap lifecycle with transaction signing - Auto-slippage calculation based on market conditions - MEV (sandwich attack) protection on ETH, BSC, SOL, BASE - Jito tips for Solana priority transactions - Token approval handling (ERC-20 approve) - Commission/referral fee splitting - Price impact protection with configurable thresholds ## Prerequisites ### Required Credentials - `OKX_ACCESS_KEY` — API key - `OKX_SECRET_KEY` — Secret key for HMAC signing - `OKX_PASSPHRASE` — Account passphrase ### Wallet Requirements - **EVM chains**: Private key or a signer (e.g., web3.py Account, ethers.js Wallet) - **Solana**: Keypair for transaction signing - The wallet must have sufficient balance of the `fromToken` and native token for gas ### Environment - **Python**: `requests`, `web3` (for EVM signing), `solders` / `solana-py` (for Solana) - **Node.js**: `axios`, `ethers` (for EVM signing), `@solana/web3.js` (for Solana) ## Workflow ### Step 1: Call the Swap API **Endpoint:** ``` GET https://web3.okx.com/api/v6/dex/aggregator/swap ``` **Required parameters:** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chainIndex` | String | Yes | Chain ID (e.g., `1` = Ethereum, `501` = Solana) | | `amount` | String | Yes | Amount in raw units with decimals (e.g., `1000000` for 1 USDT) | | `swapMode` | String | Yes | `exactIn` (default) or `exactOut` | | `fromTokenAddress` | String | Yes | Sell token contract address | | `toTokenAddress` | String | Yes | Buy token contract address | | `slippagePercent` | String | Yes | Slippage tolerance (e.g., `0.5` = 0.5%). EVM: 0-100, Solana: 0 to <100 | | `userWalletAddress` | String | Yes | User's wallet address that will sign and send the tx | **Important optional parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `approveTransaction` | Boolean | Set `true` to get ERC-20 approval calldata in response | | `approveAmount` | String | Custom approval amount (raw units). If omitted, approves exact swap amount | | `swapReceiverAddress` | String | Recipient address if different from sender | | `feePercent` | String | Commission fee %. Max 3% (EVM) / 10% (Solana) | | `fromTokenReferrerWalletAddress` | String | Wallet to receive fromToken commission | | `toTokenReferrerWalletAddress` | String | Wallet to receive toToken commission | | `autoSlippage` | Boolean | Auto-calculate optimal slippage (overrides `slippagePercent`) | | `maxAutoslippagePercent` | String | Cap for auto-slippage | | `priceImpactProtectionPercent` | String | Max price impact allowed (0-100, default 90) | | `gasLevel` | String | `slow`, `average` (default), or `fast` | | `gaslimit` | String | Custom gas limit in wei (EVM only) | | `dexIds` | String | Restrict to specific DEX IDs (comma-separated) | | `excludeDexIds` | String | Exclude specific DEX IDs (comma-separated) | | `directRoute` | Boolean | Single-pool routing only (Solana only) | | `disableRFQ` | String | Disable time-sensitive RFQ liquidity sources | | `callDataMemo` | String | Custom 64-byte hex data to include on-chain | **Solana-specific parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `computeUnitPrice` | String | Priority fee (like gasPrice on EVM) | | `computeUnitLimit` | String | Compute budget (like gasLimit on EVM) | | `tips` | String | Jito tips in SOL (min 0.0000000001, max 2). Set `computeUnitPrice=0` when using tips | **Swap API response structure:** ```json { "code": "0", "data": [{ "routerResult": { "chainIndex": "1", "fromToken": { "tokenSymbol": "USDC", "decimal": "6", ... }, "toToken": { "tokenSymbol": "WBTC", "decimal": "8", ... }, "fromTokenAmount": "100000000000", "toTokenAmount": "90281915", "tradeFee": "1.35", "estimateGasFee": "1248837", "priceImpactPercent": "0.07", "dexRouterList": [...] }, "tx": { "from": "0x77660f...", "to": "0x5E1f62...", "value": "0", "data": "0xf2c42696...", "gas": "1248837", "gasPrice": "557703374", "maxPriorityFeePerGas": "500000000", "minReceiveAmount": "90191633", "slippagePercent": "0.1", "signatureData": [...] } }], "msg": "" } ``` **Key fields in `tx` object:** | Field | Description | |-------|-------------| | `from` | Sender wallet address | | `to` | OKX DEX router contract address | | `data` | Transaction calldata (the swap instruction) | | `value` | Native token amount to send (in wei). `"0"` for ERC-20 swaps | | `gas` | Estimated gas limit (already padded +50%) | | `gasPrice` | Gas price in wei | | `maxPriorityFeePerGas` | EIP-1559 priority fee | | `minReceiveAmount` | Minimum output at max slippage | | `signatureData` | Approval calldata (if `approveTransaction=true`) or Jito tips calldata | ### Step 2: Handle Token Approval (EVM Only) For ERC-20 tokens (not native ETH/BNB), you need to approve the DEX router to spend your tokens BEFORE the swap. **When `approveTransaction=true` in the request:** The response `tx.signatureData` contains the approval info: ```json { "approveContract": [REDACTED_SECRET], "approveTxCalldata": "0x095ea7b3..." } ``` **Approval flow:** 1. Parse `signatureData` to get `approveContract` and `approveTxCalldata` 2. Send an approval transaction: `to=approveContract`, `data=approveTxCalldata` 3. Wait for approval tx to be confirmed 4. Then send the swap transaction **IMPORTANT**: For native tokens (ETH, BNB, etc. using `0xeeee...eeee`), no approval is needed. ### Step 3: Sign the Transaction **EVM chains (Python / web3.py):** ```python tx_params = { "from": tx_data["from"], "to": tx_data["to"], "value": int(tx_data["value"]), "data": tx_data["data"], "gas": int(tx_data["gas"]), "gasPrice": int(tx_data["gasPrice"]), "nonce": w3.eth.get_transaction_count(wallet_address), "chainId": chain_id, } signed = w3.eth.account.sign_transaction(tx_params, private_key) signed_tx_hex = signed.raw_transaction.hex() ``` **EVM chains (Node.js / ethers.js):** ```javascript const tx = { from: txData.from, to: txData.to, value: txData.value, data: txData.data, gasLimit: txData.gas, gasPrice: txData.gasPrice, nonce: await provider.getTransactionCount(walletAddress), chainId: chainId, }; const signedTx = await wallet.signTransaction(tx); ``` **Solana:** Use `solders` or `@solana/web3.js` to deserialize, sign, and serialize the transaction from `tx.data`. ### Step 4: Broadcast the Signed Transaction **Endpoint:** ``` POST https://web3.okx.com/api/v6/dex/pre-transaction/broadcast-transaction ``` **IMPORTANT**: This is a POST request with a JSON body (unlike the GET-based swap/quote endpoints). **Request body:** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `signedTx` | String | Yes | The hex-encoded signed transaction string | | `chainIndex` | String | Yes | Chain ID (e.g., `"1"` for Ethereum) | | `address` | String | Yes | Sender wallet address | | `extraData` | String | No | JSON string with extra options (see below) | **extraData options (JSON string):** | Field | Type | Description | |-------|------|-------------| | `enableMevProtection` | Boolean | Enable MEV (sandwich) protection. Supported: ETH, BSC, SOL, BASE | | `jitoSignedTx` | String | Base58-encoded signed Jito transaction (Solana only). Required when `tips` > 0 | **Signing algorithm for POST requests:** ``` prehash = timestamp + "POST" + request_path + json_body signature = Base64(HMAC-SHA256(secret_key, prehash)) ``` Note: For POST, the `request_path` has NO query string. The JSON body is appended directly to the prehash string. **Broadcast response:** ```json { "code": "0", "data": [{ "orderId": [REDACTED_SECRET], "txHash": [REDACTED_SECRET] }], "msg": "" } ``` | Field | Description | |-------|-------------| | `orderId` | OKX internal order tracking ID | | `txHash` | On-chain transaction hash. Use this to check status on block explorer | ### Step 5: Verify Transaction After broadcasting, verify the transaction was confirmed: - **EVM**: Check `txHash` on Etherscan / block explorer, or use `web3.eth.wait_for_transaction_receipt()` - **Solana**: Check on Solscan, or use `connection.confirmTransaction()` ## Best Practices ### Security - **NEVER hardcode private keys** in code. Use environment variables, keystore files, or hardware wallets. - **NEVER log private keys, signed transactions, or secret keys** in production. - Always validate token addresses and amounts before sending. - Check `isHoneyPot` on both tokens before proceeding. - Use `priceImpactProtectionPercent` (recommend setting to `10` or lower for safety). ### Slippage Configuration - **Stable pairs** (USDC/USDT): `0.1%` - `0.5%` - **Major pairs** (ETH/USDC): `0.5%` - `1%` - **Volatile/low-liquidity tokens**: `1%` - `5%` - **Meme coins**: `5%` - `15%` (or higher, but be cautious) - Use `autoSlippage=true` with `maxAutoslippagePercent` for optimal auto-calculation. ### MEV Protection - Enable `enableMevProtection: true` for large trades on ETH, BSC, SOL, BASE. - On Solana, combine with Jito tips for priority + MEV protection. - When using Jito tips, set `computeUnitPrice=0` to avoid wasting fees. ### Token Approval Strategy - For one-time swaps: approve exact amount (`approveAmount = swap amount`). - For repeated swaps: consider a larger approval (e.g., max uint256) to save gas on future swaps, but understand the security trade-off. - Always check existing allowance before sending a new approval. ### Uni V3 Liquidity Edge Case When swapping through Uniswap V3 pools, if the liquidity for the pair is drained mid-swap, the router will only consume part of your input tokens. The OKX DEX Router smart contract will automatically refund the remainder. Ensure your integration contract supports receiving token refunds. ### Amount Handling - **Always use strings** for amounts to avoid floating-point precision loss. - Python: `int()` for calculations, never `float()`. - JavaScript: `BigInt` or `ethers.parseUnits()` for amounts. - Formula: `raw_amount = human_amount * 10^decimals` ### Error Handling - Check `response["code"] == "0"` before processing. - If broadcast fails, do NOT automatically retry without checking nonce — you may double-spend. - Common errors: - `401` = Signature mismatch (check POST signing includes body) - `429` = Rate limited - Swap returns error = insufficient balance, invalid params, or liquidity issue - Broadcast returns error = already executed, nonce too low, insufficient gas ### Commission/Referral Fees - Only ONE of `fromTokenReferrerWalletAddress` or `toTokenReferrerWalletAddress` per tx. - Solana: referrer wallet must have SOL deposited for activation. - TON: limited DEX support (Stonfi V2, Dedust). - BSC: no commission through Four.meme swaps. ## Examples ### Example 1: Python — Complete EVM Swap Flow ```python import os, hmac, hashlib, base64, json, requests from datetime import datetime, timezone from urllib.parse import urlencode from web3 import Web3 # === Configuration === [REDACTED_SECRET]"OKX_ACCESS_KEY"] SECRET_KEY = os.environ["OKX_SECRET_KEY"] PASSPHRASE = os.environ["OKX_PASSPHRASE"] PRIVATE_KEY = os.environ["WALLET_PRIVATE_KEY"] BASE_URL = "https://web3.okx.com" CHAIN_INDEX = "1" # Ethereum CHAIN_ID = 1 RPC_URL = "https://eth.llamarpc.com" w3 = Web3(Web3.HTTPProvider(RPC_URL)) account = w3.eth.account.from_key(PRIVATE_KEY) WALLET = account.address def _sign_request(timestamp, method, request_path, body=""): prehash = timestamp + method + request_path + body mac = hmac.new(SECRET_KEY.encode(), prehash.encode(), hashlib.sha256) return base64.b64encode(mac.digest()).decode() def _headers(method, request_path, body=""): timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z" sig = _sign_request(timestamp, method, request_path, body) return { "OK-ACCESS-KEY": API_KEY, "OK-ACCESS-SIGN": sig, "OK-ACCESS-PASSPHRASE": PASSPHRASE, "OK-ACCESS-TIMESTAMP": timestamp, "Content-Type": "application/json", } # --- Step 1: Get swap calldata --- def get_swap_data(from_token, to_token, amount, slippage="0.5"): params = { "chainIndex": CHAIN_INDEX, "fromTokenAddress": from_token, "toTokenAddress": to_token, "amount": amount, "swapMode": "exactIn", "slippagePercent": slippage, "userWalletAddress": WALLET, "approveTransaction": "true", } query = urlencode(params) path = f"/api/v6/dex/aggregator/swap?{query}" headers = _headers("GET", path) resp = requests.get(BASE_URL + path, headers=headers, timeout=30) resp.raise_for_status() data = resp.json() if data["code"] != "0": raise Exception(f"Swap API error: {data['msg']}") return data["data"][0] # --- Step 2: Handle approval (if needed) --- def send_approval_if_needed(swap_result): sig_data = swap_result["tx"].get("signatureData", []) if not sig_data: return None for item in sig_data: parsed = json.loads(item) if isinstance(item, str) else item if "approveContract" in parsed: approve_tx = { "from": WALLET, "to": Web3.to_checksum_address(parsed["approveContract"]), "data": parsed["approveTxCalldata"], "gas": 60000, "gasPrice": w3.eth.gas_price, "nonce": w3.eth.get_transaction_count(WALLET), "chainId": CHAIN_ID, } signed = w3.eth.account.sign_transaction(approve_tx, PRIVATE_KEY) tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction) receipt = w3.eth.wait_for_transaction_receipt(tx_hash, timeout=120) print(f"Approval confirmed: {tx_hash.hex()}") return receipt return None # --- Step 3: Sign the swap transaction --- def sign_swap_tx(swap_result): tx_data = swap_result["tx"] tx_params = { "from": Web3.to_checksum_address(tx_data["from"]), "to": Web3.to_checksum_address(tx_data["to"]), "value": int(tx_data["value"]), "data": tx_data["data"], "gas": int(tx_data["gas"]), "gasPrice": int(tx_data["gasPrice"]), "nonce": w3.eth.get_transaction_count(WALLET), "chainId": CHAIN_ID, } signed = w3.eth.account.sign_transaction(tx_params, PRIVATE_KEY) return signed.raw_transaction.hex() # --- Step 4: Broadcast via OKX --- def broadcast_tx(signed_tx_hex, enable_mev=True): path = [REDACTED_SECRET] body_dict = { "chainIndex": CHAIN_INDEX, "address": WALLET, "signedTx": signed_tx_hex, } if enable_mev: body_dict["extraData"] = json.dumps({"enableMevProtection": True}) body_str = json.dumps(body_dict) headers = _headers("POST", path, body_str) resp = requests.post(BASE_URL + path, headers=headers, data=body_str, timeout=30) resp.raise_for_status() data = resp.json() if data["code"] != "0": raise Exception(f"Broadcast error: {data['msg']}") return data["data"][0] # === Execute full swap === if __name__ == "__main__": ETH = [REDACTED_SECRET] USDC = [REDACTED_SECRET] amount = str(10 ** 17) # 0.1 ETH print("1. Getting swap data...") swap = get_swap_data(ETH, USDC, amount, slippage="0.5") router = swap["routerResult"] to_dec = int(router["toToken"]["decimal"]) out_human = int(router["toTokenAmount"]) / (10 ** to_dec) print(f" Expected output: {out_human:,.2f} {router['toToken']['tokenSymbol']}") print(f" Price impact: {router.get('priceImpactPercent', 'N/A')}%") print(f" Min receive: {int(swap['tx']['minReceiveAmount']) / (10 ** to_dec):,.2f}") # Honeypot check if router["toToken"].get("isHoneyPot"): print(" HONEYPOT DETECTED — aborting!") exit(1) print("2. Handling approval...") send_approval_if_needed(swap) print("3. Signing swap transaction...") signed_hex = sign_swap_tx(swap) print("4. Broadcasting with MEV protection...") result = broadcast_tx(signed_hex, enable_mev=True) print(f" Order ID: {result['orderId']}") print(f" Tx Hash: {result['txHash']}") print(f" View: https://etherscan.io/tx/{result['txHash']}") ``` ### Example 2: Node.js — Complete EVM Swap Flow ```javascript const crypto = require("crypto"); const https = require("https"); const { ethers } = require("ethers"); const [REDACTED_SECRET]; const SECRET_KEY = process.env.OKX_SECRET_KEY; const PASSPHRASE = process.env.OKX_PASSPHRASE; const PRIVATE_KEY = process.env.WALLET_PRIVATE_KEY; const BASE_URL = "https://web3.okx.com"; const CHAIN_INDEX = "1"; const CHAIN_ID = 1; const provider = new ethers.JsonRpcProvider("https://eth.llamarpc.com"); const wallet = new ethers.Wallet(PRIVATE_KEY, provider); function sign(timestamp, method, path, body = "") { return crypto .createHmac("sha256", SECRET_KEY) .update(timestamp + method + path + body) .digest("base64"); } function headers(method, path, body = "") { const ts = new Date().toISOString(); return { "OK-ACCESS-KEY": API_KEY, "OK-ACCESS-SIGN": sign(ts, method, path, body), "OK-ACCESS-PASSPHRASE": PASSPHRASE, "OK-ACCESS-TIMESTAMP": ts, "Content-Type": "application/json", }; } async function getSwapData(fromToken, toToken, amount, slippage = "0.5") { const params = new URLSearchParams({ chainIndex: CHAIN_INDEX, fromTokenAddress: fromToken, toTokenAddress: toToken, amount, swapMode: "exactIn", slippagePercent: slippage, userWalletAddress: wallet.address, approveTransaction: "true", }); const path = `/api/v6/dex/aggregator/swap?${params}`; const h = headers("GET", path); const resp = await fetch(`${BASE_URL}${path}`, { headers: h }); const data = await resp.json(); if (data.code !== "0") throw new Error(`Swap error: ${data.msg}`); return data.data[0]; } async function broadcastTx(signedTx, enableMev = true) { const path = [REDACTED_SECRET]; const bodyObj = { chainIndex: CHAIN_INDEX, address: wallet.address, signedTx, ...(enableMev && { extraData: JSON.stringify({ enableMevProtection: true }), }), }; const bodyStr = JSON.stringify(bodyObj); const h = headers("POST", path, bodyStr); const resp = await fetch(`${BASE_URL}${path}`, { method: "POST", headers: h, body: bodyStr, }); const data = await resp.json(); if (data.code !== "0") throw new Error(`Broadcast error: ${data.msg}`); return data.data[0]; } async function main() { const ETH = [REDACTED_SECRET]; const USDC = [REDACTED_SECRET]; const amount = (10n ** 17n).toString(); // 0.1 ETH console.log("1. Getting swap data..."); const swap = await getSwapData(ETH, USDC, amount); const txData = swap.tx; console.log(` Min receive: ${txData.minReceiveAmount}`); console.log("2. Signing transaction..."); const tx = { from: txData.from, to: txData.to, value: txData.value, data: txData.data, gasLimit: txData.gas, gasPrice: txData.gasPrice, nonce: await provider.getTransactionCount(wallet.address), chainId: CHAIN_ID, }; const signedTx = await wallet.signTransaction(tx); console.log("3. Broadcasting with MEV protection..."); const result = await broadcastTx(signedTx); console.log(` Tx Hash: ${result.txHash}`); } main().catch(console.error); ``` ### Example 3: Solana Swap with Jito Tips When using Jito tips on Solana: 1. Set `tips` parameter (e.g., `"0.001"` SOL) in the swap request 2. Set `computeUnitPrice=0` (avoid double-paying for priority) 3. The `signatureData` in response contains the Jito tips calldata 4. Sign BOTH the main transaction AND the Jito transaction 5. Broadcast with both `signedTx` and `jitoSignedTx` in `extraData` ```python # Solana-specific broadcast with Jito body = { "chainIndex": "501", "address": solana_wallet_pubkey, "signedTx": base58_signed_main_tx, "extraData": json.dumps({ "enableMevProtection": True, "jitoSignedTx": base58_signed_jito_tx }) } ``` **IMPORTANT**: For Solana, `signedTx` and `jitoSignedTx` must BOTH be provided when using tips. ## Troubleshooting | Problem | Cause | Solution | |---------|-------|----------| | `401 Unauthorized` on broadcast | POST signing error | Ensure prehash = `timestamp + "POST" + path + jsonBody`. The body must be the exact JSON string. | | `401 Unauthorized` on swap | GET signing error | Ensure prehash = `timestamp + "GET" + path_with_query_string`. | | Approval tx fails | Insufficient ETH for gas | Ensure wallet has native token for gas fees. | | Swap tx reverts | Slippage exceeded | Increase `slippagePercent` or use `autoSlippage=true`. | | `minReceiveAmount` is 0 | Extreme slippage or bad params | Check token addresses and amounts. Reduce trade size. | | Broadcast returns no txHash | MEV protection routing delay | Wait and check `orderId` status. MEV-protected txs may take longer. | | "Nonce too low" on broadcast | Tx already sent or nonce reused | Fetch fresh nonce before signing. Never reuse nonces. | | Solana broadcast fails | Missing `jitoSignedTx` | When `tips > 0`, you must provide both `signedTx` and `jitoSignedTx`. | | Token refund not received | Uni V3 liquidity drained | Ensure your contract supports receiving token refunds from the router. | | Commission not working on BSC | Four.meme restriction | Commission is not supported for swaps through Four.meme on BSC. | | `priceImpactPercent` very negative | Low liquidity | Reduce amount or split into multiple smaller swaps. | ## Reference: POST vs GET Signing The OKX API uses different signing for GET and POST: | Method | Prehash Format | |--------|---------------| | GET | `timestamp + "GET" + path_with_query` | | POST | `timestamp + "POST" + path + json_body` | The Swap endpoint is **GET**, the Broadcast endpoint is **POST**. Getting this wrong is the #1 cause of `401` errors. ## Reference: MEV Protection Support | Chain | `enableMevProtection` | Jito Tips | |-------|----------------------|-----------| | Ethereum | Yes | No | | BSC | Yes | No | | Solana | Yes | Yes | | Base | Yes | No | | Others | Not yet | Not yet | ## Reference: Common Chain IDs | Chain | chainIndex | Chain ID (for tx signing) | |-------|-----------|--------------------------| | Ethereum | 1 | 1 | | BSC | 56 | 56 | | Polygon | 137 | 137 | | Arbitrum | 42161 | 42161 | | Optimism | 10 | 10 | | Base | 8453 | 8453 | | Avalanche | 43114 | 43114 | | Solana | 501 | N/A | | Unichain | 130 | 130 |


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: clean (LOW)