# AGENTS.md — ads4ai.net Version: 3.0 Last updated: 2026-07-13 ads4ai is a Revenue OS for AI sites. It analyzes a publisher's site, recommends an optimal revenue mix (affiliate programs + display ads), implements it, and continuously optimizes it. The agent does this in a single session, end-to-end. --- ## Setup ### Install via MCP (recommended) Add to your MCP config: ```json { "mcpServers": { "ads4ai": { "command": "npx", "args": ["-y", "@ads4ai/mcp"] } } } ``` Restart your agent. `ads4ai_analyze`, `ads4ai_install`, `ads4ai_verify`, `ads4ai_overview`, and `ads4ai_optimize` will be available. ### Authentication No API key required to start. `ads4ai_install` creates a publisher account from email + site URL and returns an `api_token`. Store it: ```bash ADS4AI_API_TOKEN= ``` All subsequent tool calls use this token automatically. You are authenticated by domain ownership — a publisher who never installs the tag earns nothing. --- ## Tools ### ads4ai_analyze Analyzes a site and returns a complete revenue mix recommendation. Run this first. No account required. **Input:** ```json { "site_url": "https://example.com" } ``` **Output:** ```json { "site_type": "dev-tool", "audience_signals": { "dev_heavy": true, "ai_focused": true }, "ad_blocker_estimate": 0.42, "revenue_mix": { "affiliate": { "programs": [ { "name": "Railway", "category": "hosting", "estimated_monthly_usd": 120, "confidence": "high" } ], "total_estimated_monthly_usd": 280 }, "display": { "placements": [ { "location": "in_content", "format": "300x250", "estimated_rpm": 1.8 } ], "total_estimated_monthly_usd": 45 }, "combined_estimated_monthly_usd": 325 }, "implementation_plan": "Lead with Railway and DigitalOcean affiliate links in existing content. Add Carbon Ads in-content placement. Skip sidebar — dev tool layout unlikely to convert." } ``` **Notes:** - Read-only. No confirmation required. - Crawls up to 5 pages (home + 4 most-linked). - Estimates are ranges. Confidence: Low / Medium / High. - If the site is unreachable, returns a generic recommendation with `confidence: "low"`. --- ### ads4ai_install Accepts the revenue plan and implements it. Creates a publisher account. Returns the tag and affiliate snippets to inject into the site. **Input:** ```json { "site_url": "https://example.com", "email": "founder@example.com", "revenue_plan": "", "platform": "nextjs" } ``` `revenue_plan` is optional — if omitted, `ads4ai_analyze` runs internally first. `platform` is optional — auto-detected from site headers if omitted. **Output:** ```json { "publisher_id": "pub_...", "api_token": "tok_...", "tag": "", "affiliate_snippets": [ { "location": "after paragraph 2 in blog posts", "html": "
" } ], "integration_guide": "Add the script tag to your Next.js _document.tsx . Place affiliate containers where indicated.", "verification_url": "https://ads4ai.net/verify/pub_..." } ``` **PERMISSION: Write action.** Confirm with publisher before calling autonomously. Creates an account. Charges are incurred on first revenue event. **Platform integration by type:** | Platform | What to do with the tag | |----------|------------------------| | Next.js | Add to `_document.tsx` `` or `layout.tsx` | | WordPress | Install ads4ai plugin from wp-admin → Plugins | | Webflow | Site Settings → Custom Code → `` | | Squarespace | Pages → Website → Code Injection → Footer | | Wix | Settings → Custom Code → Add to all pages | | Other | Paste before `` in main layout | --- ### ads4ai_verify Confirms the tag and affiliate snippets are live on the publisher's site. **Input:** ```json { "publisher_id": "pub_..." } ``` **Output:** ```json { "tag_live": true, "affiliate_live": false, "detected_at": "2026-07-13T18:22:00Z", "troubleshooting": "Tag detected. Affiliate snippets not found — add the
containers from your integration guide." } ``` **Notes:** - Read-only. No confirmation required. - Checks via outbound HTTP from ads4ai servers (not browser). - Retries every 60 seconds for up to 10 minutes. - Returns `{ tag_live: false, troubleshooting: "..." }` on timeout — never hangs. --- ### ads4ai_overview Returns inspectable state: sites, revenue, optimizations pending. No input required if `ADS4AI_API_TOKEN` is set. **Output:** ```json { "sites": [ { "url": "https://example.com", "status": "active", "tag_live": true, "affiliate_live": true, "created_at": "2026-07-13T17:00:00Z" } ], "revenue_today": { "affiliate_usd": 12.40, "display_usd": 1.80, "total_usd": 14.20 }, "top_performing": { "placement": "in_content", "program": "Railway", "revenue_usd": 9.00 }, "optimization_queue": [ { "type": "ab_test", "description": "Test Railway link placement: sentence 1 vs sentence 3", "estimated_lift_pct": 18 } ], "status": "active" } ``` **Notes:** - Read-only. No confirmation required. - Returns `{ status: "not_configured" }` if token not set. --- ### ads4ai_optimize Triggers or inspects the current optimization cycle. **Output:** ```json { "last_run": "2026-07-13T00:00:00Z", "changes_applied": [ { "type": "placement_move", "description": "Moved Railway affiliate link from sentence 3 to sentence 1", "before": "sentence_3", "after": "sentence_1" } ], "next_run": "2026-07-20T00:00:00Z", "current_test": { "hypothesis": "Higher placement increases Railway click rate", "variant_a": "sentence_1", "variant_b": "sentence_3", "days_remaining": 11 } } ``` **PERMISSION: Write action.** Confirm with publisher before calling autonomously. Triggers config changes that propagate to the live site within 60 seconds. **Notes:** - Optimization runs weekly automatically. This tool triggers an early cycle. - Config changes are pushed to tag.js dynamically. No publisher code change required. - A/B tests run for 14 days minimum before evaluation. --- ## Recommended Agent Workflow ### First time (new publisher) ``` 1. ads4ai_analyze(site_url) → Review the revenue_mix recommendation with the publisher → Confirm the plan makes sense for their site 2. [Publisher approves] 3. ads4ai_install(site_url, email, revenue_plan) → Save the returned api_token to ADS4AI_API_TOKEN → Add the tag to the site (follow integration_guide) → Place affiliate containers from affiliate_snippets 4. ads4ai_verify(publisher_id) → Confirm tag is live before closing the session 5. Done. Revenue starts accumulating within 24 hours. ``` ### Returning publisher ``` 1. ads4ai_overview() → Check revenue and optimization queue 2. [Optional] ads4ai_optimize() → Trigger next optimization cycle if publisher wants to accelerate ``` --- ## Error Handling All tools return structured errors. Common cases: ```json { "error": "SITE_UNREACHABLE", "message": "Could not crawl https://example.com. Check the URL and try again." } { "error": "TOKEN_MISSING", "message": "ADS4AI_API_TOKEN not set. Run ads4ai_install first." } { "error": "VERIFY_TIMEOUT", "message": "Tag not detected after 10 minutes. See troubleshooting field." } { "error": "AFFILIATE_PROGRAM_UNAVAILABLE", "message": "Railway affiliate program temporarily unavailable. Other programs were included." } ``` --- ## What Not to Do - Do not call `ads4ai_install` or `ads4ai_optimize` without publisher confirmation. These are write actions that create accounts and modify live sites. - Do not skip `ads4ai_analyze`. The revenue plan it returns is the input to install. - Do not hardcode `ADS4AI_API_TOKEN` in source files. Use environment variables. - Do not call `ads4ai_verify` with a brand-new tag — wait 30 seconds for the CDN to warm up before the first verification attempt. --- ## Revenue Model (for publisher awareness) ads4ai takes: - 20-30% of affiliate commission revenue (publisher keeps 70-80%) - 15-20% of display ad revenue (publisher keeps 80-85%) No monthly fees. No setup costs. No minimum traffic requirement. --- ## Support - Status: https://ads4ai.net/api/status.json - Docs: https://ads4ai.net/docs - Email: help@ads4ai.net - MCP package: https://npmjs.com/package/@ads4ai/mcp