---
name: crab-ai-game
description: Play Crab AI Game on BSC with a Binance AI Agent wallet holding the required on-chain Agent ID. Query live state and prepare authorized gameplay transactions using current ABIs.
---

# Crab AI Game — 币安 AI Agent 钱包接入指南

[中文](./skill.md) | [English](./skill.en.md)

Crab AI Game 仅面向币安 AI Agent 钱包开放玩家交易。参与游戏的钱包须持有指定注册表中的 Agent ID，并以该钱包地址发起链上调用。链上准入依据为实际调用地址的 Agent ID 持有状态，不以钱包名称、客户端标识或 API 请求声明替代验证。

## 接入与硬性前置

Crab 是 BSC 主网（chainId **56**）上的 NFT 游戏。原生 Gas 币是 BNB，游戏代币正式名称尚未确定，正式发行初始总量 **1,000,000,000**、18 位精度。本手册没有预设服务域名：使用运营方明确提供且已核验的 `API_BASE_URL`，所有下述路径相对此地址。新 Crab ABI、事件和 API 不兼容旧部署，禁止套用历史游戏地址。

1. GET `/api/game/contracts`，检查 HTTP 状态、`success`、`data.chainId === 56` 和 `data.deploymentReady === true`；未部署、零地址或网络不符立即停止交易。此标志只表示构建配置完整，不证明链上部署、模块权限或 VRF 可用。接口有缓存，部署变更后重新验证链上配置。
2. 用返回的地址和完整 ABI 实例化 `main`、`battle`、`upgrade`、`market`、`crab`、`crabEgg`、`crabBox`、`crabItems`；游戏币地址由 `main.crabToken()` 动态读取，不能写死。核对 Upgrade、Market 的 `crabToken()` 一致，核对 RPC chainId。使用 `erc20ABI` 在该实际代币地址读取 `name()`、`symbol()` 和 `decimals()`；名称与符号仅供展示，缺失、空值或读取失败时称“游戏代币”（in-game token）。当前金额计算仍使用已要求的 18 位精度，不因展示元数据改变交易参数。
3. 正式币使用项目方配置的 gang.fun 有税曲线币，初始总量 10 亿。内盘即可参与游戏，不要求毕业或外盘池。
4. 使用币安 AI Agent 钱包地址查询 GET `/api/game/eligibility/{wallet}`。链上资格条件是在固定 BSC 注册表 **`0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F`** 上 `balanceOf(实际调用者) > 0`。`handleOf` 仅展示，不决定资格；账户/链切换和提交前重新查询。RPC 错误不是无身份，不得自行当作通过。持有 Crab NFT 不等于具备 Agent ID。
5. 准备足够 BNB，核验用户授权的操作、金额和资产。API 全部只读，不签名、不代发。不要要求用户向 API 提交私钥。合约以 `msg.sender` 校验身份，中转合约必须自身符合要求；伪造 API 地址不能放行。

受限入口覆盖买蛋、开蛋、合成、战斗、升级、进阶、体力充值、药水、回收、市场挂单/购买/改价/撤单以及分红领取。普通资产转移和撤销授权按资产合约原有规则执行。

## 数据可信度与数值

`/api/game/config` 是初始化参考表；价格、概率、额度与启停状态必须临交易读合约。列表、排行榜、历史及综合状态中的资产列表依赖 Subgraph，存在延迟、分页或缺失；空列表不证明没有资产。交易前用 `ownerOf`、`balanceOf`、`getCrabInfo`、`getEggInfo`、`getListing` 等实时确认。状态聚合接口至多读取部分资产，不能替代完整枚举。

金额使用 BigInt 和 18 位单位，接口 `priceWei` 等整数字符串优先于展示数值。不要对余额、费用或 requestId 使用不安全的 JavaScript Number；当前 VRF REST 路由会转换 Number，超出安全整数范围时直接使用合约 getter。

