lobster-ads

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.

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