diff --git a/packages/playground/.env.template b/packages/playground/.env.template
index e2ffb4208b..0e136025e0 100644
--- a/packages/playground/.env.template
+++ b/packages/playground/.env.template
@@ -1,5 +1,50 @@
+# OnchainKit Playground — Environment Variables
+# Copy this file to .env.local and fill in your values.
+# Never commit .env.local to version control.
+
+# ─── RPC URLs ────────────────────────────────────────────────────────────────
+
+# Ethereum Mainnet RPC URL (optional).
+# Used by AppProvider to create a public viem client for mainnet reads.
+# Get a free endpoint from Coinbase Developer Platform, Alchemy, or Infura:
+#   https://portal.cdp.coinbase.com/  (Coinbase — recommended for Base projects)
+#   https://www.alchemy.com/
+#   https://www.infura.io/
+# Leave empty to use the default public RPC (rate-limited, not for production).
 NEXT_PUBLIC_ETHEREUM_MAINNET_RPC_URL=""
+
+# Base Sepolia RPC URL (optional, recommended for local development & testing).
+# Base Sepolia is the testnet for Base. Use it to test transactions without
+# spending real ETH. Get a free endpoint from:
+#   https://portal.cdp.coinbase.com/  (Coinbase Developer Platform)
+#   https://www.alchemy.com/
+# Public fallback (rate-limited): https://sepolia.base.org
+NEXT_PUBLIC_BASE_SEPOLIA_RPC_URL=""
+
+# ─── OnchainKit ──────────────────────────────────────────────────────────────
+
+# OnchainKit API key (required).
+# Passed to <OnchainKitProvider apiKey={...}>.
+# Get your key at: https://portal.cdp.coinbase.com/
 NEXT_PUBLIC_OCK_API_KEY=""
+
+# ─── Vercel ──────────────────────────────────────────────────────────────────
+
+# Vercel environment name (optional).
+# Automatically set by Vercel on deploy: "production" | "preview" | "development"
+# Only needed if you deploy this playground to Vercel.
 NEXT_PUBLIC_VERCEL_ENV=""
+
+# ─── WalletConnect ───────────────────────────────────────────────────────────
+
+# WalletConnect / Reown Project ID (required for WalletConnect support).
+# Passed to <OnchainKitProvider projectId={...}>.
+# Create a free project at: https://cloud.reown.com/
 NEXT_PUBLIC_PROJECT_ID=""
-NEXT_PUBLIC_RESERVOIR_API_KEY=""
\ No newline at end of file
+
+# ─── Reservoir ───────────────────────────────────────────────────────────────
+
+# Reservoir API key (optional).
+# Used for NFT data in the playground.
+# Get a free key at: https://reservoir.tools/
+NEXT_PUBLIC_RESERVOIR_API_KEY=""