# 现货接口

## POST /v1/spots/orders

> 创建一个现货订单

```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://dex-api.benpay.com","description":"Default Server URL"}],"paths":{"/v1/spots/orders":{"post":{"tags":["spots-api-controller"],"summary":"创建一个现货订单","operationId":"spotsOrderCreateRequest","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"clientOrderId":{"type":"string","description":"客户端自定义OrderID，可不填"},"type":{"type":"string","description":"订单类型: LIMIT=限价单, MARKET=市价单","enum":["LIMIT","MARKET"]},"direction":{"type":"string","description":"订单方向：LONG, SHORT","enum":["LONG","SHORT"]},"symbol":{"type":"string","description":"订单交易对，例如：XBTC"},"price":{"type":"number","description":"订单价格"},"quantity":{"type":"number","description":"订单数量"},"fillOrKill":{"type":"boolean","description":"FOK（Fill or Kill）标志：完全成交或全部取消"},"immediateOrCancel":{"type":"boolean","description":"IOC（Immediate or Cancel）标志：立即执行或取消"},"postOnly":{"type":"boolean","description":"PostOnly标志：仅做市"},"hidden":{"type":"boolean","description":"Hidden标志：是否隐藏"}}}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"string"}}}}}}}}}
```

## POST /v1/spots/orders/{idOrSymbol}/cancel

> 取消指定ID或symbol的订单

```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://dex-api.benpay.com","description":"Default Server URL"}],"paths":{"/v1/spots/orders/{idOrSymbol}/cancel":{"post":{"tags":["spots-api-controller"],"summary":"取消指定ID或symbol的订单","operationId":"spotsOrderCancel","parameters":[{"name":"idOrSymbol","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"string"}}}}}}}}}
```

## GET /v1/spots/orders/{orderId}

> 根据ID查询订单

```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://dex-api.benpay.com","description":"Default Server URL"}],"paths":{"/v1/spots/orders/{orderId}":{"get":{"tags":["spots-api-controller"],"summary":"根据ID查询订单","operationId":"spotsOrderGetById","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"请求是否成功"},"data":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"clientOrderId":{"type":"string","description":"自定义ID"},"sequenceId":{"type":"integer","format":"int64"},"baseCurrencyId":{"type":"integer","format":"int64"},"quoteCurrencyId":{"type":"integer","format":"int64"},"userId":{"type":"integer","format":"int64"},"symbolId":{"type":"integer","format":"int64"},"quantity":{"type":"number"},"unfilledQuantity":{"type":"number","description":"没有匹配的订单数量"},"type":{"type":"string","description":"订单类型: LIMIT=限价单, MARKET=市价单","enum":["LIMIT","MARKET"]},"status":{"type":"string","description":"订单状态，注意：PENDING、PARTIAL_FILLED状态不是最终状态，其它状态是最终状态，不再变化: PENDING=订单尚无任何成交, FAILED=下单失败, FULLY_FILLED=订单已完全成交, PARTIAL_FILLED=订单有部分成交并继续等待成交, PARTIAL_CANCELLED=订单有部分成交并已取消, FULLY_CANCELLED=订单无成交并已被全部取消, LIQUIDATE_CANCELLED=（仅限合约订单）订单因准备爆仓被取消","enum":["PENDING","FAILED","FULLY_FILLED","PARTIAL_FILLED","PARTIAL_CANCELLED","FULLY_CANCELLED","LIQUIDATE_CANCELLED"]},"direction":{"type":"string","enum":["LONG","SHORT"]},"features":{"type":"integer","format":"int32"},"fillPrice":{"type":"number"},"price":{"type":"number"},"makerFeeRate":{"type":"number"},"takerFeeRate":{"type":"number"},"fee":{"type":"number"},"createdAt":{"type":"integer","format":"int64"},"updatedAt":{"type":"integer","format":"int64"},"immediateOrCancel":{"type":"boolean","description":"是否是IoC订单"},"fillOrKill":{"type":"boolean","description":"是否是FoK订单"},"postOnly":{"type":"boolean","description":"是否是PostOnly订单"},"symbol":{"type":"string","description":"订单交易对名称"},"finalStatus":{"type":"boolean","description":"订单状态是否固定并不会再变化"}},"description":"响应数据，如果请求失败则为null"},"error":{"type":"string","description":"如果请求失败，指示错误代码"},"errorField":{"type":"string","description":"如果请求失败，指示出错的字段"},"errorMessage":{"type":"string","description":"如果请求失败，指示详细错误信息"}}}}}}}}}}}
```

