欧意API参数详解
本文档旨在详细解读欧意API常用参数，为开发者提供清晰的参考，助力高效便捷地进行程序化交易与数据获取。
一、通用参数
以下参数适用于欧意API的大部分接口，务必熟悉并正确使用。这些参数是与欧意交易所进行高效、准确交互的基础。正确理解和使用这些参数能显著提升API交易的成功率和效率。
-
instId(必选): 交易对 ID，唯一标识交易标的。例如：BTC-USDT(现货交易对),ETH-USDT-SWAP(永续合约),BTC-USDT-231229(交割/季度合约)。instId是API请求中识别特定交易标的的关键参数，必须提供。不同的产品类型（现货、合约、期权等）需要不同的instId格式。务必根据所交易的产品类型，选择正确的instId格式。错误的instId将导致API请求失败。该参数具有大小写敏感性，请仔细检查。 -
mktId(可选): 市场 ID，用于指定请求的市场。例如：SPOT(现货),FUTURES(期货),SWAP(永续合约),OPTION(期权)。虽然instId通常已经能够明确市场类型，但在某些情况下，为了提高请求的清晰度和准确性，强烈建议显式指定mktId。显式指定mktId可以避免歧义，尤其是在交易多个市场的产品时。 -
ccy(可选): 币种，用于指定具体的加密货币。例如：BTC(比特币),ETH(以太坊),USDT(泰达币)。主要用于查询账户余额、资金划转等接口。当请求与具体交易对无关，而仅涉及币种本身的操作时，ccy参数至关重要。例如，查询账户中BTC的余额，或者将USDT从现货账户划转到合约账户，都需要用到该参数。 -
clOrdId(可选): 客户自定义订单 ID，允许用户为每个订单设置一个唯一的标识符。这方便用户进行订单管理和跟踪，特别是在需要对订单进行后续操作（例如查询、取消）时。clOrdId由用户自行生成，建议长度不超过32个字符。强烈建议保证clOrdId的唯一性，避免因ID冲突导致订单管理混乱。可以使用UUID等方法生成唯一ID。 -
tag(可选): 订单标签，允许用户为订单添加自定义标签，以便于订单的分类和统计。与clOrdId类似，tag也由用户自定义，长度限制通常为16个字符。用户可以根据自己的需求，为订单添加各种标签，例如 “策略A”、“高频交易” 等，方便后续的数据分析和报表生成。 -
ordId(可选): 订单 ID，是由欧意平台生成的唯一订单标识符。用于查询、取消特定订单等操作。当需要对特定订单执行操作时，必须提供ordId。ordId是平台唯一标识，在订单创建成功后会返回给用户。 -
px(可选): 价格，订单的委托价格。限价单(limit) 必填，市价单(market) 通常不填。需要特别注意的是价格精度问题，不同的交易对具有不同的价格精度要求。必须根据具体交易对的要求设置价格精度，否则订单可能会被拒绝。例如，BTC-USDT 交易对的价格精度可能是小数点后两位，而 ETH-USDT 可能是小数点后三位。 -
sz(可选): 数量/张数。订单的数量或张数，取决于交易的产品类型。现货交易为数量，合约交易为张数。同样需要注意精度问题，不同的交易对具有不同的数量/张数精度要求。请务必参考API文档，确认具体的精度要求。例如，购买 0.001 个 BTC，或开仓 10 张 ETH 合约。 -
side(必选): 买卖方向，指定交易的方向。buy(买入) 或sell(卖出)。清晰明确地指定交易方向是交易的核心要素，如果指定错误，将会导致完全相反的交易结果。 -
ordType(必选): 订单类型，定义订单的执行方式。常用的订单类型包括：market(市价单，以当前市场最优价格立即成交),limit(限价单，以指定价格或更优价格成交),post_only(只挂单，如果订单会立即成交，则会被取消),fok(立即全部成交或取消，Fill or Kill),ioc(立即成交并取消剩余，Immediate or Cancel)。选择合适的订单类型对于交易策略的成功执行至关重要。例如，如果希望立即成交，可以选择市价单；如果希望以特定价格买入，可以选择限价单；如果希望避免吃单，可以选择只挂单。 -
tdMode(可选): 交易模式，指定账户的交易模式。cash(现货),cross(全仓),isolated(逐仓)。如果不指定，则使用默认的交易模式。现货交易通常使用cash模式，合约交易可以使用cross或isolated模式。全仓模式下，账户所有资金都将被用于维持仓位；逐仓模式下，只有分配给该仓位的资金会被用于维持仓位。 -
posSide(可选): 持仓方向，用于合约交易，指定开仓或平仓的方向。long(多仓，看涨),short(空仓，看跌),net(净持仓，仅适用于某些特殊的合约类型)。双向持仓模式下，该参数是必填的，用于明确指定是开多仓、开空仓、平多仓还是平空仓。 -
reduceOnly(可选): 只减仓，限制订单只能减少当前仓位，防止意外开仓。true(是，只减仓),false(否，允许开仓)。用于合约交易，尤其是在进行止盈止损操作时，可以避免因参数错误而意外增加仓位。 -
tgtCcy(可选): 标价币种，指定结算币种。例如：USDT,BTC。当使用非USDT币种进行交易时，需要指定tgtCcy。例如，用BTC购买ETH，则tgtCcy为 BTC。这允许用户使用不同的加密货币进行交易，而不仅仅局限于USDT。 -
slTp(可选): 止盈止损类型，指定是止盈还是止损。tp(止盈，Take Profit),sl(止损，Stop Loss)。用于设置止盈止损订单，在价格达到预设水平时自动平仓，以锁定利润或控制风险。 -
tpTriggerPx(可选): 止盈触发价格，当市场价格达到该价格时，止盈订单将被触发。需要根据具体的市场情况和风险偏好设置合适的止盈触发价格。 -
slTriggerPx(可选): 止损触发价格，当市场价格达到该价格时，止损订单将被触发。需要根据具体的市场情况和风险偏好设置合适的止损触发价格。止损是风险管理的重要手段。 -
tpOrdPx(可选): 止盈委托价格，用于指定止盈单的委托价格。如果不指定，则使用市价单。如果指定，则会创建一个限价止盈单。 -
slOrdPx(可选): 止损委托价格，用于指定止损单的委托价格。如果不指定，则使用市价单。如果指定，则会创建一个限价止损单。需要权衡市价止损的快速执行和限价止损的精确价格控制。 -
amt(可选): 数量，用于市价买入/卖出时，指定买入/卖出的金额。例如，使用 100 USDT 市价买入 BTC。这允许用户直接指定用于购买的金额，而无需计算具体的购买数量。 -
offsetTag(可选): 开平仓标志，用于指定是开仓还是平仓。open(开仓),close(平仓)。一般用于单向持仓模式下的合约交易。在单向持仓模式下，需要使用该参数来明确指定是开仓还是平仓。 -
uly(可选): 标的指数，用于期权交易，指定期权合约对应的标的指数。例如：BTC-USD。期权合约的价格取决于标的指数的价格。 -
expTime(可选): 到期日，用于期权交易，指定期权合约的到期日。格式为YYYY-MM-DD。期权合约在到期日之后将失效。 -
optType(可选): 期权类型，指定是看涨期权还是看跌期权。C(看涨期权，Call Option),P(看跌期权，Put Option)。 -
strike(可选): 行权价，用于期权交易，指定期权合约的行权价格。行权价是期权买方可以购买或出售标的资产的价格。 -
after(可选): 分页参数，用于获取指定ID之后的数据。通常用于API请求返回大量数据时，进行分页显示。 -
before(可选): 分页参数，用于获取指定ID之前的数据。通常用于API请求返回大量数据时，进行分页显示。 -
limit(可选): 每页返回的数据条数。通常有最大限制，例如 100 条。需要根据API文档的说明设置合适的limit值。过大的limit值可能会导致请求失败。
二、账户相关参数
以下参数主要用于账户相关的接口操作，例如查询账户余额、进行资产划转等。理解这些参数对于正确调用API、管理您的加密货币账户至关重要。
-
bal(可选): 划转数量。用于指定需要划转的具体币种数量。该参数的值应为数字，并确保精度符合交易所的要求，避免因精度问题导致划转失败。如果未提供该参数，API可能会使用默认值或者抛出错误，具体行为取决于API的设计。 -
type(必选): 划转类型。该参数定义了账户的类型，例如：0(现货账户),1(合约账户),3(资金账户)。不同的数字代码代表不同的账户类型，必须仔细查阅API文档，以确保选择正确的账户类型代码。错误的账户类型代码会导致划转请求失败，甚至可能造成资产损失。请务必参考交易所提供的最新API文档，因为账户类型代码可能会随着交易所的更新而变化。 -
from(必选): 划转来源账户。指定划转资金的来源账户类型代码。例如，如果资金从现货账户划转到合约账户，那么from参数的值应为现货账户对应的代码（例如0）。如同type参数，这个数值也务必与API文档保持一致。 -
to(必选): 划转目标账户。指定资金划转的目标账户类型代码。例如，如果资金要划转到合约账户，那么to参数的值应为合约账户对应的代码（例如1）。确保from和to参数的值不同，且都存在于您的账户中，否则划转操作将无法成功执行。 -
subAcct(可选): 子账户名称。用于母子账户体系中子账户之间的划转操作。如果您的账户是母账户，并且希望在不同的子账户之间进行资金调拨，则需要指定该参数。该参数的值应为子账户的名称，通常是一个字符串。如果您的账户不是母子账户，则可以忽略该参数。请注意，子账户名称需要与交易所平台上的子账户名称完全一致。
三、合约相关参数
以下参数主要用于合约交易相关的API接口，正确配置这些参数对执行交易策略至关重要。
-
lever(可选): 杠杆倍数 。允许用户设置或调整交易的杠杆比例。更高的杠杆意味着更大的潜在收益，但同时也伴随着更高的风险。例如，设置lever为10，意味着您可以以10倍的资金参与交易。请务必在调整杠杆前充分了解其风险，并根据自身风险承受能力进行合理选择。高杠杆可能导致快速亏损，因此有效的风险管理至关重要。 -
mgnMode(可选): 保证金模式 。指定交易的保证金计算方式。可选值为cross(全仓保证金模式)和isolated(逐仓保证金模式)。在cross模式下，您的所有可用余额都将被用作保证金，任何一笔交易的亏损都可能影响到您的整个账户。在isolated模式下，每笔交易都有其独立的保证金，亏损仅限于该交易的保证金金额。选择合适的保证金模式取决于您的风险偏好和交易策略。建议初学者优先考虑逐仓模式以控制单笔交易的风险。 -
autoOffset(可选): 自动撤单 。布尔值，true表示启用自动撤单，false表示禁用。此功能用于设置在触发止盈或止损订单后，系统是否自动撤销所有其他未成交的同方向委托订单。启用autoOffset可以避免重复成交，特别是在快速变动的市场中。禁用此功能则允许您保留其他未成交的订单，但需要密切关注市场变化，以防出现意外情况。 -
algoId(可选): 算法ID 。用于指定计划委托、跟踪委托、冰山委托或时间加权委托等高级订单类型的算法标识。不同的算法ID对应不同的交易策略。在使用高级订单类型之前，请确保您已经了解其工作原理和适用场景。 -
algoOrdType(可选): 算法订单类型 。指定计划委托、跟踪委托、冰山委托或时间加权委托的具体订单类型。例如，市价单、限价单等。根据您的交易策略和市场情况选择合适的订单类型。不同的订单类型具有不同的执行速度和成交概率。 -
algoPx(可选): 算法价格 。指定计划委托、跟踪委托、冰山委托或时间加权委托的触发价格或执行价格。这是高级订单类型中非常重要的参数，直接影响订单的执行结果。请仔细设置价格，以确保订单能够按照您的预期执行。例如，对于跟踪委托，algoPx可能代表激活委托的偏离价格。 -
algoSz(可选): 算法数量 。指定计划委托、跟踪委托、冰山委托或时间加权委托的交易数量。此参数决定了每次执行交易的规模。根据您的资金管理策略和风险承受能力，合理设置交易数量。
四、其他参数
除了上述常用的API参数（如
symbol
、
side
、
order_type
、
price
、
quantity
等）之外，欧易（OKX）API还提供了大量的其他参数，这些参数服务于更精细化的交易策略和账户管理功能。这些参数通常是针对特定的接口或功能定制的，例如，条件委托订单可能需要额外的触发价格参数（
trigger_price
），止损止盈订单可能需要止损价（
stop_price
）和止盈价（
take_profit
），而某些高级接口可能需要指定交易手续费类型（
fee_type
）或使用特定的抵押资产（
margin_coin
）。
为确保API调用的准确性和稳定性，开发者务必详细阅读欧易官方提供的API文档，深入了解每个接口支持的详细参数说明，包括参数的具体含义、数据类型、取值范围以及是否为必填项。某些参数的缺失或不正确设置可能导致API调用失败或产生意料之外的结果。
在使用欧易API进行交易和数据查询时，以下几点至关重要，需要开发者特别注意：
-
参数类型：
严格按照API文档中规定的参数类型传递数据。例如，数量（
quantity）和价格（price）通常要求使用字符串类型，并且可能需要满足特定的格式要求（例如，小数点位数限制）。如果参数类型不匹配，API调用将会失败，并返回相应的错误信息。 - 参数范围： 仔细检查每个参数的取值范围，确保参数值在允许的范围内。超出范围的参数值可能会导致交易失败或数据异常。例如，订单数量不能低于平台的最小交易单位，委托价格不能偏离市场价格过远。
-
参数精度：
特别注意价格（
price）和数量（quantity）的精度。欧易API对交易参数的精度有严格的要求，超出精度的部分会被截断或四舍五入，这可能会影响交易结果。建议开发者使用高精度的数据类型（例如，Decimal）来处理价格和数量，并根据API文档的要求进行格式化。 - 鉴权： 在每次API调用时，都必须正确配置API密钥，并按照API文档的要求进行身份验证。API密钥包括API Key和Secret Key，Secret Key用于生成签名，确保API请求的安全性。如果鉴权失败，API将会拒绝请求，并返回相应的错误信息。务必妥善保管API密钥，避免泄露。
- 频率限制： 欧易API对每个用户的API调用频率都有一定的限制，以防止滥用和保证平台的稳定性。如果API调用频率超过限制，API将会返回错误信息。开发者需要注意API的频率限制，并合理地安排API调用，避免触发限流。可以使用缓存或队列等技术来减少API调用次数。
- 错误处理： 建立完善的错误处理机制至关重要。当API返回错误信息时，开发者需要及时处理错误，并采取相应的措施。API返回的错误信息通常包含错误代码和错误描述，开发者可以根据这些信息来判断错误的原因，并进行修复。例如，如果API返回“余额不足”的错误，开发者可以增加账户余额或调整交易策略。
