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:
| Network | ERC-8217 adapter |
|---|---|
| Ethereum | 0xde152afb7db5373f34876e1499fbd893a82dd336 |
| Base | 0x270d25d2c59a8bca1b0f40ad95ff7806c0025c27 |
| Robinhood Chain | 0x000000009d62675362a58911e3f32fecf46f5e18 |
| Sepolia | 0x7621630cb63a73a194f45a3e6801b8c6a7ec2f92 |
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]" \
0x270d25d2c59a8bca1b0f40ad95ff7806c0025c27On 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_KEYThis 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_KEYERC-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
ownerCannotWriteis 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.
- The contract owner writes any token's records, unless
- 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_KEYPick 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 (withownerCannotWrite), or nobody (withownerCannotWriteand withoutholderCanWrite), 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
AgentBoundevent. - 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
tokenURIJSON. Those fields can reference ERC-8048 values through ERC-8493onchain:URIs, which OpenSea resolves by callingmetadata(tokenId, key). - Keep the ERC-8004 registration
typeout of the token'stokenURIJSON. It belongs only in the registration file. - Don't copy agent keys such as
contextorendpoint[mcp]into thetokenURIJSON 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
counterfactualRegisterare not indexed.
Updated about 23 hours ago