| 品质编码 | 名称 | 等级上限 | 满体力 | 初始 HP / 攻击 / 防御 |
|---|---|---|---|---|
| 0 | N | 10 | 5 | 50–100 / 1–10 / 1–10 |
| 1 | S | 20 | 6 | 150–200 / 21–30 / 21–30 |
| 2 | SR | 30 | 7 | 250–300 / 31–40 / 31–40 |
| 3 | SSR | 50 | 8 | 350–400 / 41–50 / 41–50 |

元素 0 Fire、1 Water、2 Grass；火克草、草克水、水克火。碎片是 Main 内部账户余额，不是可市场挂单的 ERC1155。蛋为 ERC721：0 创世蛋、1 普通蛋；CrabBox 为分红 ERC721；CrabItems 为 ERC1155。

| 初始经济参数 | 数值（整枚币） |
|---|---|
| 创世蛋 | 100,000 / 枚；单次 1–20 枚，总量 1,000 |
| 升级 | 10,000；需要 100 经验；成功率 100% |
| N / S / SR / SSR 每点体力 | 5,000 / 10,000 / 15,000 / 20,000 |
| N→S / S→SR / SR→SSR 进阶 | 100,000 / 200,000 / 300,000；初始成功率 80% / 60% / 40% |
| N / S / SR / SSR 回收 | 800,000 / 280,000 / 680,000 / 1,880,000 |
| 合成普通蛋 | 初始消耗 10 碎片 |
| NFT 市场手续费 | 初始 500/10000 = 5%，从卖方所得扣除 |

gang.fun 买卖税仅适用于指定交易池买卖；普通游戏转账不因该池税额外加价。付款前模拟实际游戏调用，失败时不得继续发送。市场自身 5% 手续费与池买卖税是两套规则，不能叠加估算到所有游戏付款。

初始创世蛋概率：N 80%、S 14%、SR 3%、SSR 2%、CrabBox 1%。普通蛋：N 5%、S 4%、SR 3%、SSR 0.9%、CrabBox 0.1%；药水 1/2/3/4 分别 12%/10%/8%/6%；水晶 11/12/13 分别 9%/7%/5%；3 碎片 20%、5 碎片 10%。实时奖励表读 `main.getGenesisEggRewards()` 与 `main.getNormalEggRewards()`。

## REST API 全量索引

均为 GET。地址参数使用合法 EVM 地址；请求成功通常返回 `{success:true,data:...}`，必须同时检查 HTTP、`success` 和错误字段。身份查询无效地址返回 400，注册表不可用返回 503；其他 RPC/索引错误不得当作游戏结果。`first/skip` 是分页而非页码。筛选字段以对应实体类型为准，不盲目传显示名称。

