API 文档

公开接口，供外部应用查询画廊数据和区块链拍卖信息

基础 URL

photo_library 画廊接口

GET /gallery/tabs 获取所有 Tab 分类

响应示例：

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "tab_key": "consensus",
      "tab_label": "The Consensus",
      "icon": "account_balance",
      "sort_order": 1,
      "status": 1
    },
    {
      "id": 2,
      "tab_key": "zrtoken",
      "tab_label": "ZR Token",
      "icon": "token",
      "sort_order": 2,
      "status": 1
    }
  ]
}

curl 请求： 

curl -X GET 'https://sandbox.bidder.club/api/gallery/tabs'
GET /gallery/artworks?tab={tab_key} 按 Tab 获取作品列表
参数： tab - Tab 标识（如 consensus, zrtoken）

响应示例：

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "title": "The Consensus #001",
      "artist": "ZRDAO",
      "year": 2024,
      "platform": "Ethereum",
      "materials": "Smart Contract",
      "contract_address": "0x...",
      "image_url": "https://...",
      "tab_type": "consensus",
      "status": 1
    }
  ]
}

curl 请求： 

curl -X GET 'https://sandbox.bidder.club/api/gallery/artworks?tab=consensus'
GET /gallery/artworks/{id} 获取作品详情
参数： id - 作品 ID
lang - 语言 (zh/en, 默认中文)

响应示例：

{
  "code": 0,
  "data": {
    "id": 1,
    "title": "The Consensus #001",
    "artist": "ZRDAO",
    "year": 2024,
    "platform": "Ethereum",
    "materials": "Smart Contract",
    "contract_address": "0x...",
    "edition": "1/1",
    "description": "...",
    "background": "...",
    "concept": "...",
    "form": "...",
    "tech_description": "...",
    "image_url": "https://...",
    "video_url": "https://...",
    "tab_type": "consensus",
    "status": 1,
    "comments": [...],
    "exhibitions": [...],
    "media_coverage": [...]
  }
}

curl 请求： 

curl -X GET 'https://sandbox.bidder.club/api/gallery/artworks/1?lang=zh'

gavel 拍卖接口

GET /auction/period?period={n} 获取拍卖状态
期数 (可选，不填为当前)

响应示例：

{
  "period": 43,
  "current_round": 43,
  "total_periods": 201,
  "is_current": true,
  "period_status": "active",
  "countdown": { "days": 0, "hours": 0, "minutes": 12, "seconds": 34 },
  "ends_at": "2025-01-15T10:30:00Z",
  "raised_eth": "1.5000",
  "participants": 10
}

curl 请求： 

curl -X GET 'https://sandbox.bidder.club/api/auction/period'
GET /auction/transactions?period={n} 获取期数交易记录
期数 (可选)
参数： period - 期数（可选）

响应示例：

