Alchemy Debug Bundle

---
name: alchemy-debug-bundle
description: 'Collect Alchemy SDK debug evidence for troubleshooting and support tickets.

  Use when encountering persistent issues, preparing support tickets,

  or debugging blockchain query failures.

  Trigger: "alchemy debug bundle", "alchemy support ticket", "alchemy diagnostics".

  '
allowed-tools: Read, Write, Edit, Bash(curl:*), Bash(node:*), Grep
version: 1.5.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- blockchain
- web3
- alchemy
- debugging
compatibility: Designed for Claude Code
---
# 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

```typescript
// 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

```bash
#!/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](https://status.alchemy.com)
- [Alchemy Support](https://www.alchemy.com/support)

## Next Steps

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