> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:**

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL (minimal) theme={null}
  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,...]"
    }'
  ```

  ```bash cURL (frenzy + USDC) theme={null}
  curl -X POST https://swarms.world/api/token/launch \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "My Frenzy Agent",
      "description": "Launched in frenzy mode with a USDC-denominated bonding curve.",
      "ticker": "FRNZ",
      "private_key": "[1,2,3,...]",
      "fee_selection": "frenzy",
      "quote_mint": "USDC"
    }'
  ```

  ```python Python theme={null}
  import requests

  BASE_URL = "https://swarms.world"
  API_KEY = "YOUR_API_KEY"

  payload = {
      "name": "My Token Agent",
      "description": "An agent launched and tokenized via the Token Launch API.",
      "ticker": "MAG",
      "private_key": "[1,2,3,...]",
      # Optional fields:
      # "image": "https://example.com/agent-icon.png",
      # "fee_selection": "frenzy",   # "frenzy" | "market" (default)
      # "quote_mint": "USDC",        # "SOL" (default) | "USDC"
  }

  response = requests.post(
      f"{BASE_URL}/api/token/launch",
      headers={
          "Authorization": f"Bearer {API_KEY}",
          "Content-Type": "application/json",
      },
      json=payload,
  )
  data = response.json()
  if response.ok:
      print("Success:", data.get("listing_url"), "Token:", data.get("token_address"))
  else:
      print("Error:", data.get("message", data.get("error")))
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://swarms.world/api/token/launch", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_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: "[1,2,3,...]",
      // fee_selection: "frenzy",  // "frenzy" | "market" (default)
      // quote_mint: "USDC",       // "SOL" (default) | "USDC"
    }),
  });
  const data = await response.json();
  if (response.ok) {
    console.log("Success:", data.listing_url, "Token:", data.token_address);
  } else {
    console.error("Error:", data.message || data.error);
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"bytes"
  	"encoding/json"
  	"net/http"
  )

  const baseURL = "https://swarms.world"
  const apiKey = "YOUR_API_KEY"

  func main() {
  	payload := map[string]string{
  		"name":          "My Token Agent",
  		"description":   "An agent launched and tokenized via the Token Launch API.",
  		"ticker":        "MAG",
  		"private_key":   "[1,2,3,...]",
  		// "fee_selection": "frenzy",
  		// "quote_mint":    "USDC",
  	}
  	body, _ := json.Marshal(payload)
  	req, _ := http.NewRequest("POST", baseURL+"/api/token/launch", bytes.NewBuffer(body))
  	req.Header.Set("Authorization", "Bearer "+apiKey)
  	req.Header.Set("Content-Type", "application/json")
  	client := &http.Client{}
  	resp, _ := client.Do(req)
  	defer resp.Body.Close()
  	// decode resp.Body for id, listing_url, token_address
  }
  ```

  ```rust Rust theme={null}
  // Add reqwest and serde_json to Cargo.toml
  use reqwest::blocking::Client;
  use serde_json::json;

  fn main() -> Result<(), Box<dyn std::error::Error>> {
      let client = Client::new();
      let payload = json!({
          "name": "My Token Agent",
          "description": "An agent launched and tokenized via the Token Launch API.",
          "ticker": "MAG",
          "private_key": "[1,2,3,...]",
          // "fee_selection": "frenzy",
          // "quote_mint": "USDC"
      });
      let res = client
          .post("https://swarms.world/api/token/launch")
          .header("Authorization", "Bearer YOUR_API_KEY")
          .json(&payload)
          .send()?;
      let data: serde_json::Value = res.json()?;
      if res.status().is_success() {
          println!("Success: {} Token: {}", data["listing_url"], data["token_address"]);
      } else {
          println!("Error: {}", data["message"].as_str().unwrap_or("Unknown"));
      }
      Ok(())
  }
  ```
</CodeGroup>

**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):**

```json theme={null}
{
  "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):

```json theme={null}
{
  "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.

```json theme={null}
{
  "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):**

```json theme={null}
{
  "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](https://swarms.world/platform/api-keys).

7. **Rate limits**\
   Subject to the same daily agent creation limits. See the [API Reference](https://docs.swarms.ai/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](/docs/marketplace/token-launch-frenzy-example) – Complete walkthrough for launching a tokenized frenzy agent with 2× fees.
* [Token Launch Batch API](/docs/marketplace/token-launch-batch-api) – Create multiple tokenized agents in a single request (1–50 tokens per call).
* [API Reference](https://docs.swarms.ai/api-reference) – Overview, authentication, and other endpoints.