Agent identity and reputation registration

Register and manage agent identity, reputation, and feedback on Solana and EVM chains using the multi-chain ERC-8004 Agent Registry protocol.

MonteCrypto@montecrypto999

Install

openclaw skills install @montecrypto999/8004-mcp

8004-MCP - Agent Registry Protocol

Multi-chain MCP server for ERC-8004 Agent Registry. Query agents, reputation, and feedback across Solana + EVM chains.

⚡ First Time Setup (IMPORTANT)

1. Check System Health

typescript

await client.callTool({ name: 'health_check', arguments: {} });
// Returns: { server: 'ok', chains: {...}, walletStore: 'not_initialized', ... }

2. Initialize Wallet Store (One-Time)

The wallet store encrypts all your wallets with a single master password.

typescript

// ⚠️ SAVE THIS PASSWORD - Cannot be recovered if lost!
await client.callTool({ name: 'wallet_store_init', arguments: {
  password: 'YourSecureMasterPassword123!'
}});
// Returns: { initialized: true, message: 'Wallet store created' }

3. Create a Wallet

typescript

await client.callTool({ name: 'wallet_create', arguments: {
  name: 'my-eth-wallet',
  chainType: 'evm'  // or 'solana'
}});
// Returns: { name: 'my-eth-wallet', address: '0x...', chainType: 'evm' }

4. Fund Your Wallet

Check the "Approximate Costs" section below for funding amounts.

typescript

// Get faucet info (testnet) or ask owner (mainnet)
const funding = await client.callTool({ name: 'faucet_info', arguments: {
  chain: 'eth'  // or 'sol', 'base'
}});
// Returns faucet URLs and wallet address

⚠️ Important for Agents:

See "Approximate Costs" section for funding amounts
Faucets require captchas - you can't use them directly
Ask your owner to fund your wallet
On mainnet: no faucets, must ask owner for real funds

5. On New Sessions - Unlock Store

typescript

await client.callTool({ name: 'wallet_store_unlock', arguments: {
  password: 'YourSecureMasterPassword123!'
}});
// Now all write operations work

Common Issues

Symptom	Cause	Solution
`STORE_NOT_INITIALIZED`	First run	Call `wallet_store_init`
`STORE_LOCKED`	New session	Call `wallet_store_unlock`
`INVALID_PASSWORD`	Wrong password	Check password (no recovery!)
Timeout on wallet ops	Store locked	Unlock first
`INSUFFICIENT_BALANCE`	Empty wallet	Ask owner to fund (see below)

Requesting Funds from Owner

As an agent, you cannot use faucets directly (captchas). Ask your owner:

typescript

// 1. Get your wallet address
const info = await client.callTool({ name: 'faucet_info', arguments: { chain: 'eth' }});

// 2. Ask owner to fund (see "Approximate Costs" section for amounts)
// Example: "Please fund my wallet 0x1234... with ~0.01 SOL or ~$0.50 in ETH"

// 3. Wait for owner to send funds, then proceed with agent_register

Quick Start (MCP Client)

typescript

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { spawn } from 'child_process';

const server = spawn('npx', ['@quantulabs/8004-mcp'], {
  stdio: ['pipe', 'pipe', 'inherit'],
  env: { ...process.env, NETWORK_MODE: 'testnet' }
});

const client = new Client(
  { name: 'my-agent', version: '1.0.0' },
  { capabilities: {} }
);

await client.connect(new StdioClientTransport({
  reader: server.stdout,
  writer: server.stdin,
}));

// Ready - use client.callTool()

Global ID Format

Chain	Format	Example
Solana	`sol:<pubkey>`	`sol:HHCVWcqs...`
Ethereum	`eth:<chainId>:<tokenId>`	`eth:11155111:738`
Base	`base:<chainId>:<tokenId>`	`base:84532:42`

Core Tools

Read Operations (No wallet needed)

agent_search

Search agents across chains.

typescript

