# Agentic Cards: how an AI agent mints

You are an AI agent that controls a BNB Chain wallet (for example a Binance Agentic Wallet). This file tells you how to mint your user's **Agentic Card** and report the result. It takes one HTTP GET and one transaction.

A human may paste you this prompt (the same one on the site under “Give your AI this prompt”):

> Mint my Agentic Card. Go to https://agentic-cards.pages.dev/AGENT.md and follow it: check my wallet's score at https://agentic-cards.pages.dev/api/score?wallet=MY_WALLET, then call mint() on the Agentic Cards contract on BNB Chain with the signed payload and the mint price, from my wallet. When done, tell me my card number, rank, score and how many $CARDS were allocated.

Replace `MY_WALLET` with the user's address if they have not already.

- **Chain:** BNB Smart Chain, chainId `56`
- **AgenticCards (ERC-721):** `CONTRACT_ADDRESS_HERE`
- **$CARDS (ERC-20, 18 decimals):** `CARDS_TOKEN_ADDRESS_HERE`
- **Reputation scanner:** `https://agentic-cards.pages.dev/api` (no API key) · [openapi.json](/.well-known/openapi.json)
- **ABI:** [/abi/AgenticCards.json](/abi/AgenticCards.json) · manifest: [/.well-known/agent.json](/.well-known/agent.json)

## Who can mint

Only wallets that **own a .ai Agent ID** can mint, which means `handleOf(wallet)` on the SPACE ID registry `0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F` returns a non-empty name. Each Agent ID and each wallet gets one card.

`mint()` reverts with `NoAgentId()` if `msg.sender` has no Agent ID. This includes smart contracts, relayers and agents that send the transaction from a different wallet than the one holding the .ai. **Send the transaction from the wallet that owns the Agent ID.**

## Steps

### 1. Get the signed reputation payload

```
GET https://agentic-cards.pages.dev/api/score?wallet=0xYOUR_WALLET
```

Example response (shortened):

```json
{
  "wallet": "0x1234567890abcdef1234567890abcdef1234abcd",
  "handle": "kai",
  "eligible": true,
  "score": 420,
  "rank": "Specialist",
  "breakdown": [40, 55, 42, 36, 30],
  "labels": ["AGE", "TXNS", "DAYS", "NFTS", "LOYALTY"],
  "cards": 2175,
  "cardsAmount": "2175000000000000000000",
  "deadline": 1794929630,
  "signature": "0x…",
  "mint": {
    "to": "CONTRACT_ADDRESS_HERE",
    "chainId": 56,
    "function": "mint(uint16 score, uint8[5] breakdown, uint256 cardsAmount, uint256 deadline, bytes sig)",
    "args": [420, [40, 55, 42, 36, 30], "2175000000000000000000", "1794929630", "0x…"]
  },
  "facts": { "walletAgeDays": 400, "txs": 180, "activeDaysLast365": 60, "nftsCounted": 8 }
}
```

- If `eligible` is `false` or `signature` is `null`, stop. Tell the user what the `error` field says. Usually it means the wallet has no Agent ID.
- HTTP `503` or `429` means the scanner is busy. Wait 30–60 s and retry.
- The signature is valid for 30 minutes (`deadline`). If it expires, fetch a new one.
- Optional dry run: `checkPayload(wallet, ...args)` is a view that returns `0` when the mint will pass. Other codes: `1` paused, `2` no Agent ID, `3` name already minted, `4` wallet already minted, `5` sold out, `6` bad name, `7` expired, `8` bad signature, `9` bad score, `10` bad reward.

### 2. (Optional) preview for your user

> "Your wallet scores 420/1000 (Specialist). Minting costs 0.00034 BNB + gas and sends you 2,175 $CARDS. Mint?"

### 3. Send the mint transaction

- `to`: AgenticCards
- `value`: `mintPrice()` (read it live; default `340000000000000` wei = 0.00034 BNB)
- `data`: `mint(score, breakdown, cardsAmount, deadline, sig)` with `args` from step 1, unchanged

```js
// ethers v6
const nft = new ethers.Contract(CONTRACT, [
  "function mintPrice() view returns (uint256)",
  "function mint(uint16 score, uint8[5] breakdown, uint256 cardsAmount, uint256 deadline, bytes sig) payable returns (uint256 tokenId, uint256 score, string rank, uint256 cardsAmount)",
  "function mintMessage(uint256 tokenId) view returns (string)",
  "event CardMinted(address indexed minter, uint256 indexed tokenId, string handle, uint256 score, string rank, uint256 cardsAmount)"
], wallet);
const p = await (await fetch(`${SCANNER}/score?wallet=${wallet.address}`)).json();
if (!p.signature) throw new Error(p.error);
const tx = await nft.mint(...p.mint.args, { value: await nft.mintPrice() });
const rc = await tx.wait();
const ev = rc.logs.map((l) => { try { return nft.interface.parseLog(l); } catch { return null; } }).find((e) => e?.name === "CardMinted");
console.log(await nft.mintMessage(ev.args.tokenId));
```

Raw calldata selector: `mint(uint16,uint8[5],uint256,uint256,bytes)`. Gas is about 370k. Set the limit to 450k if you can't estimate. The only thing your user signs is this transaction. Never sign messages, approvals or permits for this project.

### 4. Report to your user

Read the `CardMinted(minter, tokenId, handle, score, rank, cardsAmount)` event, or call the view `mintMessage(tokenId)`:

> "kai.ai minted Agentic Card #12 (Specialist, score 420). 2,175 $CARDS allocated."

`cardsAmount` in the event is in wei (18 decimals). `mintMessage` already formats it. The card is fully on-chain: `tokenURI(tokenId)` returns base64 JSON with an SVG image. Faster option: `GET https://agentic-cards.pages.dev/api/card/{tokenId}`.

## Errors (custom errors on revert)

| Error | Meaning | What to do |
|---|---|---|
| `NoAgentId()` | sender has no .ai Agent ID | use the wallet that owns the .ai |
| `WalletAlreadyMinted()` / `HandleAlreadyMinted()` | already has a card | report the existing card |
| `Expired()` | signature deadline passed | fetch `/score` again |
| `BadSignature()` | payload not for this wallet/contract, or edited | fetch `/score` again for **msg.sender** and don't change the args |
| `WrongPrice()` | value < `mintPrice()` | read `mintPrice()` again |
| `MintClosed()` / `SoldOut()` | paused / all 1,500 minted | tell the user |

## How the score works

Five sub-scores from 0 to 100, weighted 25/25/20/15/15 into a score from 0 to 1000:

| Stat | Source | Curve, cap |
|---|---|---|
| AGE | time since the wallet's first transaction | sqrt, 3 years = 100 |
| TXNS | transactions sent (nonce) | log, 2,000 = 100 |
| DAYS | days with a transaction in the last 365 | sqrt, 180 days = 100 |
| NFTS | NFTs held in any collection (spam filtered, max 10 per collection, Agent ID excluded) | log, 100 = 100 |
| LOYALTY | Whalers, Agentic Bull, Agentical Glyphs (20 each, 25 if 3+ held) + $GLYPHERS (up to 25) | capped at 100 |

Ranks: Recruit 0–199 · Operative 200–349 · Specialist 350–499 · Commander 500–649 · Elite 650–799 · Legendary 800–1000.

$CARDS per mint = **500 + 9,500 × (score / 1000)²**, so 500 minimum and 10,000 maximum. The contract recomputes the score from the breakdown and the reward from the score, and rejects any mismatch.

Independent community project. Not affiliated with Binance or SPACE ID.

## Links
- X: https://x.com/agenticcardsNft
