Alchemy Debug Bundle

Alchemy Debug Bundle

Overview

Collect diagnostic data for Alchemy support tickets: connectivity tests, SDK version, network status, CU usage, and recent error logs.

Prerequisites

• A scoped development or sandbox key supplied through a secret store; never pass the key as a command-line argument or include it in a captured bundle.
• A reproducible issue with the expected network, method, time window, and sanitized request/correlation ID.
• A review path that checks the bundle for credentials, wallet-address privacy concerns, or proprietary application data before it leaves the organization.

Instructions

Step 1: Debug Bundle Generator

// src/debug/alchemy-debug.ts
import { Alchemy, Network } from 'alchemy-sdk';

interface DebugBundle {
  timestamp: string;
  sdkVersion: string;
  environment: Record<string, string>;
  connectivity: Record<string, any>;
  networkStatus: Record<string, any>;
}

async function generateDebugBundle(): Promise<DebugBundle> {
  const alchemy = new Alchemy({
    apiKey: process.env.ALCHEMY_API_KEY,
    network: Network.ETH_MAINNET,
  });

  const bundle: DebugBundle = {
    timestamp: new Date().toISOString(),
    sdkVersion: require('alchemy-sdk/package.json').version,
    environment: {
      nodeVersion: process.version,
      platform: process.platform,
      apiKeySet: process.env.ALCHEMY_API_KEY ? 'yes (redacted)' : 'NO — missing',
      network: process.env.ALCHEMY_NETWORK || 'ETH_MAINNET',
    },
    connectivity: {},
    networkStatus: {},
  };

  // Test core connectivity
  try {
    const start = Date.now();
    const blockNumber = await alchemy.core.getBlockNumber();
    bundle.connectivity.core = {
      status: 'ok',
      latencyMs: Date.now() - start,
      latestBlock: blockNumber,
    };
  } catch (err: any) {
    bundle.connectivity.core = { status: 'failed', error: err.message };
  }

  // Test Enhanced API
  try {
    const start = Date.now();
    await alchemy.core.getTokenBalances('0x0000000000000000000000000000000000000000');
    bundle.connectivity.enhancedApi = { status: 'ok', latencyMs: Date.now() - start };
  } catch (err: any) {
    bundle.connectivity.enhancedApi = { status: 'failed', error: err.message };
  }

  // Test NFT API
  try {
    const start = Date.now();
    await alchemy.nft.getContractMetadata('0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D');
    bundle.connectivity.nftApi = { status: 'ok', latencyMs: Date.now() - start };
  } catch (err: any) {
    bundle.connectivity.nftApi = { status: 'failed', error: err.message };
  }

  // Multi-network status
  for (const [name, network] of Object.entries({
    ethereum: Network.ETH_MAINNET,
    polygon: Network.MATIC_MAINNET,
    arbitrum: Network.ARB_MAINNET,
  })) {
    try {
      const client = new Alchemy({ apiKey: process.env.ALCHEMY_API_KEY, network });
      const block = await client.core.getBlockNumber();
      bundle.networkStatus[name] = { status: 'ok', block };
    } catch (err: any) {
      bundle.networkStatus[name] = { status: 'failed', error: err.message };
    }
  }

  const filename = `alchemy-debug-${Date.now()}.json`;
  require('fs').writeFileSync(filename, JSON.stringify(bundle, null, 2));
  console.log(`Debug bundle saved: ${filename}`);
  return bundle;
}

generateDebugBundle().catch(console.error);

Step 2: Bash Quick Diagnostic

#!/bin/bash
echo "=== Alchemy Quick Diagnostics ==="
echo "API Key: ${ALCHEMY_API_KEY:+SET (redacted)}"

echo -n "ETH Mainnet: "
curl -s "https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}" \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":0}' \
  | jq -r '.result // .error.message'

echo -n "Polygon: "
curl -s "https://polygon-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}" \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":0}' \
  | jq -r '.result // .error.message'

echo "=== Done ==="

Output

• JSON debug bundle with connectivity, latency, and network status
• SDK version and environment configuration
• Multi-network health check results

Examples

When a testnet application reports intermittent RPC failures, run the generator with a scoped development key and inspect the JSON locally. Confirm it reports SDK version, network status, aggregate latency, and only redacted key state; remove wallet addresses or application payloads if any were added by local instrumentation. Attach the sanitized bundle and relevant request ID to a support ticket. If a bundle exposes a credential or sensitive application data, do not upload it—revoke the exposed credential if necessary, correct the redaction logic, and regenerate the evidence.

Error Handling

Resources

• Alchemy Status Page
• Alchemy Support

Next Steps

For rate limit handling, see alchemy-rate-limits.