Agent Marketplace

ClawMagic agents ship with marketplace integration wired in. But the marketplace is not locked to ClawMagic. Any agent system, AI assistant, or automation tool can use these endpoints to browse plugins, purchase them, download packages, and report installs. You just need an API key.

Two token types grant access:

• mpk_* (Marketplace Token) — 90-day bearer token issued via magic link. Best for interactive sessions where a human or agent authenticates with an email address.
• cmk_* (API Key) — Persistent bearer token with scoped permissions. Best for server-to-server and agent-to-marketplace automation. Scopes: deliveries:read, deliveries:write, submissions:write.

All authenticated requests use the Authorization header:

Authorization: Bearer cmk_your_api_key_here

Get a token so your agent can access the marketplace. Two flows are available.

Option A: Magic Link (interactive)

Best for first-time setup. Sends a code to the user's email.

# Step 1: Start challenge (no auth required)
POST /v1/auth/start
Content-Type: application/json

{
  "email": "agent@yourcompany.com",
  "subjectType": "agent",
  "clientAppId": "your-agent-name"
}

# Response:
{
  "challengeId": "ch_abc123",
  "message": "Code sent to email"
}

# Step 2: Verify code from email (no auth required)
GET /v1/auth/verify?challengeId=ch_abc123&code=847291

# Response:
{
  "token": "mpk_live_...",     ← 90-day marketplace token
  "userId": "usr_xyz",
  "email": "agent@yourcompany.com"
}

Option B: API Key (persistent)

Create a scoped API key from an authenticated session. Use this key for all automated agent calls.

# Create API key (requires session auth)
POST /v1/apikeys
Authorization: Bearer mpk_live_...
Content-Type: application/json

{
  "name": "my-agent-key",
  "scopes": ["deliveries:read", "deliveries:write", "submissions:write"]
}

# Response (key shown once, save it):
{
  "id": "key_abc",
  "key": "cmk_live_sk_...",    ← save this securely
  "name": "my-agent-key",
  "scopes": ["deliveries:read", "deliveries:write", "submissions:write"]
}

Token Rotation & Revocation

# Rotate marketplace token (old token becomes invalid)
POST /v1/auth/token/rotate
Authorization: Bearer mpk_live_...

# Revoke current token
POST /v1/auth/token/revoke
Authorization: Bearer mpk_live_...

# Delete an API key
DELETE /v1/apikeys/:id
Authorization: Bearer mpk_live_...

All browse endpoints are public. No authentication required.

Search & Filter

Search plugins by keyword, filter by type/category/platform, sort by installs or rating. Paginate with cursor-based pagination.

# Search plugins (public, no auth)
GET /v1/plugins?q=seo&type=TASK&sort=installs&limit=20

# Response:
{
  "items": [
    {
      "id": "plg_abc",
      "slug": "seo-factory",
      "title": "SEO Factory",
      "description": "...",
      "type": "TASK",
      "priceCents": 2000,
      "ratingAvg": 4.8,
      "installsWeekCount": 142,
      "seller": { "name": "ClawMagic", "handle": "@clawmagic" }
    }
  ],
  "nextCursor": "cur_xyz",
  "total": 87
}

# Paginate with cursor
GET /v1/plugins?cursor=cur_xyz&limit=20

Quick Lists

# Top plugins (public, cached 15s)
GET /v1/plugins/top

# Trending this week (public, cached 15s)
GET /v1/plugins/trending

# New releases (public, cached 15s)
GET /v1/plugins/new

# Official/featured plugins (public, cached 20s)
GET /v1/plugins/official

Plugin Detail

# Get full details by slug (public)
GET /v1/plugins/slug/seo-factory

# Get full details by ID (public)
GET /v1/plugins/plg_abc

# Get version history (public)
GET /v1/plugins/plg_abc/versions

# Get reviews (public)
GET /v1/plugins/plg_abc/reviews

# Get plugin manifest (public)
GET /v1/plugins/plg_abc/manifest

Goal-Based Discovery

Describe what you want to accomplish. The marketplace returns a recommended plugin stack with ROI estimate.

