---

name: swarms-token-launch description: Use this skill whenever the user wants to launch a token on Solana via the Swarms platform, create a tokenized AI agent listing, interact with the Swarms Token Launch API, or build code that calls https://swarms.world/api/token/launch. Trigger this skill any time the user mentions "Swarms token", "launch token", "tokenize agent", "Swarms API", Solana agent tokens, or asks to write a script/app that mints a token through the Swarms marketplace. Also use when the user asks about the Token Launch Batch API or needs to handle Swarms API authentication, error handling, or private key formats for token creation.

Swarms Token Launch API

A guide for creating tokenized AI agent listings on the Swarms platform and launching associated Solana tokens via the Token Launch API.

---

Overview

Endpoint: POST https://swarms.world/api/token/launch

Creates a minimal agent listing on swarms.world and launches a paired Solana token in a single request. Token creation costs ~0.04 SOL (deducted from the wallet tied to the provided private key).

---

Required Inputs

Parameter	Type	Notes
name	string	Display name; minimum 2 characters
description	string	Cannot be empty
ticker	string	Token symbol (e.g. SWARM); 1–10 alphanumeric chars, auto-uppercased
private_key	string	Solana wallet private key — see Private Key Formats below

Optional:

• image — URL, base64 data URL, or raw file (multipart). Used for agent profile and token metadata.

---

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Obtain and manage keys at: https://swarms.world/platform/api-keys

---

Private Key Formats

The private_key field accepts three formats:

1. JSON array — 64 integers: [1,2,3,...,64]
2. Base64 — 64-byte key encoded as base64
3. Base58 — 64-byte key encoded as base58 (standard Phantom export format)

⚠️ Never commit private keys to source control. Use environment variables.

---

Request Examples

JSON (cURL)

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": "An agent launched and tokenized via the Token Launch API.",
    "ticker": "MAG",
    "private_key": "[1,2,3,...]"
  }'

Python

import requests, os

response = requests.post(
    "https://swarms.world/api/token/launch",
    headers={
        "Authorization": f"Bearer {os.environ['SWARMS_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "name": "My Token Agent",
        "description": "An agent launched and tokenized via the Token Launch API.",
        "ticker": "MAG",
        "private_key": os.environ["WALLET_PRIVATE_KEY"],
        # "image": "https://example.com/icon.png",  # optional
    },
)
data = response.json()
if response.ok:
    print("Agent:", data["listing_url"])
    print("Token:", data["token_address"])
else:
    print("Error:", data.get("message") or data.get("error"))

TypeScript / JavaScript

const res = await fetch("https://swarms.world/api/token/launch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SWARMS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "My Token Agent",
    description: "An agent launched and tokenized via the Token Launch API.",
    ticker: "MAG",
    private_key: process.env.WALLET_PRIVATE_KEY,
  }),
});
const data = await res.json();
if (res.ok) {
  console.log("Listing:", data.listing_url, "| Token:", data.token_address);
} else {
  console.error("Error:", data.message || data.error);
}

Multipart (with raw image file)

curl -X POST https://swarms.world/api/token/launch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "name=My Token Agent" \
  -F "description=An agent with a custom image." \
  -F "ticker=MAG" \
  -F "private_key=[1,2,3,...]" \
  -F "image=@/path/to/agent-icon.png"

Python multipart equivalent:

with open("agent-icon.png", "rb") as img:
    requests.post(url, headers=auth_header, data={...fields...}, files={"image": img})

---

Success Response (HTTP 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"
}

Field	Description
id	UUID of the created agent in the DB
listing_url	Public URL for the agent page
token_address	Solana mint address of the created token
pool_address	Pool/config address (when available)

---

Error Handling

All errors share this shape:

{
  "error": "Short error category",
  "message": "Human-readable description",
  "details": "...",
  "status_code": 400
}

Status Codes & Causes

Code	Cause
400	Validation failure, invalid private key, or tokenization failure
401	Missing or invalid API key
405	Wrong HTTP method (only POST accepted)
429	Daily agent creation limit exceeded
500	Internal/database/tokenization error

401 — Authentication failed

{
  "error": "Authentication failed",
  "message": "Invalid or missing API key. Please check your API key and try again.",
  "how_to_get_key": "https://swarms.world/platform/api-keys",
  "status_code": 401
}

400 — Validation error

{
  "error": "Validation error",
  "message": "Request validation failed",
  "details": {
    "fieldErrors": {
      "ticker": ["Ticker must contain only letters and numbers"],
      "name": ["Name must be at least 2 characters"]
    }
  },
  "status_code": 400
}

429 — Rate limit exceeded

Response includes currentUsage, limits, and resetTime (UTC timestamp).

Robust error handling pattern (Python)

def launch_token(name, description, ticker, private_key, image_url=None):
    payload = {"name": name, "description": description,
               "ticker": ticker, "private_key": private_key}
    if image_url:
        payload["image"] = image_url

    try:
        res = requests.post(
            "https://swarms.world/api/token/launch",
            headers={"Authorization": f"Bearer {os.environ['SWARMS_API_KEY']}",
                     "Content-Type": "application/json"},
            json=payload,
            timeout=30,
        )
        data = res.json()
    except requests.RequestException as e:
        raise RuntimeError(f"Network error: {e}")

    if res.status_code == 401:
        raise PermissionError(f"Auth failed. Get a key at: {data.get('how_to_get_key')}")
    if res.status_code == 429:
        raise RuntimeError(f"Rate limit hit. Resets at: {data.get('resetTime')}")
    if not res.ok:
        raise RuntimeError(f"[{res.status_code}] {data.get('message') or data.get('error')}")

    return data  # {"listing_url": ..., "token_address": ...}

---

Key Notes for Code Generation

1. Content-Type — Use application/json for JSON body requests; multipart/form-data for raw file uploads. Do not mix them.
2. Ticker validation — Uppercase letters and numbers only, max 10 chars. API auto-uppercases but rejects special chars.
3. SOL balance — The wallet must hold at least ~0.04 SOL before calling this endpoint.
4. No agent code required — The endpoint creates a placeholder agent listing automatically; you only need the five parameters above.
5. Batch creation — For 1–50 tokens in one call, use the Token Launch Batch API.
6. Environment variables — Always store private_key and API key in environment variables, never hardcoded.

---

See Also

• Batch endpoint: POST https://swarms.world/api/token/launch-batch — up to 50 tokens per call
• Full API reference: https://docs.swarms.ai/api-reference
• API key management: https://swarms.world/platform/api-keys