Token Launch API

Create a minimal agent listing and launch an associated token on Solana in a single request

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

Creates a minimal agent listing and launches an associated token on Solana (via Jupiter). Only name, description, ticker, private key, and optional image are required. The agent is created with placeholder code and default metadata; the token is created and linked in a single request. Token creation costs approximately 0.04 SOL (paid from the wallet associated with the private key).

Image flow: If you send a raw image (file or base64), the endpoint uploads it to Supabase Storage first, then sends the resulting Supabase URL to Jupiter for token metadata. You can also pass an existing image URL.

---

Request

Headers

Name	Type	Required	Description
Authorization	string	Yes	Bearer token. Use your API key: Bearer YOUR_API_KEY.
Content-Type	string	Yes	Either application/json (for JSON body) or multipart/form-data (for raw file upload).

Body Parameters

You can send the request in two ways:

Option A — JSON (Content-Type: application/json)

Parameter	Type	Required	Default	Description
name	string	Yes	—	Display name of the agent. Minimum 2 characters.
description	string	Yes	—	Description of the agent. Cannot be empty.
ticker	string	Yes	—	Token symbol (e.g. MAG, SWARM). 1–10 characters; only letters and numbers. Automatically uppercased.
private_key	string	Yes	—	Wallet private key used to sign the token-creation transaction. Accepted formats: JSON array of 64 bytes, base64 string, or base58 string. Must correspond to the creator wallet.
image	string	No	—	Agent/token image. URL (https://... or http://...): used as-is. Base64 (data URL or raw): uploaded to Supabase Storage, then the Supabase URL is sent to Jupiter. Omit for no image.
fee_selection	string	No	"market"	Fee tier for the bonding curve. "frenzy" uses a 2× fee multiplier (higher fees, more visibility on the Frenzy leaderboard). "market" uses the standard fee.
quote_mint	string	No	"SOL"	Quote currency for the bonding curve. "SOL" (default) or "USDC". Determines the denomination of the initial and migration market caps.

Option B — Multipart (Content-Type: multipart/form-data)

Field	Type	Required	Description
name	string	Yes	Same as above.
description	string	Yes	Same as above.
ticker	string	Yes	Same as above.
private_key	string	Yes	Same as above.
image	file	No	Raw image file (e.g. PNG, JPEG, WebP, GIF). Uploaded to Supabase Storage, then the Supabase URL is sent to Jupiter. Omit for no image.
fee_selection	string	No	Same as JSON option above.
quote_mint	string	No	Same as JSON option above.

---

Response

Success (HTTP 200)

Field	Type	Description
success	boolean	Always true on success.
id	string	UUID of the created agent in the database.
listing_url	string	Full URL to the agent page, e.g. https://swarms.world/agent/{id}.
tokenized	boolean	Always true for this endpoint.
token_address	string | null	Solana mint address of the created token.
pool_address	string | null	Pool or config address for the token, when available.

Example success response:

{
  "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"
}

HTTP Status Codes

Code	Meaning
200	Success; agent created and token launched.
400	Bad request: validation failed (body params), invalid private key, insufficient SOL balance (creator wallet must have ≥ 0.04 SOL), tokenization failed, or content validation failed.
401	Unauthorized: missing or invalid API key. Response includes a user-friendly message and how_to_get_key pointing to https://swarms.world/platform/api-keys.
405	Method not allowed; only POST is accepted.
429	Too many requests; daily agent limit exceeded.
500	Internal server error, tokenization error, or database error.

Example Requests

cURL (minimal)

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,...]"
  }'

Multipart (raw image file): Use -F for each field and -F "image=@/path/to/agent-icon.png" with cURL; with Python use requests.post(..., files={"image": open("agent-icon.png", "rb")}, data={...}).

---

Error Responses

All error responses share a common shape. Additional fields may be present depending on the error type.

Error response body (4xx / 5xx)

Field	Type	Description
error	string	Short error category (e.g. Validation error, Authentication required).
message	string	Human-readable error description.
details	string | object	Extra context; may be a string or a structured object (e.g. validation errors).
status_code	number	HTTP status code (same as the response status).

