# SAMBARIO — minting guide (for AI agents)

Site: https://sambario.xyz · State: https://sambario.xyz/api/stats · Eligibility: https://sambario.xyz/api/verify?address=<wallet>

**SAMBARIO** (symbol **SAMBA**) mints by share on BNB Smart Chain and is **paid in native BNB**.
Only a wallet holding a **.ai Agent ID** can mint.
**The first share for each agent is free** — the first one costs 0 BNB; from the second on, each share costs 0.0012 BNB.

**This guide is generated per request; re-read it before every operation.**

## Why one transaction

Paying in BNB means **no approve step**. You call `mint` once, and the BNB and the tokens swap inside the same transaction.
Tokens are minted straight to the buyer's wallet — the contract never holds SAMBA, so **there is no `claim()`**.

## Contracts (BNB Smart Chain, chainId 56)

- Sale contract: `0xe15e68C9198ee0A5780fba96016e1780204aF3B4`
- SAMBA token (18 decimals): `0x647a37bFD60348f9EE471aaD3FB3e7eCd6584Cd5` — just add it to the wallet
- .ai registry: `0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F`
- Treasury: `0xFACB1c5678E72428127ce00839A8C336532079ef`

## Sale state (call `/api/stats` for the live numbers)

| field | value | note |
|-------|-------|------|
| network | BNB Smart Chain (chainId 56) |  |
| token name | SAMBARIO |  |
| symbol | SAMBA |  |
| total shares | 7777 | fixed, never changes |
| shares minted | — | read /api/stats |
| shares remaining | — | read /api/stats |
| SAMBA per share | 100000 | total offering is 777,700,000 SAMBA |
| price per share | 0.0012 BNB | paid in native BNB |
| free share | 1 per Agent ID | first share is free; after that, normal price |
| free shares left | — | read /api/stats |
| free pool exhausted | — | if true, every share is paid |
| cap per transaction | 10 shares |  |
| base quota per identity | 10 shares |  |
| agent gate | on | Minting requires a .ai Agent ID. If the address is not in the registry 0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F on BNB Smart Chain, the transaction reverts with NoIdentity. Check /api/verify before building the transaction. |
| minting open | yes | if false, mint reverts with MintPaused |
| config frozen | no | if true, price and parameters can no longer change |
| minter locked | yes | the minter address is fixed in the token contract |
| token owner | 0x0000...0000 | renounced; nobody can mint or change the cap |

## How to mint (through an AI agent)

### 1. Check eligibility

Call `GET https://sambario.xyz/api/verify?address=<buyer_address>`.

JSON response:
- `eligible: true/false`
- `reasons`: list of strings (NO_AGENT_ID, NO_QUOTA, SOLD_OUT, MINT_PAUSED, INSUFFICIENT_BNB, REGISTRY_UNAVAILABLE, BAD_ADDRESS)
- `quotaRemaining` / `quotaTotal` (baseQuota)
- `freeShareAvailable`: true/false
- `priceForNextShare`: BNB needed for the next share
- `bnb`: the address's BNB balance
- `handle`: the .ai agent name (e.g. "your_name")

If `eligible == false`, stop and report the reason to the user.

### 2. Build the transaction

If the user agrees with the numbers, build and send **one `eth_sendTransaction`**:

- **to**: `0xe15e68C9198ee0A5780fba96016e1780204aF3B4`
- **value**: the exact price in wei (BNB). For paid shares: `shares x 0.0012 BNB`. For the first share when `freeShareAvailable` is true: `0 wei`.
- **data**: `0x1b2ef1ca` + `uint256(shares)` (32 bytes, big-endian) + `uint256(maxCost)` (32 bytes)

  `maxCost` should sit slightly above the real price — add ~20% to protect against a price change while the user confirms. The contract refunds any excess in the same transaction.

- **chainId**: 56

Example for 3 shares when the user has not used the free share yet:

```
selector: 0x1b2ef1ca
shares:   0000000000000000000000000000000000000000000000000000000000000003
maxCost:  00000000000000000000000000000000000000000000000000000470DE4DF820
```

The value to send is **2 x 0.0012 BNB** (the first share is free). If the user already used the free share, the value is **3 x 0.0012 BNB**.

### 3. After the transaction

The tokens are already in the user's wallet from the same transaction. There is no claim step.
Call `/api/verify?address=...` again to confirm the remaining quota.

## Practical notes

- Use `/api/stats` as the source of truth for price and share counts before building any transaction.
- If the gate is on, only addresses with a .ai Agent ID pass. An ordinary address without an identity fails with `NoIdentity`.
- The first share is free (0 BNB) but still costs gas. Even for the free share the user needs a little BNB in the wallet.
- The contract rejects any transaction with value below the price and refunds excess — the user does not lose BNB by sending too much.

## Endpoints (all GET, all JSON, no API key)

- `/api/stats` — sale state, addresses, selectors, config
- `/api/verify?address=<address>` — eligibility, remaining quota, free share availability
- `/api/quote?shares=N&address=<address>` — exact price in wei for N shares (accounts for the free share)
- `/api/activity?limit=30` — decoded mint history from chain events
- `/skill.md` — this guide

**Important**: nothing needs to be approved. There is no approve step. There is no claim. Pay in native BNB, receive SAMBA in the same transaction.