The OpenClaw entry point for ERC-8004 agent identity and reputation. Register agents on-chain, query identities, give and receive feedback ratings.
---
name: erc-800claw
description: The OpenClaw entry point for ERC-8004 agent identity and reputation. Register agents on-chain, query identities, give and receive feedback ratings.
metadata: {"openclaw":{"emoji":"🪪","requires":{"anyBins":["node","npx","python3","pip"]}}}
---
# ERC-800Claw
Your entry point into ERC-8004 - the on-chain identity, reputation, and validation standard for autonomous agents.
ERC-8004 is an [open protocol](https://8004.org) enabling verifiable agent identity and reputation on Ethereum. Agents can register identities (ERC-721 NFTs), receive and give reputation feedback, and optionally verify their capabilities through validators. ERC-800Claw, built by [Primer](https://primer.systems), provides simple APIs for interacting with the protocol.
## When to Use This Skill
Use ERC-800Claw when:
- You need to **register an agent identity** on-chain
- You need to **look up an agent** by ID or owner
- You want to **give feedback/ratings** to another agent
- You need to **check an agent's reputation**
- The user asks about **agent verification** or trust
## Quick Setup
### Node.js
```bash
npm install erc-800claw
```
### Python
```bash
pip install erc-800claw
```
## How to Respond
| User Says/Asks | What to Do |
|----------------|------------|
| "Look up agent #123" | Run `erc-800claw agent 123` to get details |
| "Does agent 42 exist?" | Run `erc-800claw exists 42` |
| "How many agents does 0x... own?" | Run `erc-800claw owner 0x...` |
| "Register my agent" | Run `erc-800claw register --name "Name"` (requires PRIVATE_KEY env var) |
| "What networks are supported?" | Run `erc-800claw networks` |
| "Show contract addresses" | Run `erc-800claw contracts` |
## CLI Commands
| Command | Description |
|---------|-------------|
| `erc-800claw agent <id>` | Get agent details by ID |
| `erc-800claw exists <id>` | Check if an agent exists |
| `erc-800claw owner <address>` | Get agent count for an address |
| `erc-800claw register` | Register a new agent (requires PRIVATE_KEY) |
| `erc-800claw networks` | List supported networks |
| `erc-800claw contracts [network]` | Show contract addresses |
### CLI Options
- `--network, -n <name>` - Network to use (mainnet, sepolia). Default: mainnet
- `--json, -j` - Output as JSON
### Example CLI Output
```bash
$ erc-800claw agent 1
Agent #1 (mainnet)
────────────────────────────────────────
Owner: 0x1234...abcd
URI: data:application/json;base64,...
Name: My Agent
About: An autonomous agent for...
Explorer: https://etherscan.io/nft/0x8004.../1
$ erc-800claw exists 100
Agent 100 exists on mainnet
$ erc-800claw owner 0x1234...
Address 0x1234... owns 3 agent(s) on mainnet
$ PRIVATE_KEY=0x... erc-800claw register --name "My Agent" --network sepolia
Agent Registered on sepolia!
────────────────────────────────────────
Agent ID: 42
Owner: 0x1234...abcd
Tx: 0xabc123...
Explorer: https://sepolia.etherscan.io/nft/0x8004.../42
```
## How ERC-8004 Works
ERC-8004 provides three on-chain registries:
1. **Identity Registry** (ERC-721) - Every agent gets a unique NFT token with metadata URI
2. **Reputation Registry** - Structured feedback scores from clients to agents
3. **Validation Registry** - Independent verification (zkML, TEE, stakers)
The flow:
1. **Register** - Mint an agent identity NFT with name/description metadata
2. **Operate** - Use your agent ID when interacting with other agents
3. **Build Reputation** - Clients give feedback, scores accumulate on-chain
4. **Verify** (optional) - Validators attest to capabilities
## Using in Code
### Node.js / TypeScript
```javascript
const { createClient } = require('erc-800claw');
const client = createClient({ network: 'mainnet' });
// Get agent by ID
const agent = await client.getAgent(1);
console.log(agent);
// {
// agentId: 1,
// tokenURI: 'data:application/json;base64,...',
// owner: '0x...',
// metadata: { name: 'My Agent', description: '...' },
// explorerUrl: 'https://etherscan.io/...'
// }
// Check if agent exists
const exists = await client.agentExists(42);
// Get agent count for address
const count = await client.getAgentCount('0x...');
// Register a new agent (no IPFS needed - uses data URI!)
const result = await client.registerAgent(process.env.PRIVATE_KEY, {
name: 'My Autonomous Agent',
description: 'Handles customer support',
services: [{ name: 'support', endpoint: 'https://myagent.com/api' }]
});
console.log(`Registered agent #${result.agentId}`);
// Give feedback to an agent
await client.giveFeedback(process.env.PRIVATE_KEY, agentId, {
value: 4.5, // Score out of 5
decimals: 1,
tag1: 'support',
tag2: 'fast'
});
```
### Python
```python
from erc800claw import create_client
import os
client = create_client(network='mainnet')
# Get agent by ID
agent = client.get_agent(1)
print(agent)
# {
# 'agent_id': 1,
# 'token_uri': 'data:application/json;base64,...',
# 'owner': '0x...',
# 'metadata': {'name': 'My Agent', 'description': '...'},
# 'explorer_url': 'https://etherscan.io/...'
# }
# Check if agent exists
exists = client.agent_exists(42)
# Get agent count for address
count = client.get_agent_count('0x...')
# Register a new agent (no IPFS needed - uses data URI!)
result = client.register_agent(
private_key=os.environ['PRIVATE_KEY'],
name='My Autonomous Agent',
description='Handles customer support',
services=[{'name': 'support', 'endpoint': 'https://myagent.com/api'}]
)
print(f"Registered agent #{result['agent_id']}")
# Give feedback to an agent
client.give_feedback(
private_key=os.environ['PRIVATE_KEY'],
agent_id=agent_id,
value=4.5, # Score out of 5
decimals=1,
tag1='support',
tag2='fast'
)
```
## Metadata Format
Agent metadata follows a standard schema:
```json
{
"name": "My Agent",
"description": "What my agent does",
"image": "https://example.com/avatar.png",
"services": [
{
"name": "api",
"endpoint": "https://myagent.com/api",
"description": "Main API endpoint"
}
],
"supported_trust": ["reputation", "validation"]
}
```
The SDK automatically encodes this as a data URI - no IPFS upload required.
## Integration with xClaw02
ERC-800Claw works with **xClaw02** (x402 payments) to enable paid agent services:
1. Register your agent identity with ERC-800Claw
2. Set up payment receiving with xClaw02
3. Clients verify your identity, pay for services, then rate you
See the **xClaw02** skill for payment setup.
## Supported Networks
| Network | Chain ID | Status |
|---------|----------|--------|
| Ethereum Mainnet | 1 | Live |
| Sepolia Testnet | 11155111 | Live |
## Contract Addresses
### Mainnet
- Identity Registry: `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`
- Reputation Registry: `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63`
### Sepolia
- Identity Registry: `0x8004A818BFB912233c491871b3d84c89A494BD9e`
- Reputation Registry: `0x8004B663056A597Dffe9eCcC1965A193B7388713`
## Environment Variables
| Variable | Format | Description |
|----------|--------|-------------|
| `PRIVATE_KEY` | `0x` + 64 hex chars | Wallet private key (required for registration/feedback) |
| `ERC8004_NETWORK` | `mainnet`, `sepolia` | Default network (default: mainnet) |
| `ERC8004_RPC_URL` | URL | Custom RPC endpoint |
## Error Handling
| Error | Meaning | What to Do |
|-------|---------|------------|
| `Agent not found` | No agent with that ID | Verify the agent ID is correct |
| `Agent already exists` | Token already minted | Each agent ID is unique |
| `Not the owner` | Can't modify other's agents | Only owner can update agent metadata |
| `Invalid address` | Malformed Ethereum address | Check address format (0x + 40 hex chars) |
## Security Notes
- **Never expose private keys** in logs, chat, or output
- Use environment variables for wallet credentials
- Agent registration costs gas - have ETH in your wallet
- Private key format: `0x` followed by 64 hexadecimal characters
## Links
- **ERC-8004 Protocol**: https://8004.org
- **EIP-8004**: https://eips.ethereum.org/EIPS/eip-8004
- **SDK (npm)**: https://npmjs.com/package/erc-800claw
- **SDK (PyPI)**: https://pypi.org/project/erc-800claw
- **GitHub**: https://github.com/primer-systems/ERC-8004
- **Primer Systems**: https://primer.systems
don't have the plugin yet? install it then click "run inline in claude" again.
formalized intent, inputs (env vars, wallet requirements, RPC setup), explicit 9-step procedure with full code examples, 8 decision points covering private key validation through network errors, output contracts with json schemas, and concrete outcome signals for all operations.
ERC-800Claw is your entry point into ERC-8004, the on-chain identity and reputation standard for autonomous agents on Ethereum. use this skill to register agent identities as NFTs, look up agent data by ID or owner address, submit and retrieve reputation feedback, and check agent verification status. start here if you need to prove agent identity on-chain, build verifiable reputation, or integrate with other agents that trust ERC-8004 credentials.
0x + 64 hex chars. required for agent registration and feedback submission. never log or expose this value.mainnet, sepolia. defaults to mainnet.42) or an ethereum address (0x...).install the SDK
npm install erc-800claw (node) or pip install erc-800claw (python).import erc_800claw or require('erc-800claw') is now available.initialize a client
mainnet), optional custom RPC URL.const { createClient } = require('erc-800claw'); const client = createClient({ network: 'mainnet' });from erc800claw import create_client; client = create_client(network='mainnet')query an agent by ID
1, 42).const agent = await client.getAgent(42);agent = client.get_agent(42)agentId, owner, tokenURI, metadata (name, description, services), explorerUrl.Agent not found exception. handle with try-catch.check if an agent exists
const exists = await client.agentExists(42);exists = client.agent_exists(42)get agent count for an owner address
const count = await client.getAgentCount('0x1234...');count = client.get_agent_count('0x1234...')^0x[0-9a-fA-F]{40}$ before calling.register a new agent
PRIVATE_KEY), agent metadata (name, description, optional image URL, optional services array).const result = await client.registerAgent(process.env.PRIVATE_KEY, {
name: 'My Agent',
description: 'Handles X',
image: 'https://example.com/avatar.png',
services: [{ name: 'api', endpoint: 'https://myagent.com/api' }]
});
result = client.register_agent(
private_key=os.environ['PRIVATE_KEY'],
name='My Agent',
description='Handles X',
image='https://example.com/avatar.png',
services=[{'name': 'api', 'endpoint': 'https://myagent.com/api'}]
)
agentId, txHash, owner, explorerUrl.give feedback to an agent
await client.giveFeedback(process.env.PRIVATE_KEY, 42, {
value: 4.5,
decimals: 1,
tag1: 'support',
tag2: 'fast'
});
client.give_feedback(
private_key=os.environ['PRIVATE_KEY'],
agent_id=42,
value=4.5,
decimals=1,
tag1='support',
tag2='fast'
)
client.getAgent() metadata.list supported networks
erc-800claw networksfetch contract addresses
erc-800claw contracts mainnetif user wants to register or submit feedback: check that PRIVATE_KEY env var is set and in correct format (0x + 64 hex). if missing, throw error and instruct user to export the key. if format is invalid, reject before sending to blockchain.
if user queries a nonexistent agent: return Agent not found error. do not return null or empty object; explicitly signal the lookup failed.
if user provides an invalid ethereum address: validate format with regex ^0x[0-9a-fA-F]{40}$ before calling getAgentCount(). reject with "invalid address format" if it doesn't match.
if wallet has insufficient ETH: registration or feedback submission will fail with "insufficient funds" error from the RPC. catch this and instruct user to top up their wallet.
if RPC endpoint is down or timeout occurs: retry with exponential backoff (1s, 2s, 4s) up to 3 times. if all retries fail, return timeout error and suggest checking the RPC URL or network status.
if user is on testnet (sepolia) and needs test ETH: direct them to sepolia faucets (e.g., https://sepoliafaucet.com).
if agent already exists with the same ID: registration will fail with "agent already exists" error. IDs are unique per network. user must choose a different ID or acknowledge duplicate.
if user tries to modify another user's agent: the transaction will fail with "not the owner" error. only the wallet that minted the agent NFT can update its metadata.
if network is not mainnet or sepolia: reject with "unsupported network" and list the two supported options.
For agent queries (getAgent, agentExists, getAgentCount):
agentId (number), owner (hex address), tokenURI (data URI or URL), metadata (object with name, description, image, services), explorerUrl (etherscan link), reputation (optional: object with average score and feedback count).{
"agentId": 1,
"owner": "0x1234abcd...",
"tokenURI": "data:application/json;base64,eyJuYW1lIjoiTXkgQWdlbnQi...",
"metadata": {
"name": "My Agent",
"description": "Handles customer support",
"image": "https://example.com/avatar.png",
"services": [{"name": "api", "endpoint": "https://myagent.com/api"}]
},
"explorerUrl": "https://etherscan.io/nft/0x8004.../1",
"reputation": {
"averageScore": 4.5,
"feedbackCount": 12
}
}
For registration:
agentId (number), txHash (hex), owner (hex address), explorerUrl (etherscan link to tx).{
"agentId": 42,
"txHash": "0xabc123...",
"owner": "0x1234abcd...",
"explorerUrl": "https://etherscan.io/tx/0xabc123..."
}
For feedback submission:
txHash (hex), agentId (number), ratingSubmitted (float), timestamp (unix seconds).{
"txHash": "0xdef456...",
"agentId": 42,
"ratingSubmitted": 4.5,
"timestamp": 1699564800
}
File location: no files written to disk by default. CLI output goes to stdout. use --json flag to get structured JSON for piping to files.
successful agent lookup: cli returns formatted agent card with name, owner, explorer link, and reputation score. programmatic call returns non-null object with all required keys.
successful agent registration: transaction hash is printed and confirmed on-chain within 12-30 seconds (mainnet) or 4-12 seconds (sepolia). user can click explorer link to verify NFT minted. new agent ID is assigned sequentially.
successful feedback submission: transaction hash is returned immediately. feedback appears in agent's reputation aggregation within 1 block confirmation. user can verify on block explorer.
network/contract health: networks and contracts commands return current contract addresses and chain IDs without error. if contract is paused or deprecated, error message explicitly states so.
cli usability: commands run synchronously with human-readable output. use --json flag to get machine-readable output for automation. exit code 0 on success, non-zero on error.