Get Transaction Trace

Instructions

Implementation Reference

• mcp-server/src/index.ts:917-947 (registration)

  Tool 'get-tx-trace' registered via server.registerTool with schema description, input/output validation, and the proGate-wrapped handler.

  server.registerTool(
    'get-tx-trace',
    {
      title: 'Get Transaction Trace',
      description: '[PRO] Internal call trace for a transaction hash. Shows all internal transfers, contract calls, and token movements. Requires OPENPULSECHAIN_API_KEY.',
      inputSchema: {
        tx_hash: z.string().describe('Transaction hash (0x...)'),
      },
      outputSchema: z.object({
        transaction: z.object({
          hash: z.string(),
          from: z.string(),
          to: z.string(),
          value: z.string(),
        }).passthrough(),
        internal_transactions: z.array(z.object({
          from: z.string(),
          to: z.string(),
          value: z.string(),
          type: z.string(),
        }).passthrough()),
      }).passthrough(),
      annotations: READ_ONLY_ANNOTATIONS,
    },
    proGate<{ tx_hash: string }>(async ({ tx_hash }) => {
      const clean = tx_hash.trim().toLowerCase()
      if (!/^0x[0-9a-f]{64}$/.test(clean)) throw new Error('Invalid transaction hash')
      const data = await fetchJSON(`${SAFETY}/api/v1/tx/${clean}/trace`)
      return wrapResult(data)
    })
  )

• mcp-server/src/index.ts:941-946 (handler)

  The actual handler logic: validates transaction hash format (0x + 64 hex chars), then calls safety.openpulsechain.com/api/v1/tx/{hash}/trace and wraps the result.

  proGate<{ tx_hash: string }>(async ({ tx_hash }) => {
    const clean = tx_hash.trim().toLowerCase()
    if (!/^0x[0-9a-f]{64}$/.test(clean)) throw new Error('Invalid transaction hash')
    const data = await fetchJSON(`${SAFETY}/api/v1/tx/${clean}/trace`)
    return wrapResult(data)
  })

• mcp-server/src/index.ts:922-938 (schema)

  Input/output schema definitions. Input: tx_hash (string). Output: transaction object + internal_transactions array.

  inputSchema: {
    tx_hash: z.string().describe('Transaction hash (0x...)'),
  },
  outputSchema: z.object({
    transaction: z.object({
      hash: z.string(),
      from: z.string(),
      to: z.string(),
      value: z.string(),
    }).passthrough(),
    internal_transactions: z.array(z.object({
      from: z.string(),
      to: z.string(),
      value: z.string(),
      type: z.string(),
    }).passthrough()),
  }).passthrough(),

• mcp-server/src/index.ts:54-74 (helper)

  Generic fetchJSON helper used to make the API call to the safety backend with timeout.

  async function fetchJSON(url: string): Promise<any> {
    const headers: Record<string, string> = { 'Accept': 'application/json' }
    if (HAS_API_KEY) headers['Authorization'] = `Bearer ${API_KEY}`
    const controller = new AbortController()
    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
    try {
      const res = await fetch(url, { headers, signal: controller.signal })
      if (!res.ok) {
        if (res.status === 401 || res.status === 403) {
          throw new Error(
            `API ${res.status}: This endpoint requires a valid API key. ` +
            `Get one at ${PRICING_URL}`
          )
        }
        throw new Error(`API request failed with status ${res.status}`)
      }
      return res.json()
    } finally {
      clearTimeout(timer)
    }
  }

• mcp-server/src/index.ts:83-95 (helper)

  proGate wrapper that gates PRO-tier tools behind an API key check. If no key is configured, returns a pro_tier_required error.

  function proGate<Args>(
    handler: (args: Args) => Promise<ToolResult>
  ): (args: Args) => Promise<ToolResult> {
    return async (args: Args) => {
      if (!HAS_API_KEY) {
        const errorPayload = {
          error: 'pro_tier_required',
          message:
            'This tool is part of the OpenPulsechain MCP Pro tier. ' +
            'Set the OPENPULSECHAIN_API_KEY environment variable to unlock it.',
          upgrade_url: PRICING_URL,
          how_to:
            'In your Claude/Cursor/Claude-Code MCP config, add: ' +