{
  "period": 42,
  "total": 100,
  "data": [
    {
      "tx_hash": "0x...",
      "from_address": "0x...",
      "amount_eth": "1.5",
      "block_number": 10748000,
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ],
  "source": "database"
}

curl 请求： 

curl -X GET 'https://sandbox.bidder.club/api/auction/transactions?period=1'
GET /auction/chart?period={n}&points=31 获取完整累计 ETH 聚合曲线

数据库按区块汇总全部交易，再返回固定数量的累计点；交易数量不会截断曲线。

响应示例：

{
  "period": 26,
  "start_block": 11429068,
  "end_block": 11429367,
  "latest_block": 11429238,
  "point_count": 31,
  "transaction_count": 1300,
  "total_eth": "650.0",
  "points": [
    { "blockNumber": 11429068, "cumulative_eth": "0.0", "transaction_count": 0 }
  ]
}
GET /claimable/total?address={address} 查询用户可领取代币总额
参数： address - 用户以太坊地址

响应示例：

{
  "total": 1500.5,
  "periods": [
    { "period": 40, "amount": 500.2, "claimed": false },
    { "period": 41, "amount": 1000.3, "claimed": false }
  ]
}

curl 请求： 

curl -X GET 'https://sandbox.bidder.club/api/claimable/total?address=0x0000000000000000000000000000000000000001'

storefront 市场接口

info Seaport 配置信息

Seaport 地址 Seaport 是独立部署的，和 OpenSea 平台没有关系 0xB446252f05a36ED9AC60fB95255c5F8F19001541
WETH 地址 0x7b79995e5f793a07bc00c21412e50ecae098e7f9
官方文档 https://docs.opensea.io/reference/api-overview open_in_new
Seaport JS SDK https://www.npmjs.com/package/@opensea/seaport-js open_in_new
GET /config 获取 Seaport 配置信息

响应示例：

{
  "env": "sandbox",
  "contract": {
    "address": "0xDD9dF36038DEB0b2243d5aAc46c9CC9F2b7a5fc3",
    "genesisStartBlock": 11359300,
    "blocksPerPeriod": 300
  },
  "seaport": {
    "address": "0x19657da3a4890d6997b8b1a6e34038d019069c14",
    "wethAddress": "0x7b79995e5f793a07bc00c21412e50ecae098e7f9",
    "version": "1.6",
    "conduitKey": "0x0000000000000000000000000000000000000000000000000000000000000000"
  },
  "blockExplorer": {
    "url": "https://sepolia.etherscan.io",
    "apiUrl": "https://api-sepolia.etherscan.io"
  }
}

curl 请求： 

curl -X GET 'https://sandbox.bidder.club/api/config'
GET /marketplace/nfts 获取 NFT 列表（支持分页和筛选）
参数： (可选) 页码，默认 1
(可选) 每页数量，默认 20，最大 100
(可选) 按名称/TokenID 搜索
(可选) 合约地址筛选
(可选) 是否挂单
(可选) 是否有出价
(可选) 最低价格（ETH），仅筛选已挂单 NFT
(可选) 最高价格（ETH），仅筛选已挂单 NFT

响应示例：

{
  "code": 0,
  "data": {
    "nfts": [
      {
        "id": 21,
        "contractAddress": "0x...",
        "tokenId": "1",
        "name": "Hills",
        "description": "Test Hill",
        "imageUrl": "https://...",
        "ownerAddress": "0x...",
        "isListed": 0,
        "listingPrice": null,
        "listingTime": null,
        "listingOrder": null,
        "highestBid": "0.0",
        "attributes": [],
        "timeLastUpdated": "2026-06-08T06:47:43.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1,
      "hasMore": false
    }
  }
}

curl 请求： 

curl -X GET 'https://sandbox.bidder.club/api/marketplace/nfts'
POST /marketplace/nfts/listing 创建/更新 NFT 挂单记录
请求体 (JSON)：
(必填) 合约地址
(必填) Token ID
(必填) Seaport 订单数据
(必填) 挂牌价格 (ETH)

请求示例：

{
  "contractAddress": "0x157471ebe3f8fc1695f297145484c855fe931684",
  "tokenId": "0",
  "price": "0.002",
  "order": {
    "parameters": {
      "offerer": "0xaba6e75FDa0b7ea200CA94a3cC4f07C6F179f11f",
      "zone": "0x0000000000000000000000000000000000000000",
      "zoneHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "startTime": "1785292253",
      "endTime": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
      "orderType": 0,
      "offer": [
        {
          "itemType": 2,
          "token": "0x157471ebe3f8fc1695f297145484c855fe931684",
          "identifierOrCriteria": "0",
          "startAmount": "1",
          "endAmount": "1"
        }
      ],
      "consideration": [
        {
          "itemType": 0,
          "token": "0x0000000000000000000000000000000000000000",
          "identifierOrCriteria": "0",
          "startAmount": "2000000000000000",
          "endAmount": "2000000000000000",
          "recipient": "0xaba6e75FDa0b7ea200CA94a3cC4f07C6F179f11f"
        }
      ],
      "totalOriginalConsiderationItems": 1,
      "salt": "0x0000000000000000000000000000000000000000000000000a5eccfc4b150f50",
      "conduitKey": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "counter": "0"
    },
    "signature": "0xf32c0805c5f68eca5f0c3b0f3a260885e54db86088db6525573d30b7890ee170c33d3ca042665ca7d393724416969d2832d70fd1fe382f8f5c631b1ff7c63b5d"
  }
}

响应示例：

{
  "code": 0,
  "message": "Listing saved successfully"
}

curl 请求： 

curl -X POST 'https://sandbox.bidder.club/api/marketplace/nfts/listing' \
  -H 'Content-Type: application/json' \
  -d '{"contractAddress":"0x...","tokenId":"1","price":"0.1","order":{...}}'
GET /marketplace/offers 获取 NFT 报价列表（支持分页）
参数： (必填) 合约地址
(必填) Token ID
(可选) 页码，默认 1
(可选) 每页数量，默认 20，最大 100

响应示例：

{
  "code": 0,
  "data": {
    "offers": [
      {
        "id": 50,
        "contractAddress": "0x...",
        "tokenId": "1",
        "offerer": "0x...",
        "price": "0.001",
        "priceHex": "0x1000000000000000",
        "floorPrice": "0.003",
        "orderHash": "0x218ac1ce7aabdc6787c9223c0584cd5ffeaa9f79f249a7197a58a219395f7305",
        "orderData": {
          "signature": "0x...",
          "parameters": {...}
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1,
      "hasMore": false
    }
  }
}

curl 请求： 

curl -X GET 'https://sandbox.bidder.club/api/marketplace/offers?contractAddress=0x...&tokenId=1'

data_object 响应格式

所有接口统一响应格式：

{
  "code": 0,        // 0=成功，其他=错误
  "data": {...},    // 返回数据
  "message": ""     // 错误信息（如果有）
}

error 错误码

code 说明
0 请求成功
400 请求参数错误
401 未授权（管理接口需要认证）
404 资源不存在
500 服务器内部错误

speed 请求限制

为保证服务质量，公开接口请求频率限制为 1000 次/分钟。请合理使用缓存机制。

contact_support 联系我们

如有问题或建议，请通过以下方式联系：

share X chat GitHub