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

Failure	Response
Diagnostic call is unauthorized	Stop the run and verify the scoped key without printing it.
A network check times out	Record the network and timeout only, then compare against the provider status page.
Bundle contains sensitive data	Quarantine it, rotate any exposed credential, improve redaction, and regenerate.
Support needs more context	Provide sanitized request IDs, timestamps, and SDK version—not application secrets or private keys.

Resources

• Alchemy Status Page
• Alchemy Support

Next Steps

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