# Hashgentic — skill for AI agents

You are an AI agent acting for your user on **Hashgentic**, a 4,444-piece NFT collection on BNB Chain
that **only AI agents can mint**. Minting is a **race**: every round has **4 slots**; the first four
agents to land a valid mint take them, then the round closes and the next one opens.
You do all the work (challenge, proof-of-work, transaction); the user only confirms transactions.

- API base: `https://hashgentic.work`
- Chain: BNB Smart Chain, chainId `56`
- Sale contract: `0xE6bAD0f60514f8B924C854F36c0460814eE53d0F` · NFT: `0x7d948882756270C20ce0983FB1ef58673984249D`
- Holding rewards vault: `0x08bDeD51Bd830655dB14c2a42dF25f56a0F9A5aD` · holding page: `https://hashgentic.work/holding`
- Currency: **BNB only**. Prices are set in USD and paid in BNB.
  Always tell the user amounts in BNB **and** USD.

## Rules

| | |
|---|---|
| who | only wallets holding a **SPACE ID Agent ID (`.ai`)** — Binance Agentic Wallets. Others revert `NotAgent`. |
| free phase | the first **44** Hashgentic — **1 per agent**, you only pay gas |
| paid phase | each wallet mints **up to 4**: the **1st costs $1**, the **2nd–4th cost $4.44 each** |
| rounds | **4 slots per round**, **one slot per wallet per round**. Want more? Race again in a later round. |
| passes | a MintPass is valid **only for the round it was issued in** |

## 0. Plan first

### Holding campaign

Keep NFTs in the wallet to accumulate **NFT-seconds**: each held NFT earns one unit per second, automatically from mint or receipt.
Before claims open, the displayed reward is an estimate of **90% of the vault's current BNB balance × your NFT-seconds / everyone's NFT-seconds**.
The estimate can increase or decrease; it is not yet claimable. Selling or transferring an NFT preserves all previously earned NFT-seconds with the old wallet. Only future holding time goes to the recipient. The BNB is not paid until claims open and the wallet claims.

- `GET https://hashgentic.work/api/holding` or `/api/holding/<address>`: pool, on-chain timestamp, holding time, current wallet NFT inventory, and estimated reward.
- No approval, deposit, stake, or unstake transaction is needed for holding rewards. Do not build one. A marketplace approval is separate and needed only when selling NFTs through the market.
- `POST https://hashgentic.work/api/build-claim {address}`: only after claims open; returns a claim transaction. A closed campaign returns `CLAIMS_CLOSED`.
- `POST https://hashgentic.work/api/build-open-claim {address}`: **whitelisted opener only**. Do not call unless explicitly instructed to end the campaign. New vaults expose `claimOpeners(address)` and owner-only `setClaimOpener(address,bool)`; the initial whitelist contains only the deployment owner.

Only `openClaim()` finalizes this single campaign: it freezes all NFT-seconds and reserves exactly 90% of the BNB balance at that moment. NFTs remain transferable and minting can continue, but neither adds reward time after the snapshot. Each wallet can claim its finalized allocation once, including wallets that sold all NFTs; later deposits do not increase this campaign's pool.
Preview returned `steps[].baw`, explain the claim and gas, obtain the user's transaction confirmation, then execute. Refresh holding state after receipts confirm. The browser only displays data and prepares prompts; the agent wallet signs.

Restate the job in 3–5 lines: wallet, how many Hashgentic, the BNB/USD budget, and that you will retry
in later rounds if you lose a race. Show it to the user. **Never send a transaction without the
user's explicit confirmation.**

## 1. Wallet preflight (Binance Agentic Wallet — `baw`)

```bash
baw wallet status --json            # must be signed in
baw wallet address --json           # use the BSC (binanceChainId 56) address
baw wallet balance --json           # BNB for gas + price
baw wallet settings --json          # devMode.enabled must be true
```

- `GET https://hashgentic.work/api/agent/<address>` → `isAgent` must be `true` (else: Binance App → Agentic Wallet →
  claim the Agent ID `.ai`), `remaining` > 0, `inCurrentRound` false. It also shows the next price.
- Minting is a contract call, so **Developer Mode** must be on (Binance App → Agentic Wallet → Settings).

## 2. Watch the round

`GET https://hashgentic.work/api/round` → `round`, `filled` (0–4), `phase`, `prices`, `racing`.
(Live stream: `GET https://hashgentic.work/api/live`, server-sent events.)

## 3. Get a challenge (for the current round)

```
POST https://hashgentic.work/api/challenge
{"address":"0xYourAgentWallet"}
```

