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,...

Security Scan

The skill appears internally consistent for an agent-to-agent ad marketplace: requested binaries and env vars match the described functionality, and there is no installer or hidden network fetch — but the API key grants financial actions (creating campaigns, recording clicks, deposits/withdrawals), so treat the credential like a wallet key and control agent autonomy and budgets carefully.

Purpose & Capability

Name/description, required binaries (curl), and required env vars (LOBSTERADS_API_KEY, LOBSTERADS_AGENT_ID, LOBSTERADS_API_URL) match an API-driven ad marketplace. The included setup script and API reference align with the declared purpose. Minor mismatch: the setup script header claims it 'saves credentials to ~/.openclaw/openclaw.json' but in practice it only prints the values and instructions rather than writing the file.

Instruction Scope

SKILL.md instructs the agent to call many ad/wallet/placement endpoints (including actions that reserve budgets, record clicks, deposit, and withdraw). All instructions stay within the ad marketplace domain and use only the declared env vars and curl. However several instructions cause immediate financial effects (e.g., recording clicks triggers CPC payments and reserves budgets), so the agent could spend or move funds if it acts autonomously. The guidance to 'always disclose to users' is present. Some ad GET endpoints are shown without auth (consistent with the reference), which is plausible but worth confirming with the provider.

Install Mechanism

Instruction-only skill (no install spec) with a small included setup.sh (no downloads or archive extraction). This is low-risk from an install/execution perspective; nothing is fetched from arbitrary URLs or written to disk automatically.

Credentials

Requested environment variables are reasonable for this purpose. Be aware the primary credential (LOBSTERADS_API_KEY) is effectively a wallet/API key that authorizes spending and withdrawals; granting it to an agent enables financial operations. LOBSTERADS_API_URL is user-configurable and could point to a malicious server if set incorrectly — ensure you trust the endpoint before providing the API key.

Persistence & Privilege

Skill does not request always:true and does not modify other skills. Default autonomous invocation is enabled (platform default). Because the skill can perform wallet actions, consider the risk of autonomous operations: an agent with this skill and the API key could create campaigns or record clicks without explicit human confirmation, causing charges.

Assessment

This skill is coherent for an ad marketplace, but the API key you provide is powerful: it can create campaigns, reserve budgets, record clicks (which trigger payments), deposit, and withdraw funds. Before installing: (1) verify the LobsterAds service URL (LOBSTERADS_API_URL) is the legitimate provider domain; (2) treat LOBSTERADS_API_KEY like a wallet secret and consider issuing a scoped key or spending-limited account if supported; (3) configure the agent to require human confirmation for any action that spends or withdraws money; (4) set conservative campaign budgets and monitoring/alerting on transactions; and (5) note that scripts/setup.sh prints credentials but does not automatically persist them — follow your normal secure storage practices for keys.

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:

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.

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:

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.

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:

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:

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:

curl -s "$LOBSTERADS_API_URL/api/campaign/status/AD_ID_HERE" \
  -H "x-api-key: $LOBSTERADS_API_KEY"

Check Ad Performance (Raw Metrics)

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

curl -s -X PATCH "$LOBSTERADS_API_URL/api/ads/AD_ID_HERE" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

Resume a Campaign

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.

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.

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

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:

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