API

// payfomo.ts: launch a coin for a fomo trader, buy one, claim creator fees. Node 18+.
//   npm i @solana/web3.js@1
//   npx tsx payfomo.ts launch unipcs ./logo.png
//   npx tsx payfomo.ts buy <mint> 0.05
//   npx tsx payfomo.ts claim <mint>
import { readFileSync } from 'node:fs'
import { Connection, Keypair, VersionedTransaction } from '@solana/web3.js'

const API = 'https://api.payfomo.family'
// Any mainnet RPC works. The payfomo proxy is HTTP only, so we poll for confirmation.
const connection = new Connection(process.env.RPC_URL ?? `${API}/rpc`, 'confirmed')
// A solana-keygen JSON file. The key stays on this machine; the API never sees it.
const wallet = Keypair.fromSecretKey(
  Uint8Array.from(JSON.parse(readFileSync(process.env.KEYPAIR ?? 'wallet.json', 'utf8'))),
)

type Quote = { inAmount: string; outAmount: string; minOut: string; feeQuote: string; priceImpactPct: number | null; route: string }
type Built = {
  preTransactions?: string[]
  transaction: string
  lastValidBlockHeight: number
  mint?: string
  mintSigned?: boolean
  quote: Quote | null
}

async function api<T>(path: string, body?: unknown): Promise<T> {
  const res = await fetch(`${API}${path}`, {
    method: body === undefined ? 'GET' : 'POST',
    headers: body === undefined ? undefined : { 'content-type': 'application/json' },
    body: body === undefined ? undefined : JSON.stringify(body),
  })
  const json: unknown = await res.json()
  if (!res.ok) {
    const e = json as { error?: string; details?: unknown }
    throw new Error(`${res.status} ${e.error ?? 'error'} ${e.details ? JSON.stringify(e.details) : ''}`)
  }
  return json as T
}

async function confirm(signature: string, timeoutMs = 90_000): Promise<void> {
  const started = Date.now()
  while (Date.now() - started < timeoutMs) {
    const { value } = await connection.getSignatureStatuses([signature])
    const st = value[0]
    if (st?.err) throw new Error(`${signature} failed: ${JSON.stringify(st.err)}`)
    if (st?.confirmationStatus === 'confirmed' || st?.confirmationStatus === 'finalized') return
    await new Promise((r) => setTimeout(r, 1_000))
  }
  throw new Error(`${signature} not confirmed in time; build a fresh transaction and retry`)
}

async function signSendConfirm(b64: string): Promise<string> {
  const tx = VersionedTransaction.deserialize(Buffer.from(b64, 'base64'))
  // Adds the wallet's signature; the server's mint signature (launches) is kept.
  tx.sign([wallet])
  const signature = await connection.sendRawTransaction(tx.serialize(), { maxRetries: 3 })
  await confirm(signature)
  return signature
}

/** preTransactions first, in order, each confirmed; then the main transaction. */
async function sendBuilt(built: Built): Promise<string> {
  for (const pre of built.preTransactions ?? []) console.log('pre-transaction', await signSendConfirm(pre))
  return signSendConfirm(built.transaction)
}

async function launch(handle: string, imagePath: string): Promise<void> {
  // 1. Pin the image. The server reads the bytes; the declared type is ignored.
  const image = `data:image/png;base64,${readFileSync(imagePath).toString('base64')}`
  const { imageUrl, imageMime } = await api<{ imageUrl: string; imageMime: string }>('/launch/image', { image })

  // 2. Build. `match` is the fomo handle; the server checks it on fomo.family, assigns a …fomo
  //    vanity mint, pins the metadata (website = the coin's payfomo page) and signs for the mint.
  const built = await api<Built>('/launch/build', {
    creator: wallet.publicKey.toBase58(),
    match: handle,
    name: 'Cat Coin', // <= 32 bytes
    symbol: 'CAT', // <= 10, letters and digits
    description: 'Launched from a script',
    twitter: 'https://x.com/example', // optional, https only
    imageUrl,
    imageMime,
    firstBuy: { amount: '0.1', payWith: 'SOL', slippageBps: 500 }, // optional
  })
  if (!built.mint || !built.mintSigned) throw new Error('server did not assign a mint')
  console.log('mint', built.mint, 'first buy', built.quote)

  // 3. Sign with the creator wallet only, send, confirm.
  console.log('launched', await sendBuilt(built))
  console.log(`https://payfomo.family/token/${built.mint}`)
}