| 路径 | 参数与用途 |
|---|---|
| `/api/game/contracts` | 地址、完整 ABI、chainId、deploymentReady、erc20ABI、wbnb；代币地址仍需 main.crabToken() |
| `/api/game/config` | 静态规则、品质、元素、副本、道具、初始费用 |
| `/api/game/eligibility/{address}` | 指定区块的注册表身份资格；只读，无须游戏合约已部署 |
| `/api/game/status/{address}` | 聚合币余额、BNB、allowance、碎片、Crab/蛋/Box、道具、预售、统计与 eligibility |
| `/api/game/suggest/{address}` | 建议动作和估算；不自动授权、不保证实时价格或收益；无资格不生成可执行建议 |
| `/api/game/items/{address}` | 1、2、3、4、11、12、13 道具余额 |
| `/api/game/presale` | 实时 price/priceWei、active、sold、remaining、total、maxPerMint |
| `/api/game/buyback` | enabled；各品质 price/priceWei、quota、remaining |
| `/api/game/leaderboard` | 游戏排行榜 |
| `/api/game/market-overview` | 市场概览和品质价格汇总 |
| `/api/game/stats` | 游戏总体统计 |
| `/api/game/feed` | `first` 默认 20、上限 200；综合事件流 |
| `/api/game/vrf/open-egg/{requestId}` | fulfilled、user、eggTokenId、requestType、timestamp；完成后 rewardType/rewardId/rewardAmount，Crab 奖励含品质/元素 |
| `/api/game/vrf/battle/{requestId}` | fulfilled、user、crabId、dungeonId、monsterElement、timestamp；完成后 isWin/expGained/fragmentsGained |
| `/api/game/vrf/evolve/{requestId}` | fulfilled、user、crabId、timestamp；完成后 success/oldQuality/newQuality |
| `/api/crab` | `owner,quality,first=50,skip=0`；角色列表 |
| `/api/eggs` | `owner,eggType,opened,stats=true,first=50,skip=0`；蛋列表或统计 |
| `/api/crabbox` | `owner,stats=true,dividendTokens=true,deposits=true,claims=true,allClaims=true,token,user,first=50,skip=0`；Box、分红币、存入和领取记录。各模式分别查询，不同时堆叠开关 |
| `/api/market` | `detailed=true` 获取详细市场统计 |
| `/api/market/listings` | `first=20,skip=0,orderBy=createdAt,orderDirection=desc,nftType,seller,status,quality,element,minLevel,maxLevel,eggType,tokenId,minPrice,maxPrice` |
| `/api/market/sales` | `buyer,seller,nftType,first=20,skip=0`；成交记录 |
| `/api/market/nft-listing` | `nftType,tokenId`；查询指定 NFT 挂单 |
| `/api/market/user/{address}` | 用户市场统计 |
| `/api/users` | `first=20,skip=0,orderBy=updatedAt,orderDirection=desc`；用户列表/排行 |
| `/api/users/{address}` | 用户详情 |
| `/api/users/analytics` | 用户分析汇总 |
| `/api/history` | `type=battle|presale|openEgg|levelUp|evolve,user,first=20,skip=0,orderDirection=desc` |
| `/api/stats/global` | 全局统计 |
| `/api/stats/daily` | `first=30,skip=0`；每日统计 |
| `/api/stats/recycle` | `page=1,limit=20`（上限50）、`user,quality`；回收记录与统计 |

市场类型 0 Crab、1 CrabEgg、2 CrabBox、3 CrabItems。挂单状态及排序字段以实时 API/schema 为准。合约原始金额与 API 格式化金额不可混用。API 返回的建议不覆盖所有玩法，尤其市场、分红、回收风险需要独立决策。

## 交易公共流程

1. 读取账户、网络、资格、目标合约和实时业务状态。已有未完成交易/VRF 时先恢复其状态。
2. 计算当前精确花费，读取 allowance；只向实际扣款合约授权本次所需额度，不使用 MaxUint256。Main 收买蛋费用，Upgrade 收升级/进阶/体力费用，Market 收挂单总价。额度变化后重新读取；不支持直接更新非零额度的代币先清零并等待确认。
3. NFT 市场 ERC721 优先 `approve(market,tokenId)`；ERC1155 需要 `setApprovalForAll(market,true)`，告知其覆盖全部道具并在任务结束按授权撤销。
4. 用返回 ABI 编码，调用 staticCall/estimateGas 模拟，再使用钱包当前 BSC 费率；不套固定 Gas limit 或固定价格。估算失败先解码 custom error，不用提高 Gas 掩盖业务失败。
5. 持久记录 chainId、账户、操作参数、交易 hash、nonce、业务 requestId；等待成功 receipt。超时先查 receipt 和 nonce，不重复发送业务交易。仅在已证明未上链并有替换授权时处理替换。
6. 成功后刷新链上状态；索引未更新可稍后重读，不因此重复写入。

## 各玩法执行契约

### 买蛋、开蛋与合成

买蛋：读 `main.getPresaleInfo()`，确认 active、剩余数量和 1–20 范围。授权 `price * count` 给 Main，调用 `main.buyGenesisEgg(count)`。以 `PresalePurchased` 确认得到的蛋 ID。

开蛋：确认 `crabEgg.ownerOf(id)`、`getEggInfo(id)` 未打开、Main 未暂停且 `openEggEnabled()`。先读 `main.quoteVrfFee()` 并作为交易 `value`，调用 `main.requestOpenEgg(id, { value })`，从 Main 的 `OpenEggRequested` 日志取 requestId，进入 VRF 等待。开蛋请求确认不是奖励到账；奖励可能是角色、道具、碎片或 Box。

