兑换#

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

请求地址#

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

请求参数#

参数	类型	必传	描述
chainId	String	是	链 ID (如`1`: Ethereum，更多可查看链 ID 列表)
amount	String	是	币种询价数量 (数量需包含精度，如兑换 1.00 USDT 需输入 1000000，兑换 1.00 DAI 需输入 1000000000000000000)，币种精度可通过币种列表取得。
fromTokenAddress	String	是	询价币种合约地址 (如：`0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`)
toTokenAddress	String	是	目标币种合约地址 (如：`0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48`)
slippage	String	是	滑点限制，最小值：0，最大值：1。（如：0.005代表你接受这笔交易最大 0.5%滑点，1 就代表你接受这笔交易最大 100%的滑点） `min:0` `max:1`
userWalletAddress	String	是	用户钱包地址 (如：`0x3f6a3f57569358a512ccc0e513f171516b0fd42a`)
referrerAddress	String	否	fromToken 分佣地址 (支持 SOL 或 SPL Token 分佣，SOL 分佣使用 wallet 地址，SPL Token 分佣使用 token account) 收取分佣费用的 fromToken 地址。使用 API 时，需要结合 feePercent 设置佣金比例，且单笔交易只能选择 fromToken 分佣或 toToken 分佣。注意: 1.对于 EVM:此处不支持涉及打包币对的交易,例如 ETH 和 WETH 的交易 2.对于 Solana:分佣地址需提前存入一些 SOL 进行激活。
swapReceiverAddress	String	否	购买的资产的收件人地址如果未设置，则用户钱包地址收到购买的资产 (如：`0x3f6a3f57569358a512ccc0e513f171516b0fd42a`)
feePercent	String	否	发送到分佣地址的询价币种数量百分比，`最小百分比：0`，`最大百分比：3`。最多支持小数点后 2 位，系统将自动忽略超出的部分。(例如：实际传入 1.326%，但分拥计算时仅会取 1.32% 的分拥比例)
gaslimit	String	否	gas费用限额 (交易的gas (单位：wei)。如果该值太低，无法实现报价，则会返回错误信息)
gasLevel	String	否	gas价格等级 (默认为 `average`,交易消耗gas价格水平，可设置为 `average`、`fast` 或 `slow`)
dexIds	String	否	限定询价的流动性池 dexId , 多个组合按 `,` 分隔 (如 `1,50,180` ，更多可查看流动性列表)
priceImpactProtectionPercentage	String	否	(可选，默认值为 90%) 允许的价格影响百分比 (介于 0 和 1.0 之间)。当用户设置了 priceImpactProtectionPercentage 后，如果估算的价格影响超过了指定的百分比，将会返回一个错误。例如，如果 PriceImpactProtectionPercentage = .25 (25%)，任何价格影响高于 25% 的报价都将返回错误。这是一个可选开启的功能，默认值为 0.9。当百分比被设置为 1.0 (100%) 时，此功能将被禁用，也就是说，每一笔交易都会被允许通过。注意：当我们无法计算价格影响时，我们会返回 null，并且价格影响保护也会被禁用。
callDataMemo	String	否	你可以自定义 callData 中上链携带的参数，将想要带到链上的数据编码成长度固定为 64 bytes、128 个字符长度的 16 进制字符串。例如，“0x111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111”，字符串中需要保留“0x”开头。
toTokenReferrerAddress	String	否	toToken 分佣地址 (只支持 SPL Token 分佣，使用 token account) 收取分佣费用的 toToken 地址。使用 API 时，需要结合 feePercent 设置佣金比例，且单笔交易只能选择 fromToken 分佣或 toToken 分佣。注意: 1.对于 EVM:此处不支持涉及打包币对的交易,例如 ETH 和 WETH 的交易 2.对于 Solana:分佣地址需提前存入一些 SOL 进行激活。
computeUnitPrice	String	否	用于 Solana 网络上的交易，类似于 Ethereum 上的 gasPrice，这个价格决定了交易的优先级，价格越高意味着交易越有可能更快地被网络处理。
computeUnitLimit	String	否	用于 Solana 网络上的交易，可类比为 Ethereum 上的的 gasLimit，这个限制可以确保交易不会占用过多的计算资源。
fromTokenReferrerWalletAddress	String	否	收取 fromToken 分佣费用的钱包地址。新字段针对 SPL Token 不再需要 token account 入参，指定 Sol 钱包地址即可。使用 API 时，需要结合 feePercent 设置佣金比例，且单笔交易只能选择 fromToken 分佣或 toToken 分佣。注意: 1.对于 EVM:此处不支持涉及打包币对的交易,例如 ETH 和 WETH 的交易 2.对于 Solana:分佣地址需提前存入一些 SOL 进行激活。
toTokenReferrerWalletAddress	String	否	收取 toToken 分佣费用的钱包地址。新字段针对 SPL Token 不再需要 token account 入参。使用 API 时，需要结合 feePercent 设置佣金比例，且单笔交易只能选择 fromToken 分佣或 toToken 分佣。注意: 1.对于 EVM:此处不支持涉及打包币对的交易, 例如 ETH 和 WETH 的交易 2.对于 Solana:分佣地址需提前存入一些 SOL 进行激活。
autoSlippage	String	否	默认为 false。当设置为 true 时，原 slippage 参数（如果有传入）将会被 autoSlippage 覆盖，将基于当前市场数据计算并设定自動滑点。
maxAutoSlippage	String	否	当 autoSlippage 设置为 true 时，此值为 API 所返回的 autoSlippage 的最大上限，建议用户采用此值以控制风险。

