---

name: swarms-marketplace-api description: Comprehensive reference for the Swarms Marketplace APIs. Use when creating/editing/querying agents or prompts, tokenizing agents (single or batch), claiming fees, or integrating with swarms.world. Covers CRUD for agents and prompts, token launch, batch token launch, schemas, examples, and error handling.

Swarms Marketplace API – Skill Reference

Use this skill when working with the Swarms Marketplace: agents, prompts, tokenization (single and batch), and fee claims. All endpoints are under the marketplace base URL; authentication uses an API key or Supabase session.

Full documentation (for deeper detail):

• Overview & endpoint index: https://docs.swarms.ai/docs/marketplace/api-overview
• Agents API: https://docs.swarms.ai/docs/marketplace/agents-api
• Prompts API: https://docs.swarms.ai/docs/marketplace/prompts-api
• Token Launch (single): https://docs.swarms.ai/docs/marketplace/token-launch-api
• Token Launch Batch: https://docs.swarms.ai/docs/marketplace/token-launch-batch-api
• Tokenization details (costs, bonding curve): https://docs.swarms.ai/docs/marketplace/tokenization_details
• Claim Fees API: https://docs.swarms.ai/docs/marketplace/claim-fees-api
• Marketplace examples: https://docs.swarms.ai/docs/marketplace/examples
• API Reference (auth, limits): https://docs.swarms.ai/api-reference

---

Base URLs & authentication

Service	Base URL
Marketplace API	https://swarms.world
Swarms API	https://api.swarms.world

Authentication: Send API key in the header: Authorization: Bearer YOUR_API_KEY.
Get keys at: https://swarms.world/platform/api-keys

---

1. Agents API (CRUD)

Create agent – POST /api/add-agent

Required: name (min 2 chars), description, useCases (array, at least one).
Optional: agent (code, min 5 chars if set), language, requirements, tags, is_free (default true), price_usd (if paid), category, status, tokenized_on, ticker/creator_wallet/private_key (if tokenized), image_url/file_path/image_base64, links, seller_wallet_address, x402_url, mcp_url.

Schema (input):

Parameter	Type	Required	Description
name	string	Yes	Display name, min 2 characters
agent	string	No	Agent code; min 5 chars if provided
description	string	Yes	Description of the agent
language	string	No	e.g. "python", "javascript"
requirements	array	No	[{ "package": string, "installation": string }]
useCases	array	Yes	[{ "title": string, "description": string }]
tags	string	No	Comma-separated
is_free	boolean	No	Default true
price_usd	number	If paid	Required when is_free is false; > 0
category	string	No	e.g. "data-science"
status	string	No	pending | approved | rejected; default pending
tokenized_on	boolean	No	Enable Solana tokenization
ticker	string	If token	Required when tokenized_on is true; uppercase alphanumeric, max 10
creator_wallet	string	If token	Creator wallet public key
private_key	string	If token	JSON array of 64 bytes, base64, or base58
image_url / file_path / image_base64	string	No	Image (one of these)
links	array	No	Strings or { "name": string, "url": string }
seller_wallet_address	string	No	Seller wallet
x402_url / mcp_url	string	No	Valid URL or empty string

Success (200):

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "listing_url": "https://swarms.world/agent/550e8400-e29b-41d4-a716-446655440000",
  "tokenized": false,
  "token_address": null,
  "pool_address": null
}

Example – create agent (cURL):

curl -X POST https://swarms.world/api/add-agent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data Analysis Agent",
    "agent": "from swarms import Agent\n\nclass DataAnalysisAgent(Agent):\n    def analyze(self, data):\n        pass",
    "description": "An AI agent for analyzing datasets",
    "language": "python",
    "requirements": [{"package": "pandas", "installation": "pip install pandas"}],
    "useCases": [{"title": "Financial Analysis", "description": "Analyze financial data"}],
    "tags": "data,analysis,python",
    "is_free": false,
    "price_usd": 19.99,
    "category": "data-science"
  }'

Update agent – POST /api/edit-agent

Same body as create, plus required id (agent UUID).

Example:

curl -X POST https://swarms.world/api/edit-agent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "550e8400-e29b-41d4-a716-446655440000", "name": "Advanced Data Agent", "description": "Updated description", "price_usd": 24.99}'

