# Hash Hunters: guide for AI agents

Hash Hunters lets a wallet claim a recent block hash. The more leading zero hex digits the hash has, the bigger the reward.
This guide is for agents using a **Binance Agentic Wallet** (`baw` CLI, `binance-agentic-wallet` skill).

## Contract facts

| Item | Value |
|---|---|
| Fee | 0.01 USDT per hunt (18 decimals on BSC: `10000000000000000`) |
| Reward | `1000 * 3^zeros` HUNT, zeros = leading `0` hex digits of the block hash (0 to 6) |
| Window | Only the most recent **255** blocks can be hunted |
| One hunter per block | First transaction wins |
| Token tax | 1% on buys/sells on the official pool (half burned, half to the creator). Hunting and normal transfers are not taxed |
| Function | `hunt(uint256 blockNumber)`, selector `0x` + keccak256("hunt(uint256)")[0:4] |

Addresses depend on the network. Read them from the website page `CONFIG` or the project README. Never use an address
you did not get from the user or the official site.

> Current testnet deployment is on BSC testnet (chain 97), which `baw` does not support. Agent minting works on
> **BNB Smart Chain mainnet (chain 56)** once the mainnet contract is announced.

## Preconditions (check first)

1. `baw wallet status --json` is `CONNECTED`.
2. `baw wallet settings --json` shows `devMode.enabled: true`. If not, ask the user to enable Developer Mode in the
   Binance App (Agentic Wallet management page, Settings). Do not continue until it is on.
3. The wallet holds at least 0.01 USDT per planned hunt plus a little BNB for gas.

## Find the best open blocks

Use any BSC RPC. Pseudocode with ethers v6:

```js
const head = await provider.getBlockNumber();
for (let n = head - 1; n >= head - 240; n--) {          // leave a safety margin of ~15 blocks
  const h = (await provider.getBlock(n)).hash;           // 0x...
  const zeros = h.slice(2).match(/^0*/)[0].length;       // leading zero digits
  const taken = await hunt.hunterOf(n);                  // 0x000... means still open
  if (taken === ethers.ZeroAddress && zeros >= 1) candidates.push({ n, zeros });
}
```

Sort candidates by `zeros` desc, then by block number desc (newest first, more time left). Prefer blocks with at least
**20 blocks left** (`255 - (head - n) >= 20`): a transaction needs a few blocks to land.

## Hunt (two contract calls)

Compute calldata with ethers:

```js
const approveData = new ethers.Interface(["function approve(address,uint256)"])
  .encodeFunctionData("approve", [HUNT_ADDRESS, ethers.parseEther("0.01")]);   // approve exactly one hunt's fee
const huntData = new ethers.Interface(["function hunt(uint256)"])
  .encodeFunctionData("hunt", [blockNumber]);
```

For each call, follow the **two-step flow** of the `binance-agentic-wallet` skill. Never skip the preview.

```bash
# 1) approve USDT (only if allowance is lower than the fee)
baw contract-call preview --binanceChainId 56 --from <AGENT_WALLET> --to <USDT_ADDRESS> --value 0 --inputData <approveData> --json
# show the user the parsed tx + risks, get explicit confirmation, then:
baw contract-call execute --requestId <requestId> --json

# 2) hunt
baw contract-call preview --binanceChainId 56 --from <AGENT_WALLET> --to <HUNT_ADDRESS> --value 0 --inputData <huntData> --json
baw contract-call execute --requestId <requestId> --json
```

`--value` is in wei and must be `0` here. Do not send BNB to the contract.

## Safety rules for the agent

- Verify `<HUNT_ADDRESS>` against the official site and BscScan source before the first call. Refuse if it differs.
- Approve only the fee for the planned hunts. Never approve an unlimited amount.
- Obey the user's spending cap (for example "at most 0.5 USDT in fees").
- If preview shows a risk, an unexpected token movement, or `authorityChanges`, stop and tell the user.
- A `txHash` means broadcast, not confirmed. Confirm with `baw wallet tx-history --json` and read the `Hunted` event or
  `hunterOf(blockNumber)`. If another hunter won the block, the transaction reverts with `AlreadyHunted`: this is
  normal, move to the next block. Do not retry the same block.
- This is experimental software. Hunting costs real USDT and HUNT can lose all value. No financial advice.

## Errors

| Error | Meaning |
|---|---|
| `AlreadyHunted` | Someone else claimed that block |
| `BlockTooOld` | More than 255 blocks passed, pick a newer block |
| `BlockNotFinal` | Block number is not in the past yet |
| `SupplyExhausted` | Max supply reached |