Token Launcher

API Reference: https://api.play.fun/api-reference

Authentication

Token launcher endpoints require user authentication via Privy. The user must have an embedded Solana wallet with delegation enabled and sufficient SOL balance.

---

Launch Endpoints

Launch a Playcoin

POST /token-launcher/launch 🔒

Queue a playcoin launch for a game. The launch executes asynchronously — use the returned jobId to poll for status.

Headers:

Content-Type: application/json
Authorization: Bearer <privy-auth-token>

Request Body:

{
  "gameId": "550e8400-e29b-41d4-a716-446655440000",
  "emissionDays": 30,
  "buyAmount": "100000000",
  "gameCoinSymbol": "AWESOME"
}

Body Parameters:

Parameter	Type	Required	Description
gameId	string (UUID)	Yes	The game to launch a playcoin for
emissionDays	number	Yes	Emission schedule duration. Must be 7 or 30
buyAmount	string	No	Initial buy amount in lamports (1 SOL = 1,000,000,000 lamports). Buys tokens at launch price on the bonding curve
gameCoinSymbol	string | null	No	Custom ticker symbol for the playcoin. If not provided, one is generated from the game name

Response (200 — launch queued):

{
  "jobId": "token-launch-550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "Token launch started. Poll /token-launcher/launch/:jobId for status."
}

Response (200 — launch already in progress):

{
  "jobId": "token-launch-550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "Token launch already in progress. Poll /token-launcher/launch/:jobId for status."
}

Error Responses:

Status	Condition	Example Message
400	Invalid emissionDays value	"Invalid emissionDays value. Allowed values are: 7, 30"
400	Game already has an active playcoin	"Game already has an active gamecoin (TokenMint...). Please wait until the current gamecoin emissions are complete before launching another."
400	Insufficient SOL balance	"Insufficient SOL balance in embedded wallet to cover transaction fees and buy amount. Please ensure at least 0.07 SOL is available."
403	Launch restricted to game owner during grace period	"Only the creator or owner (if ownership is validated) of the game can launch tokens within this period."
404	Game not found	"Game with ID ... not found"

JavaScript Example:

async function launchPlaycoin(gameId, emissionDays, buyAmountSol = 0) {
  const buyAmountLamports =
    buyAmountSol > 0 ? (buyAmountSol * 1_000_000_000).toString() : undefined;

  const response = await fetch('https://api.play.fun/token-launcher/launch', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${privyAuthToken}`,
    },
    body: JSON.stringify({
      gameId,
      emissionDays,
      buyAmount: buyAmountLamports,
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }

  const { jobId } = await response.json();

  // Poll for completion
  return await pollLaunchStatus(jobId);
}

Notes:

• The launch requires approximately 0.07 SOL for transaction fees, plus any buyAmount

• Only one playcoin can be active per game at a time

• After a playcoin's emission ends, the game creator/owner gets a 48-hour grace period before external launchers can launch the next one

• The gameCoinSymbol must be unique if provided

---

Get Launch Status

GET /token-launcher/launch/{jobId}

Poll the status of an in-progress playcoin launch.

Path Parameters:

• jobId (required) — The job ID returned from the launch endpoint

Response (completed):

{
  "status": "completed",
  "progress": 100,
  "bundleTx": "5K8s7...transaction-signature",
  "gtokenAddress": "TokenMint123...",
  "message": "Launch completed successfully"
}

Response (in progress):

{
  "status": "active",
  "progress": 50,
  "message": "Job is still processing"
}

Response (failed):

{
  "status": "failed",
  "progress": 80,
  "error": "Launch completed but gamecoin address is missing"
}

Response Fields:

Field	Type	Description
status	string	Job state: "completed", "active", "waiting", "failed"
progress	number	Progress percentage (0–100)
bundleTx	string	Solana transaction signature (only on completion)
gtokenAddress	string	The minted playcoin token address (only on completion)
message	string	Human-readable status message
error	string	Error description (only on failure)

JavaScript Example:

async function pollLaunchStatus(jobId, intervalMs = 3000, maxAttempts = 60) {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(`https://api.play.fun/token-launcher/launch/${jobId}`);

    if (!response.ok) {
      throw new Error(`Status check failed: ${response.status}`);
    }

    const result = await response.json();

    if (result.status === 'completed') {
      console.log(`Playcoin launched: ${result.gtokenAddress}`);
      console.log(`Transaction: ${result.bundleTx}`);
      return result;
    }

    if (result.status === 'failed') {
      throw new Error(`Launch failed: ${result.error}`);
    }

    console.log(`Progress: ${result.progress}%`);
    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }

  throw new Error('Launch timed out');
}

Notes:

• Poll every 2–5 seconds

• A typical launch completes in ~30 seconds

• The progress field updates during the launch process (10% → 50% → 80% → 100%)

---

Complete Launch

POST /token-launcher/complete-launch

Finalize a launch by verifying on-chain state and creating the token record. This is called automatically by the launch job but can be retried manually if needed.

Request Body:

{
  "gtokenAddress": "TokenMint123..."
}

Body Parameters:

Parameter	Type	Required	Description
gtokenAddress	string	Yes	The Solana token mint address of the launched playcoin

Response (success):

{
  "success": true,
  "message": "Launch completed successfully"
}

Response (already completed):

{
  "success": true,
  "message": "GToken already created (another finalization won the race)"
}

Response (failure):