async function buy(mint: string, amountSol: string): Promise<void> {
  const params = { mint, side: 'BUY', amount: amountSol, payWith: 'SOL', slippageBps: '300' }
  const quote = await api<Quote>(`/trade/quote?${new URLSearchParams(params)}`)
  console.log('quote', quote)
  const built = await api<Built>('/trade/build', { ...params, slippageBps: 300, owner: wallet.publicKey.toBase58() })
  console.log('bought', await sendBuilt(built))
}

/** Withdraw this wallet's creator fees from one coin it launched. */
async function claim(mint: string): Promise<void> {
  const built = await api<Built>('/creator/claim', { creator: wallet.publicKey.toBase58(), mint })
  console.log('claimed', await sendBuilt(built))
}

const [cmd, a, b] = process.argv.slice(2)
const run =
  cmd === 'launch' && a && b ? launch(a, b) : cmd === 'buy' && a && b ? buy(a, b) : cmd === 'claim' && a ? claim(a) : null
if (!run) console.log('usage: launch <fomo handle> <image> | buy <mint> <sol> | claim <mint>')
run?.catch((err: unknown) => {
  console.error(err instanceof Error ? err.message : err)
  process.exit(1)
})

# Live launchpad parameters (fee split, buyback token, graduation threshold)
curl -s https://api.payfomo.family/config

# Coins still on the curve, by 24h volume
curl -s 'https://api.payfomo.family/tokens?sort=volume&status=CURVE&limit=10'

# Every coin made for one fomo trader, and their page
curl -s 'https://api.payfomo.family/tokens?match=unipcs'
curl -s https://api.payfomo.family/fomo/users/unipcs

# One coin, its last 20 trades, 1h candles and fee history
curl -s https://api.payfomo.family/tokens/<mint>
curl -s 'https://api.payfomo.family/tokens/<mint>/trades?limit=20'
curl -s 'https://api.payfomo.family/tokens/<mint>/candles?tf=1h&limit=200'
curl -s https://api.payfomo.family/tokens/<mint>/fees

# Quote a 0.05 SOL buy (read-only, nothing is built or signed)
curl -s 'https://api.payfomo.family/trade/quote?mint=<mint>&side=BUY&amount=0.05&payWith=SOL&slippageBps=300'

{ "transaction": "<base64 v0 tx>", "lastValidBlockHeight": 429320148,
  "mint": "…fomo", "mintSigned": true,
  "quote": { "inAmount": "0.1", "outAmount": "…", "minOut": "…", "feeQuote": "…",
             "priceImpactPct": 0, "route": "Meteora DBC" } }

curl -s https://api.payfomo.family/rpc -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSignatureStatuses","params":[["<signature>"]]}'

// Browsers, Node 22+ (global WebSocket), or the `ws` package on older Node.
const ws = new WebSocket('wss://api.payfomo.family/ws')
ws.onopen = () => {
  ws.send(JSON.stringify({ op: 'subscribe', topics: ['trades', 'tokens', `token:${mint}`] }))
  setInterval(() => ws.send(JSON.stringify({ op: 'ping' })), 25_000)
}
ws.onmessage = (m) => {
  const msg = JSON.parse(String(m.data))
  if (msg.op !== 'event') return // 'pong' | 'error'
  const e = msg.event
  if (e.type === 'trade') console.log(e.trade.side, e.trade.quoteAmount, e.trade.symbol)
  if (e.type === 'token:new') console.log('new coin', e.token.mint, 'for', e.token.match?.handle)
  if (e.type === 'buyback') console.log('bought back', e.buybackQuote, 'SOL for', e.handle, 'from', e.mint)
}

// 400: validation (details lists each field)
{ "error": "invalid request", "details": [{ "path": "symbol", "message": "symbol is letters and digits only" }] }

// 404: the fomo handle does not exist
{ "error": "fomo.family has no user @someone" }

// 403: claiming another wallet's creator fees
{ "error": "only the wallet that launched this token can claim its creator fees" }