DEX API

兑换#

通过 DEX 聚合器 router 获取兑换所需的交易数据。

请求地址#

GET https://www.okx.com/api/v5/dex/aggregator/swap

请求参数#

参数类型必传描述
chainIdString链 ID (如1: Ethereum,更多可查看链 ID 列表)
amountString币种询价数量
(数量需包含精度,如兑换 1.00 USDT 需输入 1000000,兑换 1.00 DAI 需输入 1000000000000000000),币种精度可通过币种列表取得。
fromTokenAddressString询价币种合约地址 (如:0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee)
toTokenAddressString目标币种合约地址 (如:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48)
slippageString滑点限制,最小值:0,最大值:1。(如:0.005代表你接受这笔交易最大 0.5%滑点,1 就代表你接受这笔交易最大 100%的滑点)
min:0 max:1
userWalletAddressString用户钱包地址 (如:0x3f6a3f57569358a512ccc0e513f171516b0fd42a)
referrerAddressStringfromToken 分佣地址 (支持 SOL 或 SPL Token 分佣,SOL 分佣使用 wallet 地址,SPL Token 分佣使用 token account)
收取分佣费用的 fromToken 地址。使用 API 时,需要结合 feePercent 设置佣金比例,且单笔交易只能选择 fromToken 分佣或 toToken 分佣

注意:
1.对于 EVM:此处不支持涉及打包币对的交易,例如 ETH 和 WETH 的交易
2.对于 Solana:分佣地址需提前存入一些 SOL 进行激活。
swapReceiverAddressString购买的资产的收件人地址 如果未设置,则用户钱包地址收到购买的资产 (如:0x3f6a3f57569358a512ccc0e513f171516b0fd42a)
feePercentString发送到分佣地址的询价币种数量百分比 最小百分比:0 最大百分比:3
gaslimitStringgas费用限额 (交易的gas (单位:wei)。如果该值太低,无法实现报价,则会返回错误信息)
gasLevelStringgas价格等级 (默认为 average,交易消耗gas价格水平,可设置为 averagefastslow)
dexIdsString限定询价的流动性池 dexId , 多个组合按 , 分隔 (如 1,50,180 ,更多可查看流动性列表)
priceImpactProtectionPercentageString(可选,默认值为 90%) 允许的价格影响百分比 (介于 0 和 1.0 之间)。

当用户设置了 priceImpactProtectionPercentage 后,如果估算的价格影响超过了指定的百分比,将会返回一个错误。例如,如果 PriceImpactProtectionPercentage = .25 (25%),任何价格影响高于 25% 的报价都将返回错误。

这是一个可选开启的功能,默认值为 0.9。当百分比被设置为 1.0 (100%) 时,此功能将被禁用,也就是说,每一笔交易都会被允许通过。

注意:当我们无法计算价格影响时,我们会返回 null,并且价格影响保护也会被禁用。
callDataMemoString你可以自定义 callData 中上链携带的参数,将想要带到链上的数据编码成长度固定为 64 bytes、128 个字符长度的 16 进制字符串。例如,“0x111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111”,字符串中需要保留“0x”开头。
toTokenReferrerAddressStringtoToken 分佣地址 (只支持 SPL Token 分佣,使用 token account)
收取分佣费用的 toToken 地址。使用 API 时,需要结合 feePercent 设置佣金比例,且单笔交易只能选择 fromToken 分佣或 toToken 分佣

注意:
1.对于 EVM:此处不支持涉及打包币对的交易,例如 ETH 和 WETH 的交易
2.对于 Solana:分佣地址需提前存入一些 SOL 进行激活。
computeUnitPriceString用于 Solana 网络上的交易,类似于 Ethereum 上的 gasPrice,这个价格决定了交易的优先级,价格越高意味着交易越有可能更快地被网络处理。
computeUnitLimitString用于 Solana 网络上的交易,可类比为 Ethereum 上的的 gasLimit,这个限制可以确保交易不会占用过多的计算资源。
fromTokenReferrerWalletAddressString收取 fromToken 分佣费用的钱包地址。新字段针对 SPL Token 不再需要 token account 入参,指定 Sol 钱包地址即可。
使用 API 时,需要结合 feePercent 设置佣金比例,且单笔交易只能选择 fromToken 分佣或 toToken 分佣