{
  "success": false,
  "message": "No verified launch attempts found. Stale attempts have been cleaned up."
}

---

Snapshot Endpoints

These endpoints support airdrop functionality for playcoins launched with an airdropTokenAddress configured on the game.

Get Snapshot Summary

GET /token-launcher/snapshot/{tokenMint}

Get the merkle snapshot summary for a token, including the merkle root and holder count.

Path Parameters:

• tokenMint (required) — The token mint address used for the airdrop snapshot

Response (success):

{
  "merkleRoot": "0xabc123...",
  "totalHolders": 1500,
  "totalAllocation": "500000000000000000"
}

Response (not found):

{
  "error": "Snapshot not found"
}

---

Get User Merkle Proof

GET /token-launcher/snapshot/{tokenMint}/proof/{userAddress}

Get a specific user's merkle proof for claiming their airdrop allocation.

Path Parameters:

• tokenMint (required) — The token mint address

• userAddress (required) — The user's Solana wallet address

Response (success):

{
  "proof": ["0xabc...", "0xdef...", "0x123..."],
  "amount": "1500000000000",
  "index": 42
}

Response (not found):

{
  "error": "Proof not found for user"
}

---

Get Snapshot Holders

GET /token-launcher/snapshot/{tokenMint}/holders

Get the full list of holders included in a snapshot.

Path Parameters:

• tokenMint (required) — The token mint address

Response (success):

{
  "holders": [
    {
      "address": "9qdvVLY3vLhmvV7uBkLJsQKcHDjxhoUWJ9uZASYEfwwC",
      "amount": "1500000000000"
    }
  ],
  "count": 1500
}

Response (not found):

{
  "error": "Snapshot not found"
}

---

Exercise Claim Endpoints

These endpoints allow holders of a game's airdrop token to claim their playcoin allocation.

Build Exercise Claim Transactions

POST /token-launcher/exercise-claim/build-transactions

Build the Solana transactions needed for a user to claim their airdrop allocation.

Request Body:

{
  "gtokenAddress": "PlaycoinMint123...",
  "participant": "9qdvVLY3vLhmvV7uBkLJsQKcHDjxhoUWJ9uZASYEfwwC",
  "referrer": "ReferrerWallet123...",
  "blockhash": "optional-recent-blockhash"
}

Body Parameters:

Parameter	Type	Required	Description
gtokenAddress	string	Yes	The playcoin token mint address
participant	string	Yes	The claimer's Solana wallet address
referrer	string	No	Referrer wallet address (for referral tracking)
blockhash	string	No	A recent Solana blockhash. If not provided, one is fetched automatically

Response:

{
  "transactions": ["base64-encoded-transaction-1", "base64-encoded-transaction-2"],
  "claimableAmount": "1500000000000"
}

---

Get Claim Status

GET /token-launcher/exercise-claim/{gtokenAddress}/status/{wallet}

Check whether a wallet is eligible to claim airdrop tokens and the current claim status.

Path Parameters:

• gtokenAddress (required) — The playcoin token mint address

• wallet (required) — The user's Solana wallet address

Response:

{
  "eligible": true,
  "claimableAmount": "1500000000000",
  "claimed": false
}

---

Full Launch Flow Example

// 1. Launch a playcoin for a game
const launchResponse = await fetch('https://api.play.fun/token-launcher/launch', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${privyAuthToken}`,
  },
  body: JSON.stringify({
    gameId: '550e8400-e29b-41d4-a716-446655440000',
    emissionDays: 30,
    buyAmount: '100000000', // 0.1 SOL
  }),
});

const { jobId } = await launchResponse.json();
console.log('Launch started, job:', jobId);

// 2. Poll for completion
let result;
while (true) {
  await new Promise((r) => setTimeout(r, 3000));

  const statusResponse = await fetch(`https://api.play.fun/token-launcher/launch/${jobId}`);
  result = await statusResponse.json();

  console.log(`Status: ${result.status}, Progress: ${result.progress}%`);

  if (result.status === 'completed') break;
  if (result.status === 'failed') throw new Error(result.error);
}

console.log('Playcoin address:', result.gtokenAddress);
console.log('Transaction:', result.bundleTx);

// 3. Check airdrop eligibility (if game has airdrop configured)
const claimStatus = await fetch(
  `https://api.play.fun/token-launcher/exercise-claim/${result.gtokenAddress}/status/${walletAddress}`,
);
const claim = await claimStatus.json();

if (claim.eligible && !claim.claimed) {
  console.log(`Claimable: ${claim.claimableAmount} tokens`);

  // 4. Build and submit claim transactions
  const txResponse = await fetch(
    'https://api.play.fun/token-launcher/exercise-claim/build-transactions',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        gtokenAddress: result.gtokenAddress,
        participant: walletAddress,
      }),
    },
  );
  const { transactions } = await txResponse.json();
  // Sign and submit transactions...
}

---

Error Responses

All endpoints may return the following error responses:

400 Bad Request:

{
  "statusCode": 400,
  "message": "Invalid emissionDays value. Allowed values are: 7, 30",
  "error": "Bad Request"
}

401 Unauthorized:

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

403 Forbidden:

{
  "statusCode": 403,
  "message": "Only the creator or owner of the game can launch tokens within this period.",
  "error": "Forbidden"
}

404 Not Found:

{
  "statusCode": 404,
  "message": "Game with ID ... not found",
  "error": "Not Found"
}