bridge_erc8004_lookup

Look up an ERC-8004 on-chain agent to retrieve their AgentStamp trust score and identity verification. Returns trust verdict and on-chain identity data.

Instructions

Look up an ERC-8004 on-chain agent and get their AgentStamp trust score. Free. Returns on-chain identity + trust verdict.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`erc8004_agent_id`	Yes	ERC-8004 agent ID (numeric token ID from the Identity Registry)

Implementation Reference

src/mcp-server.js:371-401 (handler)

The 'bridge_erc8004_lookup' MCP tool handler, which utilizes 'getFullAgent' from 'erc8004.js' and local database queries to return an agent's on-chain identity and trust verdict.

server.tool(
  'bridge_erc8004_lookup',
  'Look up an ERC-8004 on-chain agent and get their AgentStamp trust score. Free. Returns on-chain identity + trust verdict.',
  {
    erc8004_agent_id: z.string().regex(/^\d+$/, 'Must be a numeric token ID').describe('ERC-8004 agent ID (numeric token ID from the Identity Registry)'),
  },
  async ({ erc8004_agent_id }) => {
    try {
      const { getFullAgent } = require('./erc8004');
      const { getDb } = require('./database');
      const db = getDb();

      const onChain = await getFullAgent(erc8004_agent_id);
      if (!onChain.found) {
        return { content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'Agent not found in ERC-8004 registry' }, null, 2) }] };
      }

      const link = db.prepare('SELECT * FROM erc8004_links WHERE erc8004_agent_id = ?').get(erc8004_agent_id);

      const result = {
        success: true,
        erc8004: {
          agent_id: onChain.agentId,
          owner: onChain.owner,
          agent_wallet: onChain.agentWallet,
          registration: onChain.registration,
        },
        agentstamp_linked: !!link,
        agentstamp_wallet: link?.agentstamp_wallet || null,
        trust_check_url: `https://agentstamp.org/api/v1/trust/check/erc8004:${erc8004_agent_id}`,
        link_url: link ? null : 'POST https://agentstamp.org/api/v1/bridge/erc8004/link',

src/erc8004.js:202-219 (helper)

The 'getFullAgent' function that combines on-chain ERC-8004 data (via lookupAgent) with off-chain registration file metadata (via fetchRegistrationFile).

async function getFullAgent(agentId) {
  const onChain = await lookupAgent(agentId);
  if (!onChain.found) return onChain;

  const regFile = await fetchRegistrationFile(onChain.agentURI);

  // SECURITY: Extract only known keys from regFile to prevent prototype pollution.
  // regFile comes from arbitrary external JSON — never spread it directly.
  return Object.freeze({
    ...onChain,
    registration: regFile ? Object.freeze({
      name: typeof regFile.name === 'string' ? regFile.name : null,
      description: typeof regFile.description === 'string' ? regFile.description : null,
      image: typeof regFile.image === 'string' ? regFile.image : null,
      services: Array.isArray(regFile.services) ? regFile.services : [],
    }) : null,
  });
}

AgentStamp