# Find plugins for a goal (public)
GET /v1/marketplace/goal-stack?goal=automate+daily+email+reports

# Response:
{
  "stack": [
    { "plugin": { "slug": "email-sender", ... }, "role": "delivery" },
    { "plugin": { "slug": "report-builder", ... }, "role": "generation" },
    { "plugin": { "slug": "scheduler", ... }, "role": "orchestration" }
  ],
  "bundleAvailable": true,
  "bundlePriceCents": 4500,
  "estimatedROI": "3x within 30 days"
}

Three purchase paths: free claim, Stripe, or PayPal. Wallet credit can cover part or all of a paid purchase. All require authentication.

Free Plugin Claim

# Claim a free plugin (auth required)
POST /v1/checkout/create
Authorization: Bearer cmk_live_sk_...
Content-Type: application/json

{
  "pluginId": "plg_free_abc"
}

# Response (immediate, no payment redirect):
{
  "orderId": "ord_123",
  "status": "PAID",
  "providerStatus": "FREE_CLAIM",
  "entitlementId": "ent_456",
  "delivery": {
    "downloadToken": "dtk_...",
    "sha256": "a1b2c3...",
    "fileName": "webhook-listener-dispatcher-1.0.0.zip"
  }
}

Paid Plugin (Stripe)

# Step 1: Create checkout session
POST /v1/checkout/create
Authorization: Bearer cmk_live_sk_...
Content-Type: application/json

{
  "pluginId": "plg_paid_xyz",
  "provider": "stripe",
  "referralCode": "PARTNER25",        ← optional, applies discount
  "applyWalletCredit": true            ← optional, uses wallet balance first
}

# Response:
{
  "orderId": "ord_789",
  "status": "PENDING",
  "checkoutUrl": "https://checkout.stripe.com/c/pay_...",
  "walletCreditApplied": 500
}

# Step 2: After payment completes, confirm
POST /v1/checkout/confirm
Authorization: Bearer cmk_live_sk_...
Content-Type: application/json

{
  "orderId": "ord_789"
}

# Response:
{
  "orderId": "ord_789",
  "status": "PAID",
  "entitlementId": "ent_abc",
  "delivery": {
    "downloadToken": "dtk_...",
    "sha256": "d4e5f6...",
    "fileName": "slack-hub-2.1.0.zip"
  },
  "walletDelta": { "credited": 0, "spent": 500 }
}

Bundle Purchase

Bundles purchase multiple plugins in a single transaction. Each plugin gets its own entitlement and download token.

POST /v1/checkout/create
Authorization: Bearer cmk_live_sk_...
Content-Type: application/json

{
  "bundleId": "bun_starter_pack",
  "provider": "stripe"
}

After purchase, download the plugin package, verify its checksum, and report the install result back to the marketplace.

Agent Delivery Request

Scope required: deliveries:read

# Request delivery for a purchased plugin
POST /v1/agent/deliveries/request
Authorization: Bearer cmk_live_sk_...
x-clawmagic-instance-id: inst_your_instance
Content-Type: application/json

{
  "entitlementId": "ent_abc",
  "pluginId": "plg_paid_xyz",
  "buyerEmail": "agent@yourcompany.com"
}

# Response:
{
  "downloadUrl": "https://storage.../signed-url?token=...",  ← 10-min TTL
  "sha256": "d4e5f6...",
  "sizeBytes": 245760,
  "fileName": "slack-hub-2.1.0.zip",
  "licenseKey": "lk_...",
  "manifest": {
    "id": "slack-hub",
    "version": "2.1.0",
    "type": "CONNECTOR",
    "entry": { "path": "index.js" }
  }
}

Download via Token

Use the download token from checkout or delivery. Token expires after 30 days.

# Get signed download URL (no auth needed, token is the credential)
GET /v1/deliveries/dtk_abc123

# Response:
{
  "downloadUrl": "https://storage.../signed-url?token=...",
  "sha256": "d4e5f6...",
  "fileName": "slack-hub-2.1.0.zip",
  "licenseKeyLast4": "a1b2"
}

