Developers

Build on PairsFun — launch multipairs from your own site

You collect the token details on your page. We build the transactions. The creator signs them in their own wallet, and the token goes live on PairsFun with the same pools, the same lock and the same fees. You earn a share of what the creator earns. Neither of us ever holds a key.

The flow

1. 1
   PreparePOST /v1/launches with the token, the basket of assets and the creator's wallet. You get unsigned transactions and a review to show the creator: the fee split, the plan and any warnings.
2. 2
   The creator signsIn their own wallet, once for the first phase (the address table, and swaps if the creator buy is paid in SOL) and once for the launch itself.
3. 3
   SubmitThe first phase goes to the network through POST /v1/rpc. The launch goes through POST /v1/launches/{id}/submit, as one all-or-nothing bundle when the creator buys.
4. 4
   LiveThe token is listed on pairsfun.xyz. Your share of the creator share is in the fee vault on-chain; claim it any time with your payout wallet.

All money logic is the same code that runs pairsfun.xyz: pool prices, the fee tier, the lock, the anti-snipe creator buy. The API only wraps it with keys, limits and a stable error format.

Quick start

TypeScript in the browser, with fetch only. The one library you need is the one that reads and writes transactions for the wallet. Replace KEY with your publishable key (it works from the origins we registered for you).

import { VersionedTransaction } from '@solana/web3.js'

const API = 'https://pairsfun.xyz/v1'
const KEY = 'pfp_...' // publishable key: browser only

type Wallet = {
  publicKey: { toString(): string }
  signAllTransactions(txs: VersionedTransaction[]): Promise<VersionedTransaction[]>
}

async function api(path: string, body?: unknown, headers: Record<string, string> = {}) {
  const res = await fetch(API + path, {
    method: body === undefined ? 'GET' : 'POST',
    headers: { authorization: `Bearer ${KEY}`, 'content-type': 'application/json', ...headers },
    body: body === undefined ? undefined : JSON.stringify(body),
  })
  const json = await res.json()
  // Errors always look the same: { error: { code, message, status, requestId, details? } }
  if (!res.ok) throw Object.assign(new Error(json.error.message), json.error)
  return json
}

const rpc = (method: string, params: unknown[]) =>
  api('/rpc', { jsonrpc: '2.0', id: 1, method, params }).then((j) => {
    if (j.error) throw new Error(j.error.message)
    return j.result
  })
const decode = (b64: string) => VersionedTransaction.deserialize(Uint8Array.from(atob(b64), (c) => c.charCodeAt(0)))
const encode = (tx: VersionedTransaction) => btoa(String.fromCharCode(...tx.serialize()))
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))

async function sendAndConfirm(signed: string) {
  const sig: string = await rpc('sendTransaction', [signed, { encoding: 'base64', preflightCommitment: 'confirmed' }])
  for (let i = 0; i < 60; i++) {
    const st = (await rpc('getSignatureStatuses', [[sig]])).value[0]
    if (st?.err) throw new Error('transaction failed: ' + JSON.stringify(st.err))
    if (st?.confirmationStatus === 'confirmed' || st?.confirmationStatus === 'finalized') return sig
    await sleep(1500)
  }
  throw new Error('not confirmed in time')
}

export async function launch(
  wallet: Wallet,
  token: { name: string; symbol: string; image?: string; basket: { mint: string; weightBps: number }[]; devBuyUsd?: number },
) {
  const creator = wallet.publicKey.toString()

  // 1. Prepare. Send an Idempotency-Key: a retry with the same key returns the same launch.
  const prepared = await api('/launches', {
    creator, name: token.name, symbol: token.symbol, image: token.image, basket: token.basket,
    ...(token.devBuyUsd ? { devBuy: { usd: token.devBuyUsd, pay: 'sol' } } : {}),
  }, { 'idempotency-key': crypto.randomUUID() })
  const id: string = prepared.launch.id

  // Show prepared.review to the creator and wait for a yes:
  // review.feePolicy is the split of the creator share (your share is in it), plus plan and warnings.

  // 2. First phase: swaps (if any), then the address table. One wallet window, sent in order.
  const first = [...prepared.phase1.swapTransactions.map((s: { transaction: string }) => decode(s.transaction)), ...prepared.phase1.transactions.map(decode)]
  const { blockhash } = (await rpc('getLatestBlockhash', [{ commitment: 'confirmed' }])).value
  for (const tx of first) tx.message.recentBlockhash = blockhash // unsigned: refresh right before signing
  for (const tx of await wallet.signAllTransactions(first)) await sendAndConfirm(encode(tx))

  // 3. Ask for the bundle. 409 table_not_ready until the address table is final: retry once a second.
  let bundle: any
  for (let i = 0; i < 40 && !bundle; i++) {
    try {
      bundle = await api(`/launches/${id}/bundle`, {})
    } catch (e: any) {
      if (e.code !== 'table_not_ready' && e.code !== 'swaps_pending') throw e
      await sleep(1200)
    }
  }
  if (!bundle) throw new Error('the address table did not become final in time')

  // 4. The creator signs the launch bundle and the bookkeeping together, then you send the bundle.
  const n = bundle.transactions.length
  const signed = (await wallet.signAllTransactions([...bundle.transactions, ...bundle.followUpTransactions].map(decode))).map(encode)
  await api(`/launches/${id}/submit`, { stage: 'bundle', transactions: signed.slice(0, n) })

  // 5. When the token exists on-chain, send the bookkeeping that makes it Live.
  //    Bundles are sometimes dropped: if the mint never shows up, nothing was launched. Go back to step 3 for a fresh bundle,
  //    have the creator sign it, send it again. Do not send the bookkeeping for a token that does not exist.
  let landed = false
  for (let i = 0; i < 40 && !landed; i++) {
    landed = !!(await rpc('getAccountInfo', [prepared.launch.mint, { encoding: 'base64' }])).value
    if (!landed) await sleep(1500)
  }
  if (!landed) throw new Error('the launch bundle did not land: ask for /launches/{id}/bundle again, sign it, send it with stage "bundle"')
  try {
    await api(`/launches/${id}/submit`, { stage: 'followup', transactions: signed.slice(n) })
  } catch (e: any) {
    // The bookkeeping can fail on its own (an old blockhash is the usual reason). details.signatures lists what already landed:
    // /finalize gives the rest with a fresh blockhash, the creator signs it, you send it.
    if (e.code !== 'submit_failed') throw e
    const again = await api(`/launches/${id}/finalize`, { from: e.details?.signatures?.length ?? 0 })
    const resigned = (await wallet.signAllTransactions(again.transactions.map(decode))).map(encode)
    await api(`/launches/${id}/submit`, { stage: 'followup', transactions: resigned })
  }
  return prepared.launch.mint as string
}

