diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c7d277..98e3260 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,21 @@ # Changelog +## 2026-05-19 + +### Added + +#### `POST /fapi/v3/chase` — Place Chase Order / 下追单 + +A new public endpoint that **places a BBO-pegged GTX limit order with automatic price tracking**. The strategy service polls each tick and re-pegs the order to `bid1 − chaseOffset` (BUY) or `ask1 + chaseOffset` (SELL). The chase auto-cancels when the market moves beyond `maxChaseOffset` from the original BBO. Supports `priceLimit`, `quantityUnit` (`BASE` / `QUOTE`), and optional `maxChaseOffset` in `ABSOLUTE` or `PERCENTAGE` units. + +### Changed + +#### `PUT /fapi/v3/order` — Modify Order: clarified BBO-pegged behavior + +Added a note that BBO-pegged orders (placed with `pegPriceType = COUNTERPARTY_1 / QUEUE_1`) cannot have their price re-resolved via plain modify — to continuously track the BBO use a Chase order (`POST /fapi/v3/chase`). + +--- + ## 2026-05-12 ### Added diff --git a/V3(Recommended)/EN/aster-finance-futures-api-testnet.md b/V3(Recommended)/EN/aster-finance-futures-api-testnet.md index 37129fb..4d88579 100644 --- a/V3(Recommended)/EN/aster-finance-futures-api-testnet.md +++ b/V3(Recommended)/EN/aster-finance-futures-api-testnet.md @@ -2190,6 +2190,9 @@ Send in a new order. | workingType | ENUM | NO | stopPrice triggered by: "MARK_PRICE", "CONTRACT_PRICE". Default "CONTRACT_PRICE" | | priceProtect | STRING | NO | "TRUE" or "FALSE", default "FALSE". Used with`STOP/STOP_MARKET` or `TAKE_PROFIT/TAKE_PROFIT_MARKET` orders. | | newOrderRespType | ENUM | NO | "ACK", "RESULT", default "ACK" | +| pegPriceType | ENUM | NO | BBO peg mode: `COUNTERPARTY_1` or `QUEUE_1`. When set on a `LIMIT` order, the engine resolves the actual price from the order book at trigger time using the BBO + `pegOffset`. Defaults to no peg. | +| pegOffset | DECIMAL | NO | Signed offset from BBO when `pegPriceType` is set. BUY orders should use a non-positive value (e.g. `-0.5`); SELL non-negative. Units: same scale as `price` (must be a `tickSize` multiple). | +| priceLimit | DECIMAL | NO | Absolute price cap for BBO-pegged orders. BUY: ceiling — peg never resolves above this; SELL: floor. Must be > 0 and a multiple of `tickSize`. Defaults to no cap. | | recvWindow | LONG | NO | | | timestamp | LONG | YES | | @@ -2290,6 +2293,79 @@ price | DECIMAL | NO | Order price * If the new `quantity` or `price` does not meet `PRICE_FILTER` / `PERCENT_FILTER` / `LOT_SIZE` restrictions, the modification will be rejected and the original order will remain. * Only `LIMIT` order type is supported. * Maximum 10000 modifications per order. +* **BBO-pegged orders** (those placed with `pegPriceType` = `COUNTERPARTY_1` / `QUEUE_1`): the engine resolves the actual price from the order book at trigger time. To auto-track the BBO with a continuously re-pegged limit order, use a **Chase order** (see `POST /fapi/v3/chase` below) which the strategy service amends in real time as the BBO moves. + +## Place Chase Order (TRADE) + +> **Response:** + +```javascript +{ + "strategyId": 12345, + "clientStrategyId": "my_chase_1", + "symbol": "BTCUSDT", + "side": "BUY", + "positionSide": "BOTH", + "quantity": "0.1", + "quantityUnit": "BASE", + "reduceOnly": false, + "chaseOffset": "0.5", + "chaseOffsetType": "ABSOLUTE", + "maxChaseOffset": "10.0", + "maxChaseOffsetType": "ABSOLUTE", + "priceLimit": "50100.00", + "timeInForce": "GTX", + "strategyStatus": "NEW", + "bookTime": 1747728000000, + "updateTime": 1747728000000 +} +``` + +``POST /fapi/v3/chase`` + +Place a **Chase strategy order** — a BBO-pegged GTX limit order that automatically re-pegs to the best bid/ask as the market moves. The strategy service polls the order book each tick and amends the order price in real time to keep the order near the top of the book until it fills or until the market moves beyond `maxChaseOffset` from the original BBO. + +**Weight:** 1 + +**Parameters:** + +| Name | Type | Mandatory | Description | +| ------------------ | ------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| symbol | STRING | YES | Trading pair. | +| side | ENUM | YES | `BUY` or `SELL`. Missing/blank returns `"Mandatory parameter 'side' was not sent, was empty/null, or malformed."` | +| positionSide | ENUM | NO | Default `BOTH` for One-way Mode; `LONG` or `SHORT` for Hedge Mode. | +| quantityUnit | STRING | YES | `BASE` (qty in base asset, e.g. BTC) or `QUOTE` (qty in quote asset, e.g. USDT). For `QUOTE` orders the system converts to BASE using mark price. | +| quantity | DECIMAL | YES | Order quantity in the unit specified by `quantityUnit`. | +| reduceOnly | STRING | NO | `"true"` or `"false"` (case-insensitive). Any other value is rejected. Default `"false"`. | +| chaseOffset | DECIMAL | NO | Distance from BBO to peg the order. Default `"0"` (exact BBO peg). Must be ≥ 0 and a multiple of `tickSize`. BUY price = `bid1 − chaseOffset`; SELL price = `ask1 + chaseOffset`. | +| chaseOffsetType | STRING | NO | `ABSOLUTE` (default) . only supports `ABSOLUTE` for now. Will support or `PERCENTAGE` latter | +| maxChaseOffset | DECIMAL | NO | Maximum tolerated distance from the original BBO before the chase auto-cancels. Required if `maxChaseOffsetType` is sent. Must be `> 0`. | +| maxChaseOffsetType | STRING | NO | `ABSOLUTE` or `PERCENTAGE` (default `ABSOLUTE` when `maxChaseOffset` is sent). `ABSOLUTE`: same unit as price, must be a multiple of `tickSize`. `PERCENTAGE`: ≤ 2 decimal places. | +| priceLimit | DECIMAL | NO | Absolute price cap. BUY: ceiling — chase never crosses above this; SELL: floor. Must be > 0 and a multiple of `tickSize`. | +| timeInForce | ENUM | NO | Default `GTX` (post-only). **`NO_FILL` is not allowed** and is rejected with `INVALID_TIF`. | +| clientStrategyId | STRING | NO | User-defined strategy id. Auto-generated if not sent. **Length ≤ 28 characters** (DB column is `varchar(28)`). Must match `^[\.A-Z\:/a-z0-9_-]{1,28}$`. | +| recvWindow | LONG | NO | | +| timestamp | LONG | YES | | + +**Validation rules:** + +* `side` is mandatory. +* `reduceOnly` accepts only `"true"` / `"false"` (case-insensitive). Any other string returns `INVALID_PARAMETER` with `reduceOnly` as the offending param name. +* `chaseOffset` must be ≥ 0 and a multiple of `tickSize`. +* `chaseOffsetType` / `maxChaseOffsetType` must be `ABSOLUTE` or `PERCENTAGE`; an invalid value returns `INVALID_PARAMETER` (not `INVALID_CHASE_OFFSET`). +* When `maxChaseOffsetType = PERCENTAGE`, the input value must have ≤ 2 decimal places (it is stored at scale 2 on the wire, e.g. `"1"` → 1.00%, `"100"` → 100.00%). +* When `maxChaseOffsetType = ABSOLUTE`, `maxChaseOffset` must be a multiple of `tickSize`. +* `timeInForce` cannot be `NO_FILL`. +* `clientStrategyId` length must be ≤ 28 characters. +* OI cap check: for `quantityUnit = QUOTE`, the gateway converts to BASE quantity for the symbol-leverage OI bracket check using `qtyBase = qtyQuote × 10^quantityDecimal / markPrice`. + +**Behavior:** + +* The initial order is placed as a GTX (post-only) limit with `pegPriceType = QUEUE_1` and signed `pegOffset` (negative for BUY, positive for SELL). +* The strategy service polls every second and amends the order price as the BBO moves, keeping the order at `bid1 − chaseOffset` (BUY) or `ask1 + chaseOffset` (SELL). +* If the market moves beyond `maxChaseOffset` from the original BBO, the chase **auto-cancels** with reason `OFFSET_CANCELLED`. +* If the new peg price would breach `priceLimit`, the chase clamps to `priceLimit` and stops further re-pegs in that direction. +* The chase terminates on FILL, user cancel (via standard `DELETE /fapi/v3/order`), `maxChaseOffset` breach, or `priceLimit` clamp + no further improvement opportunity. ## Place Multiple Orders (TRADE) diff --git a/V3(Recommended)/EN/aster-finance-futures-api-v3.md b/V3(Recommended)/EN/aster-finance-futures-api-v3.md index f19aca7..0489b33 100644 --- a/V3(Recommended)/EN/aster-finance-futures-api-v3.md +++ b/V3(Recommended)/EN/aster-finance-futures-api-v3.md @@ -2405,6 +2405,9 @@ Send in a new order. | workingType | ENUM | NO | stopPrice triggered by: "MARK_PRICE", "CONTRACT_PRICE". Default "CONTRACT_PRICE" | | priceProtect | STRING | NO | "TRUE" or "FALSE", default "FALSE". Used with`STOP/STOP_MARKET` or `TAKE_PROFIT/TAKE_PROFIT_MARKET` orders. | | newOrderRespType | ENUM | NO | "ACK", "RESULT", default "ACK" | +| pegPriceType | ENUM | NO | BBO peg mode: `COUNTERPARTY_1` or `QUEUE_1`. When set on a `LIMIT` order, the engine resolves the actual price from the order book at trigger time using the BBO + `pegOffset`. Defaults to no peg. | +| pegOffset | DECIMAL | NO | Signed offset from BBO when `pegPriceType` is set. BUY orders should use a non-positive value (e.g. `-0.5`); SELL non-negative. Units: same scale as `price` (must be a `tickSize` multiple). | +| priceLimit | DECIMAL | NO | Absolute price cap for BBO-pegged orders. BUY: ceiling — peg never resolves above this; SELL: floor. Must be > 0 and a multiple of `tickSize`. Defaults to no cap. | Additional mandatory parameters based on `type`: @@ -2504,6 +2507,77 @@ price | DECIMAL | NO | Order price * If the new `quantity` or `price` does not meet `PRICE_FILTER` / `PERCENT_FILTER` / `LOT_SIZE` restrictions, the modification will be rejected and the original order will remain. * Only `LIMIT` order type is supported. * Maximum 10000 modifications per order. +* **BBO-pegged orders** (those placed with `pegPriceType` = `COUNTERPARTY_1` / `QUEUE_1`): the engine resolves the actual price from the order book at trigger time. To auto-track the BBO with a continuously re-pegged limit order, use a **Chase order** (see `POST /fapi/v3/chase` below) which the strategy service amends in real time as the BBO moves. + +## Place Chase Order (TRADE) + +> **Response:** + +```javascript +{ + "strategyId": 12345, + "clientStrategyId": "my_chase_1", + "symbol": "BTCUSDT", + "side": "BUY", + "positionSide": "BOTH", + "quantity": "0.1", + "quantityUnit": "BASE", + "reduceOnly": false, + "chaseOffset": "0.5", + "chaseOffsetType": "ABSOLUTE", + "maxChaseOffset": "10.0", + "maxChaseOffsetType": "ABSOLUTE", + "priceLimit": "50100.00", + "timeInForce": "GTX", + "strategyStatus": "NEW", + "bookTime": 1747728000000, + "updateTime": 1747728000000 +} +``` + +``POST /fapi/v3/chase`` + +Place a **Chase strategy order** — a BBO-pegged GTX limit order that automatically re-pegs to the best bid/ask as the market moves. The strategy service polls the order book each tick and amends the order price in real time to keep the order near the top of the book until it fills or until the market moves beyond `maxChaseOffset` from the original BBO. + +**Weight:** 1 + +**Parameters:** + +| Name | Type | Mandatory | Description | +| ------------------ | ------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| symbol | STRING | YES | Trading pair. | +| side | ENUM | YES | `BUY` or `SELL`. Missing/blank returns `"Mandatory parameter 'side' was not sent, was empty/null, or malformed."` | +| positionSide | ENUM | NO | Default `BOTH` for One-way Mode; `LONG` or `SHORT` for Hedge Mode. | +| quantityUnit | STRING | YES | `BASE` (qty in base asset, e.g. BTC) or `QUOTE` (qty in quote asset, e.g. USDT). For `QUOTE` orders the system converts to BASE using mark price. | +| quantity | DECIMAL | YES | Order quantity in the unit specified by `quantityUnit`. | +| reduceOnly | STRING | NO | `"true"` or `"false"` (case-insensitive). Any other value is rejected. Default `"false"`. | +| chaseOffset | DECIMAL | NO | Distance from BBO to peg the order. Default `"0"` (exact BBO peg). Must be ≥ 0 and a multiple of `tickSize`. BUY price = `bid1 − chaseOffset`; SELL price = `ask1 + chaseOffset`. | +| chaseOffsetType | STRING | NO | `ABSOLUTE` (default). only supports `ABSOLUTE` for now. Will support or `PERCENTAGE` latter later. | +| maxChaseOffset | DECIMAL | NO | Maximum tolerated distance from the original BBO before the chase auto-cancels. Required if `maxChaseOffsetType` is sent. Must be `> 0`. | +| maxChaseOffsetType | STRING | NO | `ABSOLUTE` or `PERCENTAGE` (default `ABSOLUTE` when `maxChaseOffset` is sent). `ABSOLUTE`: same unit as price, must be a multiple of `tickSize`. `PERCENTAGE`: ≤ 2 decimal places. | +| priceLimit | DECIMAL | NO | Absolute price cap. BUY: ceiling — chase never crosses above this; SELL: floor. Must be > 0 and a multiple of `tickSize`. | +| timeInForce | ENUM | NO | Default `GTX` (post-only). **`NO_FILL` is not allowed** and is rejected with `INVALID_TIF`. | +| clientStrategyId | STRING | NO | User-defined strategy id. Auto-generated if not sent. **Length ≤ 28 characters** (DB column is `varchar(28)`). Must match `^[\.A-Z\:/a-z0-9_-]{1,28}$`. | + +**Validation rules:** + +* `side` is mandatory. +* `reduceOnly` accepts only `"true"` / `"false"` (case-insensitive). Any other string returns `INVALID_PARAMETER` with `reduceOnly` as the offending param name. +* `chaseOffset` must be ≥ 0 and a multiple of `tickSize`. +* `chaseOffsetType` / `maxChaseOffsetType` must be `ABSOLUTE` or `PERCENTAGE`; an invalid value returns `INVALID_PARAMETER` (not `INVALID_CHASE_OFFSET`). +* When `maxChaseOffsetType = PERCENTAGE`, the input value must have ≤ 2 decimal places (it is stored at scale 2 on the wire, e.g. `"1"` → 1.00%, `"100"` → 100.00%). +* When `maxChaseOffsetType = ABSOLUTE`, `maxChaseOffset` must be a multiple of `tickSize`. +* `timeInForce` cannot be `NO_FILL`. +* `clientStrategyId` length must be ≤ 28 characters. +* OI cap check: for `quantityUnit = QUOTE`, the gateway converts to BASE quantity for the symbol-leverage OI bracket check using `qtyBase = qtyQuote × 10^quantityDecimal / markPrice`. + +**Behavior:** + +* The initial order is placed as a GTX (post-only) limit with `pegPriceType = QUEUE_1` and signed `pegOffset` (negative for BUY, positive for SELL). +* The strategy service polls every second and amends the order price as the BBO moves, keeping the order at `bid1 − chaseOffset` (BUY) or `ask1 + chaseOffset` (SELL). +* If the market moves beyond `maxChaseOffset` from the original BBO, the chase **auto-cancels** with reason `OFFSET_CANCELLED`. +* If the new peg price would breach `priceLimit`, the chase clamps to `priceLimit` and stops further re-pegs in that direction. +* The chase terminates on FILL, user cancel (via standard `DELETE /fapi/v3/order`), `maxChaseOffset` breach, or `priceLimit` clamp + no further improvement opportunity. ## Place Multiple Orders (TRADE) diff --git "a/V3(Recommended)/\344\270\255\346\226\207/aster-finance-futures-api-testnet_CN.md" "b/V3(Recommended)/\344\270\255\346\226\207/aster-finance-futures-api-testnet_CN.md" index 2254320..a26b7d8 100644 --- "a/V3(Recommended)/\344\270\255\346\226\207/aster-finance-futures-api-testnet_CN.md" +++ "b/V3(Recommended)/\344\270\255\346\226\207/aster-finance-futures-api-testnet_CN.md" @@ -2359,6 +2359,9 @@ timeInForce | ENUM | NO | 有效方法 workingType | ENUM | NO | stopPrice 触发类型: `MARK_PRICE`(标记价格), `CONTRACT_PRICE`(合约最新价). 默认 `CONTRACT_PRICE` priceProtect | STRING | NO | 条件单触发保护："TRUE","FALSE", 默认"FALSE". 仅 `STOP`, `STOP_MARKET`, `TAKE_PROFIT`, `TAKE_PROFIT_MARKET` 需要此参数 newOrderRespType | ENUM | NO | "ACK", "RESULT", 默认 "ACK" +pegPriceType | ENUM | NO | BBO peg 模式: `COUNTERPARTY_1` 或 `QUEUE_1`。在 `LIMIT` 订单上设置此参数后，撮合引擎在触发时基于订单簿的 BBO 加 `pegOffset` 解析实际价格。默认不使用 peg。 +pegOffset | DECIMAL | NO | 当 `pegPriceType` 已设置时，相对 BBO 的有符号偏移量。买单应为非正值（如 `-0.5`），卖单为非负值。单位与 `price` 相同，必须是 `tickSize` 的倍数。 +priceLimit | DECIMAL | NO | BBO peg 订单的绝对价格上下限。买单：上限——peg 不会高于此；卖单：下限。必须 > 0 且为 `tickSize` 倍数。默认无限制。 根据 order `type`的不同，某些参数强制要求，具体如下: @@ -2480,6 +2483,79 @@ price | DECIMAL | NO | 委托价格 * 当新订单的quantity 或 price不满足PRICE_FILTER / PERCENT_FILTER / LOT_SIZE限制，修改会被拒绝，原订单依旧被保留 订单只支持limit类型 * 同一订单修改次数最多10000次 +* **BBO peg 订单**（使用 `pegPriceType` = `COUNTERPARTY_1` / `QUEUE_1` 下的订单）：撮合引擎在触发时从订单簿解析实际价格。普通 modify 无法改变 peg 解析后的价格。若需要持续追踪 BBO，请使用追单接口 `POST /fapi/v3/chase`。 + +## 追单 (TRADE) + +> **响应:** + +```javascript +{ + "strategyId": 12345, + "clientStrategyId": "my_chase_1", + "symbol": "BTCUSDT", + "side": "BUY", + "positionSide": "BOTH", + "quantity": "0.1", + "quantityUnit": "BASE", + "reduceOnly": false, + "chaseOffset": "0.5", + "chaseOffsetType": "ABSOLUTE", + "maxChaseOffset": "10.0", + "maxChaseOffsetType": "ABSOLUTE", + "priceLimit": "50100.00", + "timeInForce": "GTX", + "strategyStatus": "NEW", + "bookTime": 1747728000000, + "updateTime": 1747728000000 +} +``` + +``POST /fapi/v3/chase`` + +下一笔**追单策略订单** —— BBO peg GTX 限价单，自动跟随最优买/卖价重新挂单。策略服务每个 tick 轮询订单簿，实时修改委托价格，使订单保持在盘口前列，直到成交或市场偏离原始 BBO 超过 `maxChaseOffset`。 + +**权重:** 1 + +**参数:** + +| 名称 | 类型 | 是否必需 | 描述 | +| ------------------ | ------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| symbol | STRING | YES | 交易对。 | +| side | ENUM | YES | `BUY` 或 `SELL`。缺失/空值返回 `"Mandatory parameter 'side' was not sent, was empty/null, or malformed."` | +| positionSide | ENUM | NO | 单向持仓模式默认 `BOTH`；双向持仓模式必须传 `LONG` 或 `SHORT`。 | +| quantityUnit | STRING | YES | `BASE`（数量以标的资产计价，如 BTC）或 `QUOTE`（数量以计价资产计价，如 USDT）。`QUOTE` 时系统按 mark price 换算到 BASE。 | +| quantity | DECIMAL | YES | 数量，单位由 `quantityUnit` 决定。 | +| reduceOnly | STRING | NO | `"true"` 或 `"false"`（大小写不敏感）。任何其他值会被拒绝。默认 `"false"`。 | +| chaseOffset | DECIMAL | NO | 距 BBO 的偏移量。默认 `"0"`（完全贴近 BBO）。必须 ≥ 0 且为 `tickSize` 的倍数。买单价 = `bid1 − chaseOffset`；卖单价 = `ask1 + chaseOffset`。 | +| chaseOffsetType | STRING | NO | `ABSOLUTE`（默认）。v1 仅支持 `ABSOLUTE`。`PERCENTAGE` 后续支持。 | +| maxChaseOffset | DECIMAL | NO | 相对原始 BBO 允许偏移的最大距离，超出后追单自动撤销。当 `maxChaseOffsetType` 已传时必填。必须 > 0。 | +| maxChaseOffsetType | STRING | NO | `ABSOLUTE` 或 `PERCENTAGE`（默认 `ABSOLUTE`）。`ABSOLUTE`：同价格单位，必须为 `tickSize` 倍数；`PERCENTAGE`：≤ 2 位小数。 | +| priceLimit | DECIMAL | NO | 绝对价格上下限。买单：上限（追单不会高于此）；卖单：下限。必须 > 0 且为 `tickSize` 倍数。 | +| timeInForce | ENUM | NO | 默认 `GTX`（post-only）。**不允许 `NO_FILL`**，否则返回 `INVALID_TIF`。 | +| clientStrategyId | STRING | NO | 用户自定义策略 id。未传则自动生成。**长度 ≤ 28 字符**（DB 字段为 `varchar(28)`）。须满足 `^[\.A-Z\:/a-z0-9_-]{1,28}$`。 | +| recvWindow | LONG | NO | | +| timestamp | LONG | YES | | + +**校验规则:** + +* `side` 必填。 +* `reduceOnly` 仅接受 `"true"` / `"false"`（大小写不敏感）。其他值返回 `INVALID_PARAMETER`，参数名为 `reduceOnly`。 +* `chaseOffset` 必须 ≥ 0 且为 `tickSize` 倍数。 +* `chaseOffsetType` / `maxChaseOffsetType` 必须为 `ABSOLUTE` 或 `PERCENTAGE`；非法值返回 `INVALID_PARAMETER`（不再误用 `INVALID_CHASE_OFFSET`）。 +* `maxChaseOffsetType = PERCENTAGE` 时，输入值小数位数 ≤ 2（线上以 ×100 存储，如 `"1"` → 1.00%，`"100"` → 100.00%）。 +* `maxChaseOffsetType = ABSOLUTE` 时，`maxChaseOffset` 必须为 `tickSize` 倍数。 +* `timeInForce` 不允许 `NO_FILL`。 +* `clientStrategyId` 长度必须 ≤ 28 字符。 +* OI cap 校验：`quantityUnit = QUOTE` 时按 mark price 换算到 BASE 数量进行 symbol-leverage OI 档位校验，公式 `qtyBase = qtyQuote × 10^quantityDecimal / markPrice`。 + +**行为:** + +* 初始订单以 GTX（post-only）LIMIT 形式发出，`pegPriceType = QUEUE_1`、`pegOffset` 取符号（买单为负，卖单为正）。 +* 策略服务每秒轮询，将订单价格修改为 `bid1 − chaseOffset`（买单）或 `ask1 + chaseOffset`（卖单），跟随 BBO 移动。 +* 当市场偏移超过 `maxChaseOffset` 时**自动撤销**，原因为 `OFFSET_CANCELLED`。 +* 新的 peg 价若会突破 `priceLimit`，追单将 clamp 在 `priceLimit` 并在该方向停止继续追价。 +* 追单在以下情形终止：成交、用户撤单（`DELETE /fapi/v3/order`）、`maxChaseOffset` 触发、`priceLimit` clamp 且无新的优化空间。 ## 批量下单 (TRADE) diff --git "a/V3(Recommended)/\344\270\255\346\226\207/aster-finance-futures-api-v3_CN.md" "b/V3(Recommended)/\344\270\255\346\226\207/aster-finance-futures-api-v3_CN.md" index bf31e74..73f23ab 100644 --- "a/V3(Recommended)/\344\270\255\346\226\207/aster-finance-futures-api-v3_CN.md" +++ "b/V3(Recommended)/\344\270\255\346\226\207/aster-finance-futures-api-v3_CN.md" @@ -2444,6 +2444,9 @@ timeInForce | ENUM | NO | 有效方法 workingType | ENUM | NO | stopPrice 触发类型: `MARK_PRICE`(标记价格), `CONTRACT_PRICE`(合约最新价). 默认 `CONTRACT_PRICE` priceProtect | STRING | NO | 条件单触发保护："TRUE","FALSE", 默认"FALSE". 仅 `STOP`, `STOP_MARKET`, `TAKE_PROFIT`, `TAKE_PROFIT_MARKET` 需要此参数 newOrderRespType | ENUM | NO | "ACK", "RESULT", 默认 "ACK" +pegPriceType | ENUM | NO | BBO peg 模式: `COUNTERPARTY_1` 或 `QUEUE_1`。在 `LIMIT` 订单上设置此参数后，撮合引擎在触发时基于订单簿的 BBO 加 `pegOffset` 解析实际价格。默认不使用 peg。 +pegOffset | DECIMAL | NO | 当 `pegPriceType` 已设置时，相对 BBO 的有符号偏移量。买单应为非正值（如 `-0.5`），卖单为非负值。单位与 `price` 相同，必须是 `tickSize` 的倍数。 +priceLimit | DECIMAL | NO | BBO peg 订单的绝对价格上下限。买单：上限——peg 不会高于此；卖单：下限。必须 > 0 且为 `tickSize` 倍数。默认无限制。 根据 order `type`的不同，某些参数强制要求，具体如下: @@ -2565,6 +2568,77 @@ price | DECIMAL | NO | 委托价格 * 当新订单的quantity 或 price不满足PRICE_FILTER / PERCENT_FILTER / LOT_SIZE限制，修改会被拒绝，原订单依旧被保留 订单只支持limit类型 * 同一订单修改次数最多10000次 +* **BBO peg 订单**（使用 `pegPriceType` = `COUNTERPARTY_1` / `QUEUE_1` 下的订单）：撮合引擎在触发时从订单簿解析实际价格。普通 modify 无法改变 peg 解析后的价格。若需要持续追踪 BBO，请使用追单接口 `POST /fapi/v3/chase`。 + +## 追单 (TRADE) + +> **响应:** + +```javascript +{ + "strategyId": 12345, + "clientStrategyId": "my_chase_1", + "symbol": "BTCUSDT", + "side": "BUY", + "positionSide": "BOTH", + "quantity": "0.1", + "quantityUnit": "BASE", + "reduceOnly": false, + "chaseOffset": "0.5", + "chaseOffsetType": "ABSOLUTE", + "maxChaseOffset": "10.0", + "maxChaseOffsetType": "ABSOLUTE", + "priceLimit": "50100.00", + "timeInForce": "GTX", + "strategyStatus": "NEW", + "bookTime": 1747728000000, + "updateTime": 1747728000000 +} +``` + +``POST /fapi/v3/chase`` + +下一笔**追单策略订单** —— BBO peg GTX 限价单，自动跟随最优买/卖价重新挂单。策略服务每个 tick 轮询订单簿，实时修改委托价格，使订单保持在盘口前列，直到成交或市场偏离原始 BBO 超过 `maxChaseOffset`。 + +**权重:** 1 + +**参数:** + +| 名称 | 类型 | 是否必需 | 描述 | +| ------------------ | ------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| symbol | STRING | YES | 交易对。 | +| side | ENUM | YES | `BUY` 或 `SELL`。缺失/空值返回 `"Mandatory parameter 'side' was not sent, was empty/null, or malformed."` | +| positionSide | ENUM | NO | 单向持仓模式默认 `BOTH`；双向持仓模式必须传 `LONG` 或 `SHORT`。 | +| quantityUnit | STRING | YES | `BASE`（数量以标的资产计价，如 BTC）或 `QUOTE`（数量以计价资产计价，如 USDT）。`QUOTE` 时系统按 mark price 换算到 BASE。 | +| quantity | DECIMAL | YES | 数量，单位由 `quantityUnit` 决定。 | +| reduceOnly | STRING | NO | `"true"` 或 `"false"`（大小写不敏感）。任何其他值会被拒绝。默认 `"false"`。 | +| chaseOffset | DECIMAL | NO | 距 BBO 的偏移量。默认 `"0"`（完全贴近 BBO）。必须 ≥ 0 且为 `tickSize` 的倍数。买单价 = `bid1 − chaseOffset`；卖单价 = `ask1 + chaseOffset`。 | +| chaseOffsetType | STRING | NO | `ABSOLUTE`（默认）。v1 仅支持 `ABSOLUTE`。`PERCENTAGE` 后续支持。 | +| maxChaseOffset | DECIMAL | NO | 相对原始 BBO 允许偏移的最大距离，超出后追单自动撤销。当 `maxChaseOffsetType` 已传时必填。必须 > 0。 | +| maxChaseOffsetType | STRING | NO | `ABSOLUTE` 或 `PERCENTAGE`（默认 `ABSOLUTE`）。`ABSOLUTE`：同价格单位，必须为 `tickSize` 倍数；`PERCENTAGE`：≤ 2 位小数。 | +| priceLimit | DECIMAL | NO | 绝对价格上下限。买单：上限（追单不会高于此）；卖单：下限。必须 > 0 且为 `tickSize` 倍数。 | +| timeInForce | ENUM | NO | 默认 `GTX`（post-only）。**不允许 `NO_FILL`**，否则返回 `INVALID_TIF`。 | +| clientStrategyId | STRING | NO | 用户自定义策略 id。未传则自动生成。**长度 ≤ 28 字符**（DB 字段为 `varchar(28)`）。须满足 `^[\.A-Z\:/a-z0-9_-]{1,28}$`。 | + +**校验规则:** + +* `side` 必填。 +* `reduceOnly` 仅接受 `"true"` / `"false"`（大小写不敏感）。其他值返回 `INVALID_PARAMETER`，参数名为 `reduceOnly`。 +* `chaseOffset` 必须 ≥ 0 且为 `tickSize` 倍数。 +* `chaseOffsetType` / `maxChaseOffsetType` 必须为 `ABSOLUTE` 或 `PERCENTAGE`；非法值返回 `INVALID_PARAMETER`（不再误用 `INVALID_CHASE_OFFSET`）。 +* `maxChaseOffsetType = PERCENTAGE` 时，输入值小数位数 ≤ 2（线上以 ×100 存储，如 `"1"` → 1.00%，`"100"` → 100.00%）。 +* `maxChaseOffsetType = ABSOLUTE` 时，`maxChaseOffset` 必须为 `tickSize` 倍数。 +* `timeInForce` 不允许 `NO_FILL`。 +* `clientStrategyId` 长度必须 ≤ 28 字符。 +* OI cap 校验：`quantityUnit = QUOTE` 时按 mark price 换算到 BASE 数量进行 symbol-leverage OI 档位校验，公式 `qtyBase = qtyQuote × 10^quantityDecimal / markPrice`。 + +**行为:** + +* 初始订单以 GTX（post-only）LIMIT 形式发出，`pegPriceType = QUEUE_1`、`pegOffset` 取符号（买单为负，卖单为正）。 +* 策略服务每秒轮询，将订单价格修改为 `bid1 − chaseOffset`（买单）或 `ask1 + chaseOffset`（卖单），跟随 BBO 移动。 +* 当市场偏移超过 `maxChaseOffset` 时**自动撤销**，原因为 `OFFSET_CANCELLED`。 +* 新的 peg 价若会突破 `priceLimit`，追单将 clamp 在 `priceLimit` 并在该方向停止继续追价。 +* 追单在以下情形终止：成交、用户撤单（`DELETE /fapi/v3/order`）、`maxChaseOffset` 触发、`priceLimit` clamp 且无新的优化空间。 ## 批量下单 (TRADE)