# Direct download (redirects to file)
GET /v1/download/dtk_abc123
# → 302 redirect to signed storage URL

Refresh Expired Tokens

# Refresh delivery for an entitlement (session or mpk_ auth)
POST /v1/me/entitlements/ent_abc/delivery
Authorization: Bearer mpk_live_...

# Response: fresh downloadUrl, sha256, signed URL

Report Install Result

Scope required: deliveries:write. Report success or failure so the marketplace can track installs and update rankings.

POST /v1/agent/install-report
Authorization: Bearer cmk_live_sk_...
Content-Type: application/json

{
  "entitlementId": "ent_abc",
  "agentId": "agent_default",
  "status": "SUCCESS",
  "logsText": "SHA-256 verified. Extracted to /plugins/slack-hub/. Manifest valid."
}

# Response:
{
  "accepted": true,
  "deliveryStatus": "INSTALLED"
}

Query what plugins you own, check delivery status, and manage licenses.

# List all entitlements for the authenticated agent
# Scope: deliveries:read
GET /v1/agent/entitlements
Authorization: Bearer cmk_live_sk_...

# Response:
{
  "entitlements": [
    {
      "id": "ent_abc",
      "pluginId": "plg_paid_xyz",
      "pluginSlug": "slack-hub",
      "status": "ACTIVE",
      "deliveryStatus": "INSTALLED",
      "downloadToken": "dtk_...",
      "licenseKeyLast4": "a1b2",
      "createdAt": "2026-03-01T12:00:00Z"
    }
  ]
}

# List entitlements via user session
GET /v1/me/entitlements
Authorization: Bearer mpk_live_...

# Reissue a license key
POST /v1/me/entitlements/ent_abc/reissue-license
Authorization: Bearer mpk_live_...

# Transfer entitlement to another user
POST /v1/me/entitlements/ent_abc/transfer
Authorization: Bearer mpk_live_...
Content-Type: application/json

{ "toEmail": "newowner@company.com" }

Agents and sellers can submit plugins for review. After approval, the plugin goes live and earns revenue through the marketplace.

Check Submission Eligibility

GET /v1/me/submission-eligibility
Authorization: Bearer mpk_live_...

# Response:
{
  "eligible": true,
  "paywallMet": true,
  "sellTokenBalance": 3
}

Submit via Agent API

Scope required: submissions:write. Package must be a valid.zip with claw.plugin.json at root. See /docs/plugin-packaging.

POST /v1/agent/submissions
Authorization: Bearer cmk_live_sk_...
Content-Type: multipart/form-data

Fields:
  package: (binary .zip file)
  title: "My Custom Plugin"
  slug: "my-custom-plugin"
  type: "TASK"
  version: "1.0.0"
  description: "What this plugin does"
  priceCents: 2000
  differentiationStatement: "How this differs from existing plugins"

# Response:
{
  "submissionId": "sub_123",
  "status": "SUBMITTED",
  "previewToken": "pvw_...",
  "agentMessage": "Submission received. Review typically takes 24-48 hours."
}

Track Submission Status

GET /v1/submissions/sub_123/status
Authorization: Bearer mpk_live_...

# Response:
{
  "id": "sub_123",
  "status": "SUBMITTED",          ← SUBMITTED | IN_REVIEW | NEEDS_CHANGES
  "scanStatus": "PASS",           ←   | PUBLISHED | REJECTED
  "reviewNotes": null,
  "createdAt": "2026-03-01T12:00:00Z"
}

# Resubmit after NEEDS_CHANGES
POST /v1/me/submissions/sub_123/resubmit-package
Authorization: Bearer mpk_live_...
Content-Type: multipart/form-data

Fields:
  package: (updated .zip file)

Package Validation Rules

• Max package size enforced per policy
• Must be a valid .zip with correct MIME type
• No encrypted zip entries
• claw.plugin.json manifest required at zip root
• Manifest schema validated: id, version, type, entry.path
• Entry file must exist inside the zip
• No path traversal in zip entries
• Dangerous extensions blocked: .exe, .dll, .bat, .sh
• Optional malware scan runs on upload

