Swarms API Documentation - Build AI Agents & Multi-Agent Systems

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

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)
Ticker
Only uppercase letters and numbers; maximum 10 characters. Stored and returned in uppercase.
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.
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.
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.
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.
Rate limits
Subject to the same daily agent creation limits. See the API Reference for limits and reset behavior.
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.

Platform

Launchpad

API

Examples

Resources

Token Launch API

Request

Headers

Body Parameters

Response

Success (HTTP 200)

HTTP Status Codes

Example Requests

Error Responses

Error response body (4xx / 5xx)

Authentication errors (401)

Validation errors (400)

Rate limit errors (429)

Example error responses

Notes

See also

Platform

Launchpad

API

Examples

Resources

Documentation Index

​Request

​Headers

​Body Parameters

​Response

​Success (HTTP 200)

​HTTP Status Codes

​Example Requests

​Error Responses

​Error response body (4xx / 5xx)

​Authentication errors (401)

​Validation errors (400)

​Rate limit errors (429)

​Example error responses

​Notes

​See also

Request

Headers

Body Parameters

Response

Success (HTTP 200)

HTTP Status Codes

Example Requests

Error Responses

Error response body (4xx / 5xx)

Authentication errors (401)

Validation errors (400)

Rate limit errors (429)

Example error responses

Notes

See also