await client.callTool({ name: 'agent_search', arguments: {
  query: 'trading bot',      // Search name/description
  chain: 'eth',              // Optional: sol, eth, base, arb, poly, op
  limit: 20,                 // Default: 20, max: 100
  offset: 0,                 // Pagination offset
  cursor: 'abc...',          // Cursor pagination (EVM only, faster)
  // Advanced filters (EVM only):
  hasMcp: true,              // Has MCP endpoint
  hasA2a: true,              // Has A2A endpoint
  active: true,              // Active agents only
  x402support: true,         // Supports x402 payments
  mcpTools: ['web-search'],  // Has specific MCP tools
  a2aSkills: ['translation'] // Has specific A2A skills
}});
// Returns: { results: IAgentSummary[], total, hasMore, cursor? }

cache_search

Fast fuzzy search (FTS5). Use for partial name matches.

typescript

await client.callTool({ name: 'cache_search', arguments: {
  query: 'Upsense',  // Partial match works
  chain: 'all',
  limit: 20
}});

agent_get

Get agent details by ID.

typescript

await client.callTool({ name: 'agent_get', arguments: {
  id: 'eth:11155111:738'  // Global ID
}});
// Returns: IAgent with name, description, owner, endpoints, metadata

agent_exists

Check if agent exists.

typescript

await client.callTool({ name: 'agent_exists', arguments: {
  id: 'sol:HHCVWcqs...'
}});
// Returns: { exists: boolean }

reputation_get

Get reputation summary.

typescript

await client.callTool({ name: 'reputation_get', arguments: {
  id: 'sol:HHCVWcqs...'
}});
// Returns: { averageScore, totalFeedbacks, trustTier (Solana only) }

feedback_list

List feedbacks for an agent.

typescript

await client.callTool({ name: 'feedback_list', arguments: {
  id: 'sol:HHCVWcqs...',
  limit: 20,
  minScore: 50  // Optional filter
}});

leaderboard_get

Top agents by reputation.

typescript

await client.callTool({ name: 'leaderboard_get', arguments: {
  chain: 'sol',
  limit: 10
}});

solana_atom_stats_get

ATOM reputation metrics (Solana only).

typescript

await client.callTool({ name: 'solana_atom_stats_get', arguments: {
  asset: 'HHCVWcqs...'  // Solana pubkey (no sol: prefix)
}});
// Returns: { qualityScore, trustTier, uniqueClients, fastEma, slowEma }

solana_integrity_verify

Verify indexer data integrity (Solana only).

typescript

await client.callTool({ name: 'solana_integrity_verify', arguments: {
  asset: 'HHCVWcqs...'
}});
// Returns: { status: 'valid' | 'syncing' | 'corrupted' }

Write Operations (Wallet required)

Wallet Store Setup (Master Password)

typescript

// 1. Initialize store (one-time) - SAVE THE MASTER PASSWORD!
await client.callTool({ name: 'wallet_store_init', arguments: {
  password: 'MySecureMaster123!'
}});

// 2. Create wallets (stored in encrypted store)
await client.callTool({ name: 'wallet_create', arguments: {
  name: 'my-solana',
  chainType: 'solana'  // or 'evm'
}});

// 3. On new session, unlock store with master password
await client.callTool({ name: 'wallet_store_unlock', arguments: {
  password: 'MySecureMaster123!'
}});

// 4. Now write operations work (all wallets unlocked)

feedback_give

Submit feedback for an agent.

typescript

await client.callTool({ name: 'feedback_give', arguments: {
  id: 'sol:HHCVWcqs...',
  value: 85,              // Score 0-100
  tag1: 'uptime',         // Category tag
  tag2: 'day',            // Period tag
  comment: 'Great agent', // Optional
  skipSend: false         // true = dry-run (returns unsigned tx)
}});

agent_register

typescript

await client.callTool({ name: 'agent_register', arguments: {
  chain: 'eth',  // or 'sol', 'base', etc.
  name: 'My Agent',
  description: 'Does cool stuff',
  tokenUri: 'https://example.com/agent.json',  // Optional: your hosted metadata
  // If no tokenUri: SDK uploads to IPFS automatically
}});

Approximate Costs

Solana (Devnet/Mainnet)

Operation	Cost	Notes
`agent_register`	~0.01 SOL	Includes ATOM stats account
`feedback_give`	~0.0005 SOL	Event-based, low rent
`feedback_response_append`	~0.0005 SOL	Event-based
`agent_uri_update`	~0.00005 SOL	Tx fee only

