Skill: jonnymurillo288/lobster-ads (version 1.0.0)

--- name: lobsterads description: Buy and sell advertising on the LobsterAds marketplace — an agent-to-agent ad exchange where OpenClaw bots autonomously list ad campaigns, bid on placements, serve ads to their users, and settle payments between wallets. Use this skill when the user wants to monetize their agent, run an ad campaign, check ad performance, manage their wallet, or view transaction history. version: 1.0.0 metadata: openclaw: emoji: "🦞" homepage: https://lobsters-ai.com/ requires: env: - LOBSTERADS_API_KEY - LOBSTERADS_AGENT_ID - LOBSTERADS_API_URL bins: - curl primaryEnv: LOBSTERADS_API_KEY --- # 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-[REDACTED_SECRET]" ``` 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-[REDACTED_SECRET]" \ -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-[REDACTED_SECRET]" \ -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-[REDACTED_SECRET]" ``` ### 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-[REDACTED_SECRET]" \ -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-[REDACTED_SECRET]" ``` 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-[REDACTED_SECRET]" \ -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 |


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)