# EarnLayer SDK
**Monetize your AI application with context-aware ads.**
✨ **Works with ANY LLM** - OpenAI, Google Gemini, Claude, or custom models
## Quick Start
**Already have a working chat app?** Perfect! Add EarnLayer in ~20 minutes with our **phased approach**.
**Phase 1A (5 min):** See hyperlink ads immediately - quick win!
**Phase 1B (10 min):** Complete setup - production ready!
**Phase 2 (5-10 min):** Add display ads - maximize revenue!
**Prerequisites:**
- ✅ Node.js 16+
- ✅ Next.js 13+ with App Router
- ✅ Working chat app with API route
- ✅ EarnLayer API key - [Get one here](https://app.earnlayerai.com/api-keys)
---
## Phase 1A: Quick Start - See Hyperlink Ads
Get sponsored hyperlinks showing in your chat responses immediately.
**Time: 5 minutes**
💡 This gets you started fast! You'll see sponsored links immediately. Complete Phase 1B to ensure all ad types bill correctly.
### 1. Install Dependencies
**OpenAI:**
```bash
npm install openai
```
**Gemini:**
```bash
npm install @google/genai @modelcontextprotocol/sdk
```
### 2. Add API Keys
**ADD** to your `.env.local`:
```bash
# ADD: Required for SDK (Phase 1B and Phase 2)
EARNLAYER_API_KEY=el_your_api_key_here
# ADD: Required ONLY for MCP integration in chat route (Phase 1A)
EARNLAYER_MCP_URL=https://mcp.earnlayerai.com/mcp
# Your existing LLM provider key (keep as-is)
# OpenAI
OPENAI_API_KEY=sk_your_openai_key_here
# OR Gemini
GOOGLE_API_KEY=your_google_api_key_here
```
> **Note:** `EARNLAYER_MCP_URL` is only needed in your chat API route for hyperlink ads. The SDK (used in Phase 1B and Phase 2) only needs `EARNLAYER_API_KEY`.
### 3. Add MCP to Your Chat Route
**OpenAI (Responses API):**
In your existing `app/api/chat/route.ts`:
```typescript
// Your existing imports (keep as-is)
import OpenAI from 'openai';
// Your existing client setup (keep as-is)
const client = new OpenAI({
apiKey: process.env.OPENAI_API_KEY,
});
// ADD: New environment variables
const EARNLAYER_MCP_URL = process.env.EARNLAYER_MCP_URL!;
const EARNLAYER_API_KEY = process.env.EARNLAYER_API_KEY!;
// ADD: System instructions for ad integration
const SYSTEM_INSTRUCTIONS =
'You are a helpful assistant. IMPORTANT: Whenever a user asks about products, services, tools, software, or anything that could be purchased or subscribed to, ' +
'you MUST FIRST call the earnlayer_content_ads_search tool to find sponsored recommendations. ' +
'After getting results, review the ads and ONLY include the ones that are RELEVANT to the user\'s question. ' +
'Ignore any ads that are not related to what the user is asking about. ' +
'For relevant ads, include them in your response with their clickable links in markdown format [Product Name](url). ' +
'ALWAYS include the URLs as clickable links.';
// MODIFY: Update your existing API call to use Responses API with MCP tools
const resp = await client.responses.create({
model: 'gpt-4o',
// ADD: Tools array for MCP integration
tools: [
{
type: 'mcp',
server_label: 'earnlayer',
server_url: EARNLAYER_MCP_URL,
require_approval: 'never',
headers: {
'x-api-key': EARNLAYER_API_KEY
}
}
],
// ADD: Input format for Responses API
input: [
{
role: 'developer',
content: [{ type: 'input_text', text: SYSTEM_INSTRUCTIONS }]
},
{
role: 'user',
content: [{ type: 'input_text', text: message }]
}
]
});
// Your existing response handling (keep as-is)
return NextResponse.json({ response: resp.output_text });
```
**Gemini:**
```typescript
// ADD: New imports for MCP integration
import { GoogleGenAI, mcpToTool } from '@google/genai';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
// ADD: New environment variables
const EARNLAYER_MCP_URL = process.env.EARNLAYER_MCP_URL!;
const EARNLAYER_API_KEY = process.env.EARNLAYER_API_KEY!;
// ADD: System instructions for ad integration
const SYSTEM_INSTRUCTIONS =
'You are a helpful assistant. IMPORTANT: Whenever a user asks about products, services, tools, software, or anything that could be purchased or subscribed to, ' +
'you MUST FIRST call the earnlayer_content_ads_search tool to find sponsored recommendations. ' +
'After getting results, review the ads and ONLY include the ones that are RELEVANT to the user\'s question. ' +
'Ignore any ads that are not related to what the user is asking about. ' +
'For relevant ads, include them in your response with their clickable links in markdown format [Product Name](url). ' +
'ALWAYS include the URLs as clickable links.';
// ADD: Set up MCP client
const transport = new StreamableHTTPClientTransport(
new URL(EARNLAYER_MCP_URL),
{
requestInit: {
headers: { 'x-api-key': EARNLAYER_API_KEY }
}
}
);
const client = new Client(
{ name: 'earnlayer-client', version: '1.0.0' },
{ capabilities: {} }
);
await client.connect(transport);
// MODIFY: Update your existing Gemini call to include MCP tools
const ai = new GoogleGenAI({
apiKey: process.env.GOOGLE_API_KEY!
});
const response = await ai.models.generateContent({
model: 'gemini-2.0-flash-exp',
contents: SYSTEM_INSTRUCTIONS + '\n\nUser: ' + message,
config: {
// ADD: MCP tools integration
tools: [mcpToTool(client)], // Automatically calls MCP tools
},
});
await client.close();
// Your existing response handling (keep as-is)
return NextResponse.json({ response: response.text });
```
### 4. Test It!
```bash
npm run dev
```
Ask: **"What are the best VPNs?"** or **"What project management tools should I use?"**
✅ You should see sponsored links in the AI response.
🎉 **Phase 1A Complete!** You're seeing hyperlink ads. Now complete Phase 1B for production.
---
## Phase 1B: Complete Setup - Production Ready
Enable full impression tracking and billing for all ad types.
**Time: 10 minutes**
⚠️ **Required for production.** This ensures all ads bill correctly.
### 1. Install SDK
```bash
npm install @earnlayer/sdk
```
### 2. Create Proxy Endpoint
**CREATE** new file `app/api/earnlayer/[...slug]/route.ts`:
```typescript
// CREATE: New file - EarnLayer proxy endpoint
import { createEarnLayerProxy } from '@earnlayer/sdk/nextjs';
const handler = createEarnLayerProxy({
apiKey: process.env.EARNLAYER_API_KEY!
});
export { handler as GET, handler as POST };
```
✅ This handles all EarnLayer API calls securely (no API key exposed to browser).
### 3. Wrap with Provider
**MODIFY** your chat page component (e.g., `app/page.tsx`):
```typescript
// ADD: New imports for EarnLayer
import { EarnLayerProvider, useEarnLayerClient } from '@earnlayer/sdk/react';
// MODIFY: Wrap your existing chat component with the provider
export default function ChatPage() {
return (
);
}
// ADD: Inside your existing chat component
function YourChatComponent() {
// ADD: EarnLayer hooks
const { conversationId, initializeConversation } = useEarnLayerClient();
const hasInitialized = useRef(false);
// ADD: Initialize conversation once on page load
useEffect(() => {
if (!hasInitialized.current) {
hasInitialized.current = true;
initializeConversation();
}
}, []);
// Your existing component code (keep as-is)
// ... rest of your component
}
```
### 4. Add Impression Confirmation
**MODIFY** your chat component, after receiving and displaying the AI response:
```typescript
// Your existing imports (keep as-is)
import { useEarnLayerClient } from '@earnlayer/sdk/react';
function YourChatComponent() {
// Your existing state and hooks (keep as-is)
const { client, conversationId, initializeConversation } = useEarnLayerClient();
const [messages, setMessages] = useState([]);
const handleSendMessage = async (message: string) => {
// Your existing message sending code (keep as-is)
const response = await fetch('/api/chat', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ message, conversationId }),
});
const data = await response.json();
const aiResponseText = data.response;
// Your existing message display code (keep as-is)
setMessages(prev => [...prev, { role: 'assistant', content: aiResponseText }]);
// ADD: Confirm impressions (secure - goes through proxy)
if (conversationId && aiResponseText) {
client.confirmHyperlinkImpressions(conversationId, aiResponseText)
.then(result => {
console.log(`✅ Confirmed ${result.confirmed_count} impressions`);
})
.catch(error => {
console.error('Failed to confirm impressions:', error);
});
}
};
// Your existing component code (keep as-is)
// ... rest of component
}
```
**Why this is required:**
- MCP creates impressions when returning ads to your LLM
- Not all ads returned are included in the final response
- This confirms which ads were actually shown to users
- Only confirmed impressions are billed and tracked
### 5. Update Chat Route with ConversationId
**MODIFY** your `app/api/chat/route.ts` to receive and pass conversationId:
**OpenAI:**
```typescript
// MODIFY: Receive conversationId from client
const { message, conversationId } = await req.json();
// MODIFY: Add conversationId to MCP headers
const resp = await client.responses.create({
model: 'gpt-4o',
tools: [
{
type: 'mcp',
server_label: 'earnlayer',
server_url: EARNLAYER_MCP_URL,
require_approval: 'never',
headers: {
'x-api-key': EARNLAYER_API_KEY,
'x-conversation-id': conversationId // ADD: conversationId header
}
}
],
// Your existing code (keep as-is)
// ... rest of your existing code
});
```
**Gemini:**
```typescript
// MODIFY: Receive conversationId from client
const { message, conversationId } = await req.json();
// MODIFY: Add conversationId to MCP headers
const transport = new StreamableHTTPClientTransport(
new URL(EARNLAYER_MCP_URL),
{
requestInit: {
headers: {
'x-api-key': EARNLAYER_API_KEY,
'x-conversation-id': conversationId // ADD: conversationId header
}
}
}
);
```
### 6. Test Again!
```bash
npm run dev
```
Ask: **"What are the best database tools?"**
✅ **Validate:**
- AI response includes sponsored links
- Browser console shows: `✅ Confirmed X impressions`
- Check Network tab for POST to `/api/earnlayer/impressions/confirm`
🎉 **Phase 1B Complete!** You're production-ready with full billing.
---
## Phase 2: Add Display Ads
Add visual banner/popup/video ads for maximum revenue.
**Time: 5-10 minutes**
### 1. Set Up Display Ad Trigger
**MODIFY** your chat component, add state to trigger ad refreshes:
```typescript
function YourChatComponent() {
// Your existing hooks (keep as-is)
const { conversationId } = useEarnLayerClient(); // Already added in Phase 1B
const [shouldRefetchAd, setShouldRefetchAd] = useState(false);
const handleSendMessage = async (message: string) => {
// Your existing send message code (keep as-is)
// ... your existing send message code ...
const data = await response.json();
setMessages(prev => [...prev, { role: 'assistant', content: data.response }]);
// ADD: Trigger ad refetch AFTER AI response
setShouldRefetchAd(true);
setTimeout(() => setShouldRefetchAd(false), 100);
};
// Your existing component code (keep as-is)
// ... rest of component
}
```
### 2. Add Display Ad Component
**CREATE** a display ad component (or add to existing file):
```typescript
// CREATE: New display ad component
import { useDisplayAd } from '@earnlayer/sdk/react';
import { useEffect, useRef } from 'react';
function DisplayAdComponent({ shouldRefetch }: { shouldRefetch: boolean }) {
// ADD: EarnLayer display ad hook
const { ad, isLoading, refetch } = useDisplayAd({
adType: 'banner',
placement: 'sidebar',
autoFetch: false // We'll control fetching manually
});
const prevShouldRefetch = useRef(false);
// ADD: Fetch when shouldRefetch toggles from false to true
useEffect(() => {
if (shouldRefetch && !prevShouldRefetch.current) {
prevShouldRefetch.current = true;
refetch();
} else if (!shouldRefetch) {
prevShouldRefetch.current = false;
}
}, [shouldRefetch]);
if (isLoading) return
)}
AD
);
}
```
### 3. Add Sidebar to Your Layout
**MODIFY** your chat component, add a sidebar for the display ad:
```typescript
return (
{/* Your existing chat UI (keep as-is) */}
{/* Your messages, input, etc. */}
{/* ADD: New sidebar for display ad */}
);
```
### 4. Test Phase 2
```bash
npm run dev
```
Ask: **"What are the best database tools?"**
✅ **Validate:**
- AI response includes sponsored hyperlinks
- Display ad visible in sidebar
- Display ad updates after each AI response
- Check EarnLayer dashboard for analytics
🎉 **Phase 2 Complete!** You now have hyperlinks + display ads.
---
## Advanced: Thinking Ads (Optional)
Show ads during AI loading states:
```typescript
// CREATE: New thinking ad component
import { useDisplayAd } from '@earnlayer/sdk/react';
function ThinkingAdComponent() {
// ADD: EarnLayer thinking ad hook
const { ad, isLoading } = useDisplayAd({
adType: 'thinking',
autoFetch: true // Auto-fetch when component mounts
});
if (isLoading || !ad) return null;
return (
●
{ad.title}
);
}
// ADD: Use in your chat (only shown during AI thinking):
{isThinking && (