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. 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: You can pass an image URL, send a raw file (multipart), or base64 data. Raw images are stored and used for token metadata; omit for no image.

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: used as-is. Base64 (data URL or raw): stored and used for token metadata. Omit for no image.

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). Stored and used for token metadata. Omit for no image.

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

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
}

Tokenization failed (400):

{
  "error": "Tokenization failed",
  "message": "Failed to create token",
  "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
Send image as a URL, a raw file in multipart/form-data, or base64 in the JSON body. Image is optional; the token can be created without one.
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

Resources

Token Launch API

Request

Headers

Body Parameters

Response

Success (HTTP 200)

HTTP Status Codes

Example Request

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

Resources

​Request

​Headers

​Body Parameters

​Response

​Success (HTTP 200)

​HTTP Status Codes

​Example Request

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

Error Responses

Error response body (4xx / 5xx)

Authentication errors (401)

Validation errors (400)

Rate limit errors (429)

Example error responses

Notes

See also