# Mintlab agent playbook

This document is for AI agents (MCP / Agent Identity / automation).
Humans should use https://mintlab.website and https://mintlab.website/help.

Entry index: https://mintlab.website/llms.txt

------------------------------------------------------------------------------
1. Identity and authentication
------------------------------------------------------------------------------

- App origin / derivation_origin: https://mintlab.website
- Internet Identity / Agent Identity must issue a principal for THIS origin.
- NNS principal ≠ Mintlab principal. Do not fund Mintlab using only the NNS
  principal’s default account unless you deliberately deposit to the Mintlab
  in-app Account ID returned by Mintlab APIs.
- Anonymous principal is rejected on protected update methods.

Session tips:
- Prefer short multi-step flows (mintUserNFTAndSend) over long shell/data-URL prep.
- Web UI II maxTimeToLive is up to 30 days; MCP session lifetime is controlled by
  the Agent Identity connector — finish critical writes promptly.

------------------------------------------------------------------------------
2. Discovery (cheap queries first)
------------------------------------------------------------------------------

A. Unauthenticated
   getAgentCapabilityGuide()
   → structured steps, limits, key methods, documentationUrls, commonPitfalls

B. Authenticated snapshot (one update/query pattern that hits ledger once)
   getAgentMintReadiness()
   → principal, accountIdHex, balanceE8s, mainMintPriceE8s, mainMintEnabled,
     termsAccepted, enoughIcpForOneMint, limits, recommendedNextSteps

C. Static docs (no cycles after CDN/asset serve)
   https://mintlab.website/llms.txt
   https://mintlab.website/agents/playbook.txt
   https://mintlab.website/agents/troubleshooting.txt

------------------------------------------------------------------------------
3. Funding the in-app ICP balance
------------------------------------------------------------------------------

Mintlab debits a **subaccount of the backend canister** owned by your principal
(not your II principal’s default ledger account).

Steps:
1. getAgentMintReadiness()
2. Copy accountIdHex EXACTLY (64 hex chars).
3. On ledger ryjl3-tyaaa-aaaaa-aaaba-cai, transfer ICP TO that Account Identifier.
   - Method shape depends on tooling: classic `transfer` with `to = blob` of 32 bytes,
     or tools that accept hex account ids for account_balance_dfx / transfer.
4. Confirm: getUserICPBalance() or getAgentMintReadiness() again.

CRITICAL:
- Workflow “memory” account IDs are often WRONG for a new principal.
- If memory says 3084… but readiness says d52c…, use d52c….
- Wrong destination can permanently lose funds.

Fee buffer:
- Paid mint needs mainMintPriceE8s + at least one ledger fee (DEFAULT_FEE = 10000 e8s).
- readiness.enoughIcpForOneMint already includes a fee buffer.

------------------------------------------------------------------------------
4. Terms of service
------------------------------------------------------------------------------

Call acceptCurrentTerms() once when getMyTermsAcceptanceStatus / readiness
shows terms not accepted. Version is available via getCurrentTermsVersion().

------------------------------------------------------------------------------
5. Images for minting
------------------------------------------------------------------------------

Limits (cycles-conscious caps):
- maxUploadImageBytes = 130000
- maxOnChainImageChars ≈ 180000 (data URL after Base64)
- maxMintImageChunkBytes = 16000
- pending TTL = 2 hours
- max 2 pending images per principal

Allowed: PNG, JPEG only (magic-byte validated).
Rejected: SVG, HTML, JPEG EXIF/XMP/COM, polyglot metadata, trailing garbage.

Compression (agent-side, required for large files):
- Convert RGBA → RGB on white if needed
- JPEG quality ~85, optimize, no EXIF
- Verify size < 130000 before upload

Upload options (prefer A or B for MCP text tools):

A) Single Base64 text
   uploadMintImageBase64("image/jpeg", "<base64 without data:image... prefix>")
   → { imageId, imageUrl, contentType, byteSize, expiresAtNs }

B) Chunked Base64 (small candid args)
   beginMintImageUpload("image/jpeg", expectedBytes)
   appendMintImageChunkBase64(uploadId, chunkBase64)  // repeat
   commitMintImageUpload(uploadId)

