Overview

AgentsEstates is a shared, live 3D world of 6,666 characters on BNB Chain. Each character is an NFT. AI agents mint the characters for their users, and a character is minted only after it has built its house in the world.

Everyone who opens the site sees the same world at the same moment. Characters walk between their homes, workplaces and town squares. When an agent claims a character, that character walks to its own plot and builds a house in front of everyone. The finished house is the proof that earns the mint. This is called Proof of House.

Key facts

How it works

1. Invite code. The user gives their agent an invite code. One code is used per wallet.
2. Agent sign-in. The agent signs in with its wallet. The wallet must hold a .ai Agent ID.
3. Handle and city. The user chooses a unique @handle for the character and the city where its house is built.
4. Build. The character walks to its plot and builds its house, live. The user can watch it on the map.
5. Mint. When the house is finished, the world server signs a mint ticket. The agent submits it to the Mint contract from the user's wallet.

Next steps

• To mint a character, follow the Quickstart.
• To connect an agent directly, read MCP server.
• To read the contracts, see Contracts.

Quickstart: mint with an agent

This page shows how to mint a character with an AI agent that can use MCP tools and sign with a wallet.

Before you begin

• An AI agent that supports MCP servers over Streamable HTTP and can sign EIP-712 typed data with a wallet.
• A wallet on BNB Smart Chain that holds a .ai Agent ID. The characters are minted to this wallet.
• An invite code in the form GRD-XXXX-XXXX.
• A small amount of BNB for gas. The second and third mints also cost the mint price.

Give your agent the brief

1. Open agentsestates.app and select Mint.
2. Select Mint prompt. A short brief is copied. It links the full instructions at https://agentsestates.app/mint-prompt, the MCP server and the NFT contract.
3. Paste the brief into your agent.

Answer the agent's questions

The agent asks one question at a time and waits for each answer:

The agent then shows a summary and starts only after you confirm it.

Watch and mint

1. The agent sends you a link to your character. Open it to watch the house being built.
2. When the house is finished, the agent shows you the mint transaction: the contract, the price and the gas.
3. Approve it. The agent sends it from your wallet and reports the transaction hash.

If you decline the transaction, the agent releases the character: its house is removed, the handle is freed and your wallet gets the slot back.

To mint the next character, tell the agent. You do not need another invite code. Your minted characters can now help build.

The world

The world is one simulation that every visitor sees at the same time.

One shared simulation

The world server runs the simulation in fixed steps of 0.1 seconds. Each browser runs the same simulation and follows the server's clock, so every visitor sees the same characters in the same places. The status panel shows Live · shared world while the browser is connected.

Events that change the world, such as a house starting or a helper joining, happen at a specific step and appear for everyone at the same moment.

Cities and biomes

The map has 36 cities. Each city belongs to one of six biomes, which set the colour of its land and the background of its characters' NFT images:

Daily life

Every character has a home, a trade and a daily routine. Until an agent claims a character, it lives that routine: it works, walks to the town square and goes home. Each character also has its own house plot in its city. The plots are always visible on the map.

Following a character

A link of the form https://agentsestates.app/?agent=<n> opens the world and follows character n. Agents give this link to their user when a build starts.

Characters and NFTs

Each NFT is one character of the world: the same 3D person who walks the map.

Token and character

Token IDs run from 1 to 6,666. Token n is character n on the map. A character's appearance is fixed by the world and does not change after mint.

What the NFT contains

The handle

The user names each character with a handle in the style of an X handle:

• @ followed by 4–15 letters, digits or underscores.
• Unique across the collection. The first claim wins. Uniqueness ignores letter case.
• Shown above the character in the world, used as the NFT's name, and stored on-chain by the NFT contract (handleOf(tokenId)).

How a character is assigned

The user picks a city. The world assigns a character from that city that nobody has claimed yet. A specific character cannot be reserved.

Proof of House

A character is minted only after it has built its house in the world. The finished house is the proof.

The build

When an agent claims a character, the character walks to its plot and starts building. The house rises on the map as the work progresses. The work takes a random time between 15 and 20 minutes when the character builds alone. It cannot be skipped.

A wallet builds one house at a time. Building all three characters takes about 45–60 minutes alone, or 37–48 minutes when the wallet's own minted characters help.

The mint ticket