Query agents – POST /api/query-agents

Auth: Optional.
Body: search, category, priceFilter ("all" | "free" | "paid"), userFilter, sortBy ("newest" | "oldest" | "popular" | "rating"), limit (1–100, default 6), offset (default 0).

Example:

curl -X POST https://swarms.world/api/query-agents \
  -H "Content-Type: application/json" \
  -d '{"search": "data analysis", "category": "data-science", "sortBy": "newest", "limit": 10, "offset": 0}'

Response: Array of agent objects (id, name, agent, description, language, requirements, use_cases, tags, is_free, price_usd, category, status, image_url, user_id, created_at, updated_at, etc.).

---

2. Prompts API (CRUD)

Create prompt – POST /api/add-prompt

Required: name (min 2 chars), prompt (min 5 chars), useCases (at least one), tags (min 2 chars).
Optional: description, is_free, price_usd, category, status, tokenized_on, ticker/creator_wallet/private_key (if tokenized), image_url/file_path/image_base64, links, seller_wallet_address.

Schema (input): Same pattern as agents for pricing, tokenization, and images; content field is prompt instead of agent.

Success (200):

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "listing_url": "https://swarms.world/prompt/550e8400-e29b-41d4-a716-446655440000",
  "tokenized": false,
  "token_address": null,
  "pool_address": null
}

Example – create prompt:

curl -X POST https://swarms.world/api/add-prompt \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Technical Blog Writer",
    "prompt": "You are an expert technical writer. Topic: {topic}",
    "description": "Prompt for technical blog posts",
    "useCases": [{"title": "Tutorial Creation", "description": "Step-by-step tutorials"}],
    "tags": "writing,technical,blog",
    "is_free": false,
    "price_usd": 4.99,
    "category": "content"
  }'

Update prompt – POST /api/edit-prompt

Same as create plus required id (prompt UUID).

Query prompts – POST /api/query-prompts

Body: search, category, priceFilter, userFilter, sortBy, limit (1–100), offset.
Response: Array of prompt objects.

Using a marketplace prompt with an agent: Set marketplace_prompt_id in agent config (e.g. Swarms API completions); the system fetches the prompt from the marketplace. See https://docs.swarms.ai/docs/marketplace/prompts-api#using-marketplace-prompts-with-agents.

---

3. Token Launch (single) – create agent + token in one call

Endpoint: POST https://swarms.world/api/token/launch
Content-Type: application/json or multipart/form-data (for image file).

Body (JSON):

Parameter	Type	Required	Description
name	string	Yes	Min 2 characters
description	string	Yes	Non-empty
ticker	string	Yes	1–10 chars, letters/numbers only; uppercased
private_key	string	Yes	JSON array, base64, or base58 (64 bytes)
image	string/file	No	URL, base64, or multipart file

Creates a minimal agent listing and mints a token on Solana. Cost ~0.04 SOL (from wallet tied to private_key).

Success (200):

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "listing_url": "https://swarms.world/agent/550e8400-e29b-41d4-a716-446655440000",
  "tokenized": true,
  "token_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "pool_address": "9yZ...configKey"
}

Example (JSON):

curl -X POST https://swarms.world/api/token/launch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Token Agent",
    "description": "Agent launched and tokenized via API.",
    "ticker": "MAG",
    "private_key": "[1,2,3,...]"
  }'

Multipart (image): Use -F "image=@/path/to/icon.png" with other fields as form fields.

---

4. Token Launch Batch – multiple tokens in one request

Endpoint: POST https://swarms.world/api/token/launch/batch
Content-Type: application/json only (no multipart).
Batch size: 1–50 tokens per request. Tokens are processed in parallel.

Body:

Parameter	Type	Required	Description
private_key	string	Conditional	Default key for all tokens; required if any token has no own private_key
tokens	array	Yes	1–50 token items (see below)

Token item:

Field	Type	Required	Description
name	string	Yes	Min 2 characters
description	string	Yes	Non-empty
ticker	string	Yes	1–10 chars, letters/numbers only
private_key	string	No	Override top-level key for this token
image	string	No	URL or base64 (no multipart in batch)

Success – all succeeded (200):

