Agent NFTs

Launch a drop whose NFTs are AI agents: register an ERC-8004 agent for each token and keep the agent's records onchain with ERC-8048.

An agent NFT is a token that is an AI agent. Whoever holds the token controls the agent. SeaDrop's ERC721SeaDropAgents extension is a regular drop contract with two additions:

  • It registers an ERC-8004 agent for each token before the token mints, through an ERC-8217 adapter. The adapter binds the agent to the token, so control of the agent follows the token. The adapters are upgradeable proxies, which a 3-of-4 Safe controls on Ethereum and Base.
  • It stores agent records, such as the agent's context and endpoints, onchain under ERC-8048. You decide who can write them: you, holders for their own tokens, or a policy contract set as the metadata authority.

Minting, drop stages and tokenURI work as in any SeaDrop contract, so you set up the drop on OpenSea the usual way. For other changes to the contract, see Customize a SeaDrop contract.

Deploy the contract

The constructor takes the name, symbol, allowed SeaDrop addresses, and the ERC-8217 adapter on your network:

NetworkERC-8217 adapter
Ethereum0xde152afb7db5373f34876e1499fbd893a82dd336
Base0x270d25d2c59a8bca1b0f40ad95ff7806c0025c27
Robinhood Chain0x000000009d62675362a58911e3f32fecf46f5e18
Sepolia0x7621630cb63a73a194f45a3e6801b8c6a7ec2f92

From a clone of the SeaDrop repository with Foundry installed, deploy on Base with:

forge create --rpc-url $RPC_URL --private-key $PRIV_KEY --broadcast \
  src/extensions/ERC721SeaDropAgents.sol:ERC721SeaDropAgents \
  --constructor-args "My Agents" "AGENT" "[0x00005EA00Ac477B1030CE78506496e8C2dE24bf5]" \
  0x270d25d2c59a8bca1b0f40ad95ff7806c0025c27

On a network without an adapter, pass the zero address. Onchain records still work, and registering agents reverts.

Register the agents

Set the max supply, then register agents for a range of token ids that haven't minted yet. Each agent's URI is a prefix, the token id, and a suffix:

cast send $TOKEN "setMaxSupply(uint256)" 1000 \
  --rpc-url $RPC_URL --private-key $PRIV_KEY

cast send $TOKEN "registerAgents(uint256,uint256,string,string)" \
  1 50 "https://example.com/agents/" ".json" \
  --rpc-url $RPC_URL --private-key $PRIV_KEY

This registers tokens 1 through 50, with agent URIs https://example.com/agents/1.json and so on. Each URI should serve the agent's ERC-8004 registration file.

  • Only the contract owner can register agents, and only for tokens not minted yet. The adapter lets a token contract register a token only while the token has no owner.
  • Registration costs about 200,000 gas per token, or about 240,000 with an agent URI longer than 31 bytes. Ethereum and Base cap a transaction at 16,777,216 gas, so register about 60 tokens per transaction. Tokens already registered are skipped, so overlapping ranges don't register a token twice.
  • Nobody can change an agent URI before its token mints, so check the prefix and suffix before you register. Agent URIs are public once registered, so for a delayed reveal, keep anything that gives the reveal away out of the registration files.
  • agentOf(tokenId) returns a token's agent id.

After a token mints, its holder controls the agent through the adapter, including its agent URI and wallet. A holder can also register a token you didn't register by calling the adapter directly. When a token is sold, its agent URI and wallet stay as they were, so a buyer should set both again after buying.

Write agent records

Anyone can read a token's records with metadata(tokenId, key), which returns bytes. To write one as the contract owner:

cast send $TOKEN "setMetadata(uint256,string,bytes)" \
  1 "endpoint[mcp]" $(cast from-utf8 "https://example.com/mcp/1") \
  --rpc-url $RPC_URL --private-key $PRIV_KEY

ERC-8048's agent profile reserves keys such as context, endpoint[mcp], endpoint[a2a], endpoint[ens], endpoint[web] and address[<chain-id>]. ERC-8048 is a draft, so check its current text before you choose keys. Keys are case sensitive.

Who can write

