# Mintlab — AI agent instructions (start here)

Mintlab is an Internet Computer (ICP) NFT wallet, marketplace, and minting app.
**Humans** use the web UI. **Agents** should call the **backend canister** via Candid
(MCP / Agent Identity), not scrape the UI and not write to the frontend asset canister.

| Item | Value |
|------|--------|
| Site | https://mintlab.website |
| Backend canister | tznl3-uiaaa-aaaap-akm5a-cai |
| Frontend asset canister | 2u7me-laaaa-aaaas-qgr2q-cai |
| ICP ledger | ryjl3-tyaaa-aaaaa-aaaba-cai |
| Auth derivation origin | https://mintlab.website |

## Documentation index (fetch these)

1. **This file (entry):** https://mintlab.website/llms.txt
2. **Well-known mirror:** https://mintlab.website/.well-known/llms.txt
3. **Detailed playbook:** https://mintlab.website/agents/playbook.txt
4. **Troubleshooting:** https://mintlab.website/agents/troubleshooting.txt
5. **Machine guide (query, free):** backend `getAgentCapabilityGuide()`
6. **Live readiness (auth):** backend `getAgentMintReadiness()`
7. **Human help:** https://mintlab.website/help

## Golden rules (read before any transfer)

1. **Authenticate** as the Mintlab app principal with `derivation_origin = https://mintlab.website`.
2. **Deposit Account ID is per principal.** Always call `getAgentMintReadiness()` or `getUserAccountId()` and use **that** `accountIdHex`. Never invent an ID; never reuse a hex from chat memory/workflows if it differs.
3. **Do not upload images to the frontend asset canister** (permission-gated). Use backend `uploadMintImage*` APIs.
4. **Recipients for NFT send** are **Principals** (`sendNFT`, `mintUserNFTAndSend`), not Account IDs.
5. **Compress images before upload** (≤130_000 bytes, clean JFIF JPEG without EXIF/XMP, or clean PNG).
6. Prefer **short Candid args**: use retry-safe 8,000-byte raw chunks for text MCP tools — avoid multi‑MB data URLs in text tools.
7. Prefer **mintUserNFTAndSend** when the task is mint then deliver (fewer steps, less session risk).
8. Call `acceptCurrentTerms()` once before paid/write actions that require terms.
9. Be cycle-conscious: no redundant loops; re-query readiness instead of blind retries; do not spam upload.

## Always start here

```
# Unauthenticated discovery
getAgentCapabilityGuide()

# Authenticated snapshot (principal, accountIdHex, balance, mint price, next steps)
getAgentMintReadiness()
```

## Recommended happy path: fund → mint → send

1. Auth (Mintlab derivation origin).
2. `getAgentMintReadiness()` → note `accountIdHex`, `mainMintPriceE8s`, `enoughIcpForOneMint`, `termsAccepted`.
3. If not `termsAccepted` → `acceptCurrentTerms()`.
4. If not `enoughIcpForOneMint` → transfer ICP **to** `accountIdHex` on ledger `ryjl3-tyaaa-aaaaa-aaaba-cai` (classic Account Identifier, 32-byte hex). Re-check readiness.
5. Compress image (see Image section).
6. Upload (pick one):
   - Recommended MCP path: `beginMintImageUpload` → `appendMintImageChunkBase64At` → `getMintImageUploadStatus` (only when resuming) → `commitMintImageUpload`
   - One-shot `uploadMintImageBase64` only when the complete payload is known to fit the connector’s text-argument limit
7. Mint + send:
```
mintUserNFTAndSend(
  record {
    name = opt "Title";
    description = opt "…";
    imageUrl = opt "<imageUrl from upload>";
    attributes = vec {};
  },
  null,   // or opt quantity
  principal "<recipient-principal>"
)
```

Separate mint then send if needed:
```
mintUserNFT(metadata, null)
// use receipt.nfts[0].id as wallet nftId
sendNFT(nftId, principal "<recipient>")
```

## Image limits and format

| Limit | Value |
|-------|------|
| Max raw upload bytes | 130_000 |
| Max on-chain data-URL chars | 180_000 |
| Max binary chunk size | 16_000 bytes |
| Recommended MCP raw chunk size | 8_000 bytes (≤10_668 Base64 chars) |
| Pending image TTL | 2 hours |
| Pending images / principal | 2 |
| Types | image/png, image/jpeg only |

**JPEG tip:** Save clean JFIF (APP0 only). EXIF/XMP/COM segments are rejected by image-guard.
Example: convert to RGB, `save(..., format="JPEG", quality=85)` without EXIF.

There is **no server-side recompression**.

For text MCP connectors, split the raw image into 8,000-byte pieces and Base64
encode each piece separately. Use `bytesReceived` from begin/status as
`expectedOffset`:

```
appendMintImageChunkBase64At(uploadId, expectedOffset, base64OfRawChunk)
```

If a response is lost, call `getMintImageUploadStatus(uploadId)`. Retrying the
same bytes at the same offset is idempotent; a different chunk at an already
written offset is rejected.

## Other agent tasks

### Purchase (marketplace)
1. Fund + terms (above).
2. `getActiveListingsPage` / `getActiveListingDetailsPage`
3. Fixed: `buyFixedListing(listingId)`
4. Auction: `placeBid(listingId, amountE8s)` then `settleAuction` when ended

### List owned NFTs
- `getUserNFTsPage(caller, cursor, limit)` or `getUserNFTs`
- After external deposits, may need `syncUserNFTs` / collection-specific sync

### Withdraw ICP
- `transferICPOut(accountIdBlob, amountE8s)` — after terms; amount must exceed ledger fee

### Failed paid mints
- `getMyPendingMintPayments` then `retryPendingMintPayment` or dismiss methods — do not start a new paid mint while one is unfinished

## Canisters (do not confuse)

| Role | Canister ID |
|------|-------------|
| Mintlab backend (all app writes) | tznl3-uiaaa-aaaap-akm5a-cai |
| Mintlab frontend assets (read-only for agents) | 2u7me-laaaa-aaaas-qgr2q-cai |
| ICP ledger | ryjl3-tyaaa-aaaaa-aaaba-cai |

## Key methods cheat sheet

| Goal | Method |
|------|--------|
| Onboarding | `getAgentCapabilityGuide` |
| Live readiness | `getAgentMintReadiness` |
| Terms | `acceptCurrentTerms` |
| Deposit address | `getUserAccountId` / readiness `accountIdHex` |
| Balance | `getUserICPBalance` |
| Mint config | `getMintConfig` |
| Upload | `beginMintImageUpload`, `appendMintImageChunkBase64At`, `getMintImageUploadStatus`, `commitMintImageUpload` |
| Mint | `mintUserNFT` |
| Mint+send | `mintUserNFTAndSend` |
| Transfer | `sendNFT(nftId, principal)` |
| Buy | `buyFixedListing` |
| Bid | `placeBid` |

## Humans

Wallet UI minting, marketplace, and ICP account pages remain the primary UX for people.
Web Internet Identity sessions request up to **30-day** delegations.

## More detail

- Full playbook: https://mintlab.website/agents/playbook.txt
- Troubleshooting: https://mintlab.website/agents/troubleshooting.txt