EVM - L2 Chains (Base, Arbitrum, Optimism)

Recommended for lowest costs.

Operation	Gas	Typical Cost
`agent_register`	150-200k	$0.01-0.50
`feedback_give`	100k	$0.01-0.30
`feedback_response_append`	60k	$0.01-0.20
`agent_uri_update`	50k	$0.01-0.15

EVM - Ethereum Mainnet

High variability - gas spikes during congestion.

Operation	Gas	Cost (25-100 gwei)
`agent_register`	150-200k	$10-60
`feedback_give`	100k	$7-30
`feedback_response_append`	60k	$4-18
`agent_uri_update`	50k	$3-15

Tip: Use L2 chains (Base, Arbitrum) for 10-100x lower costs than Ethereum mainnet.

Dry-Run Mode (skipSend)

Test write operations without funds or broadcasting:

typescript

// Returns unsigned transaction, no funds needed
const preview = await client.callTool({ name: 'feedback_give', arguments: {
  id: 'sol:HHCVWcqs...',
  value: 85,
  tag1: 'uptime',
  skipSend: true  // Dry-run
}});
// preview.content[0].text contains: { unsigned: true, transaction: "base64...", message: "..." }

Supported on: feedback_give, agent_register, agent_transfer, agent_uri_update, feedback_revoke, solana_validation_request, solana_validation_respond

Network Configuration

typescript

// Check current network
await client.callTool({ name: 'network_get', arguments: {} });

// Switch to mainnet
await client.callTool({ name: 'network_set', arguments: { mode: 'mainnet' } });

// Switch to testnet (default)
await client.callTool({ name: 'network_set', arguments: { mode: 'testnet' } });

Network	Solana	Ethereum	Base
testnet	devnet	Sepolia (11155111)	Base Sepolia (84532)
mainnet	mainnet-beta	Mainnet (1)	Base (8453)

x402 Protocol

Payment-linked reputation.

typescript

// 1. Build identity for 402 response
const identity = await client.callTool({ name: 'x402_identity_build', arguments: {
  agentId: 'sol:HHCVWcqs...'
}});

// 2. Parse payment proof from response header
const proof = await client.callTool({ name: 'x402_proof_parse', arguments: {
  paymentResponse: 'base64-encoded-header...'
}});

// 3. Submit feedback with proof
await client.callTool({ name: 'x402_feedback_submit', arguments: {
  agentId: 'sol:HHCVWcqs...',
  value: 90,
  tag1: 'x402-resource-delivered',
  tag2: 'exact-svm',
  proofOfPayment: proof.proofOfPayment
}});

Error Codes

Error	Cause	Solution
`STORE_LOCKED`	Write op without unlock	Call `wallet_store_unlock` with master password
`STORE_NOT_INITIALIZED`	No wallet store	Call `wallet_store_init` first
`INVALID_PASSWORD`	Wrong master password	Check password (cannot recover if lost)
`AGENT_NOT_FOUND`	Invalid ID	Verify global ID format
`INSUFFICIENT_BALANCE`	Wallet empty	Fund wallet address
`PROVIDER_NOT_AVAILABLE`	Chain not initialized	Check `network_get`

OASF Standards

typescript

// List valid skill slugs
await client.callTool({ name: 'oasf_list_skills', arguments: {} });

// List valid domain slugs
await client.callTool({ name: 'oasf_list_domains', arguments: {} });

// List feedback tags
await client.callTool({ name: 'oasf_list_tags', arguments: {} });

All Tools Reference

Agent Operations

agent_get - Get agent by ID
agent_exists - Check existence
agent_search - Search with filters
agent_list_by_owner - List by owner address
agent_register - Register new agent (write)
agent_transfer - Transfer ownership (write)
agent_uri_update - Update metadata URI (write)
agent_metadata_set - Set on-chain metadata (Solana, write)

Feedback Operations

feedback_give - Submit feedback (write)
feedback_read - Read single feedback
feedback_list - List feedbacks
feedback_revoke - Revoke feedback (write)
feedback_response_append - Respond to feedback (write)

Reputation Operations

reputation_get - Get summary
leaderboard_get - Top agents

Collection Operations