注意:
1.对于 EVM:此处不支持涉及打包币对的交易,例如 ETH 和 WETH 的交易
2.对于 Solana:分佣地址需提前存入一些 SOL 进行激活。
toTokenReferrerWalletAddressString收取 toToken 分佣费用的钱包地址。新字段针对 SPL Token 不再需要 token account 入参。
使用 API 时,需要结合 feePercent 设置佣金比例,且单笔交易只能选择 fromToken 分佣或 toToken 分佣

注意:
1.对于 EVM:此处不支持涉及打包币对的交易, 例如 ETH 和 WETH 的交易
2.对于 Solana:分佣地址需提前存入一些 SOL 进行激活。

响应参数#

参数类型描述
routerResultObject询价路径数据对象
chainIdString链 ID (如1: Ethereum,更多可查看链 ID 列表)
fromTokenAmountString询价币种的兑换数量 (如:500000000000000000000000)
toTokenAmountString目标币种的兑换数量 (如:168611907733361)
tradeFeeString询价路径预估消耗的网络费用 (USD 计价)
estimateGasFeeString预估消耗的 gas,各个链的最小单位返回,例如 wei
dexRouterListArray询价路径数据集合
routerString币种兑换的一条路径
routerPercentString当前兑换路径处理的资产占所有资产的百分比 (如:5)
subRouterListArray询价路径数据子集合
dexProtocolArray兑换路径中执行的 DEX 协议
dexNameStringDEX 协议名称 (如:Verse)
percentString一条路径中单一 DEX 协议的兑换资产占所有 DEX 协议百分比 (如:100)
fromTokenObject询价币种信息
tokenContractAddressString币种合约地址 (如:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48)
tokenSymbolString币种简称 (如:USDC)
tokenUnitPriceString该接口返回的币种单价是一个结合了链上、交易所以及其他第三方来源数据的综合美元价格。注:此价格仅为推荐价格,在一些特殊情况中,币种单价可能为 null
decimalString币种精度定义了单个的该币种可以被分成多少份的最小单位。例如,如果一个币种的精度是 8,则表示单个的这种代币可以被分成 100,000,000 份的最小单位。注意:该参数仅供参考,币种精度会随着合约拥有者的设置改变等原因发生变化。
isHoneyPotBoolean代币是否为貔貅币。 是:true 否:false
taxRateString代币卖出税率,适用于可设定税费机制的代币(如SafeMoon、SPL2022代币)。普通代币无税费时返回 0。取值为 最小:0 最大:1,0.01表示1%。
toTokenObject目标币种信息
tokenContractAddressString币种合约地址 (如:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48)
tokenSymbolString币种简称 (如:USDC)
tokenUnitPriceString该接口返回的币种单价是一个结合了链上、交易所以及其他第三方来源数据的综合美元价格。注:此价格仅为推荐价格,在一些特殊情况中,币种单价可能为 null
decimalString币种精度定义了单个的该币种可以被分成多少份的最小单位。例如,如果一个币种的精度是 8,则表示单个的这种代币可以被分成 100,000,000 份的最小单位。注意:该参数仅供参考,币种精度会随着合约拥有者的设置改变等原因发生变化。
isHoneyPotBoolean代币是否为貔貅币。 是:true 否:false
taxRateString代币买入税率,适用于可设定税费机制的代币(如SafeMoon、SPL2022代币)。普通代币无税费时返回 0。取值为 最小:0 最大:1,0.01表示1%。
quoteCompareListArray询价路径对比列表
dexNameString询价路径 DEX 名称
dexLogoStringDEX 协议名称
tradeFeeString询价路径预估消耗的网络费用 (USD 计价)
receiveAmountString询价路径的接收数量
priceImpactPercentageStringPercentage = (接收价值 – 支付价值) / 支付价值。因为当前兑换数量影响了流动性池深度,导致产生了价值差额。若接收价值大于支付价值,Percentage 有可能是正数。
txObject发交易信息
signatureDataArray如果返回此参数,则代表该交易需要额外的签名数据。开发者应将此参数作为交易签名的输入之一,并确保其在签名过程中正确应用。
fromString用户钱包地址 (如:0x3f6a3f57569358a512ccc0e513f171516b0fd42a)
gasStringgas 费限值的估计值,在 gasprice 基础上增加 50%,以 10 进制标准格式返回。 (如:1173250)
gasPriceString以 wei 为单位的 gas price ,以 10 进制标准格式返回。(如:58270000000)
maxPriorityFeePerGasStringEIP-1559:每单位 gas 优先费用的推荐值 (如:500000000)
toString欧易 DEX router 合约地址 (如:0x3b3ae790Df4F312e745D270119c6052904FB6790)
valueString与合约交互的主链币数量,以 10 进制标准格式最小单位返回 (wei) (如:0)
minReceiveAmountString目标币种的最小兑换数量 (兑换价格达到滑点限制的极限值时,目标币种的兑换数量,如:900645839798)
dataStringCall data