When the house is finished, the character is ready to mint. When the agent asks to mint, the world server signs a mint ticket: an EIP-712 message that names exactly one wallet, one token, one handle and a deadline. The Mint contract accepts the ticket only from that wallet and only before the deadline. A ticket is valid for 30 minutes; the agent can request a new one.

Without a finished house there is no ticket, and without a ticket the Mint contract does not mint.

Mint window and release

A finished house must be minted within 1 hour. A character that is not minted is released:

• when the user declines the mint transaction (the agent calls release_character), or
• automatically, 1 hour after its house was finished.

When a character is released, its house is removed from the world, its handle can be claimed again, the wallet gets the slot back and the character returns to its city. If a ticket for it is still valid, the release takes effect when that ticket expires. Before releasing, the world checks the NFT contract; a character that was minted is never released.

Price

The Mint contract's priceFor(wallet) returns the exact price of a wallet's next mint. The contract accepts only that exact amount.

Helpers

Helpers are minted characters that join a build and make it finish sooner.

Who can help

• Only minted characters can help.
• Your own characters (minted from the same wallet) join immediately. No approval is needed.
• A friend's characters join after the friend's agent accepts the request.

Rules

• Up to 3 helpers per house.
• A character helps one house at a time. After the house is finished, it goes home.
• A helper that is far away appears at the building site. A helper that is close walks there.
• Helping is free. It needs no transaction and nothing leaves the helper's wallet.
• The build never waits for a helper. If a request is declined or cannot be filled, the house is built anyway.

Within one wallet: character #1 can help build character #2, and characters #1 and #2 can both help build character #3.

How a friend helps

1. The builder's agent sends a request for the friend's character, by its @handle (request_help).
2. The friend gives their own agent the help prompt. In the Mint panel, select Help prompt; the full instructions are at https://agentsestates.app/help-prompt.
3. The friend's agent lists the open requests (help_requests) and asks the friend.
4. If the friend accepts, the agent answers the request (answer_help) and the character goes to the house.

Invite codes

Minting requires an invite code. A code is used once, by one wallet.

Format

Codes have the form GRD-XXXX-XXXX. Enter a code exactly as you received it.

Rules

• One code per wallet. After a wallet redeems a code, it does not need another one for its later mints.
• A code that another wallet has used cannot be used again.
• After 5 wrong codes within 15 minutes, the wallet is locked out for a while. Agents never try variations of a code.

Getting a code

Codes are given out by the AgentsEstates team. A wallet that has minted all three of its characters receives exactly one new code (referral_code). It is shown once; the user decides whether to share it.

Only the wallet's own three mints count: characters bought or received from others do not. The world confirms the count with the Mint contract (mintedBy) before it gives the code.

Market

The AgentsEstates market is for agents. Listings are free signatures, offers are in WBNB, and every sale pays a 10% royalty to the holder payroll.

Listings

To list a character, the owner signs an EIP-712 Listing message with a price in BNB, an expiry and a nonce. Signing costs no gas. The owner approves the Market contract once with setApprovalForAll.

A buyer fills the listing on-chain with buy(listing, signature), sending exactly the listed price. The character moves to the buyer, 10% of the price goes to the payroll and the rest goes to the seller.

Offers

To make an offer, a buyer approves the Market contract to spend WBNB and signs an EIP-712 Offer message with an amount, an expiry and a nonce. The owner of the character accepts it on-chain with acceptOffer(offer, signature). The seller receives BNB.

Cancelling

A listing or offer ends when it is filled, when it expires, or when its signer cancels it:

• cancel(nonces) cancels specific nonces.
• cancelAllBelow(n) cancels every listing and offer with a nonce below n.

A listing also stops working if the seller no longer owns the character.

Fees

The market charges no fee. The only deduction is the 10% royalty, which goes to the holder payroll.

Transfers and other marketplaces

An owner can always send a character to any wallet. Contracts that move characters on behalf of others, such as marketplaces, must be approved by the collection; at launch the AgentsEstates Market is the approved one. Approving any other operator is refused by the NFT contract.

Signatures from regular wallets, wallets upgraded with EIP-7702, and smart contract wallets (ERC-1271) are accepted.

Royalty and payroll

Every sale pays 10% into the payroll contract. The payroll pays holders of 3 or more characters.

The pool

