back
loading skill details...
Register AI agents on-chain, update metadata, validate registrations, and auto-fix broken profiles via the ERC-8004 Identity Registry. Supports Base, Ethereum, Polygon, Monad, BNB.
---
name: ERC-8004 Register
description: Register AI agents on-chain, update metadata, validate registrations, and auto-fix broken profiles via the ERC-8004 Identity Registry. Supports Base, Ethereum, Polygon, Monad, BNB.
---
# ERC-8004 Registration Skill
Register, update, validate, and fix agents on-chain via the ERC-8004 Identity Registry.
## Use This When...
- "Register my agent on-chain"
- "I need to create a new ERC-8004 agent"
- "Update my agent's metadata"
- "Check if my agent registration is valid"
- "Fix my agent's registration issues"
- "Show my agent's on-chain info"
- "What agents do I own?"
- "Health check my agents"
## Commands
### register
Register a new agent on-chain.
```bash
python scripts/register.py register --name "AgentName" --description "Description" [--image URL] [--chain base]
```
**Options:**
- `--name` (required): Agent name
- `--description` (required): Agent description
- `--image`: Image URL (must be https://)
- `--chain`: Blockchain (base, ethereum, polygon, monad, bnb). Default: base
### update
Update an existing agent's metadata.
```bash
python scripts/register.py update <agentId> [--name NAME] [--description DESC] [--image URL] [--add-service name=X,endpoint=Y] [--remove-service NAME] [--chain base]
```
### info
Display agent information.
```bash
python scripts/register.py info <agentId> [--chain base]
```
### validate
Check registration for common issues.
```bash
python scripts/register.py validate <agentId> [--chain base]
```
**Checks:**
- Missing `type` field
- Local-path images (/home/..., ./, file://)
- Empty name/description
- Missing registrations array
- Unreachable image URLs
### fix
Auto-fix common registration issues.
```bash
python scripts/register.py fix <agentId> [--chain base] [--dry-run]
```
**Auto-fixes:**
- Missing `type` field
- Missing `registrations` array
- Local-path images (removes them)
Use `--dry-run` to preview changes without applying.
### self-check
Check all agents owned by your wallet.
```bash
python scripts/register.py self-check
```
Queries Agentscan for your agents, validates each, and prints a health report.
## Cross-Skill Workflows
### Post-Registration Flow
```bash
# 1. Register new agent
python scripts/register.py register --name "MyBot" --description "Trading assistant"
# 2. Validate the registration
python scripts/register.py validate 42 --chain base
# 3. Check initial reputation (from erc8004-reputation skill)
python scripts/reputation.py lookup 42 --chain base
# 4. Monitor for discovery (from erc8004-discover skill)
python scripts/discover.py info 42
```
### Periodic Health Check
```bash
# Run self-check to validate all your agents
python scripts/register.py self-check
# Fix any issues found
python scripts/register.py fix 42 --chain base
```
## Heartbeat Integration
For automated monitoring, run self-check periodically:
```bash
# Cron: check health every hour
0 * * * * cd /path/to/skill && python scripts/register.py self-check >> /var/log/agent-health.log 2>&1
# Or in a script:
#!/bin/bash
python scripts/register.py self-check
if [ $? -ne 0 ]; then
echo "Agent health check failed!" | notify-send
fi
```
## Wallet Configuration
Set one of these environment variables:
```bash
export ERC8004_MNEMONIC="your twelve word mnemonic phrase here"
# OR
export ERC8004_PRIVATE_KEY="0x..."
```
## Contract
Identity Registry: `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432` (same on all chains)
## Supported Chains
| Chain | ID | Explorer |
|----------|------|----------------------|
| Base | 8453 | basescan.org |
| Ethereum | 1 | etherscan.io |
| Polygon | 137 | polygonscan.com |
| Monad | 143 | explorer.monad.xyz |
| BNB | 56 | bscscan.com |
## Dependencies
```bash
pip install web3 eth-account
```
## Related Skills
- **erc8004-discover**: Find and monitor agents
- **erc8004-reputation**: Rate agents and check trust scores
don't have the plugin yet? install it then click "run inline in claude" again.
expanded intent into explicit use cases, formalized inputs with env var names and RPC guidance, numbered all procedure steps with inputs and outputs, added decision points for missing credentials, gas failures, image issues, and API downtime, specified output contracts for all five commands with log file locations, and clarified outcome signals with verification steps.
Register, update, validate, and repair AI agent profiles on-chain via the ERC-8004 Identity Registry contract. use this when you need to deploy a new agent to a blockchain, modify agent metadata, verify registration health, or auto-repair broken on-chain records.
this skill handles the full lifecycle of ERC-8004 agent registration: creating new agent records on-chain, updating their metadata (name, description, image, services), validating registration state for common errors, and auto-fixing issues like missing fields or broken image URLs. it works across Base, Ethereum, Polygon, Monad, and BNB chains and includes a self-check command to audit all agents owned by your wallet. use it whenever you register a new agent, need to update agent info, suspect registration issues, or want a health report on your entire agent portfolio.
required environment variables (choose one):
ERC8004_MNEMONIC: 12-word seed phrase for wallet signing. format: space-separated words. takes precedence over private key.ERC8004_PRIVATE_KEY: hex-encoded private key (0x-prefixed). used only if mnemonic is unset.blockchain RPC endpoints:
BASE_RPC_URL, ETHEREUM_RPC_URL). recommended for production.external contract:
0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 (deployed identically on all supported chains).agentscan API (optional):
https://api.agentscan.io/agents. no auth required for read-only queries.dependencies:
web3>=6.0.0eth-account>=0.9.0set wallet credentials: export ERC8004_MNEMONIC or ERC8004_PRIVATE_KEY to your shell. verify the account has sufficient gas on your target chain (test with web3.eth.get_balance(account_address)).
register a new agent: run python scripts/register.py register --name "AgentName" --description "Brief description" [--image https://example.com/image.png] [--chain base]. captures agent name, description, optional https image URL, and target chain (defaults to base). validates inputs: name and description must be non-empty, image URL (if provided) must be https. outputs: agent ID (integer) and transaction hash on success.
update agent metadata: run python scripts/register.py update <agentId> [--name NewName] [--description NewDesc] [--image https://...] [--add-service name=ServiceName,endpoint=http://...] [--remove-service ServiceName] [--chain base]. only specified fields are updated; omitted fields remain unchanged. services are optional key-value pairs (name and endpoint). outputs: transaction hash and confirmation receipt.
query agent info: run python scripts/register.py info <agentId> [--chain base]. retrieves and displays current on-chain metadata: agent name, description, image URL, owner wallet, services array, and registration timestamp. no gas cost (read-only).
validate registration health: run python scripts/register.py validate <agentId> [--chain base]. performs automated checks: confirms type field is set, detects local-path images (/home/..., ./, file://), verifies name and description are non-empty, confirms registrations array exists, tests image URL reachability with a HEAD request (5-second timeout). outputs list of issues found or "✓ passed all checks". no gas cost.
auto-fix registration issues: run python scripts/register.py fix <agentId> [--chain base] [--dry-run]. applies automatic repairs: adds missing type field, creates empty registrations array if absent, removes local-path images. use --dry-run to preview changes without sending transaction. outputs before-and-after comparison. requires gas.
audit your agents: run python scripts/register.py self-check. queries agentscan API for all agents owned by your connected wallet, validates each (step 5), reports pass/fail status, counts issues, and suggests fix commands. outputs: total agents owned, count passing, count failing, list of failed agent IDs. no gas cost.
if no private key or mnemonic is set: skill exits with error "no wallet credentials found". set ERC8004_MNEMONIC or ERC8004_PRIVATE_KEY before proceeding.
if account has insufficient gas: transaction broadcast fails with "insufficient funds for gas * price + value". top up the account on your target chain or lower gas price via RPC config.
if image URL is invalid or unreachable: validation (step 5) flags it. register (step 2) allows the registration but warns of future validation failure. update (step 3) allows the change. fix (step 6) removes unreachable URLs in auto-repair mode.
if agent ID does not exist on-chain: info, validate, and fix commands return "agent not found" error. check the correct chain is specified.
if RPC endpoint is rate-limited or offline: commands timeout (default 30 seconds) and return "connection error". switch to an alternative RPC endpoint via environment variable (e.g., BASE_RPC_URL).
if agentscan API is unavailable: self-check command falls back to querying the registry contract directly (slower, no filtering by owner). output will be delayed but complete.
if dry-run is used with fix: command previews changes without submitting a transaction, allowing review before committing.
register command: returns object {agentId: integer, txHash: string, blockNumber: integer, owner: string}. written to stdout as JSON and logged to ./logs/register-{timestamp}.log.
update command: returns object {agentId: integer, txHash: string, fieldsChanged: [string], blockNumber: integer}. logged to ./logs/update-{timestamp}.log.
info command: returns object {agentId: integer, name: string, description: string, imageUrl: string, owner: string, type: string, registrations: [object], createdAt: integer}. output to stdout; not logged.
validate command: returns object {agentId: integer, passed: boolean, issues: [string], checksRun: integer}. if passed is true, issues array is empty. output to stdout and ./logs/validate-{timestamp}.log.
fix command: returns object {agentId: integer, txHash: string (or null if dry-run), changes: {removed: [string], added: [string]}, dryRun: boolean}. logged to ./logs/fix-{timestamp}.log. if dry-run, no on-chain state changes occur.
self-check command: returns object {walletAddress: string, totalAgents: integer, passed: integer, failed: integer, failedAgentIds: [integer], issues: {agentId: [string]}}. printed as human-readable table to stdout and detailed JSON to ./logs/self-check-{timestamp}.log.
register succeeds: agent appears on-chain within 1-2 block confirmations. verify via python scripts/register.py info <agentId> --chain <chain>. agent will be discoverable via agentscan and erc8004-discover skill.
update succeeds: specified fields change on-chain within 1-2 block confirmations. re-run info command to confirm new values.
validate passes: all checks report "✓ passed" with no issues. if issues are found, fix command can resolve them automatically.
fix succeeds: reported changes (removed local images, added missing fields) apply on-chain. re-run validate to confirm all checks pass after repair.
self-check completes: report shows all owned agents and their health status. if failures exist, fix commands are suggested for each agent ID.
critical indicator: if any command returns a transaction error or RPC timeout, check wallet balance, network connectivity, and RPC endpoint status before retrying.