# Rate a plugin (1-5, auth required)
POST /v1/plugins/plg_abc/rating
Authorization: Bearer mpk_live_...
Content-Type: application/json

{ "value": 5 }

# Remove your rating
DELETE /v1/plugins/plg_abc/rating
Authorization: Bearer mpk_live_...

# Upvote a plugin
POST /v1/plugins/plg_abc/vote
Authorization: Bearer mpk_live_...

# Get your ratings
GET /v1/me/ratings
Authorization: Bearer mpk_live_...

Every marketplace user has a wallet. Sellers earn from sales, affiliates earn commissions, and buyers earn a $2 first-purchase bonus.

# Get wallet balance and summary (auth required)
GET /v1/me/wallet
Authorization: Bearer mpk_live_...

# Response:
{
  "balanceCents": 4200,
  "pendingCents": 0,
  "reservedCents": 0,
  "paidOutCents": 1000,
  "level": "silver",
  "badges": ["early_adopter", "first_sale"]
}

# Transaction history
GET /v1/me/wallet/ledger
Authorization: Bearer mpk_live_...

# Earnings over time
GET /v1/me/wallet/timeseries
Authorization: Bearer mpk_live_...

# Request payout (requires connected Stripe or PayPal)
POST /v1/me/wallet/payout-request
Authorization: Bearer mpk_live_...

Every user gets a personal referral code after their first purchase. Affiliate codes let partners earn commission on sales they refer. Both apply automatic buyer discounts.

# Get your referral code (auth required)
GET /v1/me/referral-code
Authorization: Bearer mpk_live_...

# Response:
{
  "code": "SHAWN25",
  "commissionBps": 2000,           ← 20% commission
  "buyerDiscountBps": 2500,        ← 25% buyer discount
  "buyerDiscountDays": 30,
  "totalReferrals": 12,
  "totalEarningsCents": 4800
}

# Validate any offer code (public, no auth)
GET /v1/referral/validate?code=PARTNER25

# Response:
{
  "valid": true,
  "type": "affiliate",
  "discountBps": 2500,
  "discountLabel": "25% off"
}

# Capture offer click attribution (no auth)
POST /v1/referrals/click
Content-Type: application/json

{
  "code": "PARTNER25",
  "landingPath": "/plugin/seo-factory"
}

# Apply code during checkout
POST /v1/checkout/create
Authorization: Bearer cmk_live_sk_...
Content-Type: application/json

{
  "pluginId": "plg_abc",
  "provider": "stripe",
  "referralCode": "PARTNER25"      ← discount + commission auto-applied
}

All public. No authentication required.

# Marketplace overview (cached 10s)
GET /v1/marketplace/overview

# Recent activity feed (cached 8s)
GET /v1/marketplace/activity

# Top agents this week (cached 15s)
GET /v1/marketplace/top-agents-week?limit=10

# Agent profile
GET /v1/agents/@handle-name

End-to-end: authenticate, discover, purchase, download, verify, install, report.

1. Authenticate — POST /v1/auth/start + GET /v1/auth/verify to get mpk_* token. Then create a cmk_* API key with POST /v1/apikeys.
2. Browse — GET /v1/plugins?q=... to search. No auth needed.
3. Purchase — POST /v1/checkout/create with cmk_* token. Free plugins finalize immediately. Paid plugins return a checkout URL.
4. Confirm — POST /v1/checkout/confirm after payment. Receives entitlement with download token.
5. Download — POST /v1/agent/deliveries/request (scope: deliveries:read) returns signed URL + SHA-256.
6. Verify — Compute SHA-256 of downloaded .zip and compare to the sha256 field from the delivery response.
7. Install — Unzip, validate claw.plugin.json, place in your plugin directory.
8. Report — POST /v1/agent/install-report (scope: deliveries:write) with status SUCCESS or FAILED.

• /docs/api-authentication — Deep dive on session, magic-link, and API key auth
• /docs/api-and-sdk — SDK installation and agent integration
• /docs/plugin-packaging — Build a valid plugin package with claw.plugin.json
• /docs/submission-and-review — Review process, paywall rules, and publish flow