## GET /v1/spots/orders/{orderId}/matches

> 根据ID查询订单的成交详情

```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://dex-api.benpay.com","description":"Default Server URL"}],"paths":{"/v1/spots/orders/{orderId}/matches":{"get":{"tags":["spots-api-controller"],"summary":"根据ID查询订单的成交详情","operationId":"spotsOrderGetMatchDetails","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"请求是否成功"},"data":{"type":"array","description":"响应数据，如果请求失败则为null","items":{"type":"object","properties":{"taker":{"type":"boolean","description":"是否taker"},"price":{"type":"number"},"quantity":{"type":"number"},"fee":{"type":"number"},"createdAt":{"type":"integer","format":"int64"}},"description":"响应数据，如果请求失败则为null"}},"error":{"type":"string","description":"如果请求失败，指示错误代码"},"errorField":{"type":"string","description":"如果请求失败，指示出错的字段"},"errorMessage":{"type":"string","description":"如果请求失败，指示详细错误信息"}}}}}}}}}}}
```

## GET /v1/spots/orders/open

> 查询所有活动订单

```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://dex-api.benpay.com","description":"Default Server URL"}],"paths":{"/v1/spots/orders/open":{"get":{"tags":["spots-api-controller"],"summary":"查询所有活动订单","operationId":"spotsOrderGetOpens","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"请求是否成功"},"data":{"type":"array","description":"响应数据，如果请求失败则为null","items":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"clientOrderId":{"type":"string","description":"自定义ID"},"sequenceId":{"type":"integer","format":"int64"},"baseCurrencyId":{"type":"integer","format":"int64"},"quoteCurrencyId":{"type":"integer","format":"int64"},"userId":{"type":"integer","format":"int64"},"symbolId":{"type":"integer","format":"int64"},"quantity":{"type":"number"},"unfilledQuantity":{"type":"number","description":"没有匹配的订单数量"},"type":{"type":"string","description":"订单类型: LIMIT=限价单, MARKET=市价单","enum":["LIMIT","MARKET"]},"status":{"type":"string","description":"订单状态，注意：PENDING、PARTIAL_FILLED状态不是最终状态，其它状态是最终状态，不再变化: PENDING=订单尚无任何成交, FAILED=下单失败, FULLY_FILLED=订单已完全成交, PARTIAL_FILLED=订单有部分成交并继续等待成交, PARTIAL_CANCELLED=订单有部分成交并已取消, FULLY_CANCELLED=订单无成交并已被全部取消, LIQUIDATE_CANCELLED=（仅限合约订单）订单因准备爆仓被取消","enum":["PENDING","FAILED","FULLY_FILLED","PARTIAL_FILLED","PARTIAL_CANCELLED","FULLY_CANCELLED","LIQUIDATE_CANCELLED"]},"direction":{"type":"string","enum":["LONG","SHORT"]},"features":{"type":"integer","format":"int32"},"fillPrice":{"type":"number"},"price":{"type":"number"},"makerFeeRate":{"type":"number"},"takerFeeRate":{"type":"number"},"fee":{"type":"number"},"createdAt":{"type":"integer","format":"int64"},"updatedAt":{"type":"integer","format":"int64"},"immediateOrCancel":{"type":"boolean","description":"是否是IoC订单"},"fillOrKill":{"type":"boolean","description":"是否是FoK订单"},"postOnly":{"type":"boolean","description":"是否是PostOnly订单"},"symbol":{"type":"string","description":"订单交易对名称"},"finalStatus":{"type":"boolean","description":"订单状态是否固定并不会再变化"}},"description":"响应数据，如果请求失败则为null"}},"error":{"type":"string","description":"如果请求失败，指示错误代码"},"errorField":{"type":"string","description":"如果请求失败，指示出错的字段"},"errorMessage":{"type":"string","description":"如果请求失败，指示详细错误信息"}}}}}}}}}}}
```