合成：读 `main.getFragments(wallet)` 与 `main.fragmentsToSynthesize()`，确认碎片不少于 `fragmentsToSynthesize * count`、count 为正整数时调用 `main.synthesizeEgg(count)`。这是同步消耗碎片并获得普通蛋，无 ERC20 approve。

### 战斗

读 `battle.canEnterDungeon(crabId,dungeonId)`、`getRemainingDailyBattles(crabId)`、`dungeonConfigs(dungeonId)`、`calculateWinRate(crabId,dungeonId)`。初始每只每日 30 场，每场消耗体力；不能用账户总战斗次数替代单只额度。

| 副本 | 等级范围 | 胜/负经验 | 胜利碎片范围 / 失败碎片 |
|---|---|---|---|
| 1 | 1–10 | 20 / 10 | 1–3 / 1 |
| 2 | 11–20 | 20 / 10 | 3–6 / 2 |
| 3 | 21–30 | 20 / 10 | 6–12 / 3 |
| 4 | 31–50 | 20 / 10 | 12–24 / 4 |

先读 `battle.quoteVrfFee()` 并作为交易 `value`，调用 `battle.requestBattle(crabId,dungeonId, { value })`；解析 Battle 的 `BattleRequested`，等待 fulfilled，再读胜负、经验和碎片。胜率只是概率，不能保证收益；不要并发批量发送同一角色请求。

### 升级、进阶、体力

升级：`upgrade.getLevelUpInfo(crabId)` 返回 canUpgrade、cost、等级与经验；确认所有权和未到品质上限后精确授权 cost，再 `levelUp(crabId)`。同步成功，消耗经验。

进阶：`upgrade.getEvolveInfo(crabId)` 返回 canDoEvolve、crabCost、crystalId、crystalBalance、successRate（万分比）。达到品质等级上限、非 SSR 且水晶足够时精确授权，先读 `upgrade.quoteVrfFee()` 并作为交易 `value`，调用 `upgrade.requestEvolve(crabId, { value })`，解析 `EvolveRequested` 后等待。材料和代币在请求时消耗，随机失败不等于交易失败，不自动重试或承诺退款。

充值：读取品质、现有体力和 `staminaRechargePrices(quality)`，仅充值缺口范围内正整数点，精确授权单价乘点数，调用 `rechargeStamina(crabId,amount)`；避免超过上限付费。

药水：`usePotion(crabId,potionId)` 消耗一个并回满。1 绿色仅 N；2 蓝色 N/S；3 红色 N/S/SR；4 金色所有品质。水晶 11 紫色用于 N→S、12 白色 S→SR、13 金色 SR→SSR。优先比较药水机会成本与实时充值成本。

### 回收

读取 `upgrade.getRecycleInfo()`，核验 enabled、品质额度与资金池余额，以及角色所有权和实时限制。`recycleCrab(crabId)` 会销毁 NFT 并支付回收款，不可撤销；交易前确认用户接受该资产处置。初始各品质每日额度为 80/40/20/10，按链上 timestamp/86400 日界线重置。额度可能被其他交易抢先消耗，失败后重读，不盲重发。无需为回收款批准 ERC20。

### 市场

- ERC721：确认所有权、未重复挂单与市场白名单限制，授权指定 NFT，调用 `market.listERC721(nftType,tokenId,price)`。
- 道具：确认余额，授权 Market 为 ERC1155 operator，调用 `listCrabItems(tokenId,amount,price)`。price 是整批总价，购买整单，不是单件价或部分成交。
- 购买：索引选单后重新 `market.getListing(listingId)`，确认 Active、seller 不是自己、资产/数量和用户同意的价格。精确授权总价后 `market.buy(listingId,expectedPrice)`；expectedPrice 必须等于刚确认的整单价格。价格变化应停止并重新取得价格授权。
- 改价：卖方 `market.updatePrice(listingId,newPrice)`，正数且有效挂单。
- 撤单：卖方 `market.cancel(listingId)`，托管资产退还。该玩家入口仍要求 Agent ID；失去身份或注册表故障时暂停撤单，待资格恢复后重新检查挂单状态。
- 读取 `feeRate()`（分母10000）；初始化5%扣卖方，不额外向买家加5%。被暂停、黑名单或 NFT 白名单限制时按原合约拒绝。

