gabrielmoreira Alchemy Reference Architecture
Overview
This reference architecture separates wallet-facing UI from server-side provider access so API keys, rate limits, validation, caching, and webhook verification are consistently controlled across supported chains.
Prerequisites
- A written data-flow and threat model covering wallet addresses, signed messages, provider credentials, public API routes, and webhook events.
- A server-side deployment target with managed secrets, input validation, rate limiting, and observability before any frontend endpoint is exposed.
- Public-chain or testnet fixtures and a rollback mechanism for each feature that affects external users or contract interactions.
Instructions
- Begin with a single chain and server-side client factory, keeping the provider key out of browser bundles and public response payloads.
- Add validated, rate-limited API routes for each use case and define the cache freshness rule before implementing UI data fetching.
- Treat a wallet address as an identifier, not authentication; use a signed challenge when ownership must be proved.
- Verify webhook signatures and idempotency before routing any external event, then test the complete path against public or testnet fixtures.
System Architecture
┌─────────────────────────────────────────────────────────┐
│ Frontend (React/Next.js) │
│ - Wallet connection (MetaMask, WalletConnect) │
│ - Portfolio dashboard │
│ - NFT gallery │
│ - Transaction history │
└────────────────────────┬────────────────────────────────┘
│ HTTPS (no API key exposed)
┌────────────────────────▼────────────────────────────────┐
│ API Layer (Next.js/Express) │
│ - /api/balance/:address │
│ - /api/nfts/:owner │
│ - /api/tokens/:address │
│ - /api/transactions/:address │
│ - /webhooks/alchemy (webhook receiver) │
└───────┬──────────┬──────────┬───────────────────────────┘
│ │ │
┌────▼───┐ ┌───▼────┐ ┌──▼──────┐
│Alchemy │ │Alchemy │ │Alchemy │
│Core API│ │NFT API │ │Notify │
│(RPC) │ │ │ │(Webhooks│
└────────┘ └────────┘ └─────────┘
ETH/Polygon/ARB/OP/Base
Project Structure
web3-dapp/
├── src/
│ ├── alchemy/
│ │ ├── client-factory.ts # Multi-chain Alchemy client factory
│ │ ├── cache.ts # Response caching with TTL
│ │ ├── throttler.ts # CU-aware rate limiter
│ │ └── errors.ts # Error classification
│ ├── portfolio/
│ │ ├── fetcher.ts # Wallet portfolio aggregator
│ │ ├── transactions.ts # Transaction history analyzer
│ │ └── multi-chain.ts # Cross-chain balance aggregator
│ ├── nft/
│ │ ├── collection.ts # NFT collection explorer
│ │ ├── batch-metadata.ts # Batch metadata fetcher
│ │ └── verify-ownership.ts # NFT ownership verification
│ ├── contracts/
│ │ ├── read-contract.ts # Smart contract read operations
│ │ └── abis/ # Contract ABI files
│ ├── webhooks/
│ │ ├── handler.ts # Webhook endpoint
│ │ ├── verify.ts # HMAC signature verification
│ │ └── event-router.ts # Event type routing
│ ├── security/
│ │ ├── validators.ts # Input validation (addresses, blocks)
│ │ └── proxy.ts # API key proxy for frontend
│ └── api/ # API route handlers
├── tests/
│ ├── unit/ # Unit tests (mocked Alchemy)
│ ├── fork/ # Mainnet fork tests (Hardhat)
│ └── integration/ # Sepolia integration tests
├── contracts/ # Solidity contracts (if applicable)
├── hardhat.config.ts # Hardhat + Alchemy fork config
└── package.json
Key Design Decisions
| Decision | Choice | Rationale |
|---|---|---|
| SDK | alchemy-sdk |
Official, typed, Enhanced + NFT APIs included |
| Multi-chain | Client factory pattern | Lazy initialization, shared API key |
| Caching | In-memory with TTL tiers | Block data = 12s, metadata = 24h |
| Rate limiting | Bottleneck with CU weights | Matches Alchemy CU budget model |
| Frontend access | API proxy | Never expose API key to browser |
| Real-time | WebSocket subscriptions | Lower cost than polling |
| Testing | Hardhat mainnet fork | Reproducible tests with real data |
Output
- Complete project structure for Alchemy-powered dApp
- Multi-chain architecture with client factory
- API proxy pattern keeping API key server-side
- Webhook integration for real-time event processing
Examples
Implement the balance route for one public test address in a staging service. The frontend calls the route without an Alchemy key, while the server validates the address, uses the managed secret, applies the balance freshness TTL, and emits only aggregate latency and outcome telemetry. Confirm a malformed address is rejected before provider use and a simulated provider outage yields a clear unavailable response. If the key appears in a browser artifact, the route lacks rate limiting, or the failure state is ambiguous, keep the feature disabled and fix that boundary before adding multi-chain or wallet-gated behavior.
Error Handling
| Failure | Architecture response |
|---|---|
| Browser bundle contains provider credential | Revoke the credential, remove it from the artifact, and enforce server-side access. |
| Public route receives malformed or abusive input | Reject early, apply rate limits, and do not forward the request to the provider. |
| Webhook is unsigned or duplicate | Reject it or return a safe duplicate response before business processing. |
| Provider or chain is unavailable | Return explicit partial/unavailable state and activate the product fallback. |
Resources
Next Steps
Start with alchemy-install-auth, then follow skills through production deployment.