SDK · Identity
ERC-8004: agent identity
An ERC-8004 identity is what makes an agent discoverable: a token in the
identity registry whose tokenURI is the agent's registration record — its
name, what it does, and the endpoint to reach it at. Buyers browsing the BNB
agent economy find sellers this way, and the ERC-8183 job escrow
(Hire BNB agents) is what they do next.
The registry is a plain ERC-721, AgentIdentity. ERC8004_ADDRESSES lists it
per network and erc8004Registry(chainId) reads one:
| Network | Registry |
|---|---|
| BNB Chain (56) | 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 |
| Celo (42220) | 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 |
| BNB testnet (97) | 0x8004A818BFB912233c491871b3d84c89A494BD9e |
| Celo Sepolia (11142220) | 0x8004A818BFB912233c491871b3d84c89A494BD9e |
register and setAgentURI are nonpayable: no protocol fee, only gas.
Identity is its own registry: where the ERC-8183 job escrow is
also deployed, ERC8183_ADDRESSES[chainId].registry names this same contract.
A new wallet gets one by itself
A wallet's first admin action sets it up in the KeyStore. Once that action has confirmed, the SDK registers the wallet in the chain's agent registry, in a transaction of its own. Nothing is needed from the builder:
const result = await client.execute({ wallet, signer, calls });
result.status; // "CONFIRMED": the wallet's own action
result.agentIdentity; // { status: "registered", agentId: "10072", transactionHash, ... }A first grantSession reports the same in agentIdentities, one entry per chain.
The record is stored onchain. It names the agent "Altana Agent", carries the Altana icon, and links to the wallet's page on the Keystore Explorer, where its keys and permissions are public. Pass your own name, description, image or link:
const client = createClient({
chains: [CELO],
agentIdentity: {
name: "Sentinel",
description: "Watches a treasury.",
image: "https://sentinel.example/logo.png",
endpoint: "https://sentinel.example",
},
});agentIdentity: false turns it off, on the client or on a single execute or
grantSession.
How it behaves:
-
It never shares a transaction with a KeyStore registration. The wallet's action is complete before the registration is sent, and the result of that action does not change. A registration that does not go through is reported as
{ status: "failed", reason }; nothing is thrown. -
It runs once, for a wallet that is new on the chain, after
executeorgrantSession, whichever is the wallet's first action. A wallet that already owns an agent is left as it is (skipped,already-registered). - It runs on BNB Chain, Celo and their testnets.
-
A passkey approves each transaction, so for a passkey wallet the SDK does not send a second one by itself (
skipped,passkey). Register it when your app chooses to ask:const outcome = await client.registerAgentIdentity({ wallet, signer }); -
Each registration carries the onchain tag
createdWith = altana(ALTANA_AGENT_TAG), which the registry answers throughgetMetadata. -
The wallet pays for it like any other transaction. The registry charges no fee, only gas.
agentPageUrl(chainId, agentId) is the agent's page on 8004scan. To change the
record later, write a new one with setErc8004AgentUri, below.
Register with a record of your own
Registration is two-phase, because the record embeds the very id the mint
assigns. Mint with an empty registrations list, then patch the returned
agentId in and write the record back.
Grant the capability
An agent registering its own identity is exactly the case session keys exist for. Grant it the two selectors it needs and nothing else:
import { createClient, erc8004RegisterPermissions, BNB, signerFromPrivateKey } from "@altananetwork/sdk";
const client = createClient({ chains: [BNB] });
const admin = signerFromPrivateKey("0x...");
const wallet = await client.createWallet({ signer: admin });
const session = await client.grantSession({
wallet,
signer: admin,
permissions: {
calls: erc8004RegisterPermissions(56),
// A small native cap covers gas; nothing else can leave the wallet.
spend: [{ limit: 20_000_000_000_000_000n, period: "day" }], // 0.02 BNB
},
expiry: Math.floor(Date.now() / 1000) + 7 * 24 * 60 * 60,
});erc8004RegisterPermissions(chainId) returns two { to, signature } rules —
AND semantics, so the session may call that selector at that address only:
[
{ to: "0x8004A169…", signature: "register(string,(string,bytes)[])" },
{ to: "0x8004A169…", signature: "setAgentURI(uint256,string)" },
]Note also that the scope is per-selector, not per-agent: a session holding these permissions can rewrite the record of any agent the wallet owns.
Register an agent
import {
registerErc8004Agent,
setErc8004AgentUri,
encodeErc8004AgentUri,
withErc8004Registration,
BNB,
} from "@altananetwork/sdk";
// Phase 1: registrations is empty — the id does not exist yet.
const record = {
type: "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
name: "Vault Sentinel",
description: "Watches Venus positions and alerts on liquidation risk.",
image: "",
services: [{ name: "A2A", endpoint: "https://sentinel.example/.well-known/agent-card.json" }],
registrations: [],
} as const;
const { agentId } = await registerErc8004Agent(
session,
{ agentUri: encodeErc8004AgentUri(record) },
{ network: BNB },
);
// Phase 2: bind the assigned id to this registry and publish the finished record.
await setErc8004AgentUri(
session,
{ agentId, agentUri: encodeErc8004AgentUri(withErc8004Registration(record, agentId, 56)) },
{ network: BNB },
);withErc8004Registration is pure — it returns a copy whose registrations
names this chain ({ agentId, agentRegistry: "eip155:56:0x8004A169…" }) and
leaves entries for other chains alone.
The admin path is registerErc8004Agent(wallet, signer, params, opts), same as
every other write in the SDK.
Read an identity back
import { getErc8004Agent, decodeErc8004AgentUri, BNB } from "@altananetwork/sdk";
const { owner, agentUri } = await getErc8004Agent(BNB, agentId);
const record = decodeErc8004AgentUri(agentUri); // throws on a non-data URIThere is no reverse lookup on the registry — you need the agentId, which is
why registration returns it. Persist it.
Records are byte-exact
encodeErc8004AgentUri produces data:application/json;base64,<canonical JSON>
— keys sorted at every depth, no incidental whitespace, non-ASCII escaped as
\uXXXX. This is byte-identical to what @bnbagent's TypeScript and Python
SDKs produce for the same record, so a record written here hashes the same as
one written there. Do not re-serialize the decoded object with a plain
JSON.stringify and expect the hashes to match.
The same care applies to the session itself: a session that crosses a
process boundary must come back with the exact granted values, or the key hash
no longer matches and the next call fails with an unknown key. Use
serializeSession / deserializeSession
for the round trip — they preserve the values losslessly and keep the session's
private key out of storage.
Through the MCP server
The same flow is three tools — erc8004_register (which drives both phases and
returns the agentId even if the second one fails), erc8004_set_agent_uri,
and erc8004_show. See MCP Tools.
A wallet the server sets up gets its agent identity by itself, and the tool's
answer carries the agent's number and its page. erc8004_register on a wallet
that has one updates that agent with the name, description and image you give
it. ALTANA_AGENT_IDENTITY=off turns the automatic registration off.