请求示例#

shell
curl --location --request GET 'https://www.okx.com/api/v5/dex/aggregator/swap?chainId=1&amount=10000000000000&toTokenAddress=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&fromTokenAddress=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee&slippage=0.05&userWalletAddress=0x6f9ffea7370310cd0f890dfde5e0e061059dcfb8' \
--header 'OK-ACCESS-PROJECT: 86af********d1bc' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2023-10-18T12:21:41.274Z'

响应示例#

200
{
        "code": "0",
        "data": [
      {
        "routerResult": {
        "chainId": "1",
        "dexRouterList": [
      {
        "router": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee--0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "routerPercent": "100",
        "subRouterList": [
      {
        "dexProtocol": [
      {
        "dexName": "Uniswap V3",
        "percent": "100"
      }
        ],
        "fromToken": {
        "decimal": "18",
        "isHoneyPot": false,
        "taxRate": "0",
        "tokenContractAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "tokenSymbol": "WETH",
        "tokenUnitPrice": "3342.87"
      },
        "toToken": {
        "decimal": "6",
        "isHoneyPot": false,
        "taxRate": "0",
        "tokenContractAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "tokenSymbol": "USDC",
        "tokenUnitPrice": "0.9995"
      }
      }
        ]
      }
        ],
        "estimateGasFee": "135000",
        "fromToken": {
        "decimal": "18",
        "isHoneyPot": false,
        "taxRate": "0",
        "tokenContractAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        "tokenSymbol": "ETH",
        "tokenUnitPrice": "3342.87"
      },
        "fromTokenAmount": "10000000000000",
        "priceImpactPct": "0.001",
        "quoteCompareList": [
      {
        "amountOut": "32990",
        "dexLogo": "https://static.okx.com/cdn/wallet/logo/balancer.png",
        "dexName": "Balancer V1",
        "tradeFee": "44.32919149271585462"
      },
      {
        "amountOut": "334",
        "dexLogo": "https://static.okx.com/cdn/wallet/logo/DODO.png",
        "dexName": "DODO",
        "tradeFee": "36.96825563599181972"
      },
      {
        "amountOut": "33023",
        "dexLogo": "https://static.okx.com/cdn/wallet/logo/balancer.png",
        "dexName": "Balancer V2",
        "tradeFee": "19.79273863696907162"
      },
      {
        "amountOut": "32980",
        "dexLogo": "https://static.okx.com/cdn/explorer/dex/logo/Dex_Sushiswap_V3.png",
        "dexName": "Sushiswap V3",
        "tradeFee": "15.70332982767794112"
      },
      {
        "amountOut": "32964",
        "dexLogo": "https://static.okx.com/cdn/wallet/logo/SHIB.png",
        "dexName": "ShibaSwap",
        "tradeFee": "15.70332982767794112"
      }
        ],
        "toToken": {
        "decimal": "6",
        "isHoneyPot": false,
        "taxRate": "0",
        "tokenContractAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "tokenSymbol": "USDC",
        "tokenUnitPrice": "0.9995"
      },
        "toTokenAmount": "33474",
        "tradeFee": "4.3491690602723664"
      },
        "tx": {
        "data": "0x0d5f0e3b00000000000000000001881f6f9ffea7370310cd0f890dfde5e0e061059dcfb8000000000000000000000000000000000000000000000000000009184e72a0000000000000000000000000000000000000000000000000000000000000007c3800000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000001800000000000000000000000e0554a476a092703abdb3ef35c80e0d76d32939f",
        "from": "0x6f9ffea7370310cd0f890dfde5e0e061059dcfb8",
        "gas": "202500",
        "gasPrice": "32657616776",
        "maxPriorityFeePerGas": "2086453233",
        "minReceiveAmount": "31800",
        "signatureData": [
        ""
        ],
        "to": "0x7D0CcAa3Fac1e5A943c5168b6CEd828691b46B36",
        "value": "10000000000000"
      }
      }
        ],
        "msg": ""
      }