Launch
Solana mainnet · non-custodial

Developer API

Stonkrain exposes a bounded same-origin client for StonkFun's external public API. Browser code calls /api/stonk/*. It never calls www.stonkfun.xyz directly.

No API key can authorize a launch. The connected wallet signs only the provider's unsigned fee-payment transaction. Stonkrain never requests or receives a seed phrase or private key.

01

Quick start

The shared client unwraps successful same-origin responses and throws stable provider errors.

import { stonkFetch } from "@/lib/stonk-client";
import type { StonkRewardsData } from "@/lib/stonk-types";

const rewards = await stonkFetch<StonkRewardsData>(
  "/api/stonk/rewards",
  { cache: "no-store" },
);
Every read is external provider data. If StonkFun omits a field or becomes unavailable, show that state. Do not replace it with a local estimate.
02

Non-custodial launch flow

A launch costs real SOL and creates irreversible mainnet state.

  1. 1
    Prepare

    Send the creator's public wallet, exact quote mint, metadata and launch mode to /launch/prepare. Reward launches use a permanent 100 or 300 basis point transfer tax.

  2. 2
    Review

    Display the network, destination, SOL amount, expiry, quote mint and permanent fee settings from the returned quote.

  3. 3
    Sign locally

    Decode paymentTransaction, deserialize it with Transaction.from(Uint8Array) and call the wallet's signTransaction. Do not add, remove or reorder instructions.

  4. 4
    Submit exact bytes

    Serialize the signed transaction and submit it with the opaque signedQuote. A processing response must poll status. It must never prepare or request a second payment.

03

Read routes

Public reads use short caches where safe. Wallet-specific and mutation responses use no-store.

MethodSame-origin routePurpose
GET/api/stonk/configMainnet launch flags, fee quote and public stats
GET/api/stonk/pairsCurated launchable quote mints
GET/api/stonk/tokensSearchable token directory with bounded pagination
GET/api/stonk/tokens/[mint]Token identity, quote pair and market detail
GET/api/stonk/tokens/[mint]/rewardsQuote-token holder distribution totals
GET/api/stonk/tokens/[mint]/feesPublic creator-fee claimable amounts
GET/api/stonk/tokens/[mint]/airdropLaunch airdrop evidence when available
GET/api/stonk/tokens/[mint]/burnsPermanent burn records and signatures
GET/api/stonk/rewardsPublic reward aggregate
GET/api/stonk/revenuePublic revenue and buyback aggregate
GET/api/stonk/revenue/historyDaily mainnet revenue history
GET/api/stonk/flywheelObserved rankings and buyback burns
GET/api/stonk/launchesPublic launch records
GET/api/stonk/statsProvider totals, launch flags and network identity

Optional observed routes such as /rewards/overview and /revenue/overview can return richer data. Clients must fall back to the public aggregates when those routes are unavailable.

04

Signing and recovery routes

Every mutation is body-limited, time-bounded and never cached.

MethodSame-origin routePurpose
POST/api/stonk/custom-quoteValidate a custom quote mint and acknowledge any safety warnings
POST/api/stonk/launch/prepareCreate an expiring quote and unsigned fee-payment transaction
POST/api/stonk/launch/submitSubmit the exact wallet-signed payment with its opaque quote
GET/api/stonk/launch/status/[signature]Recover a processing launch without preparing another payment
POST/api/stonk/tokens/[mint]/fees/claim/prepareCreate a 90-second unsigned creator claim intent
POST/api/stonk/tokens/[mint]/fees/claim/submitSubmit the exact wallet-signed claim transaction
05

Response and error contract

Raw routes return one success or failure envelope. The client helper returns only data on success.

// success
{ "ok": true, "data": { ... } }

// failure
{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Provider request limit reached",
    "retryable": true,
    "retryAfterSeconds": 12
  }
}

Use error.code for state transitions. Treat the message as display copy. A timeout or network failure becomes upstream_unavailable. The proxy never returns upstream stack traces, signed quotes or transaction bytes in an error.

06

Rate limits

Stonkrain preserves X-RateLimit-Remaining, X-RateLimit-Reset and Retry-After from the provider.

General public routes300 requests per minute
Launch prepare25 requests per minute
Claim prepare20 requests per minute

A 429 response is not a launch failure. Wait for Retry-After. Do not busy-loop and do not prepare a replacement payment while a paid launch is processing.

07

Proxy safety boundary

The local server reduces exposure without taking custody.

  • all upstream origins are compile-time HTTPS allowlists
  • wallet and mint fields must be valid Solana public keys
  • image requests use /api/stonk/asset?src= with host, redirect, size and content-type checks
  • project URLs cannot contain credentials
  • signed transactions and opaque quotes must not enter logs
  • the server never signs, changes transaction instructions or stores private material