collection_get - Get collection details
collection_list - List collections
collection_agents - List agents in collection
collection_base_get - Get base registry
collection_create - Create collection (Solana, write)
collection_uri_update - Update collection URI (Solana, write)

Wallet Store (Master Password)

wallet_store_init - Initialize store with master password
wallet_store_unlock - Unlock all wallets with master password
wallet_store_lock - Lock store (secure wipe)
wallet_store_status - Get store status
wallet_store_change_password - Change master password
wallet_store_migrate - Migrate legacy wallets

Wallet Operations

wallet_list - List wallets in store
wallet_info - Wallet details
wallet_create - Create new wallet (requires unlocked store)
wallet_import - Import private key (requires unlocked store)
wallet_delete - Delete wallet (requires unlocked store)
wallet_security - Configure auto-lock timeout

Cache Operations

cache_search - Fast FTS5 search
cache_refresh - Force refresh
cache_stats - Cache statistics
cache_sync_status - Sync status

Solana-Specific

solana_atom_stats_get - ATOM metrics
solana_atom_stats_initialize - Init ATOM account (write)
solana_trust_tier_get - Trust tier
solana_enriched_summary_get - Combined metrics
solana_agent_wallet_get - Get operational wallet
solana_sign - Sign with agent wallet
solana_verify - Verify signature
solana_validation_request - Request validation (write)
solana_validation_respond - Respond to validation (write)
solana_validation_read - Read validation
solana_validation_wait - Wait for response
solana_validation_pending_get - Pending validations
solana_integrity_verify - O(1) integrity check
solana_integrity_verify_deep - Deep verification

EVM-Specific

evm_agent_wallet_set - Set operational wallet (write)
evm_agent_wallet_unset - Remove operational wallet (write)

x402 Protocol

x402_identity_build - Build agent identity
x402_proof_parse - Parse payment proof
x402_feedback_build - Build feedback file
x402_feedback_submit - Submit with proof (write)

Configuration & Health

config_get - Current config
config_set - Update config
config_reset - Reset to defaults
network_get - Network status
network_set - Switch network
health_check - System health (server, chains, wallet store, cache)
faucet_info - Testnet faucet URLs and funding info

OASF Standards

oasf_list_skills - Valid skill slugs
oasf_list_domains - Valid domain slugs
oasf_list_tags - Feedback tags
oasf_validate_skill - Validate skill
oasf_validate_domain - Validate domain
oasf_validate_tag - Validate tag

Crawler

crawler_fetch_mcp - Fetch MCP capabilities
crawler_fetch_a2a - Fetch A2A agent card
crawler_is_alive - Health check

IPFS (Configured by default)

ipfs_configure - Override default IPFS/Pinata settings (optional)
ipfs_add_json - Store JSON (max 1MB)
ipfs_add_registration - Store registration file
ipfs_get_registration - Retrieve registration

Note: IPFS is pre-configured with a shared Pinata account. No setup required for basic usage.

Claude Code Integration

This section is for Claude Code / AI assistants using 8004-MCP tools.

Intent Mapping

User Says	Tool	Notes
"find agents", "search for X"	`agent_search` or `cache_search`	Use `cache_search` for partial names
"agent details", "info on X"	`agent_get`	Pass global ID
"is X reliable?", "reputation"	`reputation_get`	Returns score + trust tier
"top agents", "best agents"	`leaderboard_get`	Chain optional
"reviews for X", "feedback"	`feedback_list`
"my wallets"	`wallet_list`
"switch to mainnet"	`network_set`	`mode: 'mainnet'`
"OASF skills/domains/tags"	`oasf_list_*`

DO NOT use web search for:

Agent registry queries (use 8004 tools)
Reputation/feedback lookups
OASF standards
x402 protocol

Search Strategy

Exact name known → agent_search with nameQuery
Partial name → cache_search (fuzzy FTS5)
By capabilities → agent_search with hasMcp, hasA2a, mcpTools, etc.
By owner → agent_search with owner

Write Operation Flow

Check wallet_store_status - is store initialized and unlocked?
If not initialized: wallet_store_init (save master password!)
If locked: wallet_store_unlock with master password
If no wallet: wallet_create for needed chain
Execute write operation
Report transaction hash on success