docs: add free tier API key to reduce onboarding friction (#8)

drichar · web-flow · commit 39ef7faaad47 · 2026-02-10T12:21:57.000-05:00
Replace `'your-api-key'` placeholders across all documentation and
examples with the free tier key (`1b72df7e-...`), allowing developers
to start building immediately without requesting a key.

- Add API Key Tiers table to SDK README (free vs production)
- Update all code examples with free tier key and rate limit comment
- Pre-configure .env.example files with the free key
- Simplify example setup instructions (no manual key entry needed)
- Update JSDoc examples in client.ts and middleware.ts
- Update MIGRATION.md and MIDDLEWARE.md for consistency
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -42,7 +42,7 @@ const deflex = new DeflexClient({
 
 // After
 const router = new RouterClient({
-  apiKey: 'your-api-key'
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e' // Free tier (60 requests/min)
 })
 ```
 
@@ -162,8 +162,8 @@ DEFLEX_API_KEY=your-api-key
 VITE_DEFLEX_API_KEY=your-api-key
 
 # After
-HAYSTACK_ROUTER_API_KEY=your-api-key
-VITE_HAYSTACK_ROUTER_API_KEY=your-api-key
+HAYSTACK_ROUTER_API_KEY=1b72df7e-1131-4449-8ce1-29b79dd3f51e
+VITE_HAYSTACK_ROUTER_API_KEY=1b72df7e-1131-4449-8ce1-29b79dd3f51e
 ```
 
 ## No Functional Changes
diff --git a/README.md b/README.md
@@ -49,7 +49,7 @@ This is a pnpm workspace monorepo. All packages and examples share dependencies
 
 ### Prerequisites
 
-- **Haystack Router API Key** - Request an API key by emailing [support@txnlab.dev](mailto:support@txnlab.dev)
+- **Haystack Router API Key** - An API key is included for free tier usage (60 requests/min). For production rate limits, request a key from [support@txnlab.dev](mailto:support@txnlab.dev).
 - algosdk 3.0.0 or later (peer dependency)
 - Node.js >= 20
 - pnpm 10.20.0 or later
@@ -106,7 +106,7 @@ const { activeAddress, transactionSigner } = useWallet()
 
 // Initialize client
 const router = new RouterClient({
-	apiKey: 'your-api-key',
+	apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
 })
 
 // Get quote
diff --git a/examples/README.md b/examples/README.md
@@ -56,7 +56,7 @@ All examples use the local SDK package via pnpm workspaces. This means changes t
 
 ### Prerequisites
 
-- **Haystack Router API Key** - Request an API key by emailing [support@txnlab.dev](mailto:support@txnlab.dev)
+- **Haystack Router API Key** - A free tier key is included in the `.env.example` files (60 requests/min). For production rate limits, request a key from [support@txnlab.dev](mailto:support@txnlab.dev).
 - algosdk 3.0.0 or later (peer dependency)
 - Node.js >= 20
 - pnpm 10.20.0 or later
@@ -97,18 +97,18 @@ pnpm dev
 
 ## Configuration
 
-Each example requires a Haystack Router API key. Create a `.env` file in the example directory:
+Each example includes a `.env.example` file with the free tier API key pre-configured. Create a `.env` file in the example directory:
 
 ### React / React Query
 
 ```bash
-VITE_HAYSTACK_ROUTER_API_KEY=your-api-key-here
+VITE_HAYSTACK_ROUTER_API_KEY=1b72df7e-1131-4449-8ce1-29b79dd3f51e  # Free tier (60 requests/min)
 ```
 
 ### Node.js CLI
 
 ```bash
-HAYSTACK_ROUTER_API_KEY=your-api-key-here
+HAYSTACK_ROUTER_API_KEY=1b72df7e-1131-4449-8ce1-29b79dd3f51e  # Free tier (60 requests/min)
 ACCOUNT_MNEMONIC="your 25 word mnemonic phrase"
 ```
 
diff --git a/examples/node-cli/.env.example b/examples/node-cli/.env.example
@@ -1,5 +1,5 @@
-# Haystack Router API Configuration
-HAYSTACK_ROUTER_API_KEY=your-api-key-here
+# Haystack Router API Configuration - Free tier (60 requests/min)
+HAYSTACK_ROUTER_API_KEY=1b72df7e-1131-4449-8ce1-29b79dd3f51e
 
 # Algorand Account Mnemonic (25 words)
 # WARNING: Never commit this file with your real mnemonic!
diff --git a/examples/node-cli/README.md b/examples/node-cli/README.md
@@ -12,7 +12,7 @@ This example demonstrates how to use the Haystack Router SDK in a Node.js comman
 
 ## Prerequisites
 
-- **Haystack Router API Key** - Request an API key by emailing [support@txnlab.dev](mailto:support@txnlab.dev)
+- **Haystack Router API Key** - A free tier key is included in `.env.example` (60 requests/min). For production rate limits, request a key from [support@txnlab.dev](mailto:support@txnlab.dev).
 - algosdk 3.0.0 or later (peer dependency)
 - Node.js >= 20
 - pnpm 10.20.0 or later
@@ -31,11 +31,11 @@ pnpm install
 cp .env.example .env
 ```
 
-3. Configure your `.env` file:
+3. Configure your `.env` file (the API key is pre-configured with the free tier):
 
 ```env
-# Required: Your Haystack Router API key
-HAYSTACK_ROUTER_API_KEY=your-api-key-here
+# Haystack Router API key - Free tier (60 requests/min)
+HAYSTACK_ROUTER_API_KEY=1b72df7e-1131-4449-8ce1-29b79dd3f51e
 
 # Required: Your 25-word account mnemonic
 # WARNING: Keep this file private and never commit it!
diff --git a/examples/react-query/.env.example b/examples/react-query/.env.example
@@ -1 +1 @@
-VITE_HAYSTACK_ROUTER_API_KEY=your-api-key-here
+VITE_HAYSTACK_ROUTER_API_KEY=1b72df7e-1131-4449-8ce1-29b79dd3f51e
diff --git a/examples/react-query/README.md b/examples/react-query/README.md
@@ -15,7 +15,7 @@ A React application demonstrating advanced Haystack Router SDK integration with
 
 ## Prerequisites
 
-- **Haystack Router API Key** - Request an API key by emailing [support@txnlab.dev](mailto:support@txnlab.dev)
+- **Haystack Router API Key** - A free tier key is included in `.env.example` (60 requests/min). For production rate limits, request a key from [support@txnlab.dev](mailto:support@txnlab.dev).
 - Node.js >= 20
 - pnpm 10.20.0 or later
 
@@ -33,11 +33,7 @@ pnpm install
 cp .env.example .env
 ```
 
-3. Add your Haystack Router API key to the `.env` file:
-
-```
-VITE_HAYSTACK_ROUTER_API_KEY=your-api-key-here
-```
+3. The `.env` file comes pre-configured with the free tier API key. For production use, replace it with your dedicated key.
 
 ## Development
 
diff --git a/examples/react/.env.example b/examples/react/.env.example
@@ -1 +1 @@
-VITE_HAYSTACK_ROUTER_API_KEY=your-api-key-here
+VITE_HAYSTACK_ROUTER_API_KEY=1b72df7e-1131-4449-8ce1-29b79dd3f51e
diff --git a/examples/react/README.md b/examples/react/README.md
@@ -12,7 +12,7 @@ A simple React application demonstrating basic Haystack Router SDK integration w
 
 ## Prerequisites
 
-- **Haystack Router API Key** - Request an API key by emailing [support@txnlab.dev](mailto:support@txnlab.dev)
+- **Haystack Router API Key** - A free tier key is included in `.env.example` (60 requests/min). For production rate limits, request a key from [support@txnlab.dev](mailto:support@txnlab.dev).
 - Node.js >= 20
 - pnpm 10.20.0 or later
 
@@ -30,11 +30,7 @@ pnpm install
 cp .env.example .env
 ```
 
-3. Add your Haystack Router API key to the `.env` file:
-
-```
-VITE_HAYSTACK_ROUTER_API_KEY=your-api-key-here
-```
+3. The `.env` file comes pre-configured with the free tier API key. For production use, replace it with your dedicated key.
 
 ## Development
 
diff --git a/packages/haystack/MIDDLEWARE.md b/packages/haystack/MIDDLEWARE.md
@@ -370,7 +370,7 @@ const middleware = new CustomAssetMiddleware({
 })
 
 const router = new RouterClient({
-  apiKey: 'your-api-key',
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
   middleware: [middleware],
 })
 
diff --git a/packages/haystack/README.md b/packages/haystack/README.md
@@ -10,9 +10,16 @@ TypeScript/JavaScript SDK for [Haystack Order Router](https://txnlab.gitbook.io/
 
 ## Prerequisites
 
-- **Haystack Router API Key** - Request an API key by emailing [support@txnlab.dev](mailto:support@txnlab.dev)
+- **Haystack Router API Key** - A free tier key is included below for development and testing (60 requests/min). For production rate limits, request a dedicated key from [support@txnlab.dev](mailto:support@txnlab.dev).
 - algosdk 3.0.0 or later
 
+### API Key Tiers
+
+| Tier | Key | Rate Limit | Use Case |
+| --- | --- | --- | --- |
+| **Free** | `1b72df7e-1131-4449-8ce1-29b79dd3f51e` | 60 requests/min | Development, testing, low-volume integrations |
+| **Production** | Request from [support@txnlab.dev](mailto:support@txnlab.dev) | Higher limits | Production applications |
+
 ## Installation
 
 ```bash
@@ -31,7 +38,7 @@ const { activeAddress, transactionSigner } = useWallet()
 
 // Initialize the client
 const router = new RouterClient({
-  apiKey: 'your-api-key',
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
 })
 
 // Get a quote
@@ -63,12 +70,12 @@ import { RouterClient } from '@txnlab/haystack-router'
 
 // Basic initialization
 const router = new RouterClient({
-  apiKey: 'your-api-key',
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
 })
 
 // Custom Algod configuration
 const router = new RouterClient({
-  apiKey: 'your-api-key',
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
   algodUri: 'https://mainnet-api.4160.nodely.dev/',
   algodToken: '',
   algodPort: 443,
@@ -77,7 +84,7 @@ const router = new RouterClient({
 
 // Earn fees with the referral program
 const router = new RouterClient({
-  apiKey: 'your-api-key',
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
   referrerAddress: 'YOUR_ALGORAND_ADDRESS', // Earns 25% of swap fees
   feeBps: 15, // 0.15% fee (max: 300 = 3%)
 })
@@ -265,7 +272,7 @@ const firstStage = new FirstStageMiddleware({
 
 // Pass middleware to RouterClient
 const router = new RouterClient({
-  apiKey: 'your-api-key',
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
   middleware: [firstStage], // Middleware is applied automatically
 })
 
@@ -293,7 +300,7 @@ const autoOptOut = new AutoOptOutMiddleware({
 })
 
 const router = new RouterClient({
-  apiKey: 'your-api-key',
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
   middleware: [autoOptOut],
 })
 
@@ -314,7 +321,7 @@ If you're not using `autoOptIn: true`, you can manually check if opt-in is neede
 
 ```typescript
 const router = new RouterClient({
-  apiKey: 'your-api-key',
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
   autoOptIn: false, // Default if not provided
 })
 
diff --git a/packages/haystack/src/client.ts b/packages/haystack/src/client.ts
@@ -37,14 +37,14 @@ import type {
  * @example
  * ```typescript
  * const router = new RouterClient({
- *   apiKey: 'your-api-key',
+ *   apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
  * })
  * ```
  *
  * @example
  * ```typescript
  * const router = new RouterClient({
- *   apiKey: 'your-api-key',
+ *   apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
  *   apiBaseUrl: 'https://hayrouter.txnlab.dev',
  *   algodUri: 'https://mainnet-api.4160.nodely.dev/',
  *   algodToken: '',
diff --git a/packages/haystack/src/middleware.ts b/packages/haystack/src/middleware.ts
@@ -255,7 +255,7 @@ export interface AutoOptOutConfig {
  * })
  *
  * const router = new RouterClient({
- *   apiKey: 'your-api-key',
+ *   apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
  *   middleware: [autoOptOut],
  * })
  *

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-VITE_HAYSTACK_ROUTER_API_KEY=your-api-key-here`
	`1`	`+VITE_HAYSTACK_ROUTER_API_KEY=1b72df7e-1131-4449-8ce1-29b79dd3f51e`