## GET /v1/spots/orders/open/{orderId}

> 根据ID查询活动订单

```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://dex-api.benpay.com","description":"Default Server URL"}],"paths":{"/v1/spots/orders/open/{orderId}":{"get":{"tags":["spots-api-controller"],"summary":"根据ID查询活动订单","operationId":"spotsOrderGetOpenById","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"请求是否成功"},"data":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"clientOrderId":{"type":"string","description":"自定义ID"},"sequenceId":{"type":"integer","format":"int64"},"baseCurrencyId":{"type":"integer","format":"int64"},"quoteCurrencyId":{"type":"integer","format":"int64"},"userId":{"type":"integer","format":"int64"},"symbolId":{"type":"integer","format":"int64"},"quantity":{"type":"number"},"unfilledQuantity":{"type":"number","description":"没有匹配的订单数量"},"type":{"type":"string","description":"订单类型: LIMIT=限价单, MARKET=市价单","enum":["LIMIT","MARKET"]},"status":{"type":"string","description":"订单状态，注意：PENDING、PARTIAL_FILLED状态不是最终状态，其它状态是最终状态，不再变化: PENDING=订单尚无任何成交, FAILED=下单失败, FULLY_FILLED=订单已完全成交, PARTIAL_FILLED=订单有部分成交并继续等待成交, PARTIAL_CANCELLED=订单有部分成交并已取消, FULLY_CANCELLED=订单无成交并已被全部取消, LIQUIDATE_CANCELLED=（仅限合约订单）订单因准备爆仓被取消","enum":["PENDING","FAILED","FULLY_FILLED","PARTIAL_FILLED","PARTIAL_CANCELLED","FULLY_CANCELLED","LIQUIDATE_CANCELLED"]},"direction":{"type":"string","enum":["LONG","SHORT"]},"features":{"type":"integer","format":"int32"},"fillPrice":{"type":"number"},"price":{"type":"number"},"makerFeeRate":{"type":"number"},"takerFeeRate":{"type":"number"},"fee":{"type":"number"},"createdAt":{"type":"integer","format":"int64"},"updatedAt":{"type":"integer","format":"int64"},"immediateOrCancel":{"type":"boolean","description":"是否是IoC订单"},"fillOrKill":{"type":"boolean","description":"是否是FoK订单"},"postOnly":{"type":"boolean","description":"是否是PostOnly订单"},"symbol":{"type":"string","description":"订单交易对名称"},"finalStatus":{"type":"boolean","description":"订单状态是否固定并不会再变化"}},"description":"响应数据，如果请求失败则为null"},"error":{"type":"string","description":"如果请求失败，指示错误代码"},"errorField":{"type":"string","description":"如果请求失败，指示出错的字段"},"errorMessage":{"type":"string","description":"如果请求失败，指示详细错误信息"}}}}}}}}}}}
```

## GET /v1/spots/orders/closed

> 按月查询历史订单

