# VIRTUAL mint — guide for AI agents

> VIRTUAL is a fair-mint token on BNB Smart Chain (chain id 56). Wallets that hold a Binance
> Agent ID (.ai handle) can claim 1 free share each while 3,000 free shares last. Any wallet
> can buy paid shares at 15 USDT each. Share 4,000 opens a PancakeSwap pool and ends minting.
> Use this file to help a user who asks you to check eligibility, claim, or mint VIRTUAL.
> Always confirm with your user before sending a transaction or spending their funds.
> Nothing here is investment advice.

VIRTUAL is an independent project, not affiliated with Binance or with Virtuals Protocol.
"Agent ID" means the .ai identity NFT on BNB Smart Chain (registrar below) that Binance's AI
wallets use; the mint contract only reads it to decide who may claim a free share.

Website: https://aivirtual.fun

## Contracts (BNB Smart Chain, verified on Sourcify, exact match)

- Mint contract: 0x40f76C030adbE33CD32A061Bf6fA146065cBEa3e
- VIRTUAL token: 0xeBCB4C3c5813a7d6BAb9694258B57Aa2E043De2F
- PancakeSwap VIRTUAL/USDT pool: 0xA56161008924aA7abDaF6b2Af2713c9525f8F995
- USDT (BSC-USD, 18 decimals): 0x55d398326f99059fF775485246999027B3197955
- Agent ID registrar: 0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F

You can read both contracts' source on Sourcify or BscScan (chain 56) before you act.

Never send BNB or USDT directly to the token or mint contract with a plain transfer. A plain
BNB transfer fails; USDT sent directly is not minted and cannot be recovered. Only call the
functions listed below.

## Rules (all enforced by the mint contract)

- Total: 4,000 shares (`TOTAL_SHARES()`), free and paid together. Share 4,000 opens the pool
  in the same transaction. After that, minting is over: every mint reverts with `SoldOut`.
- Free: a wallet that holds an Agent ID may call `claimFree()` once per Agent ID while
  `freeMinted() < 3000` and the pool is not open. It gives 200,000 VIRTUAL and costs only gas.
- Paid: any wallet, no Agent ID needed. 15 USDT per share for 200,000 VIRTUAL. Up to 10 shares
  per wallet (`quotaLeft(wallet)`), at most 10 per transaction, and never more than the shares
  left (`4000 - totalMinted()`). Paid shares may also take free slots nobody claimed.
- 25% of each payment goes to the project wallet immediately. 75% (11.25 USDT per share) is
  held in the mint contract for the pool, along with 150,000 VIRTUAL per paid share.
- The open price equals the mint price; LP tokens go to the dead address. VIRTUAL cannot be
  transferred or sold before the pool opens.
- Free shares add no USDT to the pool. If all 3,000 are claimed, the pool opens with 11,250 USDT
  and 150,000,000 VIRTUAL while free claimers hold 600,000,000 VIRTUAL. Tell your user that
  heavy selling by free claimers can push the price far below the mint price.
- Deadline: `deadline()` is 30 days after the sale opened. If the pool has not opened by
  then, minting stops (`closed()` / calls revert with `Closed`) and the project wallet may
  call `withdrawUnfilled()` to take all USDT held for the pool. There are NO refunds to
  buyers in that case. Tell your user this before they pay.
- Trading tax on the official pool only: buys 1%; sells 2% (1% burned, 1% to the project).
- Until `renounced()` is true, the project wallet can pause minting, block other trading
  pools, and use `withdrawUnfilled()` in the unfilled case. Prices and limits are constants.

## Step 1: check (read-only)

On the mint contract:
- `paused() -> bool` must be false; `closed() -> bool` must be false; `deadline() -> uint256`
  must be in the future; `totalMinted() -> uint256` must be below 4000.
- Free: `canClaimFree(address wallet) -> bool` is the single check (Agent ID owned by this
  wallet, not claimed yet, free shares left, pool not open, sale live).
- Paid: `quotaLeft(address wallet) -> uint256` shares left for this wallet.
- `costOf(uint256 shares) -> uint256` USDT cost (18 decimals, always shares x 15 USDT);
  `quoteTokens(uint256 shares)` VIRTUAL received (always shares x 200,000);
  `bnbQuote(uint256 shares)` BNB needed when paying in BNB.

Or use the website's read API (no auth):

    GET https://aivirtual.fun/api/state?addr=<wallet>

Returns `totalMinted`, `freeMinted`, `remaining`, `paused`, `closed`, `expired`, `deadline`,
and for the wallet: `user.agentOk`, `user.handle`, `user.canClaimFree`, `user.freeClaimed`,
`user.quotaLeft`, `user.usdt`, `user.allowance`, `user.bnb`, `user.tokens`.

## Step 2a: claim the free share

Call on the mint contract, no value:

    claimFree()            selector 0xf366afc9

Reverts: `NoAgent` (wallet has no Agent ID it owns), `AlreadyClaimed`, `FreeGone`,
`AlreadyOpen`, `Paused`, `Closed`.

## Step 2b: mint paid shares with USDT

1. Make sure USDT `allowance(wallet, mintContract) >= costOf(shares)`; if not, the wallet
   approves the mint contract for that amount.
2. Call:

       mint(uint256 shares, uint256 maxCost, uint256 minTokensOut, uint256 deadline)

   - `maxCost`: `costOf(shares)` (the price is fixed)
   - `minTokensOut`: `quoteTokens(shares)` (the amount is fixed)
   - `deadline`: a unix time a few minutes ahead

## Step 2c: mint paid shares with BNB

    mintWithBnb(uint256 shares, uint256 maxCost, uint256 minTokensOut, uint256 deadline)  payable

`maxCost` is in BNB wei; send `value = bnbQuote(shares) * 102 / 100`. The contract takes the
Chainlink BNB/USD price plus 1%, swaps that BNB to USDT, and refunds BNB sent above the quote.
USDT the swap returns above `costOf(shares)` goes to the project wallet, so the BNB route costs
about 1% more than paying in USDT. Tell your user this if they choose BNB.

Paid-mint reverts: `Quota` (more than 10 for this wallet), `BadShares`, `SoldOut` (more than
the shares left), `OverMaxCost`, `InsufficientOutput`, `Expired`, `Paused`, `Closed`,
`StalePrice` (BNB route only).

## Ready-made calldata

The website can build the exact transaction for a wallet (it never signs anything):

    POST https://aivirtual.fun/api/build
    {"from": "<wallet>", "action": "claimFree"}
    {"from": "<wallet>", "action": "approve", "shares": 3}
    {"from": "<wallet>", "action": "mint", "shares": 3}
    {"from": "<wallet>", "action": "mintBnb", "shares": 3}

Response: `{"ok": true, "tx": {"to": "...", "data": "0x...", "value": "0x..."}}`.
Show the user the destination, value and cost before sending.