okx-dex-swap

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.

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	/api/v6/dex/pre-transaction/broadcast-transaction	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:

{
  "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",
       
       ...
    
     
       
       
       
       
       
       
       
       
       
       ...
    
  
   

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:

{
  "approveContract": "0x40aA958dd87FC8305b97f2BA922CDdCa374bcD7f",
  "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):

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):

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:

{
  "code": "0",
  "data": [{
    "orderId": "0e1d79837afce1e149b6ab54b6e2edce8130c3f8",
    "txHash": "0xd394f356a16b618ed839c66c935c9cccc5dde0af832ff9b468677eea38759db5"
  }],
  "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

import os, hmac, hashlib, base64, json, requests
from datetime import datetime, timezone
from urllib.parse import urlencode
from web3 import Web3

# === Configuration ===
API_KEY = os.environ["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=):
    params = {
        : CHAIN_INDEX,
        : from_token,
        : to_token,
        : amount,
        : ,
        : slippage,
        : WALLET,
        : ,
    }
    query = urlencode(params)
    path = 
    headers = _headers(, path)

    resp = requests.get(BASE_URL + path, headers=headers, timeout=)
    resp.raise_for_status()
    data = resp.json()

     data[] != :
         Exception()
     data[][]



 ():
    sig_data = swap_result[].get(, [])
      sig_data:
         

     item  sig_data:
        parsed = json.loads(item)  (item, )  item
           parsed:
            approve_tx = {
                : WALLET,
                : Web3.to_checksum_address(parsed[]),
                : parsed[],
                : ,
                : w3.eth.gas_price,
                : w3.eth.get_transaction_count(WALLET),
                : 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=)
            ()
             receipt
     



 ():
    tx_data = swap_result[]
    tx_params = {
        : Web3.to_checksum_address(tx_data[]),
        : Web3.to_checksum_address(tx_data[]),
        : (tx_data[]),
        : tx_data[],
        : (tx_data[]),
        : (tx_data[]),
        : w3.eth.get_transaction_count(WALLET),
        : CHAIN_ID,
    }
    signed = w3.eth.account.sign_transaction(tx_params, PRIVATE_KEY)
     signed.raw_transaction.()



 ():
    path = 
    body_dict = {
        : CHAIN_INDEX,
        : WALLET,
        : signed_tx_hex,
    }
     enable_mev:
        body_dict[] = json.dumps({: })

    body_str = json.dumps(body_dict)
    headers = _headers(, path, body_str)

    resp = requests.post(BASE_URL + path, headers=headers, data=body_str, timeout=)
    resp.raise_for_status()
    data = resp.json()

     data[] != :
         Exception()
     data[][]



 __name__ == :
    ETH = 
    USDC = 
    amount = ( ** )  

    ()
    swap = get_swap_data(ETH, USDC, amount, slippage=)

    router = swap[]
    to_dec = (router[][])
    out_human = (router[]) / ( ** to_dec)
    ()
    ()
    ()

    
     router[].get():
        ()
        exit()

    ()
    send_approval_if_needed(swap)

    ()
    signed_hex = sign_swap_tx(swap)

    ()
    result = broadcast_tx(signed_hex, enable_mev=)
    ()
    ()
    ()

Example 2: Node.js — Complete EVM Swap Flow

const crypto = require("crypto");
const https = require("https");
const { ethers } = require("ethers");

const API_KEY = process.env.OKX_ACCESS_KEY;
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)
    .(timestamp + method + path + body)
    .();
}

 () {
   ts =  ().();
   {
    : ,
    : (ts, method, path, body),
    : ,
    : ts,
    : ,
  };
}

  () {
   params =  ({
    : ,
    : fromToken,
    : toToken,
    amount,
    : ,
    : slippage,
    : wallet.,
    : ,
  });
   path = ;
   h = (, path);

   resp =  (, { : h });
   data =  resp.();
   (data. !== )   ();
   data.[];
}

  () {
   path = ;
   bodyObj = {
    : ,
    : wallet.,
    signedTx,
    ...(enableMev && {
      : .({ :  }),
    }),
  };
   bodyStr = .(bodyObj);
   h = (, path, bodyStr);

   resp =  (, {
    : ,
    : h,
    : bodyStr,
  });
   data =  resp.();
   (data. !== )   ();
   data.[];
}

  () {
    = ;
    = ;
   amount = ( ** ).(); 

  .();
   swap =  (, , amount);

   txData = swap.;
  .();

  .();
   tx = {
    : txData.,
    : txData.,
    : txData.,
    : txData.,
    : txData.,
    : txData.,
    :  provider.(wallet.),
    : ,
  };
   signedTx =  wallet.(tx);

  .();
   result =  (signedTx);
  .();
}

().(.);

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

# 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