Trading works the same way: POST /v1/tokens/{mint}/quote, then .../trade for unsigned transactions, the wallet signs, POST /v1/submit sends them in order. If a multi-transaction trade lands half way, the error carries details.unfinished: send it back as resume to finish only what is missing.

From a server, use your secret key and the same calls. Add X-Pairsfun-End-User-Ip with the visitor's public address so per-person limits apply to them and not to your whole site (a private or loopback address is refused with validation_failed). These limits are counted in your own account, never against other visitors of pairsfun.xyz.

Fees

How you earn

• Your payout wallet is added to the token's fee vault as one more recipient of the creator share. Your cut is set in basis points of that share and comes out of the creator's part. The protocol share is never touched.
• The size is set on your key. Send partnerShareBps to ask for less, never more. If you leave it out you get the default of your key.
• You earn on Standard and Creator tax tokens. Reward and Custom tokens have no creator share, so there is nothing to split; the response says earns: false and why.
• The creator sees your share in review.feePolicy before they sign, and the wallet signs it. It is written into the fee vault on-chain. Until the first fee collection the creator can still change the split; if they remove you, you stop earning on that token and the "via" label goes away. After the first collection it is frozen.
• Your share and the creator's own cut are paid in the assets the pools collect. You claim with GET /v1/earnings and POST /v1/claim (secret key): we build the transaction, you sign it with your payout wallet.

A token launched through you shows via your name on pairsfun.xyz and in the API. We add it only after the chain confirms that your wallet is in the fee vault with the share we promised: attribution on GET /v1/launches/{id} goes pending, then verified.

Keys

Send a key as Authorization: Bearer <key>. We store only a hash, so a lost key can't be shown again, only replaced. A revoked key stops working within seconds. Browsers call from your origin; preflight is answered for every registered origin.

Limits

Per key, per minute unless it says otherwise. Higher limits on request.

On top of that the same per-person limits as on pairsfun.xyz apply to each visitor (by IP), counted separately for your account. Over a limit you get 429 with Retry-After, the same number in error.retryAfterSec. RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset come on every answer to a limited call, errors and the 429 itself included (the open calls, such as /config, have none).

Errors

HTTP 422
{
  "error": {
    "code": "brand_copy",
    "message": "This name or ticker copies PairsFun. Pick another one. Nothing has been charged.",
    "status": 422,
    "requestId": "req_9f2c41d07a3b55e1",
    "details": { "field": "name", "reason": "the name copies PairsFun" }
  }
}

Branch on code, show message, quote requestId when you write to us. The text can change, the code does not. The ones you will meet:

Endpoints

Base URL https://pairsfun.xyz/v1 (also under /api/v1). The full contract is the OpenAPI spec.

What we check

• Names and tickers that copy PairsFun are refused before anything is built. A name that is not a copy goes through, and the usual rules apply after launch.
• Words, images and wallets on our block list are refused before anything is built.
• Every asset in the basket is read from the chain: issuer powers, extensions, whether the pool can hold it. Assets outside our catalog launch marked unverified with the issuer's powers in warnings. Show them.
• Prices and the pool tier come from the server, never from your request, and the fee split is checked against what you were shown (policy_mismatch if it ever differs). Fields we do not know are an error, not ignored.
• A refusal costs nothing: until the creator signs in their wallet, nothing is sent and nothing is charged.

Get a key