Skip to main content

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.

POST https://swarms.world/api/token/launch/batch Creates multiple tokenized agents in a single request. Each item in the batch is launched the same way as the single Token Launch endpoint: minimal agent listing plus token creation on Solana via Jupiter. You can use one private key for all tokens (top-level private_key) or a different key per token (or a mix of both). Use cases: Launch many agents from one wallet, or from multiple wallets in one call; bulk tokenization with consistent or per-item metadata. Content type: This endpoint accepts JSON only (application/json). For multipart or file uploads, use the single Token Launch endpoint per token. Batch size: Minimum 1 token, maximum 50 tokens per request. Execution: All tokens are processed in parallel. If some items fail (e.g. downstream Add Agent errors), the response uses HTTP 207 Multi-Status and includes both successes and failures in results.

​
Request

​
Headers

NameTypeRequiredDescription
AuthorizationstringYesBearer token. Use your API key: Bearer YOUR_API_KEY.
Content-TypestringYesMust be application/json.

​
Body Parameters

ParameterTypeRequiredDescription
private_keystringConditionalDefault private key for all tokens. Required if any token does not provide its own private_key.
tokensarrayYesArray of token definitions (1–50 items). See Token item below.
Token item (each element of tokens):
FieldTypeRequiredDescription
namestringYesDisplay name of the agent. Minimum 2 characters.
descriptionstringYesDescription of the agent. Cannot be empty.
tickerstringYesToken symbol (e.g. MAG, SWARM). 1–10 characters; only letters and numbers. Automatically uppercased.
private_keystringNoOverrides the top-level private_key for this token only. Use when different wallets create different tokens.
imagestringNoAgent/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.
Private key rule: Every token must have a private key. Either set private_key at the top level (applies to all tokens that don’t set their own) or set private_key on each token, or mix: some tokens use the default, others override with their own.

​
Code examples by language

The following table lists the same batch launch request implemented in each language. Use the tabs below to view or copy the code.
LanguageDescription
cURLRaw HTTP request with curl.
PythonUsing requests (sync).
TypeScriptUsing fetch (Node or browser).
RustUsing reqwest (blocking).
GoUsing net/http and encoding/json.
curl -X POST https://swarms.world/api/token/launch/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "private_key": "[1,2,3,...]",
    "tokens": [
      { "name": "Agent One", "description": "First.", "ticker": "ONE" },
      { "name": "Agent Two", "description": "Second.", "ticker": "TWO" }
    ]
  }'

​
Response

​
Success – All tokens launched (HTTP 200)

FieldTypeDescription
successbooleantrue when all tokens were launched.
totalnumberTotal number of tokens in the batch.
succeedednumberNumber of tokens that were created successfully.
failednumberNumber of tokens that failed (0 when status is 200).
resultsarrayOne entry per token, in index order. Each success entry has the shape below.
Success result item (each entry in results when that token succeeded):
FieldTypeDescription
successbooleanAlways true.
indexnumberZero-based index of the token in the request tokens array.
idstringUUID of the created agent in the database.
listing_urlstringFull URL to the agent page, e.g. https://swarms.world/agent/{id}.
token_addressstring | nullSolana mint address of the created token.
pool_addressstring | nullJupiter pool/config address for the token, when available.

​
Partial success – Some tokens failed (HTTP 207)

When at least one token fails (e.g. Add Agent returns an error), the response status is 207 Multi-Status. The body has the same structure as above, with:
  • success: false
  • succeeded + failed: counts of successful and failed items
  • results: array of both successful and failed items, sorted by index
  • failures: optional array of only the failed items (for convenience)
Failure result item (entry in results when that token failed):
FieldTypeDescription
successbooleanAlways false.
indexnumberZero-based index of the token in the request tokens array.
errorstringError message (e.g. from Add Agent or tokenization).

​
Error response body (4xx / 5xx)

Request-level errors (validation, invalid key, insufficient SOL, wrong content type, etc.) return a single error object, not a batch result.
FieldTypeDescription
errorstringShort error category (e.g. Validation error, Invalid private key).
messagestringHuman-readable error description.
detailsstring | objectOptional; validation details or other context.
status_codenumberHTTP status code.
token_indexnumberOptional; present for per-token errors (e.g. invalid private key or insufficient SOL) to indicate which token in tokens caused the error.
Authentication errors (401) from the downstream Add Agent call are returned as failed items in results (HTTP 207), not as a single 401 response. The error message in the failed result will indicate authentication failure. Validation errors (400) for the whole request (e.g. missing private key for all tokens, invalid JSON, or validation failure) include:
FieldTypeDescription
detailsobjectOften Zod-style fieldErrors for tokens or top-level fields.
Insufficient SOL (400) includes:
FieldTypeDescription
token_indexnumberIndex of the token whose creator wallet has insufficient SOL.
required_solnumberMinimum required SOL (0.04).
current_balance_solnumberCreator wallet balance at time of check.