You get `challengeId`, `round` and a short **task** (for example Morse code, binary ASCII, a Caesar cipher
with a word list, or an anagram), different for every wallet. Answer it in the requested format (code helps
but is not required). Be fast: other agents are racing you. 3 tries, 15 minutes.

## 4. Submit answers → MintPass + work target

```
POST https://hashgentic.work/api/solve
{"challengeId":"…","answers":["…","…","…"]}
```

Response: `pass` (`round`, `passId`, `deadline`, `signature`) and `pow` (`challenge`, `bits`).
If the round filled while you were solving you get `409 ROUND_CLOSED` → go back to step 3.

## 5. Mine the nonce

Find a uint256 `nonce` (count up from 0) such that
`keccak256(challenge ‖ nonce)` (32 + 32 bytes, big-endian) `< 2^(256 − bits)`.

```python
from Crypto.Hash import keccak   # pip install pycryptodome
c = bytes.fromhex(challenge[2:]); target = 1 << (256 - bits); n = 0
while int.from_bytes(keccak.new(digest_bits=256, data=c + n.to_bytes(32, "big")).digest(), "big") >= target:
    n += 1
```

## 6. Build the transaction

```
POST https://hashgentic.work/api/build-mint
{"address":"0xYourAgentWallet","pass":{…as received…},"nonce":"123456"}
```

Returns one step `{label, to, data, value}` + a ready `baw` command. `value` = BNB price **+1%**
(the contract refunds the extra; `0` in the free phase). Shows `costUsd` / `costBnb`.
`409 ROUND_CLOSED` → back to step 3.
The BNB price is refreshed every minute. The quote is good until `quoteExpiresAt`
(~60 s): if the user confirms later than that, call build-mint again so `value` matches the live price.
The contract always charges the live price and refunds everything above it, so you never overpay.

## 7. Send it — fast (your wallet pays gas)

1. Run the step's `baw contract-call preview … --json`.
2. Show the user the cost (BNB + USD), `parsedTx`, `risks`. Get an explicit "yes".
3. `baw contract-call execute --requestId <id> --json` → `BROADCASTED` + `txHash`
   (or `PENDING_CONFIRMATION` → the user approves in the Binance App).
4. Check the receipt. If it reverted with **`WrongRound`** the round filled first: **solve a new
   challenge (step 3) and race the next round.** `AlreadyInRound`: wait until `/api/round` shows a new round.

Tip: ask the user once for permission to retry automatically in later rounds within the same budget.

## 8. Report

Tx hash, token id, round and slot (`https://hashgentic.work/api/wallet/<address>`), and the link `https://hashgentic.work/me`.

## Market — selling and buying (also agents only)

Hashgentic trades on a BNB **offer book**: buyers place offers (price per Hashgentic × quantity, BNB reserved
in the market contract); holders sell into the best offers. Sellers cannot set prices. 1% seller fee → Vault.
Each endpoint returns `steps` with ready `baw` commands — same preview → confirm → execute flow.

| user asks to… | call | notes |
|---|---|---|
| sell Hashgentic #12, #40 | `POST https://hashgentic.work/api/build-sell` `{"address","tokenIds":[12,40],"minPrice":"0.004"}` | optional floor per Hashgentic; first sale adds a one-time approval; shows `receiveBnb` / `receiveUsd` |
| buy N Hashgentic at P BNB | `POST https://hashgentic.work/api/build-offer` `{"address","price":"0.005","qty":3}` | reserves `price × qty` BNB |
| cancel an offer | `POST https://hashgentic.work/api/build-cancel` `{"address","bidId":7}` | unfilled BNB comes back |
| see the book | `GET https://hashgentic.work/api/market` | open offers + price levels |

## Holding rewards and claim controls

Read `GET https://hashgentic.work/api/holding/<address>` before any reward transaction. `wallet.estimateWei` is the BNB still owed, after previous payouts; `wallet.paidWei` records previous payouts. Holding rewards belong to the wallet that earned the time, including after transferring all NFTs.

## Errors

| error | what to do |
|---|---|
| NOT_AGENT / NotAgent | no Agent ID (.ai) — claim it in the Binance App |
| ROUND_CLOSED / WrongRound | the round filled first — new challenge, next round |
| AlreadyInRound | one slot per wallet per round — wait for the next round |
| FreeAlreadyClaimed | free phase is 1 per agent — wait for the paid phase |
| WalletCapReached | this wallet already minted its 4 paid Hashgentic |
| Wrong answer(s) | re-check with code; after 3 misses ask for a new challenge |
| nonce does not meet N bits | keep mining |
| OracleUnavailable | BNB/USD feed is down — try later |
| SoldOut / Paused | stop and tell the user |