响应参数#

参数	类型	描述
routerResult	Object	询价路径数据对象
chainId	String	链 ID (如`1`: Ethereum，更多可查看链 ID 列表)
fromTokenAmount	String	询价币种的兑换数量 (如：`500000000000000000000000`)
toTokenAmount	String	目标币种的兑换数量 (如：`168611907733361`)
tradeFee	String	询价路径预估消耗的网络费用 (USD 计价)
estimateGasFee	String	预估消耗的 gas，各个链的最小单位返回，例如 wei
dexRouterList	Array	询价路径数据集合
router	String	币种兑换的一条路径
routerPercent	String	当前兑换路径处理的资产占所有资产的百分比 (如：`5`)
subRouterList	Array	询价路径数据子集合
dexProtocol	Array	兑换路径中执行的 DEX 协议
dexName	String	DEX 协议名称 (如：`Verse`)
percent	String	一条路径中单一 DEX 协议的兑换资产占所有 DEX 协议百分比 (如：`100`)
fromToken	Object	询价币种信息
tokenContractAddress	String	币种合约地址 (如：`0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48`)
tokenSymbol	String	币种简称 (如：`USDC`)
tokenUnitPrice	String	该接口返回的币种单价是一个结合了链上、交易所以及其他第三方来源数据的综合美元价格。注：此价格仅为推荐价格，在一些特殊情况中，币种单价可能为 null
decimal	String	币种精度定义了单个的该币种可以被分成多少份的最小单位。例如，如果一个币种的精度是 8，则表示单个的这种代币可以被分成 100,000,000 份的最小单位。注意：该参数仅供参考，币种精度会随着合约拥有者的设置改变等原因发生变化。
isHoneyPot	Boolean	代币是否为貔貅币。 `是：true` `否：false`
taxRate	String	代币卖出税率，适用于可设定税费机制的代币（如SafeMoon、SPL2022代币）。普通代币无税费时返回 `0`。取值为 `最小：0` `最大：1`，0.01表示1%。
toToken	Object	目标币种信息
tokenContractAddress	String	币种合约地址 (如：`0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48`)
tokenSymbol	String	币种简称 (如：`USDC`)
tokenUnitPrice	String	该接口返回的币种单价是一个结合了链上、交易所以及其他第三方来源数据的综合美元价格。注：此价格仅为推荐价格，在一些特殊情况中，币种单价可能为 null
decimal	String	币种精度定义了单个的该币种可以被分成多少份的最小单位。例如，如果一个币种的精度是 8，则表示单个的这种代币可以被分成 100,000,000 份的最小单位。注意：该参数仅供参考，币种精度会随着合约拥有者的设置改变等原因发生变化。
isHoneyPot	Boolean	代币是否为貔貅币。 `是：true` `否：false`
taxRate	String	代币买入税率，适用于可设定税费机制的代币（如SafeMoon、SPL2022代币）。普通代币无税费时返回 `0`。取值为 `最小：0` `最大：1`，0.01表示1%。
quoteCompareList	Array	询价路径对比列表
dexName	String	询价路径 DEX 名称
dexLogo	String	DEX 协议名称
tradeFee	String	询价路径预估消耗的网络费用 (USD 计价)
receiveAmount	String	询价路径的接收数量
priceImpactPercentage	String	Percentage = (接收价值 – 支付价值) / 支付价值。因为当前兑换数量影响了流动性池深度，导致产生了价值差额。若接收价值大于支付价值，Percentage 有可能是正数。
tx	Object	发交易信息
signatureData	Array	如果返回此参数，则代表该交易需要额外的签名数据。开发者应将此参数作为交易签名的输入之一，并确保其在签名过程中正确应用。
from	String	用户钱包地址 (如：0x3f6a3f57569358a512ccc0e513f171516b0fd42a)
gas	String	gas 费限值的估计值，在 gasprice 基础上增加 50%，以 10 进制标准格式返回。 (如：`1173250`)
gasPrice	String	以 wei 为单位的 gas price ，以 10 进制标准格式返回。(如：`58270000000`)
maxPriorityFeePerGas	String	EIP-1559:每单位 gas 优先费用的推荐值 (如：`500000000`)
to	String	欧易 DEX router 合约地址 (如：`0x3b3ae790Df4F312e745D270119c6052904FB6790`)
value	String	与合约交互的主链币数量，以 10 进制标准格式最小单位返回 (wei) (如：`0`)
minReceiveAmount	String	目标币种的最小兑换数量 (兑换价格达到滑点限制的极限值时，目标币种的兑换数量，如：`900645839798`)
data	String	Call data
slippage	String	当前交易的滑点值

请求示例#

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": ""
      }