01 · 当前游戏合约
BNB Smart Chain 主网 · Chain ID 56 · ERC-721 · 主网公开测试阶段。
已铸造与未领取预留的共同上限为 2,000,000 份 NFT，100 个品种。上限不代表已铸造数量；当前归属以合约 ownerOf(tokenId) 为准，累计铸造量通过 totalSupply() 读取。
NFT 没有任何经济价值属性，仅作为收藏娱乐。本页面不提供价格、收益或交易承诺。
02 · 从合约读取元数据
当前合约的 tokenURI(tokenId) 返回 data:application/json;base64,...。将逗号后的内容按 Base64 解码，即为 UTF-8 JSON。它不是需要再次 HTTP 请求的网页地址。
元数据由合约直接生成，PNG 图片存放在网站。当前图片未发布到 IPFS，不能将其描述为图片完全上链。此文档不会修改合约或 NFT 属性。
function tokenURI(uint256 tokenId) view returns (string) function ownerOf(uint256 tokenId) view returns (address) function totalSupply() view returns (uint256)
当前系列的领取与元数据
每 200 个区块最多预留 50 份鱼获。未领取记录是合约中的鱼获权益，尚未铸造成钱包 NFT；只有玩家领取成功后才可读取对应 Token ID 的 tokenURI。总额度 200 万份包含已领取与未领取预留，totalAllocated() 表示已分配量，totalSupply() 表示已铸造量。
可运行的 Node.js 示例
npm install ethers@6 node read-nft.mjs 18
示例核验 chainId，读取同一区块的元数据与持有人，不需要私钥，不发送交易。18 是示例 NFT 编号，接入时替换为目标编号。公共 RPC 限流或不可用时，应退避重试或更换可信 BNB RPC。
本版本没有 /api/nft/{tokenId} HTTP 元数据代理。请调用合约的标准方法；钱包也应以链上返回的元数据为准。
03 · 完整卡片图片接口
GET https://bnbfish.trade/nft-images/{speciesId}.png
# 七星鱼（品种 1018）
GET https://bnbfish.trade/nft-images/1018.png图片格式 image/png，尺寸 900 × 1200，纵横比 3:4，包含鱼类图像、背景与稀有度卡框。同品种复用一张卡图；每份 NFT 的编号、体长、重量等来自自己的链上元数据。
tokenId 是 NFT 编号，speciesId 是品种编号，两者不能混用。例如先读取已领取 NFT 的 Species ID，再使用相应品种的图片；不能直接请求 /nft-images/18.png。
目录包含 speciesId、中文名称、评级、发行上限、图片地址、尺寸及 SHA-256。目录中的图片哈希仅用于本次发布文件的核对，不是合约锁定的图片哈希；存在卡图不代表该品种已经铸造。
img { aspect-ratio: 3 / 4; object-fit: contain; }请保持图片原比例，避免拉伸、裁切卡框。图片 URL 使用 HTTPS，无需登录或签名。
04 · JSON 字段与评级
标准顶层字段为 name、description、image、attributes。名称以 tokenURI 的实际返回值为准，例如 Bnbfish #18；中文鱼名可按品种目录补充展示，勿将补充标签当作原始链上字段。
| attributes.trait_type | 类型 / 单位 | 含义 |
|---|---|---|
| Species ID | 整数 | 品种编号，关联目录 |
| Rarity | 整数 0–4 | 评级，见下表 |
| Length mm | 整数 / 毫米 | 该份鱼获体长 |
| Mass grams | 整数 / 克 | 该份鱼获重量 |
| Quality bps | 整数 / 基点 | 品质值；6000 表示 60.00% |
| Water | 整数 0–2 | 钓获水域编号 |
| Caught at | Unix 秒 | 钓获时间；display_type 为 date。JS Date 需乘以 1000 |
评级与总发行上限
| Rarity | 评级 | 目录值 | 上限 |
|---|---|---|---|
| 0 | 普通 | common | 1,200,000 份 |
| 1 | 稀有 | rare | 500,000 份 |
| 2 | 珍稀 | precious | 150,000 份 |
| 3 | 罕见 | exceptional | 100,000 份 |
| 4 | 极其罕见 | legendary | 50,000 份 |
05 · 钱包与索引器接入
- 核对 chainId 56 和本页合约地址，使用 ERC-721
Transfer事件索引所属资产。 - 铸造事件的
from是零地址；普通转账不会产生新鱼获。需要当前持有人时读取ownerOf，不要把持有人与原始钓获者混淆。 - 读取并解码
tokenURI，使用 JSON 内的image下载完整卡片。 - 缓存图片和元数据；处理链重组与转账事件，刷新归属。不要仅凭网站图片判断 NFT 是否存在。
- 钱包未展示时，尝试导入 BNB 网络上的合约与 NFT 编号，并按钱包支持的方式刷新元数据。系列收录、认证及展示仍由各钱包决定。
如需游戏全局鱼获信息，可读取 GET /api/global-catches：范围为当前合约，约 12 秒共享缓存，快照延后 3 个区块，包含 total（已锁定鱼获总数，含未领取）、unclaimed（未领取）、claimed（已领取）、species（含预留的鱼种统计）、latest（最近领取）与 stale。未完成验证的垂钓不计入鱼获；领取仅将未领取转为已领取，不增加总数。这是统计辅助接口，不能替代链上资产归属核验。
06 · 缓存与常见问题
- 不存在的 NFT：
tokenURI/ownerOf会回退（ERC721NonexistentToken）。不能返回虚构的默认 NFT。 - 图片返回 404：核对品种编号和路径，勿用 tokenId 代替 speciesId。错误响应不应按图片或元数据解析。
- RPC 限流：检查错误内容，降低并发并退避重试。不要把读取失败视为 NFT 已不存在。
- 鱼讯返回 503 或 stale=true：表示读取暂不可用或缓存延迟，保留上次有效数据并提示延迟。
- 图片更新：以 HTTP 的 Cache-Control、ETag / Last-Modified 为准；钱包可能保留自己的缓存，不保证即时刷新。
- 浏览器跨域：同源页面可直接读取；第三方后端可公开抓取。当前不承诺所有路径都有 CORS，第三方网页使用 fetch 或 Canvas 读取图片像素前需检查响应头。
- 收藏卡存储：当前依赖网站域名及托管。发布本页不等于已迁移 IPFS，也不等于钱包已收录认证。