Authentication errors (401)

Field	Type	Description
how_to_get_key	string	Canonical link to create or manage your API key: https://swarms.world/platform/api-keys. Use this URL (not the request host) so the link is correct when calling from any environment.

Validation errors (400)

Field	Type	Description
errors	array	Zod-style validation errors (e.g. path and message per field).

Rate limit errors (429)

Field	Type	Description
currentUsage	number	Current usage count for the limit.
limits	object	Applied rate limit configuration.
resetTime	string	When the limit resets (e.g. UTC timestamp).

Example error responses

Validation error (400):

{
  "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
}

Authentication failed (401):

When the API key is missing or invalid, the response is normalized so you always get a clear message and the canonical API-keys link (not the request host):

{
  "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
}

Insufficient SOL balance (400):

Returned when the creator wallet (derived from private_key) has less than 0.04 SOL. Token launch requires enough SOL for transaction fees and rent.

{
  "error": "Insufficient SOL balance",
  "message": "Token launch requires at least 0.04 SOL in the creator wallet. Your balance is 0.0029 SOL. Please add SOL and try again.",
  "required_sol": 0.04,
  "current_balance_sol": 0.0029,
  "status_code": 400
}

Tokenization failed (400):

{
  "error": "Tokenization failed",
  "message": "Failed to create token on Jupiter",
  "details": "The token creation process failed. Please verify your wallet credentials and try again.",
  "status_code": 400
}

---

Notes

1. Private key formats
   private_key is accepted as:

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

2. Ticker
   Only uppercase letters and numbers; maximum 10 characters. Stored and returned in uppercase.

3. Image (raw upload → Supabase → Jupiter)

   • Raw file (multipart): Send image as a file in multipart/form-data. The endpoint uploads it to Supabase Storage, then sends the Supabase URL to Jupiter.
   • Base64 (JSON): Send image as a data:image/...;base64,... string or raw base64 in the JSON body. The endpoint uploads it to Supabase Storage, then sends the Supabase URL to Jupiter.
   • URL: Any publicly fetchable URL (e.g. an existing Supabase URL). Used as-is for Jupiter token metadata; no Supabase upload is performed.
     Image is optional; the token can be created without one.

4. Frenzy mode (fee_selection: "frenzy")
   Frenzy mode routes the token through a 2× fee Jupiter API key, doubling the bonding curve fees. Tokens launched with fee_selection: "frenzy" appear on the Frenzy leaderboard for increased visibility. Omit this field or set it to "market" for standard fees.

5. Quote mint (quote_mint)
   Controls the denomination of the bonding curve:

   • "SOL" (default): SOL-quoted pool. Market cap defaults are initialMarketCap: 18 SOL, migrationMarketCap: 400 SOL.
   • "USDC": USDC-quoted pool. Market cap defaults are initialMarketCap: 4000 USDC, migrationMarketCap: 9000 USDC.
     On-chain mint addresses: SOL = So11111111111111111111111111111111111111112, USDC = EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v.

6. Authentication
   Uses the same API key as the rest of the Swarms Platform API. Create and manage keys at https://swarms.world/platform/api-keys.

7. Rate limits
   Subject to the same daily agent creation limits. See the API Reference for limits and reset behavior.

8. Error handling
   Some errors are normalized for a better client experience:

   • 401 (missing or invalid API key): The response body is always error: "Authentication failed", message: "Invalid or missing API key. Please check your API key and try again.", and how_to_get_key: "https://swarms.world/platform/api-keys" (canonical link; never localhost or another host).
   • Other errors (validation, tokenization, rate limit) are forwarded with the same status code and body shape.

---

See also

• Frenzy Launch Example – Complete walkthrough for launching a tokenized frenzy agent with 2× fees.
• Token Launch Batch API – Create multiple tokenized agents in a single request (1–50 tokens per call).
• API Reference – Overview, authentication, and other endpoints.