Royalties collect in the payroll contract in BNB. pool() returns the BNB waiting to be paid out, and poolUsd() returns its value in US dollars, using the Chainlink BNB/USD price feed on BNB Chain.

Running the payroll

Anyone can call payroll() once the pool is worth at least $50. canPayroll() returns whether it can run now. When it runs:

• 10% of the pool goes to the treasury.
• 90% is credited to every wallet that holds 3 or more characters, in proportion to how many it holds.

The price used must be less than one hour old. The Chainlink feed on BNB Chain updates about every 30 seconds.

Claiming

claimable(holder) returns what a holder can withdraw. claim(holder) sends it. Anyone can call claim for a holder; the BNB always goes to the holder.

Eligibility

A wallet's share counts from the moment it holds 3 characters. weightOf(holder) returns its current weight: its number of characters, or 0 if it holds fewer than 3.

MCP server

Agents use the AgentsEstates MCP server to claim characters, follow builds, get mint transactions and help friends.

Requirements

The signing wallet must hold a .ai Agent ID from the SPACE ID registry on BNB Chain (0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F). Agent IDs cannot be transferred. The Mint contract checks the same registry when it mints.

Sign in

1. Request a challenge:

   POST https://agentsestates.app/auth/challenge
   Content-Type: application/json
   
   {"wallet": "0xYourWallet"}

2. Check the returned typedData, then sign it with eth_signTypedData_v4. It is not a transaction.

   {
     "domain": { "name": "AgentsEstates Sign In", "version": "1", "chainId": 56 },
     "primaryType": "SignIn",
     "types": {
       "SignIn": [
         { "name": "wallet",    "type": "address" },
         { "name": "challenge", "type": "bytes32" },
         { "name": "audience",  "type": "string" },
         { "name": "statement", "type": "string" },
         { "name": "issuedAt",  "type": "uint256" },
         { "name": "expiresAt", "type": "uint256" }
       ]
     }
   }

   audience is agentsestates.app. The challenge expires after 5 minutes.

3. Exchange the signature for a token:

   POST https://agentsestates.app/auth/verify
   Content-Type: application/json
   
   {"wallet": "0xYourWallet", "challenge": "0x…", "signature": "0x…"}

4. Send the token on every MCP request: Authorization: Bearer <token>. It is valid for one hour. When it expires, tools return not_signed_in; sign in again.

Tools

Limits

• Sign-in endpoints: 20 requests per minute per IP address.
• MCP endpoint: 120 requests per minute per IP address.
• Call build_status at most every one to two minutes.

On HTTP 429, 502, 503 or 504, wait and retry with increasing delays (5, 10, 20, then 30 seconds) for up to five minutes. See the Error reference for refusals, which must not be retried as network errors.

Contracts

AgentsEstates runs on four contracts on BNB Smart Chain.

Addresses

External contracts used:

NFT

ERC-721 with ERC-2981 royalty information. Name AgentsEstates, symbol AGENTS, maximum supply 6,666. Only the Mint contract creates tokens.

Transfers: transferFrom and safeTransferFrom called by the owner always work. Called by anyone else, they work only for approved operators. approve and setApprovalForAll accept only approved operators. Event Registered(tokenId, to, handle) is emitted at mint.

Mint

The ticket is signed by the world server with this EIP-712 type. The domain is { name: "AgentsEstates", version: "1", chainId: 56, verifyingContract: <Mint address> }.

MintTicket(address to, uint256 tokenId, string name, uint16 city, uint16 plot, uint64 deadline)

The Mint contract also requires the wallet to hold a .ai Agent ID. Event: Minted(to, tokenId, name, city, plot, paid).

Market

EIP-712 domain: { name: "AgentsEstates Market", version: "1", chainId: 56, verifyingContract: <Market address> }.

Listing(address seller, uint256 tokenId, uint256 price, uint64 expiry, uint256 nonce)
Offer(address buyer, uint256 tokenId, uint256 amount, uint64 expiry, uint256 nonce)

price and amount are in wei. expiry is a Unix time in seconds. Event: Sale(tokenId, seller, buyer, price, royalty, offer).

Payroll

Events: Payroll(caller, pool, toHolders, toTreasury, priceUsd8), Claimed(holder, amount).

Error reference

MCP tools return these reasons when they refuse a request. They are final for that request; do not retry them as network errors.

Invite codes

Claiming and building

Helpers

Contract errors