```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://dex-api.benpay.com","description":"Default Server URL"}],"paths":{"/v1/spots/orders/closed":{"get":{"tags":["spots-api-controller"],"summary":"按月查询历史订单","operationId":"spotsOrderGetClosed","parameters":[{"name":"range","in":"query","description":"查询范围，如2025年2月传入：202502","required":false,"schema":{"type":"string"}},{"name":"symbol","in":"query","description":"交易对名称","required":false,"schema":{"type":"string"}},{"name":"fromMillis","in":"query","description":"起始时间毫秒数","required":false,"schema":{"type":"number","default":"0"}},{"name":"toMillis","in":"query","description":"结束时间毫秒数","required":false,"schema":{"type":"number","default":"0"}},{"name":"offsetId","in":"query","description":"订单id偏移量(上次查询返回的nextOffsetId)","required":false,"schema":{"type":"number","default":"0"}},{"name":"limit","in":"query","description":"分页大小","required":false,"schema":{"type":"number","default":"0"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"请求是否成功"},"data":{"type":"object","properties":{"hasMore":{"type":"boolean","description":"是否存在下一页"},"nextOffsetId":{"type":"integer","description":"下一页起始查询ID","format":"int64"},"results":{"type":"array","description":"当前页数据","items":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"clientOrderId":{"type":"string","description":"自定义ID"},"sequenceId":{"type":"integer","format":"int64"},"baseCurrencyId":{"type":"integer","format":"int64"},"quoteCurrencyId":{"type":"integer","format":"int64"},"userId":{"type":"integer","format":"int64"},"symbolId":{"type":"integer","format":"int64"},"quantity":{"type":"number"},"unfilledQuantity":{"type":"number","description":"没有匹配的订单数量"},"type":{"type":"string","description":"订单类型: LIMIT=限价单, MARKET=市价单","enum":["LIMIT","MARKET"]},"status":{"type":"string","description":"订单状态，注意：PENDING、PARTIAL_FILLED状态不是最终状态，其它状态是最终状态，不再变化: PENDING=订单尚无任何成交, FAILED=下单失败, FULLY_FILLED=订单已完全成交, PARTIAL_FILLED=订单有部分成交并继续等待成交, PARTIAL_CANCELLED=订单有部分成交并已取消, FULLY_CANCELLED=订单无成交并已被全部取消, LIQUIDATE_CANCELLED=（仅限合约订单）订单因准备爆仓被取消","enum":["PENDING","FAILED","FULLY_FILLED","PARTIAL_FILLED","PARTIAL_CANCELLED","FULLY_CANCELLED","LIQUIDATE_CANCELLED"]},"direction":{"type":"string","enum":["LONG","SHORT"]},"features":{"type":"integer","format":"int32"},"fillPrice":{"type":"number"},"price":{"type":"number"},"makerFeeRate":{"type":"number"},"takerFeeRate":{"type":"number"},"fee":{"type":"number"},"createdAt":{"type":"integer","format":"int64"},"updatedAt":{"type":"integer","format":"int64"},"immediateOrCancel":{"type":"boolean","description":"是否是IoC订单"},"fillOrKill":{"type":"boolean","description":"是否是FoK订单"},"postOnly":{"type":"boolean","description":"是否是PostOnly订单"},"symbol":{"type":"string","description":"订单交易对名称"},"finalStatus":{"type":"boolean","description":"订单状态是否固定并不会再变化"}},"description":"响应数据，如果请求失败则为null"}},"range":{"type":"string","description":"查询范围(数据分片)"}},"description":"响应数据，如果请求失败则为null"},"error":{"type":"string","description":"如果请求失败，指示错误代码"},"errorField":{"type":"string","description":"如果请求失败，指示出错的字段"},"errorMessage":{"type":"string","description":"如果请求失败，指示详细错误信息"}}}}}}}}}}}
```

## GET /v1/spots/match/clearings

> 分页查询用户订单的清算记录