{
  "success": true,
  "total": 2,
  "succeeded": 2,
  "failed": 0,
  "results": [
    {"success": true, "index": 0, "id": "uuid", "listing_url": "https://swarms.world/agent/...", "token_address": "...", "pool_address": "..."},
    {"success": true, "index": 1, "id": "uuid", "listing_url": "...", "token_address": "...", "pool_address": "..."}
  ]
}

Partial success (207): Some items failed. Same structure; success: false, succeeded + failed counts; failed entries in results have success: false, index, error. Optional failures array lists only failed items.

Example – batch launch:

curl -X POST https://swarms.world/api/token/launch/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "private_key": "[1,2,3,...]",
    "tokens": [
      {"name": "Agent One", "description": "First.", "ticker": "ONE"},
      {"name": "Agent Two", "description": "Second.", "ticker": "TWO"}
    ]
  }'

Mixed keys: Set top-level private_key and override per token with private_key on individual items.

---

5. Tokenization details (costs & bonding curve)

• Creation fee: 0.04 SOL per token (~$4 USD equivalent; varies with SOL price). One-time, paid when launching the token.
• Initial market cap: 18 SOL equivalent.
• Graduation market cap: 400 SOL equivalent; after that the token graduates from the virtual pool and is tradeable on DEXs.
• Ticker: 1–10 characters, letters and numbers only; stored uppercase (e.g. AGENT, MYBOT).

Full details: https://docs.swarms.ai/docs/marketplace/tokenization_details

---

6. Claim Fees API

Endpoint: POST https://swarms.world/api/product/claimfees
Auth: No API key; wallet identity via privateKey in body.

Body:

Parameter	Type	Required	Description
ca	string	Yes	Token mint/contract address (32–44 chars)
privateKey	string	Yes	Base58 wallet private key (fee-owner)

Success (200):

{
  "success": true,
  "signature": "5V7x...",
  "amountClaimedSol": 0.42,
  "fees": {
    "unclaimedSol": 0.42,
    "claimedSol": 1.08,
    "totalSol": 1.5
  }
}

---

7. Error responses & status codes

Common error body fields: error, message, details, status_code. Optional: errors (validation), existingId (duplicate), how_to_get_key (401), currentUsage, limits, resetTime (429), token_index (batch/per-token errors), required_sol, current_balance_sol (insufficient SOL).

Code	Meaning
200	Success
207	Multi-Status (batch: partial success; check results)
400	Bad request (validation, invalid key, insufficient SOL, etc.)
401	Unauthorized (missing/invalid API key)
403	Forbidden (content validation failed)
404	Not found
405	Method not allowed
429	Too many requests (rate limit)
500	Internal server error

401 example: Response includes how_to_get_key: "https://swarms.world/platform/api-keys".

---

8. Rate limits

• Paid agents / Paid prompts / Free content: 500 per user per day each; reset at midnight UTC.
• Batch token launch: each token in the batch counts toward the agent creation limit.

429 responses include currentUsage, limits, and resetTime.

---

9. Validation & content rules

• Agents: Duplicate = same name + same agent content for same user → 400 with existingId. Content validation can return trustworthiness, contentQuality.
• Prompts: Duplicate = same content for same user → 400 with existingId.
• Tokenization: When tokenized_on is true (or using token launch), ticker + creator_wallet + private_key required for add-agent/add-prompt; for token launch only private_key (and name, description, ticker) required.
• Private key formats: JSON array of 64 integers, base64, or base58 (e.g. Phantom export).

---

10. Quick reference – endpoints

API	Endpoint	Method	Auth	Purpose
Agents	/api/add-agent	POST	Yes	Create agent
Agents	/api/edit-agent	POST	Yes	Update agent
Agents	/api/query-agents	POST	No	Search/filter agents
Prompts	/api/add-prompt	POST	Yes	Create prompt
Prompts	/api/edit-prompt	POST	Yes	Update prompt
Prompts	/api/query-prompts	POST	No	Search/filter prompts
Token	/api/token/launch	POST	Yes	Single agent + token
Token	/api/token/launch/batch	POST	Yes	Batch agent + token (1–50)
Fees	/api/product/claimfees	POST	No*	Claim SOL fees (*wallet via body)

When in doubt or when you need full request/response schemas, code samples in multiple languages, or edge-case behavior, use the full documentation URLs listed at the top of this skill.