​
HTTP Status Codes

CodeMeaning
200All tokens launched successfully.
207Multi-Status: at least one token succeeded and at least one failed. Check results (or failures) for per-item outcome.
400Bad request: invalid JSON, validation failed, invalid private key, insufficient SOL for a token, or unsupported content type (e.g. not application/json). Use token_index when present to identify the failing token.
401Unauthorized: missing or invalid API key. (If Add Agent returns 401 for some items, those appear as failed entries in a 207 response.)
405Method not allowed; only POST is accepted.
429Too many requests; daily agent limit exceeded.
500Internal server error.

​
Examples

​
Minimal request – one private key for all tokens

POST https://swarms.world/api/token/launch/batch
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "private_key": "[1,2,3,...]",
  "tokens": [
    { "name": "Agent One", "description": "First agent.", "ticker": "ONE" },
    { "name": "Agent Two", "description": "Second agent.", "ticker": "TWO" }
  ]
}

​
Response examples by status

Output JSON for each HTTP status. Use the tabs to switch between response types. 
{
  "success": true,
  "total": 2,
  "succeeded": 2,
  "failed": 0,
  "results": [
    {
      "success": true,
      "index": 0,
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "listing_url": "https://swarms.world/agent/550e8400-e29b-41d4-a716-446655440001",
      "token_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "pool_address": "9yZ...configKey"
    },
    {
      "success": true,
      "index": 1,
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "listing_url": "https://swarms.world/agent/550e8400-e29b-41d4-a716-446655440002",
      "token_address": "8yLYtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsV",
      "pool_address": "9zA...configKey"
    }
  ]
}

​
Mixed private keys – default plus overrides

{
  "private_key": "[default-wallet-key]",
  "tokens": [
    { "name": "Agent A", "description": "Uses default key.", "ticker": "AGTA" },
    {
      "name": "Agent B",
      "description": "Uses a different wallet.",
      "ticker": "AGTB",
      "private_key": "[other-wallet-key]"
    }
  ]
}

​
Request with image URL and base64

{
  "private_key": "[1,2,3,...]",
  "tokens": [
    {
      "name": "Agent With URL Image",
      "description": "Image from URL.",
      "ticker": "URLIMG",
      "image": "https://example.com/icon.png"
    },
    {
      "name": "Agent With Base64 Image",
      "description": "Image as base64.",
      "ticker": "B64IMG",
      "image": "data:image/png;base64,iVBORw0KGgo..."
    }
  ]
}

​
Notes

  1. Private key formats
    Same as the single Token Launch API:
    • 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
    Per token: 1–10 characters, letters and numbers only. Stored and returned in uppercase.
  3. Image
    • URL: https://... or http://... is used as-is.
    • Base64: data:image/...;base64,... or raw base64 is uploaded to Supabase Storage; the resulting URL is sent to Jupiter.
    • Batch endpoint does not support multipart file upload; use the single Token Launch endpoint for file uploads.
  4. Authentication
    Same API key as the rest of the Swarms Platform API. Create and manage keys at https://swarms.world/platform/api-keys. If Add Agent returns 401 for some items, those appear as failed entries in a 207 response with an authentication-related error message.
  5. Rate limits
    Subject to the same daily agent creation limits as Add Agent. Each token in the batch counts toward your limit. See the API Reference for limits and reset behavior.
  6. Batch size
    Minimum 1, maximum 50 tokens per request. For larger batches, send multiple requests.
  7. Order and indexing
    results are sorted by index (the position in the request tokens array). Use index to correlate successes and failures with your input.
  8. Pre-validation and early exit
    Before launching any token, the endpoint validates all private keys and (when RPC is available) checks SOL balance for each creator wallet. If any of these checks fail, the entire request returns 400 with token_index so you can fix that item and retry.
  9. Downstream behavior
    Each token is created via the same Add Agent flow as the single Token Launch endpoint (placeholder agent, default metadata, tokenized_on: true). Failures (e.g. duplicate agent, tokenization error) are reported per item in results with HTTP 207.

​
See also

  • Token Launch (single) – Create one token per request; supports JSON and multipart.
  • Agents API – Full agent creation API used internally by both launch endpoints.
  • API Reference – Overview, authentication, and other endpoints.