> For the complete documentation index, see [llms.txt](https://stonkfun.gitbook.io/stonkfun-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stonkfun.gitbook.io/stonkfun-docs/developer-api/launch-endpoints.md).

# Launch endpoints

Two calls. `/launches/prepare` returns an unsigned payment transaction, you sign it with the creator's wallet, and you hand it to `/launches/submit`.

***

## `POST /launches/prepare`

Validates the token and returns a signed quote plus an unsigned SOL payment transaction for the creator to sign.

Rate limit: 25 per minute, per IP.

### Required body

| Parameter       | Type     | Description                                            |
| --------------- | -------- | ------------------------------------------------------ |
| `creatorWallet` | string   | Wallet that will own and pay for the launch            |
| `quoteMint`     | string   | Pair to launch against, from `GET /pairs`              |
| `name`          | string   | 1 to 32 bytes                                          |
| `symbol`        | string   | 1 to 10 bytes                                          |
| `logo`          | data URL | `data:image/(png\|jpeg\|webp);base64,...` up to 512 KB |

### Fee model

| Parameter      | Type                     | Description                                                    |
| -------------- | ------------------------ | -------------------------------------------------------------- |
| `mode`         | `'standard' \| 'reward'` | Defaults to `standard`                                         |
| `feeTier`      | `'1%' \| '2%'`           | Standard only. Defaults to `1%`. Rejected on reward launches.  |
| `rewardTaxBps` | `100 \| 300`             | Reward only. Defaults to `100`. Rejected on standard launches. |

`mode: 'standard'` is a fee coin. `feeTier: '1%'` splits fees 50/50, so 0.5% of every trade goes to the creator and 0.5% to the platform. `feeTier: '2%'` routes 1.5% of every trade to the creator while the platform still keeps 0.5%, with the higher creator cut coming out of the trader's fee. The response echoes the result as `poolFeePercent`.

`mode: 'reward'` is a reward coin: a Token-2022 mint carrying an immutable transfer tax paid to holders on every transfer, trading on a 1% pool. The response carries the rate in `transferFee.bps`. Use the Token-2022 program for that token's accounts, and expect a dev buy to deliver `devBuy.netTokens` rather than `devBuy.tokens`.

`rewardTaxBps` is either `100` (1%, which keeps total trading friction at 2% alongside the 1% pool) or `300` (3%, which triples the holder reward stream). The choice is signed into the quote and cannot be changed once the mint exists.

{% hint style="warning" %}
While reward launches are restricted to admins, `mode: 'reward'` additionally requires the admin password header and answers `403` without it.
{% endhint %}

### Metadata links

| Parameter  | Type   | Description                                                                     |
| ---------- | ------ | ------------------------------------------------------------------------------- |
| `website`  | string | Optional. Must be a public HTTPS URL. Omit it and the launch links to StonkFun. |
| `twitter`  | string | Optional social link                                                            |
| `telegram` | string | Optional social link                                                            |

These are saved in the token's permanent metadata.

### Dev buy

{% hint style="info" %}
Available only while atomic bundling is. When it is not, both parameters answer `503` and are omitted from the OpenAPI spec.
{% endhint %}

| Parameter       | Type   | Description                                              |
| --------------- | ------ | -------------------------------------------------------- |
| `devBuyPercent` | number | Share of supply, max 2.5                                 |
| `devBuySol`     | number | A SOL amount; the supply share it buys is capped at 2.5% |

Mutually exclusive. Executed as the pool's first trade, bundled with the liquidity that makes the pool tradeable at all, so there is no block in which anyone else could trade ahead of it.

The SOL cost, being the curve price plus the pool's trading fee, is added to `payment.lamports`, and the fill is transferred to `creatorWallet` once the pool is live.

Token amounts are targets. A real swap fills within a small tolerance, and on a reward launch what arrives is net of the transfer tax.

### Airdrop mode

{% hint style="info" %}
Available only where the platform currently offers airdrops.
{% endhint %}

| Parameter        | Type                                 | Description                                                         |
| ---------------- | ------------------------------------ | ------------------------------------------------------------------- |
| `airdropPercent` | number                               | Reward launches only. Share of supply held out of the pool, max 50. |
| `airdropTier`    | `'top100' \| 'top1000' \| 'top5000'` | Defaults to `top100`                                                |
| `airdropSource`  | `'quote-holders'`                    | Defaults to `quote-holders`, the only source currently accepted     |

The recipient set is snapshotted and frozen at this call, then sealed into the signed quote, so the drop is fixed before your mint is public and cannot be gamed by anyone buying the quote token afterwards.

Exchange, custody and treasury wallets, and any account owned by a program, are removed from the ranking and backfilled by the next holder down, so you still receive the full tier.

A tier is refused if the quote token has fewer eligible holders than it names, rather than quietly delivering a smaller drop than you paid for.

The response carries an `airdrop` object with the recipient count and the extra fee, already included in `payment.lamports`.

### Response

| Field                | Meaning                                                           |
| -------------------- | ----------------------------------------------------------------- |
| `signedQuote`        | Pass this to `/submit`                                            |
| `paymentTransaction` | Base64, unsigned. Sign this.                                      |
| `payment.lamports`   | Total SOL, including dev buy and airdrop fees                     |
| `devBuy`             | Target tokens, exact lamports, and `netTokens` on reward launches |
| `airdrop`            | Recipient count and the extra fee                                 |
| `transferFee.bps`    | The transfer tax, on reward launches                              |
| `poolFeePercent`     | The resolved pool fee tier                                        |

***

## `POST /launches/submit`

Submits the signed payment and creates the token, all or nothing.

Rate limit: 300 per minute, per IP, since this endpoint is already bound to a real payment.

| Parameter           | Type     | Required | Description                                                     |
| ------------------- | -------- | -------- | --------------------------------------------------------------- |
| `signedQuote`       | string   | Yes      | From `/prepare`                                                 |
| `signedTransaction` | base64   | Yes      | The `paymentTransaction` from `/prepare`, signed by the creator |
| `logo`              | data URL | Yes      | The identical logo sent to `/prepare`                           |

The payment, mint, pool, liquidity and any dev buy are submitted as one atomic bundle, so they land together in a single block or not at all.

| Status                                      | Meaning                                                         |
| ------------------------------------------- | --------------------------------------------------------------- |
| `completed`                                 | Done                                                            |
| `processing`                                | On chain, details recording. Poll status. **Never pay twice.**  |
| `service_unavailable` with `charged: false` | Bundle did not land. Nothing charged. Retry with a fresh quote. |

***

## `GET /launches/{paymentSignature}`

Poll this after a `processing` response until `status` is `completed`.

| Parameter          | In   | Required | Description                  |
| ------------------ | ---- | -------- | ---------------------------- |
| `paymentSignature` | path | Yes      | Signature of the fee payment |

***

## Complete example

```js
import { Connection, Keypair, Transaction } from '@solana/web3.js';
import fs from 'node:fs';

const API = 'https://www.stonkfun.xyz/api/public/v1';
const creator = Keypair.fromSecretKey(            // your own wallet, never sent anywhere
  Uint8Array.from(JSON.parse(fs.readFileSync('creator.json', 'utf8')))
);

const headers = { 'Content-Type': 'application/json' };   // no key, nothing to sign up for
const call = async (path, init) => {
  const response = await fetch(API + path, init);
  const body = await response.json();
  if (!response.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  return body.data;
};

// 1. Pick a pair to launch against.
const { pairs } = await call('/pairs?launchable=true');
const pair = pairs.find((item) => item.symbol === 'NVDAx') ?? pairs[0];

// 2. Prepare. Returns an UNSIGNED payment transaction.
const logo = 'data:image/png;base64,' + fs.readFileSync('logo.png').toString('base64');
const prepared = await call('/launches/prepare', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    creatorWallet: creator.publicKey.toBase58(),
    quoteMint: pair.mint,
    name: 'My Token',
    symbol: 'MYTKN',
    mode: 'standard',          // 'standard' splits trading fees with you
    // feeTier: '2%',          // optional: 2% pool, you earn 1.5% per trade instead of 0.5%
    devBuyPercent: 1,          // optional dev buy: up to 2.5% of supply, paid in SOL
    logo,                      // with the fee, or pass devBuySol instead
  }),
});
// prepared.devBuy echoes the exact tokens you receive and the SOL it adds to the payment.

// 3. Sign the fee payment locally. Your key never leaves this process.
const tx = Transaction.from(Buffer.from(prepared.paymentTransaction, 'base64'));
tx.sign(creator);

// 4. Submit. Usually returns a finished token in this one call.
let result = await call('/launches/submit', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    signedQuote: prepared.signedQuote,
    signedTransaction: tx.serialize().toString('base64'),
    logo,                      // must be byte-identical to step 2
  }),
});

// 5. 'processing' means the launch is ON CHAIN and details are recording. NEVER pay again.
//    A failed bundle instead returns service_unavailable with charged: false. Nothing was
//    charged; get a fresh quote from /prepare and submit again.
while (result.status === 'processing') {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  result = await call(`/launches/${result.paymentSignature}`);
}

console.log('Live:', result.mint);
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://stonkfun.gitbook.io/stonkfun-docs/developer-api/launch-endpoints.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.