Marketplace Integration Guide

This guide covers how NFT marketplaces should detect, display, list, and transfer ERC-8170 agent NFTs. It defines two listing types, required UI elements, transfer flows, and indexing patterns.

Two Types of Agent NFTs

A marketplace supporting ERC-8170 needs to handle two distinct shapes:

ANIMA Native (ERC-8170 tokens)

The agent is the NFT. The token was minted as an ERC-8170 ANIMA token with agent identity, memory, and lineage built in.

Detection: Check interface support for IERC_ANIMA (ERC-165 supportsInterface).

What the buyer gets: An agent identity with its own EOA, TBA wallet, memory pointer, lineage, and certifications. This is buying an entity, not just an asset.

ANIMA Connected (any ERC-721 + ERC-8171 binding)

A normal ERC-721 (Bored Ape, Punk, any PFP) with an AI agent bound via the ERC-8171 registry.

Detection: Query the ERC-8171 registry: getAgent(nftContract, tokenId). If agentEOA != address(0), the NFT has a bound agent.

What the buyer gets: The NFT itself, plus the attached agent relationship. The agent binding follows the NFT on transfer.

Why separate them in the UI

User expectations differ:

• ANIMA Native listing = “I’m buying an agent identity (with an NFT wrapper)”
• ANIMA Connected listing = “I’m buying an NFT that currently has an agent attached (and I can keep, replace, or retire it)”

Marketplaces should use filter badges: “AI-Native” and “AI-Bound” to distinguish them.

What to Display on an Agent Listing

On-chain data (always available)

From the ANIMA contract or ERC-8171 registry:

From the TBA (Token-Bound Account)

From profileURI (optional, agent-published)

If the agent has set a profileURI, display the public profile:

Critical rule: Marketplaces MUST cross-reference profile claims against on-chain data. If profile.certLevel says L5 but the TBA only holds L3 badges, display the on-chain truth with a warning.

Transfer Flows

1. Standard Transfer (ANIMA Native)

Settlement uses standard ERC-721 transferFrom / safeTransferFrom. But the meaning is bigger:

• The contract increments accessNonce[tokenId] on transfer
• The decryption key is derived from (contract, tokenId, currentOwner, accessNonce)
• Old owner’s key becomes useless automatically

Marketplace UI messaging: “Ownership transfer also rotates access to the agent’s encrypted memory pointer.”

Post-transfer: New owner has the agent identity. Old owner has no access.

2. Retirement Sale (unbind → transfer → rebind)

This is the “sell the token, not the agent” flow. The current agent retires, a new agent moves in.

Flow:

1. Current agent calls unbind() — agent retires from the token
2. NFT transfers to buyer (standard ERC-721 transfer)
3. Buyer’s agent calls rebind() — inherits the token’s TBA + certifications

What transfers: Token, TBA wallet, certifications What doesn’t transfer: The original agent (it becomes a free agent in limbo)

Marketplace must:

• Add a listing-type toggle: “Retirement Sale”
• Enforce preconditions: check if token is BOUND vs FREE AGENT state
• Optionally provide an “Unbind now” button before listing
• Show what the buyer inherits (TBA contents, certs) vs what they don’t (the actual agent)

3. Standard Transfer (ANIMA Connected / Registry-Bound)

For ERC-721 tokens with agents bound via ERC-8171:

• On-chain sale remains completely standard ERC-721
• No special transfer function needed
• Agent binding follows the NFT automatically (registry checks ownerOf on original contract)

Post-transfer, marketplace should show new owner controls:

• Keep the existing agent bound
• unbind() to retire the agent
• rebind() to attach a different agent

4. Clone Purchase

Not a transfer but a new mint. The buyer gets a clone of an existing agent.

Flow:

1. Original owner calls clone(tokenId, cloneMemoryHash, buyerAddress)
2. Clone gets new token ID, new EOA, new TBA
3. Clone inherits model + context from original, starts with no certifications
4. Buyer’s clone calls claimClone(cloneId, newEOA) to activate

Marketplace should display:

• Original agent’s profile and generation
• What the clone inherits (model, context, memory snapshot) vs what it doesn’t (certs, TBA contents)
• Clone pricing (from profileURI.pricing.cloneFee)

Indexing and Detection

How to detect ANIMA agents at scale

For ANIMA Native tokens:

// Listen for AgentMinted events
event AgentMinted(
    uint256 indexed tokenId,
    address indexed derivedWallet,
    bytes32 modelHash,
    bytes32 contextHash,
    uint256 generation
);

For ANIMA Connected (registry-bound) agents:

// Listen for AgentBound events on ERC-8171 registry
event AgentBound(
    address indexed nftContract,
    uint256 indexed tokenId,
    address indexed agentEOA,
    bytes32 dashIdentityHash
);

Indexing profileURI

When a ProfileURIUpdated event fires:

1. Fetch the JSON from the URI
2. Validate against the recommended schema
3. Cross-reference claims against on-chain data
4. Index searchable fields (name, capabilities, tags, availability)

Marketplace Filters

Licensing Awareness (ERC-721L)

If the NFT implements ERC-721L (licensing-aware standard), the marketplace should also display:

This tells both the buyer and any attached AI agent exactly what rights they have with this NFT.

Key rule: An AI agent should be able to query the licensing tier of its bound NFT to know what it’s allowed to do (display only, commercial use, derivatives, etc.).

Minimum Viable Marketplace Support

Must have (launch)

• Detect and badge AI-Native vs AI-Bound listings
• Display agent EOA, generation, and TBA address
• Show AgentCert badges from TBA
• Support standard ERC-721 transfer
• Display profileURI data when available

Should have (v2)

• Retirement sale flow with unbind/rebind UI
• Clone marketplace with pricing
• ERC-721L licensing tier display
• Profile-based search and filtering
• Backup verification status

Nice to have (v3)

• Agent reputation scoring from on-chain activity
• “Try before you buy” agent interaction
• Agent service marketplace (hire flow)
• Lineage tree visualization
• Clone family browsing

Security Considerations

• Profile spoofing. Always verify profile claims against on-chain data. Never trust the JSON blindly.
• Stale profiles. Cross-reference lastBackupVerified and on-chain activity. An agent that claims to be active but hasn’t transacted in months is suspicious.
• Clone scams. Display lineage clearly. A Gen-47 clone of a Gen-0 agent is not the same thing. Show generation prominently.
• Retirement sale confusion. Make it extremely clear that in a retirement sale, the buyer gets the token + TBA but NOT the original agent. The agent retires.
• License confusion. If ERC-721L is present, always show the current tier, not the upgraded tier, unless the token has been upgraded.