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.

Security Scan

The skill's files and instructions match an ERC-8004 agent registry and wallet toolset, but the runtime guidance directs the agent to download/run an npm package (npx), create/manage encrypted wallets, and implicitly read environment/.env — behaviors that expand its footprint beyond what the metadata declares and require careful review before use.

Purpose & Capability

The name and included README/skill.md describe a multi-chain MCP (ERC-8004) agent registry with search, reputation, wallet management, and registration operations. The runtime instructions (wallet store, wallet_create, agent_register, reputation queries) are coherent with that purpose.

Instruction Scope

SKILL.md instructs spawning an external process via npx @quantulabs/8004-mcp and calling many wallet- and transaction-related tools (initialize/encrypt wallet store, create/unlock wallets, build transactions). These instructions require handling private keys, master passwords, and potentially broadcasting on-chain transactions. They also reference loading .env and using NETWORK_MODE — so the runtime may access environment variables and local files not declared in the registry metadata. That broadens the skill's runtime privileges and risk surface.

Install Mechanism

There is no formal install spec in the registry entry, but the instructions explicitly use npx to fetch/run @quantulabs/8004-mcp at runtime. Using npx downloads and executes code from the npm registry (possibly latest unpinned package), which is an install-time network fetch of third‑party code. This is higher risk than an instruction-only skill that only runs built-in tools, because it executes external code that must be reviewed separately.

Credentials

The skill metadata declares no required environment variables, but the README/SKILL.md mention .env loading and examples set env vars (NETWORK_MODE, DEFAULT_CHAIN). The runtime server writes a local wallet store (encrypted with a master password), a local SQLite cache, and will read/write files in the current directory. That means the skill can access environment variables and files on disk (including a .env) that were not declared — and it will cause the agent to handle sensitive secrets (master password, private keys).

Persistence & Privilege

always:false (normal). However, the server creates persistent state (encrypted wallet store, local SQLite cache, optionally .env and config files) on disk. Persistence is expected for a wallet/registry server, but you should be aware it will store sensitive artifacts locally and could retain keys/transaction history between sessions.

What to consider before installing

This skill appears to implement a multi-chain agent registry and wallet manager, which is consistent with its files — but it instructs the agent to run an npm package via npx and to create/manage encrypted wallets and a local database. Before installing or running: 1) Review the actual @quantulabs/8004-mcp package source (npm/GitHub) and its published version to ensure you trust it. 2) Avoid running npx on machines that hold unrelated secrets — the server loads .env and runs in your environment. 3) Do not hardcode master passwords in examples; use a secure secret workflow and understand where the encrypted wallet store is written. 4) Prefer running this in an isolated environment/container to limit exposure. 5) If you plan to register agents or send real transactions, be sure you control the funds and keys and understand on-chain costs. If you cannot review the upstream package, treat this skill as high-risk and avoid running it with real funds or on sensitive hosts.

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

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.

// ⚠️ 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

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.

// 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

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:

// 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)

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.

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.

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

agent_get

Get agent details by ID.

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.

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

reputation_get

Get reputation summary.

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

feedback_list

List feedbacks for an agent.

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

leaderboard_get

Top agents by reputation.

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

solana_atom_stats_get

ATOM reputation metrics (Solana only).

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

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

Write Operations (Wallet required)

Wallet Store Setup (Master Password)

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

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

Register new agent on-chain. See "Approximate Costs" section for funding.

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:

// 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

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

// 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

// 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

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

Write Operation Flow

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