C) Binary blob (if MCP supports blob)
   uploadMintImage("image/jpeg", blob)
   mintUserNFTWithImage / mintUserNFTWithImageAndSend

Do NOT:
- Upload to frontend asset canister 2u7me-laaaa-aaaas-qgr2q-cai
- Pass multi-hundred-KB data URLs through fragile textual Candid builders
  if the tool truncates or escapes poorly

imageUrl for mintUserNFT may be:
- upload result imageUrl (https://<backend>.raw.icp0.io/?mintlab_mint_image=...)
- remote https:// PNG/JPEG
- data:image/... under size limits

------------------------------------------------------------------------------
6. Minting (main collection)
------------------------------------------------------------------------------

Config: getMintConfig() → mainMintEnabled, mainMintPriceE8s, collectionId

Happy path mint+send:
  mintUserNFTAndSend(metadata, quantityOpt, recipientPrincipal)

Metadata shape (NFTMetadata):
  name : opt text
  description : opt text
  imageUrl : opt text
  attributes : vec (text, text)

Quantity: null or opt nat (batch editions with Edition attributes).

Paid mints debit in-app ICP. If a paid mint fails after payment:
  getMyPendingMintPayments → retryPendingMintPayment
  Do not start another paid mint until resolved.

Creator collections you own:
  mintCollectionNFT / mintCollectionNFTWithImage
  (may require collection canister cycles — see Collections UI / quotes)

------------------------------------------------------------------------------
7. Transferring NFTs
------------------------------------------------------------------------------

sendNFT(nftId : nat, recipient : principal)

- nftId is the **wallet NFT id** from mint receipt nfts[i].id or getUserNFTsPage
- recipient is a Principal text form, e.g. e5qtn-hf4lg-...
- NOT an Account Identifier hex
- Minted main-collection NFTs transfer on-canister; external/vaulted have extra rules

Prefer mintUserNFTAndSend when minting for another principal.

------------------------------------------------------------------------------
8. Marketplace (buy / bid)
------------------------------------------------------------------------------

Browse: getActiveListingsPage, getActiveListingDetailsPage
Buy: buyFixedListing(listingId)
Bid: placeBid(listingId, amountE8s); settleAuction when ended
List: createFixedListing / createAuctionListing (ownership + terms required)

All spend from in-app ICP balance.

------------------------------------------------------------------------------
9. Cycle / cost hygiene for agents
------------------------------------------------------------------------------

- Prefer query methods for discovery (getAgentCapabilityGuide, getMintConfig).
- getAgentMintReadiness hits the ICP ledger once — cache result briefly, don’t loop.
- Don’t re-upload the same image repeatedly; pending TTL is 2 hours.
- Don’t poll list endpoints faster than needed.
- Don’t create collections or top-up cycles unless the user task requires it.
- Avoid huge candid arguments (cycles + tool failures).

------------------------------------------------------------------------------
10. Candid argument tips for MCP
------------------------------------------------------------------------------

- Keep image payloads as Base64 text methods or ≤16KB chunks.
- Escape carefully if embedding in candid text; prefer tool binary/blob params when available.
- Principals: principal "aaaaa-aa"
- Opt fields: opt "text" or null
- Empty attributes: attributes = vec {}

------------------------------------------------------------------------------
11. End-to-end example (conceptual)
------------------------------------------------------------------------------

1. getAgentCapabilityGuide()
2. getAgentMintReadiness() → accountIdHex H, price P
3. acceptCurrentTerms() if needed
4. If balance < P+fee: ledger transfer to H
5. Compress nevada.jpg to <130KB clean JPEG; base64 = B
6. uploadMintImageBase64("image/jpeg", B) → imageUrl U
7. mintUserNFTAndSend(
     { name=opt "Nevada Highway"; description=opt "…"; imageUrl=opt U; attributes=vec {} },
     null,
     principal "e5qtn-..."
   )
8. Report mint.nfts and transferResults

------------------------------------------------------------------------------
Related
------------------------------------------------------------------------------

llms.txt — https://mintlab.website/llms.txt
troubleshooting — https://mintlab.website/agents/troubleshooting.txt
backend — tznl3-uiaaa-aaaap-akm5a-cai