API接口文档

接口及参数解释

获取订单 nonce

每个用户有一个 nonce 计数器,获取 nonce 后,在调用创建订单接口时传入

请求

GET /api/v1/orders/nonce

query参数:

参数描述
address用户 Eth 地址 例如:0x70997970C51812dc3A010C7d01b50e0d17dc79C8

响应

{
    "code": 0,
    "message": "ok",
    "data": {
        "nonce": 1
    }
}

查询订单

请求

POST /api/v1/orders/query
请求示例:

{
  "is_order_ask": true,
  "collection": "0xBcDF0Bf9B8DF0ffB0cB51A03eFb4D3C151B6aA3F",
  "token_id": "15",
  "signer": "0x584eCa68d1d96EBeBA9e9b4dafa495a30e69A5C8",
  "strategy": "0xFDaA0FD4123D7969FEDD836Ca2DaFCba954Ad1C7",
  "currency": "0xAFCA295144c6203cCe03b5932D8299Fc4fcdcBbe",
  "price": {
    "min": "123000000000000000",
    "max": "133000000000000000"
  },
  "start_time": 1656768852,
  "end_time": 1656788852,
  "statuses": [
    "VALID"
  ],
  "sort": "NEWEST",
  "pagination": {
    "first": 0,
    "cursor": ""
  }
}

参数说明:

参数描述
is_order_ask是否挂单,取值为 true 即挂单,取值为 false 即 make offer
collection合集地址
token_id合集中对应token的id
signer签名地址
strategy交易策略合约的地址,目前交易策略仅支持一口价
currency交易货币合约地址。除了 ETH,目前仅支持 WETH,即便挂单是使用的 ETH(报价只能用 WETH),currency 也使用 WETH 地址
price价格,单位为 wei
start_time订单有效时间-起始时间戳
end_time订单有效时间-结束时间戳
statuses订单状态。取值范围为 VALID, EXPIRED, EXECUTED, CANCELLED
sort排序,取值范围为 NEWEST, PRICE_ASC, PRICE_DSC, EXPIRE_SOON
pagination分页,first 为需要查询的记录数量;cursor 为查询的起始记录

响应示例:

{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "id": 1,
      "status": "VALID",
      "token_id": "15",
      "collection": "0xcf645b5b5c1127fadbaac59bb50dcd874fa6fc33",
      "signer": "0xa56035ecc91cfd275685481f79ec95806eea9a85",
      "strategy": "0xd73FA81ff6Eba3bc324fF2401c1D9ff78Dbb0eDF",
      "currency": "0xc778417E063141139Fce010982780140Aa0cD5Ab",
      "is_order_ask": false,
      "nonce": 2,
      "amount": 1,
      "price": "123000000000000000",
      "start_time": 1656768852,
      "end_time": 1657373631,
      "min_percentage_to_ask": 8500,
      "params": "0x",
      "hash": "0x704d5cad4b8525665c32e7bfff0ff173842307fd55db6521e38c1ec0e2a98b98",
      "signature": "0x3da7e46cbb7c124eb140727b914ddc766ee045e0279928502f0cc2bbc34eebe4574ed47592b73b16819c7b75a7fa2a81e716155b4d6b59bf4c5b8286aade9d981b"
    }
  ],
  "pagination": {
    "cursor": "IjIwMjItMDctMDFUMDk6Mjk6NTYuMzIwNTcxWiI=",
    "has_next": true
  }
}

创建订单(挂单/报价)

即 MakerOrder,调用后端服务保存订单

请求

POST /api/v1/orders

{
  "token_id": "15",
  "collection": "0xcf645b5b5c1127fadbaac59bb50dcd874fa6fc33",
  "signer": "0xa56035ecc91cfd275685481f79ec95806eea9a85",
  "strategy": "0xd73FA81ff6Eba3bc324fF2401c1D9ff78Dbb0eDF", // 交易策略合约地址
  "currency": "0xc778417E063141139Fce010982780140Aa0cD5Ab", // 交易货币合约地址
  "is_order_ask": true,                                     // 是否挂单
  "nonce": 2,                                               // 从 /api/v1/orders/nonce 获取
  "amount": 1,                                              // 数量
  "price": "123000000000000000",
  "start_time": 1656768852,                                // 订单有效时间-起始时间戳,需 <= now()
  "end_time": 1657373631,                                  // 订单有效时间-结束时间戳,需 > now()
  "min_percentage_to_ask": 8500,
  "params": "0x",                                         // 额外参数,目前恒为空 "0x" 
  "signature": "0x3da7e46cbb7c124eb140727b914ddc766ee045e0279928502f0cc2bbc34eebe4574ed47592b73b16819c7b75a7fa2a81e716155b4d6b59bf4c5b8286aade9d981b"    // EIP712签名,对上面所有的字段签名
}