### CrabBox 分红

读 `crabBox.getSupportedDividendTokens()`、`getAllPendingDividends(wallet)`，必要时 `getPendingDividend(wallet,token)`、`getUserDividendInfoByToken`、`getDividendStatsByToken`。最多两个支持币种，通常游戏币和 WBNB；WBNB 不是原生 BNB，不能直接作为 Gas。`claimDividend(token)` 或 `claimAllDividends()` 同步领取，不需要 approve。核验 dividendPaused 与 pending，零收益时不浪费 Gas。持有 Box 不保证未来有分红；转移时按合约结算，不按索引余额推算收益。

## VRF 请求费用

`main.requestOpenEgg`、`battle.requestBattle`、`upgrade.requestEvolve` 是 payable。每次发送前，必须从对应目标合约实时读取 `quoteVrfFee()`，将返回的 BigInt wei 精确作为交易 `value`（例如 `main.requestOpenEgg(id, { value: await main.quoteVrfFee() })`）。报价读取失败就停止，不使用缓存或默认值兜底；少付、多付或费率变化导致旧报价失效均回滚，应重新读取状态及报价后再决定是否发送。

默认费用为每次 **0.0005 BNB（500000000000000 wei）**，Provider owner 可通过 `setVrfFee` 调整（包括设为零），因此默认值不能用于构造交易。这是独立于 Gas、游戏代币、水晶和体力的原生币费用，成功请求只收费一次，随机数回调不再收费。Provider 将费用全额转给部署时固定的 Coordinator；没有独立可修改收款地址。Coordinator 请求或收款失败会原子回滚业务消耗和请求状态，但已消耗 Gas 不退；请求成功后的随机失败或回调失败不承诺退款，沿用下述恢复流程。

## VRF 恢复与防重复

三种异步操作分别使用 Main/Battle/Upgrade 的 `getOpenEggRequest` / `getBattleRequest` / `getEvolveRequest`。解析 receipt 时必须匹配发出事件的业务合约地址和 ABI，而非抓任意 RandomRequested；记录 requestId 与操作类型的组合。

请求成功后每隔几秒轮询，失败退避，并核对返回 user 与资产 ID。`fulfilled=false` 只表示待完成，不能再发一次请求；本地轮询截止也不意味着链上失败。默认空结构、零 user 或时间戳不能当作有效 pending 请求。长时间未完成时保留 hash/requestId，查询原请求和服务状态并报告待处理；不要重发请求或自行构造结果。只有 fulfilled=true 才解释业务结果，进阶的 success=false 是正常概率结果。

可同时读取无关账户状态，但同一资产按“请求→确认→回调→刷新”串行处理。

## 日常决策与错误处理

先处理未完成交易，再更新资格、余额、资产、每日额度和状态；评估体力与升级/进阶成本，再按用户策略战斗、合成和开蛋。回收、挂单和购买都涉及资产处置，不能由建议接口自动扩大授权。不得用期望胜率宣称保本。

- 参数/资格错误：修正输入或等待用户完成身份注册，不重试链上写入。
- RPC/注册表不可用：报告未知、只重试读取；禁止降级为允许。
- 未部署/未配置：停止付款和玩法，等待服务就绪。
- 余额、allowance、材料、体力不足：重读对应余额和费用，按用户已有授权处理。
- PresaleNotActive、暂停、额度耗尽、等级不符、已打开、挂单失效：更新状态，不重发同一参数。
- custom error：用当前合约 ABI 解码；记录合约、函数、参数与错误，不记录私钥。
- 查询索引失败：保留真实 RPC 结果，明确数据不完整，不能将缺失记录视为未执行。
