Architecture Overview
Understanding how earnlayer components work together
System Architecture
System Architecture
User Question
↓
Your Chat Route → MCP Server (gets hyperlink ads)
↓
↓
LLM Response ← ← ← ← ← ← ← ← ← Ads
↓
Browser (displays response with hyperlink ads)
↓
earnlayer SDK → Your Proxy → earnlayer API (tracks clicks, gets display ads)
Two Main Components
Phase 1A
MCP Server
Provides hyperlink ads to your LLM via function calling
Location:
https://mcp.earnlayerai.com/mcp
Used in:
Your chat API route only
Environment variable:
EARNLAYER_MCP_URL
How it works:
1
Your LLM calls the MCP tool when user asks about products2
MCP returns relevant sponsored ads3
LLM includes ads in response with clickable linksPhase 1B & Phase 2
earnlayer SDK
Client-side SDK for tracking impressions and fetching display ads
Location:
npm install @earnlayer/sdk
Used in:
React components and proxy endpoints
Environment variable:
EARNLAYER_API_KEY (server-side only)
How it works:
1
Browser requests ads via hooks (useDisplayAd)2
Request goes to your proxy endpoint3
Proxy calls earnlayer API with API key4
Ads returned to browserData Flow
Hyperlink Ads (Phase 1A)
1
User: "What VPN should I use?"2
Your API → OpenAI/Gemini (with MCP tool)3
LLM → MCP Server: "Get VPN ads"4
MCP → LLM: [NordVPN, ExpressVPN, ...]5
LLM → Your API: "I recommend [NordVPN](url)..."6
Your API → Browser: Formatted response7
User sees: Response with clickable sponsored linksDisplay Ads (Phase 2)
1
Browser: useDisplayAd() hook2
Hook → Proxy: GET /api/earnlayer/displayad/...3
Proxy → earnlayer API (with API key)4
earnlayer → Proxy: Ad object5
Proxy → Browser: Ad object (no API key)6
Browser: Renders ad component7
User clicks → Backend redirect → Advertiser siteSecurity Architecture
API Key Protection
Browser (no API key)
↓
Your Proxy Endpoint (has API key)
↓
earnlayer API (validates API key)
API keys never leave your server.
Click Tracking
User clicks ad.url
↓
Backend redirect: api.earnlayerai.com/redirect?...
↓
Track click server-side
↓
Redirect to advertiser
Tracking happens server-side for security and accuracy.