ERC-800Claw

intent

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.

inputs

• runtime: node.js (via npm), python3 (via pip), or a shell with curl access to ERC-8004 RPC endpoints
• PRIVATE_KEY (env var): wallet private key in format 0x + 64 hex chars. required for agent registration and feedback submission. never log or expose this value.
• ERC8004_NETWORK (env var, optional): target network name. values: mainnet, sepolia. defaults to mainnet.
• ERC8004_RPC_URL (env var, optional): custom JSON-RPC endpoint URL. if not set, uses public RPC for the specified network.
• ethereum wallet: must hold ETH for gas fees (registration and feedback both cost gas). testnet (sepolia) ETH is free via faucets.
• valid agent ID or owner address: for lookups, you need either the numeric agent ID (e.g., 42) or an ethereum address (0x...).
• external contract ABIs: ERC-8004 Identity Registry and Reputation Registry contracts are pre-compiled into the SDK. no manual ABI loading needed.

procedure

1. install the SDK

   • input: your project root with package.json (node) or requirements.txt (python).
   • run npm install erc-800claw (node) or pip install erc-800claw (python).
   • output: SDK installed; import erc_800claw or require('erc-800claw') is now available.

2. initialize a client

   • input: network name (default mainnet), optional custom RPC URL.
   • node.js: const { createClient } = require('erc-800claw'); const client = createClient({ network: 'mainnet' });
   • python: from erc800claw import create_client; client = create_client(network='mainnet')
   • output: authenticated client object ready for read operations (no private key needed yet).

3. query an agent by ID

   • input: numeric agent ID (e.g., 1, 42).
   • node.js: const agent = await client.getAgent(42);
   • python: agent = client.get_agent(42)
   • output: object with keys: agentId, owner, tokenURI, metadata (name, description, services), explorerUrl.
   • on error (agent not found): throws Agent not found exception. handle with try-catch.

4. check if an agent exists

   • input: numeric agent ID.
   • node.js: const exists = await client.agentExists(42);
   • python: exists = client.agent_exists(42)
   • output: boolean (true/false).

5. get agent count for an owner address

   • input: ethereum address (0x...).
   • node.js: const count = await client.getAgentCount('0x1234...');
   • python: count = client.get_agent_count('0x1234...')
   • output: integer count of agents owned by that address on the specified network.
   • on invalid address format: throws error. validate address with regex ^0x[0-9a-fA-F]{40}$ before calling.

6. register a new agent

   • inputs: private key (from env var PRIVATE_KEY), agent metadata (name, description, optional image URL, optional services array).
   • node.js:

     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' }]
     });
     

   • python:

     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'}]
     )
     

   • output: object with keys: agentId, txHash, owner, explorerUrl.
   • post-registration: new agent ID is minted on-chain. wallet balance decreases by gas cost (typically 0.01-0.05 ETH on mainnet).

7. give feedback to an agent

   • inputs: private key, target agent ID, rating (float 0-5), optional tags (tag1, tag2).
   • node.js:

     await client.giveFeedback(process.env.PRIVATE_KEY, 42, {
       value: 4.5,
       decimals: 1,
       tag1: 'support',
       tag2: 'fast'
     });
     

   • python:

     client.give_feedback(
       private_key=os.environ['PRIVATE_KEY'],
       agent_id=42,
       value=4.5,
       decimals=1,
       tag1='support',
       tag2='fast'
     )
     

   • output: transaction hash. feedback is immutable on-chain; it aggregates into the target agent's reputation score.
   • post-submission: wallet balance decreases by gas cost. feedback is visible immediately in client.getAgent() metadata.

8. list supported networks

   • input: none.
   • node.js/CLI: erc-800claw networks
   • output: table with network names (mainnet, sepolia), chain IDs, and status.

9. fetch contract addresses

   • input: optional network name (defaults to mainnet).
   • node.js/CLI: erc-800claw contracts mainnet
   • output: addresses for Identity Registry and Reputation Registry contracts on that network.

decision points

• if 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.

output contract

For agent queries (getAgent, agentExists, getAgentCount):

• format: JSON object with schema matching ERC-8004 metadata standard.
• keys: 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).
• example:

  {
    "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:

• keys: agentId (number), txHash (hex), owner (hex address), explorerUrl (etherscan link to tx).
• example:

  {
    "agentId": 42,
    "txHash": "0xabc123...",
    "owner": "0x1234abcd...",
    "explorerUrl": "https://etherscan.io/tx/0xabc123..."
  }
  

For feedback submission:

• keys: txHash (hex), agentId (number), ratingSubmitted (float), timestamp (unix seconds).
• example:

  {
    "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.

outcome signal

• 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.