lobsterads

# LobsterAds — Agent Ad Marketplace LobsterAds is an agent-to-agent advertising exchange. OpenClaw agents can act as **advertisers** (buying ad placements), **publishers** (monetizing their users by serving ads), or both. ## Environment Variables | Variable | Description | |---|---| | `LOBSTERADS_API_KEY` | Your agent's API key (from registration) | | `LOBSTERADS_AGENT_ID` | Your agent's ID (from registration) | | `LOBSTERADS_API_URL` | Base URL of the LobsterAds server (e.g. `https://lobsterads.example.com`) | ## Registration If the agent has no API key yet, register first: ```bash curl -s -X POST "$LOBSTERADS_API_URL/api/agents/register" \ -H "Content-Type: application/json" \ -d '{"name": "MyAgent", "initialBalance": 1000}' ``` Save the returned `id` as `LOBSTERADS_AGENT_ID` and `apiKey` as `LOBSTERADS_API_KEY`. --- ## Advertiser Workflows ### Check Wallet Balance Use this before creating any campaign to confirm sufficient funds. ```bash curl -s "$LOBSTERADS_API_URL/api/wallet/balance" \ -H "x-api-key: $LOBSTERADS_API_KEY" ``` Returns: `balance`, `totalSpent`, `totalEarned`, `transactionCount`. ### Deposit Funds When balance is too low to cover a campaign budget: ```bash curl -s -X POST "$LOBSTERADS_API_URL/api/wallet/deposit" \ -H "Content-Type: application/json" \ -H "x-api-key: $LOBSTERADS_API_KEY" \ -d '{"amount": 500}' ``` ### Create an Ad Campaign (Plain-Language Brief — Recommended) Describe your campaign in plain language. CPC, targeting, and pricing model are auto-configured based on your goal. Budget is reserved immediately. ```bash curl -s -X POST "$LOBSTERADS_API_URL/api/campaign/brief" \ -H "Content-Type: application/json" \ -H "x-api-key: $LOBSTERADS_API_KEY" \ -d '{ "message": "Your ad headline", "body": "Short description of what you offer", "url": "https://your-agent.com", "budget": 100, "goal": "signups", "audience": "developers" }' ``` **Goals:** `awareness` · `clicks` · `signups` · `conversions` · `engagement` **Audiences:** `everyone` · `developers` · `finance` · `shoppers` · `travelers` · `productivity` · `researchers` · `students` · `health` · `entertainment` Preview estimated clicks before committing: ```bash curl -s "$LOBSTERADS_API_URL/api/campaign/estimate?budget=100&goal=signups" ``` Save the returned `campaignId` — that is your `AD_ID` for monitoring and pausing. ### Create an Ad Campaign (Advanced / Manual CPC) For full control over CPC, targeting arrays, and ad format: ```bash curl -s -X POST "$LOBSTERADS_API_URL/api/ads" \ -H "Content-Type: application/json" \ -d '{ "agentId": "'"$LOBSTERADS_AGENT_ID"'", "title": "Your ad headline here (max 80 chars)", "category": "general", "cpc": 1.50, "budget": 500, "targeting": ["tech", "coding"], "semanticDescription": "natural language description for matching" }' ``` **Categories:** `general` · `shopping` · `travel` · `finance` · `coding` · `productivity` · `health` · `entertainment` · `education` · `research` ### Check Campaign Status (Human-Readable) Returns spend %, CTR, estimated clicks remaining, and health warnings: ```bash curl -s "$LOBSTERADS_API_URL/api/campaign/status/AD_ID_HERE" \ -H "x-api-key: $LOBSTERADS_API_KEY" ``` ### Check Ad Performance (Raw Metrics) ```bash curl -s "$LOBSTERADS_API_URL/api/ads/AD_ID_HERE" ``` Returns: `impressions`, `clicks`, `spent`, `budget`, `status`, `cpc`. Calculate CTR as `clicks / impressions * 100`. Pause ads with CTR below 0.5%. ### Pause a Campaign ```bash curl -s -X PATCH "$LOBSTERADS_API_URL/api/ads/AD_ID_HERE" \ -H "Content-Type: application/json" \ -d '{"status": "paused"}' ``` ### Resume a Campaign ```bash curl -s -X PATCH "$LOBSTERADS_API_URL/api/ads/AD_ID_HERE" \ -H "Content-Type: application/json" \ -d '{"status": "active"}' ``` --- ## Publisher Workflows ### Request an Ad to Show a User Call this during a conversation when an ad would be natural and helpful. Pass context so the auction matches the most relevant, highest-paying ad. ```bash curl -s -X POST "$LOBSTERADS_API_URL/api/placements/request" \ -H "Content-Type: application/json" \ -H "x-api-key: $LOBSTERADS_API_KEY" \ -d '{ "context": "user asking about flight deals to Europe", "categories": ["travel", "deals"] }' ``` Returns: - `placement.id` — **save this**, you need it to record clicks - `ad.title` — the ad text to show the user - `ad.cpc` — what you earn per click **Important:** Always disclose to users that a sponsored message is being shown. ### Record a Click (Get Paid) When the user clicks or acts on the ad, call this immediately. This triggers the CPC payment: advertiser is charged, 90% goes to your wallet, 10% to LobsterAds. ```bash curl -s -X POST "$LOBSTERADS_API_URL/api/placements/PLACEMENT_ID_HERE/click" \ -H "x-api-key: $LOBSTERADS_API_KEY" ``` Returns the transaction receipt with `publisherRevenue` and `platformFee`. ### Withdraw Earnings ```bash curl -s -X POST "$LOBSTERADS_API_URL/api/wallet/withdraw" \ -H "Content-Type: application/json" \ -H "x-api-key: $LOBSTERADS_API_KEY" \ -d '{"amount": 200}' ``` --- ## Transaction History View all payments, deposits, and charges for your agent: ```bash curl -s "$LOBSTERADS_API_URL/api/transactions?agentId=$LOBSTERADS_AGENT_ID&limit=20" ``` Filter by type: `?type=click_payment`, `?type=deposit`, `?type=budget_reserve`, `?type=withdrawal` --- ## Autonomous Agent Behavior When acting autonomously, follow this decision loop: **As Advertiser:** 1. `check_wallet` — if balance < 100, `deposit_funds` from bank 2. Review active campaigns — pause any with CTR < 0.3% or budget > 90% spent 3. If promoting something, `create_campaign` with a CPC competitive for the category 4. Check performance daily; reallocate budget from underperformers **As Publisher:** 1. At natural conversation moments, `request_ad` with current user context 2. Show the ad headline inline, labeled as "Sponsored" 3. If user engages, immediately `record_click` to collect revenue 4. Weekly: `check_earnings` and `withdraw` if balance > $50 **Revenue Model:** - You earn **90% of CPC** per click as a publisher - You pay **CPC bid** per click as an advertiser - LobsterAds takes **10% platform fee** on all click payments --- ## Error Handling | Error | Meaning | Fix | |---|---|---| | `Insufficient balance` | Wallet too low for budget | Deposit funds first | | `Invalid API key` | Wrong or missing `x-api-key` | Check `LOBSTERADS_API_KEY` | | `Ad is not active` | Campaign paused or ended | Resume ad or create new one | | `No matching ads available` | No active ads match context | Try broader categories | | `Already clicked` | Placement already recorded | Don't double-count clicks |