参数:

参数描述
token_id合集中对应token的id
collection合集地址
signer签名地址
strategy交易策略合约的地址, 目前交易策略仅支持一口价
currency交易货币合约地址。除了 ETH,目前仅支持 WETH,即便挂单是使用的 ETH(报价只能用 WETH),currency 也使用 WETH 地址
is_order_ask是否挂单,取值为 true/false
nonce从 /api/v1/orders/nonce 获取返回值
amount数量,取值为1,对1个nft进行挂单/报价
price价格,单位为 wei
start_time订单有效时间-起始时间戳,需 <= now()
end_time订单有效时间-结束时间戳,需 > now() + 10 min
min_percentage_to_ask转给卖方的最低百分比,8500意为85%
params其他参数,暂未使用,取值 "0x" 即可
signatureEIP712签名,对上面所有的字段签名

响应

响应示例:

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": 1,
    "status": "VALID",
    "token_id": "15",
    "collection": "0xcf645b5b5c1127fadbaac59bb50dcd874fa6fc33",
    "signer": "0xa56035ecc91cfd275685481f79ec95806eea9a85",
    "strategy": "0xd73FA81ff6Eba3bc324fF2401c1D9ff78Dbb0eDF",
    "currency": "0xc778417E063141139Fce010982780140Aa0cD5Ab",
    "is_order_ask": false,
    "nonce": 2,
    "amount": 1,
    "price": "123000000000000000",
    "start_time": 1656768852,
    "end_time": 1657373631,
    "min_percentage_to_ask": 8500,
    "params": "0x",
    "hash": "0x704d5cad4b8525665c32e7bfff0ff173842307fd55db6521e38c1ec0e2a98b98",
    "signature": "0x3da7e46cbb7c124eb140727b914ddc766ee045e0279928502f0cc2bbc34eebe4574ed47592b73b16819c7b75a7fa2a81e716155b4d6b59bf4c5b8286aade9d981b"
  }
}

订单EIP712签名

ethers.js 实现参考:

let domain = {
    name: "ApeNftExchange",
    version: "1",
    chainId: 1,                   // eth: 1, rinkeby: 4
    verifyingContract: "0x...",   // <ApeNftExchange> address
}
const EIP712DataTypes = {
    "MakerOrder": [
        {"name": "isOrderAsk", "type": "bool"},
        {"name": "signer", "type": "address"},
        {"name": "collection", "type": "address"},
        {"name": "price", "type": "uint256"},
        {"name": "tokenId", "type": "uint256"},
        {"name": "amount", "type": "uint256"},
        {"name": "strategy", "type": "address"},
        {"name": "currency", "type": "address"},
        {"name": "nonce", "type": "uint256"},
        {"name": "startTime", "type": "uint256"},
        {"name": "endTime", "type": "uint256"},
        {"name": "minPercentageToAsk", "type": "uint256"},
        {"name": "params", "type": "bytes"}
    ]
}
// 构造 MakerOrder, e.g.
    let makerOrder = {
        isOrderAsk: true,
        signer: "0x...",
        collection: "0x...",
        price: 100000000000,       // 单位 wei
        tokenId: 1,
        amount: 1,
        strategy: "0x...",
        currency: "0x...",
        nonce: 1,
        startTime: 1652534300,
        endTime: 1662534300,
        minPercentageToAsk: 8500,
        params: "0x",
    }
 
// EIP712签名
let signature = await signer._signTypedData(domain, EIP712DataTypes, makerOrder)
 
// 获取签名的 R S V
let signparts = ethers.utils.splitSignature(signature)
let sig_r = signparts.r
let sig_s = signparts.s
let sig_v = signparts.v