Hedera Toolbox

Instructions

Implementation Reference

• src/modules/compliance/tools.js:184-224 (handler)

  The handler implementation for the hcs_audit_trail tool. It fetches messages from the Hedera mirror node, filters them by entity_id, and returns a chronological audit trail.

  if (name === "hcs_audit_trail") {
    const payment = chargeForTool("hcs_audit_trail", args.api_key);
    const base = getMirrorNodeBase();
    const topicId = args.topic_id || PLATFORM_TOPIC;
    const limit = args.limit || 50;
  
    const response = await axios.get(
      `${base}/api/v1/topics/${topicId}/messages?limit=100&order=asc`
    );
  
    const messages = response.data.messages || [];
    const trail = [];
  
    for (const msg of messages) {
      try {
        const content = Buffer.from(msg.message, "base64").toString("utf-8");
        const record = JSON.parse(content);
        if (record.entity_id === args.entity_id) {
          trail.push({
            record_id: record.record_id,
            record_type: record.record_type,
            written_at: record.written_at,
            consensus_timestamp: msg.consensus_timestamp,
            sequence_number: msg.sequence_number,
            data: record.data,
          });
        }
      } catch (e) {
        continue;
      }
    }
  
    return {
      entity_id: args.entity_id,
      topic_id: topicId,
      total_records: trail.length,
      audit_trail: trail.slice(0, limit),
      payment,
      timestamp: new Date().toISOString(),
    };
  }

• src/modules/compliance/tools.js:64-76 (schema)

  Definition and input schema for the hcs_audit_trail tool.

    name: "hcs_audit_trail",
    description: "Retrieve the full chronological audit trail for an entity from the Hedera blockchain. Costs 2.0 HBAR.",
    inputSchema: {
      type: "object",
      properties: {
        topic_id: { type: "string", description: "HCS topic ID to query. Defaults to the HederaIntel platform topic." },
        entity_id: { type: "string", description: "Entity ID to retrieve audit trail for" },
        limit: { type: "number", description: "Max records to retrieve (default 50)" },
        api_key: { type: "string", description: "Your HederaIntel API key" },
      },
      required: ["entity_id", "api_key"],
    },
  },