# 订单接口

## 构建下单 Calldata

```
POST /api/v1/orders/calldata
```

### 请求体

| 字段             | 类型              | 必填   | 说明                                                        |
| -------------- | --------------- | ---- | --------------------------------------------------------- |
| `stockAddress` | string          | 是    | 股票 token 合约地址，必须是有效 EVM 地址。                               |
| `side`         | string          | 是    | 订单方向。枚举：`Buy`、`Sell`。                                     |
| `type`         | string          | 是    | 订单类型。枚举：`Market`、`Limit`。                                 |
| `quantity`     | string / number | 条件必填 | 数量。限价单必填；市价卖单必填。                                          |
| `notional`     | string / number | 条件必填 | 金额。市价买单必填。                                                |
| `price`        | string / number | 条件必填 | 限价价格。限价单必填。                                               |
| `timeInForce`  | string          | 条件必填 | 限价单必填。枚举：`DAY`、`GTC`、`OPG`、`IOC`、`FOK`、`GTX`、`GTD`、`CLS`。 |
| `deadline`     | number          | 是    | 交易 deadline（Unix 秒）。≤ `4294967295`。                       |

{% hint style="info" %}
金额和数量字段建议使用**字符串**传输，避免 JavaScript number 精度损失。
{% endhint %}

### 市价买单示例

```json
{
  "stockAddress": "0x0000000000000000000000000000000000000001",
  "side": "Buy",
  "type": "Market",
  "notional": "10",
  "deadline": 1893456000
}
```

### 限价卖单示例

```json
{
  "stockAddress": "0x0000000000000000000000000000000000000001",
  "side": "Sell",
  "type": "Limit",
  "quantity": "1.25",
  "price": "180.50",
  "timeInForce": "DAY",
  "deadline": 1893456000
}
```

### 返回 `data`

| 字段            | 类型     | 说明                                      |
| ------------- | ------ | --------------------------------------- |
| `chainId`     | number | 链 ID。                                   |
| `productType` | string | 产品类型。                                   |
| `toAddress`   | string | Router 合约地址。                            |
| `value`       | string | Native token 数量，当前返回 `"0"`。             |
| `callData`    | string | ABI 编码后的 calldata。                      |
| `method`      | string | `placeMarketOrder` 或 `placeLimitOrder`。 |

***

## One Click 代发下单

```
POST /api/v1/orders/send
```

请求体与 `/orders/calldata` 相同，另支持：

| 字段         | 类型     | 必填 | 说明                           |
| ---------- | ------ | -- | ---------------------------- |
| `gasLimit` | number | 否  | 指定 gas limit。为空或 ≤ 0 时服务端估算。 |

**前置条件：** API Key 必须已配置 `userAddress`，One Click 必须已启用。

***

## 记录下单 TxHash

```
POST /api/v1/orders/tx
```

| 字段       | 类型     | 必填 | 说明              |
| -------- | ------ | -- | --------------- |
| `txHash` | string | 是  | 已提交到链上的交易 hash。 |

***

## 查询订单

### 查询订单映射列表

```
GET /api/v1/orders?page=1&limit=10
```

### 按 TxHash 查询

```
GET /api/v1/orders/tx/{txHash}
```

### 按订单 ID 查询

```
GET /api/v1/orders/{orderId}
```

`orderId` 必须属于当前 API Key 记录过的交易映射。

### 订单详情字段

**openOrder：**

| 字段              | 类型     | 说明                       |
| --------------- | ------ | ------------------------ |
| `orderId`       | string | 链上订单 ID。                 |
| `userAddress`   | string | 用户地址。                    |
| `side`          | string | `Buy` 或 `Sell`。          |
| `type`          | string | `Market` 或 `Limit`。      |
| `tif`           | string | Time in force。           |
| `symbol`        | string | 标的 symbol。               |
| `placeNotional` | string | 下单金额。                    |
| `placeQuantity` | string | 下单数量。                    |
| `pay`           | string | 支付数量。                    |
| `placePrice`    | string | 下单价格。                    |
| `status`        | string | `placing` 或 `canceling`。 |

**historyOrder 额外字段：**

| 字段              | 类型            | 说明            |
| --------------- | ------------- | ------------- |
| `settleTxHash`  | string / null | 结算交易 hash。    |
| `settlePrice`   | string        | 成交价格。         |
| `settlePay`     | string / null | 实际支付数量。       |
| `settleReceive` | string / null | 实际收到数量。       |
| `mintFee`       | string        | Mint fee。     |
| `protocolFee`   | string        | Protocol fee。 |

***

## 撤销限价单

### 构建撤单 Calldata

```
DELETE /api/v1/orders/{orderId}/calldata?deadline=1893456000
```

{% hint style="warning" %}
路径参数 `orderId` 必须是 bytes32 hex（64 字符）。
{% endhint %}

### One Click 代发撤单

```
DELETE /api/v1/orders/{orderId}/send?deadline=1893456000
```

返回 `uuid` 和 `txHash`。

### 撤单前置条件

* 订单必须属于当前 API Key
* 订单必须仍在 open 状态
* 只能撤销限价单
* 订单尚未提交过撤单请求
* API Key 的 `userAddress` 必须与订单用户地址一致


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.anchored.finance/trading-api-docs-zh/api-jie-kou/orders.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.