> For the complete documentation index, see [llms.txt](https://bitlong.gitbook.io/api-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bitlong.gitbook.io/api-doc/tapd-api/nftpresale-trade-rest-api.md).

# NftPresale trade REST API

NFT预售

### 0.数据说明

~~**\[2024-10-14 17:52:18]** 增加`image_data`~~

**\[2024-10-15 10:58:12]** 删除`image_data`，新增`meta_str`，所有查询接口更新

**\[2024-10-21 09:42:36]** 新增 `whitelist` ，接口逻辑调整

* `asset_id` <mark style="color:orange;">string</mark> 资产ID
* `name` <mark style="color:orange;">string</mark> 资产名称
* `asset_type` <mark style="color:orange;">string</mark> 资产类型

  <mark style="background-color:yellow;">Collectible</mark>为收藏品(NFT)
* `meta` <mark style="color:orange;">string</mark> 资产元数据
* `group_key` <mark style="color:orange;">string</mark> 集合Key，组键
* `amount` <mark style="color:orange;">int</mark> 数量(固定为1)
* `price` <mark style="color:orange;">int</mark> 价格(单位：聪)
* `info` <mark style="color:orange;">string</mark> 预售上架信息
* `buyer_user_id` <mark style="color:orange;">int</mark> 购买用户ID
* `buyer_username` <mark style="color:orange;">string</mark> 购买用户名
* `buyer_device_id` <mark style="color:orange;">string</mark> 购买设备ID
* `receive_addr` <mark style="color:orange;">string</mark> 资产接收地址
* `addr_script_key` <mark style="color:orange;">string</mark> 接收地址脚本密钥
* `addr_internal_key` <mark style="color:orange;">string</mark> 接收地址内部密钥
* `pay_method` <mark style="color:orange;">int</mark> 支付方式

  <mark style="background-color:yellow;">0</mark>为托管账户支付
* `launch_time` <mark style="color:orange;">int</mark> 上架时间(时间戳，单位秒)
* start\_time <mark style="color:orange;">int</mark> 预售开始时间(时间戳，单位秒)
* end\_time <mark style="color:orange;">int</mark> 预售结束时间(时间戳，单位秒，为0时无结束时间，永续出售)
* `bought_time` <mark style="color:orange;">int</mark> 购买时间(时间戳，单位秒)
* `paid_id` <mark style="color:orange;">int</mark> 支付ID
* `paid_success_time` <mark style="color:orange;">int</mark> 支付成功时间(时间戳，单位秒)
* `sent_time` <mark style="color:orange;">int</mark> 资产发送时间(时间戳，单位秒)
* `sent_txid` <mark style="color:orange;">string</mark> 发送交易ID
* `sent_outpoint` <mark style="color:orange;">string</mark> 发送输出点
* `sent_address` <mark style="color:orange;">string</mark> 发送btc地址
* `state` <mark style="color:orange;">int</mark> 阶段(状态)

  <mark style="background-color:yellow;">0</mark>已上架

  <mark style="background-color:yellow;">1</mark>已购买未支付

  <mark style="background-color:yellow;">2</mark>支付中

  <mark style="background-color:yellow;">3</mark>已支付未发送

  <mark style="background-color:yellow;">4</mark>发送中

  <mark style="background-color:yellow;">5</mark>已发送

  <mark style="background-color:yellow;">-1</mark>已失败或已取消
* `process_number` <mark style="color:orange;">int</mark> 处理次数
* `meta_str` <mark style="color:orange;">string</mark> 元数据字符串(JSON)
* `whitelist` <mark style="color:orange;">Array</mark> 白名单

#### 数据示例

**\[2024-10-21 09:42:36]** 更新

```json
{"success":true,"error":"","code":200,"data":[{"ID":1,"UpdatedAt":"2024-10-18T17:37:02.42+08:00","batch_group_id":1,"asset_id":"29fc8c4b71005ea9020ff483ce1198a97150668270f60184646a4bce6744510d","name":"t2","asset_type":"Collectible","meta":"test2","group_key":"021691138b1bccce7cedb36b94dad23e09d14155e3fed726fde770eb822d14c9ca","amount":1,"price":10001,"info":"info","buyer_user_id":0,"buyer_username":"","buyer_device_id":"","receive_addr":"","addr_script_key":"","addr_internal_key":"","pay_method":0,"launch_time":1729244222,"start_time":1729243700,"end_time":0,"bought_time":0,"paid_id":0,"paid_success_time":0,"sent_time":0,"sent_txid":"","sent_outpoint":"","sent_address":"","state":0,"process_number":0,"is_re_launched":false,"meta_str":"","whitelist":["npub2xshj1SiifN1uMk2NgkwayYGp3CJw9tvoYozPM8yGs5QtQTmviQBf1ZDBiv72FjjaGQUibv87C4n7ShfcZ9DN9Wi"]}]}
```

### 1.查询批次集合

<mark style="color:green;">`GET`</mark> `/nft_presale/query/batch_group`

**\[2024-10-21 09:42:36]** 新增接口

#### Query参数

`state` <mark style="color:orange;">string</mark> 集合状态(阶段)

* `0` 全部
* `1` 进行中
* `2` 未开始
* `3` 已结束

示例

`/nft_presale/query/batch_group?state=1`

#### 响应

`ID` <mark style="color:orange;">int</mark> 批次集合ID

`group_key` <mark style="color:orange;">string</mark> 集合Key，组键

`group_name` <mark style="color:orange;">string</mark> 集合名，组名

`sold_number` <mark style="color:orange;">int</mark> NFT已售量

`supply` <mark style="color:orange;">int</mark> NFT总量

`lowest_price` <mark style="color:orange;">int</mark> 最低价格(单位：聪)

`highest_price` <mark style="color:orange;">int</mark> 最高价格(单位：聪)

`start_time` <mark style="color:orange;">int</mark> 预售开始时间(时间戳，单位秒)

`end_time` <mark style="color:orange;">int</mark> 预售结束时间(时间戳，单位秒，为0时无结束时间，永续出售)

`info` <mark style="color:orange;">string</mark> 预售上架信息

`first_asset_id` <mark style="color:orange;">string</mark> 首个资产ID(用于查找图片)

```json
{"success":true,"error":"","code":200,"data":[{"ID":1,"UpdatedAt":"2024-11-15T16:01:30.037+08:00","group_key":"0331b3a7db997c7081a81841e9bfc80798ab9cd8853be266a177dd66d2ebf9035a","group_name":"BitLong","sold_number":0,"supply":11,"lowest_price":120000,"highest_price":120000,"start_time":1731643200,"end_time":0,"info":"BitLong钱包创世NFT","first_asset_id":"a66c6d264a778641141fc57c1674367ac025d41dcfed8a2cd1c39331e622e982"}]}
```

### 2.通过批次集合ID查询NFT

<mark style="color:green;">`GET`</mark> `/nft_presale/get/batch_group_id`

**\[2024-10-21 09:42:36]** 新增接口

#### 参数

`batch_group_id` <mark style="color:orange;">int</mark> 批次集合ID

`no_meta` <mark style="color:orange;">bool</mark> 是否不返回元数据

`no_whitelist` <mark style="color:orange;">bool</mark> 是否不返回白名单

示例

`/nft_presale/get/batch_group_id?batch_group_id=1&no_meta=true&no_whitelist=false`

#### 响应

```json
{"success":true,"error":"","code":200,"data":[{"ID":1,"UpdatedAt":"2024-10-18T17:37:02.42+08:00","batch_group_id":1,"asset_id":"29fc8c4b71005ea9020ff483ce1198a97150668270f60184646a4bce6744510d","name":"t2","asset_type":"Collectible","meta":"test2","group_key":"021691138b1bccce7cedb36b94dad23e09d14155e3fed726fde770eb822d14c9ca","amount":1,"price":10001,"info":"info","buyer_user_id":0,"buyer_username":"","buyer_device_id":"","receive_addr":"","addr_script_key":"","addr_internal_key":"","pay_method":0,"launch_time":1729244222,"start_time":1729243700,"end_time":0,"bought_time":0,"paid_id":0,"paid_success_time":0,"sent_time":0,"sent_txid":"","sent_outpoint":"","sent_address":"","state":0,"process_number":0,"is_re_launched":false,"meta_str":"","whitelist":["npub2xshj1SiifN1uMk2NgkwayYGp3CJw9tvoYozPM8yGs5QtQTmviQBf1ZDBiv72FjjaGQUibv87C4n7ShfcZ9DN9Wi"]}]}
```

### 3.购买NFT

<mark style="color:orange;">`POST`</mark> `/nft_presale/buy`

#### 参数

JSON

* `asset_id` <mark style="color:orange;">string</mark> 资产ID
* `receive_addr` <mark style="color:orange;">string</mark> 资产接收地址
* `device_id` <mark style="color:orange;">string</mark> 设备ID

```json
{
    "asset_id": "1fe21af350cb6d335b35680ad8517bcdeb75e7580ea49181b1f7b09917f1092f",
    "receive_addr": "taprt1qqqszqspqqzzq8lzrte4pjmdxddn26q2mpghhn0twhn4sr4yjxqmraasnytlzzf0q5ssxjcuh6fjfguktwjq94cph70jegj0ff6kjnz6927y4226tvfexqp7qcssylgexc4qy6xvfu2m076lt4rqkw53wasdlz494qtkzgc24ua8h9yjpqss8h9l3r9h0pdwzwu0pzxhq5jelvf3fcqcqs73x2zmydcrlwwx9aczpgqszrppw4hxjan9wfek2unsvvaz7te3xvezuv3nxghrzvpe9curgw3cxs6rx3hwjm3",
    "device_id": "alice_test_device"
}
```

#### 响应

```json
{"success":true,"error":"","code":0,"data":null}
```

### 4.用户购买记录

<mark style="color:green;">`GET`</mark> `/nft_presale/get/user_bought`

#### 参数

`no_meta` <mark style="color:orange;">bool</mark> 是否不返回元数据

`no_whitelist` <mark style="color:orange;">bool</mark> 是否不返回白名单

示例

`/nft_presale/get/user_bought?no_meta=true&no_whitelist=true`

#### 响应

```json
{"success":true,"error":"","code":200,"data":[{"ID":2,"UpdatedAt":"2024-10-11T17:20:20.044+08:00","asset_id":"1fe21af350cb6d335b35680ad8517bcdeb75e7580ea49181b1f7b09917f1092f","name":"tfpst0_s02","asset_type":"Collectible","meta":"test nft presale","group_key":"034b1cbe9324a3965ba402d701bf9f2ca24f4a75694c5a2abc4aa95a5b1393003e","amount":1,"price":10001,"info":"No.1","buyer_user_id":373,"buyer_username":"alice","buyer_device_id":"alice_test_device","receive_addr":"taprt1qqqszqspqqzzq8lzrte4pjmdxddn26q2mpghhn0twhn4sr4yjxqmraasnytlzzf0q5ssxjcuh6fjfguktwjq94cph70jegj0ff6kjnz6927y4226tvfexqp7qcssylgexc4qy6xvfu2m076lt4rqkw53wasdlz494qtkzgc24ua8h9yjpqss8h9l3r9h0pdwzwu0pzxhq5jelvf3fcqcqs73x2zmydcrlwwx9aczpgqszrppw4hxjan9wfek2unsvvaz7te3xvezuv3nxghrzvpe9curgw3cxs6rx3hwjm3","addr_script_key":"027d19362a0268cc4f15b7fb5f5d460b3a917760df8aa5a81761230aaf3a7b9492","addr_internal_key":"03dcbf88cb7785ae13b8f088d705259fb1314e018043d13285b23703fb9c62f702","pay_method":0,"launch_time":1728637510,"bought_time":1728637863,"paid_id":130,"paid_success_time":1728637900,"sent_time":1728638101,"sent_txid":"c937fcfd60bcb01039d22b02368e79d764eb11dfc8ba7934756881af7c14252d","sent_outpoint":"c937fcfd60bcb01039d22b02368e79d764eb11dfc8ba7934756881af7c14252d:1","sent_address":"bcrt1ppy2sas3mjfclfyuzdjs45edufz90qhl83v4nv8aw5nhyuggyvrxssy2q62","state":5,"process_number":0,"is_re_launched":false,"meta_str":"","whitelist":[]}]}
```

### 5.按资产ID查询NFT

<mark style="color:green;">`GET`</mark> `/nft_presale/get/asset_id`

*该接口可能实际不会使用*

#### Query参数

`asset_id` <mark style="color:orange;">string</mark> 资产ID

`no_meta` <mark style="color:orange;">bool</mark> 是否不返回元数据

`no_whitelist` <mark style="color:orange;">bool</mark> 是否不返回白名单

示例

`/nft_presale/get/asset_id?asset_id=737139bfbadbc7ac7ca6e39ac05f8890604a1593ab78e6d279c50ad6a98f7cb0&no_meta=true&no_whitelist=false`

#### 响应

```json
{"success":true,"error":"","code":200,"data":{"ID":1,"UpdatedAt":"2024-10-18T17:37:02.42+08:00","batch_group_id":1,"asset_id":"29fc8c4b71005ea9020ff483ce1198a97150668270f60184646a4bce6744510d","name":"t2","asset_type":"Collectible","meta":"test2","group_key":"021691138b1bccce7cedb36b94dad23e09d14155e3fed726fde770eb822d14c9ca","amount":1,"price":10001,"info":"info","buyer_user_id":0,"buyer_username":"","buyer_device_id":"","receive_addr":"","addr_script_key":"","addr_internal_key":"","pay_method":0,"launch_time":1729244222,"start_time":1729243700,"end_time":0,"bought_time":0,"paid_id":0,"paid_success_time":0,"sent_time":0,"sent_txid":"","sent_outpoint":"","sent_address":"","state":0,"process_number":0,"is_re_launched":false,"meta_str":"","whitelist":["npub2xshj1SiifN1uMk2NgkwayYGp3CJw9tvoYozPM8yGs5QtQTmviQBf1ZDBiv72FjjaGQUibv87C4n7ShfcZ9DN9Wi"]}}
```