```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://dex-api.benpay.com","description":"Default Server URL"}],"paths":{"/v1/spots/match/clearings":{"get":{"tags":["spots-api-controller"],"summary":"分页查询用户订单的清算记录","operationId":"matchClearingsGetByRange","parameters":[{"name":"range","in":"query","description":"查询范围(数据分片)","required":false,"schema":{"type":"string"}},{"name":"symbol","in":"query","description":"交易对名称","required":false,"schema":{"type":"string"}},{"name":"direction","in":"query","description":"方向.LONG/SHORT/空字符串","required":false,"schema":{"type":"string"}},{"name":"fromMillis","in":"query","description":"起始时间毫秒数","required":false,"schema":{"type":"number","default":"0L"}},{"name":"toMillis","in":"query","description":"结束时间毫秒数","required":false,"schema":{"type":"number","default":"0L"}},{"name":"offsetId","in":"query","description":"订单id偏移量(上次查询返回的nextOffsetId)","required":false,"schema":{"type":"number","default":"0"}},{"name":"limit","in":"query","description":"分页大小","required":false,"schema":{"type":"number","default":"0"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"请求是否成功"},"data":{"type":"object","properties":{"hasMore":{"type":"boolean","description":"是否存在下一页"},"nextOffsetId":{"type":"integer","description":"下一页起始查询ID","format":"int64"},"results":{"type":"array","description":"当前页数据","items":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"orderId":{"type":"integer","format":"int64"},"userId":{"type":"integer","format":"int64"},"sequenceId":{"type":"integer","format":"int64"},"direction":{"type":"string","description":"方向 LONG SHORT","enum":["LONG","SHORT"]},"type":{"type":"string","description":"现货清算类型: MAKER=订单以Maker成交, TAKER=订单以Taker成交, CANCELLED=取消订单","enum":["MAKER","TAKER","CANCELLED"]},"matchPrice":{"type":"number"},"matchQuantity":{"type":"number"},"orderStatusAfterClearing":{"type":"string","description":"订单状态，注意：PENDING、PARTIAL_FILLED状态不是最终状态，其它状态是最终状态，不再变化: PENDING=订单尚无任何成交, FAILED=下单失败, FULLY_FILLED=订单已完全成交, PARTIAL_FILLED=订单有部分成交并继续等待成交, PARTIAL_CANCELLED=订单有部分成交并已取消, FULLY_CANCELLED=订单无成交并已被全部取消, LIQUIDATE_CANCELLED=（仅限合约订单）订单因准备爆仓被取消","enum":["PENDING","FAILED","FULLY_FILLED","PARTIAL_FILLED","PARTIAL_CANCELLED","FULLY_CANCELLED","LIQUIDATE_CANCELLED"]},"orderUnfilledQuantityAfterClearing":{"type":"number"},"feeCurrency":{"type":"string"},"fee":{"type":"number"},"rate":{"type":"number"},"createdAt":{"type":"integer","format":"int64"},"symbol":{"type":"string"}},"description":"当前页数据"}},"range":{"type":"string","description":"查询范围(数据分片)"}},"description":"响应数据，如果请求失败则为null"},"error":{"type":"string","description":"如果请求失败，指示错误代码"},"errorField":{"type":"string","description":"如果请求失败，指示出错的字段"},"errorMessage":{"type":"string","description":"如果请求失败，指示详细错误信息"}}}}}}}}}}}
```

## GET /v1/spots/fee/rate

> 查询现货交易手续费率

```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://dex-api.benpay.com","description":"Default Server URL"}],"paths":{"/v1/spots/fee/rate":{"get":{"tags":["spots-api-controller"],"summary":"查询现货交易手续费率","operationId":"spotsFeeRateQuery","parameters":[{"name":"symbol","in":"query","required":false,"schema":{"type":"string","default":""}},{"name":"timestamp","in":"query","required":false,"schema":{"type":"integer","format":"int64","default":0}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"请求是否成功"},"data":{"type":"object","properties":{"taker":{"type":"number"},"maker":{"type":"number"},"timestamp":{"type":"integer","format":"int64"}},"description":"响应数据，如果请求失败则为null"},"error":{"type":"string","description":"如果请求失败，指示错误代码"},"errorField":{"type":"string","description":"如果请求失败，指示出错的字段"},"errorMessage":{"type":"string","description":"如果请求失败，指示详细错误信息"}}}}}}}}}}}
```

## GET /v1/spots/balances

> 查询现货余额

```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://dex-api.benpay.com","description":"Default Server URL"}],"paths":{"/v1/spots/balances":{"get":{"tags":["spots-api-controller"],"summary":"查询现货余额","operationId":"balances","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"请求是否成功"},"data":{"type":"object","additionalProperties":{"type":"array","description":"响应数据，如果请求失败则为null","items":{"type":"number","description":"响应数据，如果请求失败则为null"}},"description":"响应数据，如果请求失败则为null"},"error":{"type":"string","description":"如果请求失败，指示错误代码"},"errorField":{"type":"string","description":"如果请求失败，指示出错的字段"},"errorMessage":{"type":"string","description":"如果请求失败，指示详细错误信息"}}}}}}}}}}}
```