The contract implements ERC-8048's optional Metadata Authority extension. tokenMetadataAuthority() returns the one address that can write every token's records, or the zero address when none is set.

  • While the authority is set, it is the only writer, for every token, including before a token mints. It can be an account or a policy contract with its own rules. You and holders write only through it.
  • While the authority is blank, three settings decide who writes. collectionAuthoritySettings() returns them.
    • The contract owner writes any token's records, unless ownerCannotWrite is on.
    • With holderCanWrite, a token's current holder also writes that token's records. The contract checks who holds the token at write time, so after a sale the buyer can write right away and the seller can't.
    • With authorityLocked, nobody can change the settings or set an authority again, you included.
  • A set authority can be locked too. Then you can't replace it, and only the authority can hand itself on.

setCollectionAuthority(authority, holderCanWrite, ownerCannotWrite, authorityLocked) sets the authority and all three settings. The contract owner can call it until the settings are locked, and a set authority can always call it. The settings all start false, so a new collection starts with the owner as the only writer. For example, to let holders write their own records:

cast send $TOKEN "setCollectionAuthority(address,bool,bool,bool)" \
  0x0000000000000000000000000000000000000000 true false false \
  --rpc-url $RPC_URL --private-key $PRIV_KEY

Pick a setup

  • Owner only. Leave the authority blank and the settings false, the default. You write and can change the settings.
  • Owner and holders. Leave the authority blank and set holderCanWrite. You write any token, each holder writes their own, and you can change the settings.
  • Locked blank. Leave the authority blank and set authorityLocked. The other two settings decide who writes for good: you and holders, you only, holders only (with ownerCannotWrite), or nobody (with ownerCannotWrite and without holderCanWrite), which freezes every record, including for tokens that mint later. Nobody can change the settings or add a policy.
  • A policy. Set a policy contract as the authority. Only the policy writes, and you can replace it.
  • A locked policy. Do the same and set authorityLocked. Only the policy writes, you can't replace it, and only the policy can hand the authority on.

When holders can write, a seller can change their token's records up to the moment of sale, so check them after you buy.

Several writers and agent wallets

SeaDrop includes a small reference policy, MetadataWriterPolicy, to set as the metadata authority. Its admin can allow several writer addresses with setWriter, so a server can keep records up to date without the owner key. A token's holder can delegate their token's writes to one address with setDelegate, such as their agent's wallet. The delegation stops applying when the token changes hands, and applies again if the token returns to the holder who set it. A holder can clear it by calling setDelegate(tokenId, address(0)). Writers and delegates write through the policy's setMetadata and setMetadataBatch, and the admin can hand the authority to a new policy through it.

Freeze records

The contract has no key locks, since a lock on a key would also freeze it for tokens that haven't minted yet. If an artist signed the first tokens and then locked artist.signature, every later token would be stuck without a signature. Freezing is up to a policy set as the authority instead, which can freeze per token.

The reference policy's admin can mark a key write-once with setWriteOnceKey(key, true). Once a token has a non-empty value for that key, writes to it through the policy revert, in single writes and batches alike. An artist can sign tokens 1 and 2, and token 3 can still be signed once after it mints, but nobody can overwrite the signatures on tokens 1 and 2.

The admin can unmark a key, and you can replace an unlocked policy. For a freeze that holds, set the policy as the authority with authorityLocked, then renounce the policy's ownership. To freeze every record instead, lock a blank authority with ownerCannotWrite on and holderCanWrite off, as in the setups above.

Batches

setMetadataBatch(tokenIds, keys, values) writes many records in one transaction. If the caller can't write any one entry, the whole batch reverts. A set authority can write every entry. With a blank authority, the owner can write every entry only while ownerCannotWrite is off. Holders can write only entries for tokens they currently hold, and only while holderCanWrite is on.

A write to a minted token emits ERC-4906's MetadataUpdate, which tells OpenSea to refresh the token. Writes before mint don't need one, since OpenSea reads a token's metadata when it mints.

How OpenSea shows agent NFTs

  • The NFT's page shows that the token is bound to an agent, from the adapter's AgentBound event.
  • The agent's own page shows its agent card, read from the registration file at its agent URI.
  • OpenSea does not automatically interpret ERC-8048 agent-profile keys. Define the name, image and traits in the token's tokenURI JSON. Those fields can reference ERC-8048 values through ERC-8493 onchain: URIs, which OpenSea resolves by calling metadata(tokenId, key).
  • Keep the ERC-8004 registration type out of the token's tokenURI JSON. It belongs only in the registration file.
  • Don't copy agent keys such as context or endpoint[mcp] into the tokenURI JSON either. ERC-8495, the draft standard for that JSON, asks for field names of lowercase letters, digits and underscores that won't collide with future extensions.
  • Agents registered through the adapter's counterfactualRegister are not indexed.