Skip to content
patchbaythe hook workshop

API and SDK

Read coins, rewards and hook activity, check and simulate a hook, publish a recipe, and launch a coin from your own code.

Field guide

Install

The SDK is a typed client for the public API. It has no runtime dependencies and runs on Node 20 or later and in browsers. It is not on npm yet. Download the file this site serves and install it from disk (current npm refuses to install straight from a link):

Install
curl -LO https://patchbay.wtf/sdk/patchbay-sdk-0.1.0.tgz
npm install ./patchbay-sdk-0.1.0.tgz

Checking a launch transaction needs the optional peer dependency @solana/kit, used only by launch.check and by reading a signed transaction’s signature. Everything else works without it.

You can also call the API directly. Every endpoint below is plain HTTP and JSON, and the SDK only adds types, paging helpers, the local hook rules and the launch safety checks.

Quick start

This reads a coin, its 30 day history and every landed payout, then checks that the payout rows add up to the history total.

read-coin.mjs
// Read one coin, its history, and every landed payout, then reconcile the payout rows with the
// history total for the same window. Usage: node read-coin.mjs [mint]
import { createPatchbay } from 'patchbay-sdk';

const patchbay = createPatchbay({ baseUrl: process.env.PATCHBAY_BASE_URL ?? 'https://patchbay.wtf' });

const mint = process.argv[2] ?? (await patchbay.coins.list({ limit: 1 })).coins[0]?.mint;
if (!mint) throw new Error('no coin to read');

const { coin } = await patchbay.coins.get(mint);
console.log(`coin ${coin.mint} (${coin.holders} holders)`);

const window = '30d';
const history = await patchbay.coins.history(mint, { window });
console.log(`history ${window}: fees ${history.totals.fees}, paid ${history.totals.paid} (${history.unit.symbol} atoms)`);

let total = 0n;
let rows = 0;
for await (const page of patchbay.coins.payoutPages(mint, { window })) {
  for (const row of page.payouts) {
    total += BigInt(row.amount);
    rows += 1;
  }
}
console.log(`payout rows ${rows}, sum ${total}`);
const matches = total === BigInt(history.totals.paid) && rows === history.totals.payoutTransactions;
console.log(matches ? 'proved: the payout rows add up to the history total' : 'not reconciled: the rows and the total differ');
process.exitCode = matches ? 0 : 1;

Every sample on this page is a file in the package’s examples folder, run by its tests against a stand-in for the API. The page reads those files; nothing is retyped.

Authentication

There are no accounts and no API keys. Nothing needs registering and nothing can be revoked.

Reads
Public. Any origin may call them; there is no key, token or cookie.
Recipe writes
Authenticated by a wallet signature over a short text message (see the signed message). Signing proves the wallet and moves no funds.
A launch
Authenticated by the wallet’s own transaction signature. The server builds the transaction; only the wallet can sign it, and the SDK checks it first.
Launch routes refuse browsers on other sites.

The launch routes reject a request whose Origin header is another site (bad_origin). Call them from a server, a script or a command line, which send no Origin, or from patchbay.wtf itself. Reads and recipe calls have no such rule.

Errors, paging and caching

Errors

An error is an HTTP status and a JSON body with a code and a sentence. Codes are stable; sentences may change. Read the code.

An error body
{
  "error": "invalid_window",
  "message": "window must be 24h, 7d, 30d or all."
}

The older read routes (coin, wallet, payouts, market) answer { error } without a message, and the launch routes also carry the sentence as detail. The SDK reads all three into one PatchbayError with code, status, message and, on 429 and 503, retryAfter in seconds. No answer at all is network; an answer that is not JSON is bad_response.

CodeStatusMeaning
invalid_mint, invalid_address, invalid_mints400A mint or wallet is not a base58 address, or the mints list is empty, over 100 or has a bad entry.
invalid_window, invalid_cursor, invalid_limit, invalid_hash400A query value or path value is outside what the route accepts.
unknown_coin, unknown_hook404No such coin or no registered hook with that hash.
unavailable503The data source did not answer in time. Retry after a few seconds.
bad_upstream502The data source answered something unreadable.
invalid_idempotency_key, idempotency_conflict400, 409Launch prepare only. The key is not 8 to 128 characters, or it was already used with a different request.
launch_closed, bad_origin, rate_limited, image_too_large, too_large503, 403, 429, 413Launch routes: closed, wrong origin, over a limit, or a body over the size cap.
invalid_fields, invalid_hooks, invalid_image, invalid_wallet, invalid_request, name_refused400Launch input the route did not accept.
hook_v3_closed, backing_closed, backing_unavailable, backing_needs_sol_pair, hook_ownership_required, pair_unavailable409, 422A hook feature that is not open for launch now, or a pair that is not open. Read capabilities.
unfunded, unfunded_pair, mint_taken, simulation_failed, pin_failed400, 502The wallet cannot pay, the mint exists, the launch failed its simulation, or the image could not be stored. Nothing was signed.
ticket_invalid, mode_mismatch, approval_mismatch, expired, network_refused, failed400, 410, 503Submit refusals the server gives before it sends, and the two final outcomes it reads from chain.
unconfirmed500Submit only: something broke around the send and the launch may be on chain. Never retry blind.
publish-limit, version-limit, rate-limited, wallet-rate-limited, writes-busy429Recipe writes over a limit (see Rate limits). These codes use hyphens, as the recipe library does.
invalid-message, invalid-signature, hash-mismatch, expired, replayed, not-author, self-rating, template-exists, template-not-found400, 401, 403, 404, 409Recipe write refusals. Messages say what to fix.

Paging

A list that can run long answers a page and a nextCursor. The cursor is opaque: pass it back unchanged as cursor, and stop when it is null. GET /api/v1/coins takes limit from 1 to 100 (50 by default). Other lists have a fixed page size (24 recipes). The SDK’s pages(), payoutPages() and claimPages() follow cursors for you.

Caching

Reads answer with cache-control: public, max-age=0, s-maxage=5, stale-while-revalidate=30, so a shared cache holds an answer for 5 seconds and may serve a 30 second old one while it refreshes. market holds 10 seconds. Errors and every write answer no-store. Amounts are decimal strings of atoms, never numbers, and amounts of different assets are never added together.

Read endpoints

All paths start with /api/v1. All are GET and need no authentication.

EndpointParametersAnswers
/coinslimit, cursorEvery coin, larger pot first: mode, source, total, coins, nextCursor.
/coin/{mint}mint in the pathOne coin with its board, forfeits and recent payouts: coin. 404 unknown_coin.
/coin/{mint}/historywindow: 24h, 7d (default), 30d, allTotals, the previous window and the series the analytics page charts. Each total is in the coin’s own quote asset.
/coin/{mint}/payoutswindow, cursorLanded holder payouts with their transactions, newest first. The rows add up to totals.paid of the same window.
/coin/{mint}/claimswindow, cursorProven fee claims with their transactions, newest first.
/wallet/{address}mint (required)A wallet’s standing in one coin: position. A wallet that holds none of it is a 200 with found: false.
/wallet/{address}/rewardsaddress in the pathOne wallet across every coin: totals in lamports of SOL and coins, most paid first, each with its unit and position. A wallet that holds nothing is a 200 with an empty coins.
/earnerslimit: 1 to 50; coin: a mintThe wallets coins have paid the most, or one coin’s with coin: earners with rank, wallet, paidLamports and symbols. Covers the wallets on each coin’s board; refreshed every five minutes.
/payoutscursorEvery payout and burn across coins, newest first.
/marketmints: up to 100, comma separatedMarket figures per mint, or null for a coin that could not be priced.
/capabilitiesnoneWhich hook versions and sections can launch now and the numeric limits table. Read it; do not hard-code it.
/hooks/{hash}64 hex charactersA registered hook’s canonical definition: hash, runtime, definition. 404 unknown_hook.
/templatescategory, tier, sort: deployments, rating or new; cursorA page of 24 recipes with counts per category and tier.
/templates/{id}id in the pathOne recipe with every version, metrics with their sources, forks and rating.

The SDK has one method for each: coins.list, coins.get, coins.history, coins.payouts, coins.claims, wallets.get, payouts.list, capabilities, hooks.get, recipes.list and recipes.get, plus the paging iterators.

Validate and simulate a hook

A hook is a JSON definition. The hook helpers run on your machine with the worker’s own rules: they are built from the worker’s source files and a test fails if the two ever disagree on a table of definitions. hook.validate returns the frozen definition or throws a HookValidationError whose field names the setting. hook.hash is the SHA-256 of the canonical JSON, the hash a coin’s metadata commits to. hook.simulate is a gross allocation preview and moves nothing.

hook.mjs
// Validate, hash, describe and simulate a hook locally with the worker's own rules, then compare
// the numeric limits with what the live worker reports. Usage: node hook.mjs
import { createPatchbay, hook } from 'patchbay-sdk';

const definition = hook.validate({
  version: 1,
  recipe: 'loyalty-ladder',
  payoutIntervalSeconds: 1800,
  minimumHoldSeconds: 600,
  weighting: 'loyalty',
  loyaltyCapSeconds: 14400,
  allocation: { holdersBps: 8000, protocolBps: 2000 },
});
console.log(`valid: ${hook.describe(definition)}`);
console.log(`hash ${await hook.hash(definition)}`);

try {
  hook.validate({ ...definition, payoutIntervalSeconds: 601 });
} catch (error) {
  console.log(`refused as expected, field ${error.field}`);
}

const preview = hook.simulate(definition, {
  feeLamports: '1000000',
  holders: [
    { wallet: 'holder-a', balanceRaw: '1000', heldSeconds: 7200 },
    { wallet: 'holder-b', balanceRaw: '1000', heldSeconds: 60 },
  ],
});
console.log(`simulated ${preview.feeLamports} lamports: holders get ${preview.holdersLamports}`);
for (const row of preview.allocations) console.log(`  ${row.wallet}: ${row.lamports} (multiplier ${row.multiplierTenths / 10}x)`);

const patchbay = createPatchbay({ baseUrl: process.env.PATCHBAY_BASE_URL ?? 'https://patchbay.wtf' });
const capabilities = await patchbay.capabilities();
const same = JSON.stringify(capabilities.limits) === JSON.stringify(hook.limits);
console.log(`hook versions open for launch: ${capabilities.hookVersions.join(', ')}`);
console.log(same ? 'proved: the local limits table equals the worker limits table' : 'differs: update the SDK');
process.exitCode = same ? 0 : 1;
The default hook, as JSON
{
  "version": 1,
  "recipe": "loyalty-ladder",
  "payoutIntervalSeconds": 600,
  "minimumHoldSeconds": 0,
  "weighting": "loyalty",
  "loyaltyCapSeconds": 14400,
  "allocation": {
    "holdersBps": 8000,
    "protocolBps": 2000
  }
}

Version 1 and 2 definitions are what the engine runs. Version 3 exists in the contract but cannot launch while its switches are off, and the SDK does not decide that: capabilities().hookVersions and sections say which versions and sections are open right now, and the limits are in capabilities().limits. A launch that uses a closed version answers hook_v3_closed.

Recipes and the signed message

Publishing, versioning, forking and rating are POSTs with { message, signature, definition? }. The message is UTF-8 text, one key: value per line in a fixed order. The wallet signs those exact bytes with ed25519, and the signature goes in base64. Nothing else in the request is trusted: the worker reads every stored field from the signed text, and the definition must hash to the signed hash. A signed message is single use and expires after at most 5 minutes, so resending the same one answers its first result.

A publish message
patchbay-template:v1
Signing proves this wallet. It moves no funds.
action: publish
template: hourly-payday-a1b2
wallet: Vote111111111111111111111111111111111111111
hash: 0000000000000000000000000000000000000000000000000000000000000000
name: Hourly payday
summary: Pays holders by balance every hour.
category: holder-rewards
note: First version.
issued: 2026-11-14T12:00:00.000Z
expires: 2026-11-14T12:05:00.000Z
nonce: 0123456789abcdef0123456789abcdef
ActionPathLines after wallet
publishPOST /templateshash, name, summary, category, note
versionPOST /templates/{id}/versionshash, note. Only the author.
forkPOST /templateshash, from, name, summary, category, note. from is id:version.
ratePOST /templates/{id}/ratingsstars, 1 to 5. Not your own recipe.

Text fields are plain text: 3 to 48 characters for a name, up to 200 for a summary and 200 for a note, with no links, handles or addresses. A request body is at most 8192 bytes. Categories: holder-rewards, deflationary, community-treasury, liquidity, revenue-share. The SDK checks all of this before it asks your signer for anything.

A signer is any async function from message bytes to a 64-byte signature, so a wallet adapter’s signMessage and a keypair both fit. The wallet address is passed explicitly. This example signs with a keypair file and does not send unless you pass --send; it never prints the key.

publish-recipe.mjs
// Publish a recipe signed by a Solana keypair file (the JSON array solana-keygen writes).
// The key is read here, used to sign, and never printed. Without --send nothing leaves this
// machine: the request is built, signed and verified locally. Usage:
//   node publish-recipe.mjs <keypair.json> [--send]
import { createPrivateKey, createPublicKey, sign, verify } from 'node:crypto';
import { readFileSync } from 'node:fs';
import { createPatchbay, hook, parseTemplateMessage } from 'patchbay-sdk';

const [path, flag] = process.argv.slice(2);
if (!path) throw new Error('usage: node publish-recipe.mjs <keypair.json> [--send]');
const send = flag === '--send';

const secret = Uint8Array.from(JSON.parse(readFileSync(path, 'utf8')));
if (secret.length !== 64) throw new Error('not a Solana keypair file');
const privateKey = createPrivateKey({
  key: Buffer.concat([Buffer.from('302e020100300506032b657004220420', 'hex'), secret.subarray(0, 32)]),
  format: 'der',
  type: 'pkcs8',
});
const publicBytes = secret.subarray(32);

const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
function base58(bytes) {
  let n = BigInt('0x' + Buffer.from(bytes).toString('hex'));
  let out = '';
  while (n > 0n) { out = ALPHABET[Number(n % 58n)] + out; n /= 58n; }
  for (const byte of bytes) { if (byte !== 0) break; out = '1' + out; }
  return out;
}
const wallet = base58(publicBytes);

// A signer is any async function from message bytes to a 64-byte ed25519 signature.
const signer = async message => new Uint8Array(sign(null, Buffer.from(message), privateKey));

// Dry run: answer the request here, after capturing what would be sent.
let captured;
const dryFetch = async (url, init) => {
  captured = JSON.parse(String(init.body));
  return new Response(JSON.stringify({ template: 'dry-run', version: 1, definitionHash: 'not-sent' }), { status: 201, headers: { 'content-type': 'application/json' } });
};
const patchbay = createPatchbay({ baseUrl: process.env.PATCHBAY_BASE_URL ?? 'https://patchbay.wtf', ...(send ? {} : { fetch: dryFetch }) });

const definition = hook.validate({
  version: 1, recipe: 'scheduled-payday', payoutIntervalSeconds: 3600, minimumHoldSeconds: 0,
  weighting: 'balance', loyaltyCapSeconds: 0, allocation: { holdersBps: 8000, protocolBps: 2000 },
});
const result = await patchbay.recipes.publish({
  wallet,
  name: 'Hourly payday',
  summary: 'Pays holders by balance every hour.',
  category: 'holder-rewards',
  note: 'First version.',
  definition,
}, signer);

if (send) {
  console.log(`published ${result.template} version ${result.version}, hash ${result.definitionHash}`);
} else {
  const message = parseTemplateMessage(captured.message);
  const publicKey = createPublicKey({ key: Buffer.concat([Buffer.from('302a300506032b6570032100', 'hex'), publicBytes]), format: 'der', type: 'spki' });
  const valid = verify(null, Buffer.from(captured.message), publicKey, Buffer.from(captured.signature, 'base64'));
  console.log(`dry run for wallet ${wallet}: action ${message.action}, recipe ${message.template}`);
  console.log(`signature checks out against the wallet key: ${valid}`);
  console.log(`message hash matches the definition: ${message.hash === (await hook.hash(definition))}`);
  console.log('nothing was sent; add --send to publish');
  process.exitCode = valid ? 0 : 1;
}

Launch a coin

A launch is four steps and the wallet signs only at step three. Step one spends nothing; it pins your image and metadata and registers the hook.

  1. 1

    Prepare

    launch.prepare posts the details as a multipart form to POST /api/v1/launch/prepare. The answer holds a sealed ticket good for 120 seconds, the unsigned transaction, the mint, pool, cost and, for a hook, the binding the server made.

  2. 2

    Check

    launch.check runs the same check the site runs before a wallet signs. It requires the pinned DBC config, only allowed programs, your wallet as creator and payer, the coin’s name and symbol, and a first buy of exactly the amount you typed. Your wallet, name, symbol, amount, pair and hook come from your input. Two values come from the server’s answer: the mint (a generated one is the server’s; in reserved mode it is your own key) and the quoted minimum out of the first buy. That is acceptable because the pool and the first buy are created in one transaction: a wrong mint or minimum can only buy that new coin, never move SOL anywhere else, and the check forbids every other transfer. The check also requires the pool in the answer to be the pool account in the transaction’s own create instruction, and fails on a mismatch. Any failure throws unsafe_transaction: do not sign.

  3. 3

    Sign

    Sign the transaction yourself with your wallet or keypair. In reserved mint mode the mint’s key signs too, and only after the check passes.

  4. 4

    Submit and wait

    launch.submit sends the ticket and the signed transaction. launch.waitForLaunch polls /status until the pool reads back.

launch-dry-run.mjs
// A launch up to, and not including, the signature: prepare the launch, run the site's own
// transaction check, and simulate the unsigned transaction on mainnet. Nothing is signed or sent.
// prepare pins an image and metadata and registers the hook; no coin is made.
// Usage: SOLANA_RPC_URL=<rpc url> node launch-dry-run.mjs <funded wallet address>
// Needs the optional peer dependency @solana/kit for launch.check.
import { deflateSync } from 'node:zlib';
import { createPatchbay, hook } from 'patchbay-sdk';

const wallet = process.argv[2];
const rpc = process.env.SOLANA_RPC_URL;
if (!wallet || !rpc) throw new Error('usage: SOLANA_RPC_URL=<rpc url> node launch-dry-run.mjs <wallet>');

// A solid 64 by 64 PNG, built here so the example needs no file.
function png() {
  const crc = buffer => {
    let value = 0xffffffff;
    for (const byte of buffer) {
      let c = (value ^ byte) & 0xff;
      for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
      value = (value >>> 8) ^ c;
    }
    return (value ^ 0xffffffff) >>> 0;
  };
  const chunk = (type, data) => {
    const body = Buffer.concat([Buffer.from(type), data]);
    const out = Buffer.alloc(8 + data.length + 4);
    out.writeUInt32BE(data.length, 0);
    body.copy(out, 4);
    out.writeUInt32BE(crc(body), 8 + data.length);
    return out;
  };
  const header = Buffer.alloc(13);
  header.writeUInt32BE(64, 0);
  header.writeUInt32BE(64, 4);
  header[8] = 8;
  header[9] = 2;
  const rows = Buffer.alloc(64 * (1 + 64 * 3));
  for (let y = 0; y < 64; y++) for (let x = 0; x < 64; x++) rows.set([32, 36, 38], y * 193 + 1 + x * 3);
  return Buffer.concat([Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]), chunk('IHDR', header), chunk('IDAT', deflateSync(rows)), chunk('IEND', Buffer.alloc(0))]);
}

const patchbay = createPatchbay({ baseUrl: process.env.PATCHBAY_BASE_URL ?? 'https://patchbay.wtf' });
const capabilities = await patchbay.capabilities();
console.log(`hook versions open for launch: ${capabilities.hookVersions.join(', ')}`);

const prepared = await patchbay.launch.prepare({
  name: 'dry run',
  ticker: 'DRYRUN',
  description: 'dry run, never launched',
  wallet,
  image: new Blob([png()], { type: 'image/png' }),
  hooks: hook.validate({
    version: 1, recipe: 'loyalty-ladder', payoutIntervalSeconds: 600, minimumHoldSeconds: 0,
    weighting: 'loyalty', loyaltyCapSeconds: 14400, allocation: { holdersBps: 8000, protocolBps: 2000 },
  }),
}, { idempotencyKey: `dry-run-${Date.now()}` });
console.log(`prepared mint ${prepared.mint}, pool ${prepared.pool}, ${prepared.bytes} bytes, total cost ${prepared.cost.totalLamports} lamports`);

await patchbay.launch.check(prepared);
console.log('check passed: pinned config, allowed programs, this wallet as creator, the typed name and symbol');

const response = await fetch(rpc, {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0', id: 1, method: 'simulateTransaction',
    params: [prepared.transaction, { encoding: 'base64', sigVerify: false, replaceRecentBlockhash: true, commitment: 'confirmed' }],
  }),
});
const { result, error } = await response.json();
if (error) throw new Error(`simulation request refused: ${error.message}`);
console.log(`simulation error: ${JSON.stringify(result.value.err)}, compute units ${result.value.unitsConsumed}`);
console.log(result.value.err === null ? 'proved: the unsigned launch simulates cleanly on mainnet; nothing was signed or sent' : 'the simulation failed; nothing was signed or sent');
process.exitCode = result.value.err === null ? 0 : 1;

The dry run stops before step three. It prepares, checks and simulates the unsigned transaction on mainnet through your own RPC. It signs nothing and sends nothing. prepare does write one pinned image, one metadata file and one pending hook row for a mint that never launches.

launch-submit.mjs
// The whole launch: prepare, check, sign with a keypair file, submit, wait. This SENDS a real
// transaction that spends the wallet's SOL, so it does nothing unless you pass --send. Read the
// launch chapter of the documentation first; run launch-dry-run.mjs before this one.
// The key is read here, used to sign, and never printed.
// Usage: node launch-submit.mjs <keypair.json> <image.png> --send
import { readFileSync } from 'node:fs';
import { createKeyPairFromBytes, getAddressFromPublicKey, getTransactionDecoder, getTransactionEncoder, partiallySignTransaction } from '@solana/kit';
import { createPatchbay, hook, LaunchUnconfirmedError, PatchbayError } from 'patchbay-sdk';

const [keypairPath, imagePath, flag] = process.argv.slice(2);
if (!keypairPath || !imagePath || flag !== '--send') {
  console.log('usage: node launch-submit.mjs <keypair.json> <image.png> --send');
  console.log('This spends SOL. Nothing was sent.');
  process.exit(2);
}

const keyPair = await createKeyPairFromBytes(Uint8Array.from(JSON.parse(readFileSync(keypairPath, 'utf8'))));
const wallet = await getAddressFromPublicKey(keyPair.publicKey);
const patchbay = createPatchbay({ baseUrl: process.env.PATCHBAY_BASE_URL ?? 'https://patchbay.wtf' });

const prepared = await patchbay.launch.prepare({
  name: 'Example coin',
  ticker: 'EXAMPLE',
  description: 'Launched with the Patchbay SDK.',
  firstBuy: '',
  wallet,
  image: new Blob([readFileSync(imagePath)], { type: 'image/png' }),
  hooks: hook.validate({
    version: 1, recipe: 'loyalty-ladder', payoutIntervalSeconds: 600, minimumHoldSeconds: 0,
    weighting: 'loyalty', loyaltyCapSeconds: 14400, allocation: { holdersBps: 8000, protocolBps: 2000 },
  }),
}, { idempotencyKey: `launch-${wallet.slice(0, 8)}-${Date.now()}` });

// Nothing is signed until this passes.
await patchbay.launch.check(prepared);

const unsigned = getTransactionDecoder().decode(Uint8Array.from(Buffer.from(prepared.transaction, 'base64')));
const signed = await partiallySignTransaction([keyPair], unsigned);
const transaction = Buffer.from(getTransactionEncoder().encode(signed)).toString('base64');

try {
  const sent = await patchbay.launch.submit({ ticket: prepared.ticket, transaction });
  console.log(`sent ${sent.signature}`);
  const launched = await patchbay.launch.waitForLaunch(sent);
  console.log(`launched: mint ${launched.mint}, pool ${launched.pool}`);
} catch (error) {
  if (error instanceof LaunchUnconfirmedError) {
    // Do not run this again: the launch may be on chain. Look the signature up first.
    console.log(`unconfirmed. signature ${error.signature ?? 'unknown'}, mint ${error.mint ?? prepared.mint}`);
    process.exitCode = 3;
  } else if (error instanceof PatchbayError) {
    console.log(`refused: ${error.code}: ${error.message}`);
    process.exitCode = 1;
  } else {
    throw error;
  }
}

The full flow below spends the wallet’s SOL, so it does nothing without --send.

Safety rules

  • Never sign a transaction that did not pass launch.check.
  • A launch that fails before signing is safe to start over. After signing it is not.
  • If submit throws LaunchUnconfirmedError, or waitForLaunch runs out of time, the outcome is unconfirmed. The error carries the signature. Open it in an explorer before doing anything else, and never prepare and sign a second launch for the same coin. The SDK never retries a submit.
  • Resubmitting the same signed bytes with the same ticket is safe while the ticket is live: the server reads the signature’s status first and answers what already happened. After 120 seconds use status with the signature, not a new launch.
  • The server sends only a transaction whose signed bytes match the ones it built, and only after its own simulation. Prepare needs the wallet to hold the launch’s full cost before it uploads anything.

Endpoints

EndpointBody or queryAnswers
POST /launch/prepareMultipart form: name, ticker, description, x, site, firstBuy (SOL), wallet, image (up to 4 MB), optional hooks (JSON), pair. ?reserved=1 adds mint. Optional Idempotency-Key header.ticket, transaction, mint, pool, config, bytes, lastValidBlockHeight, expiresInMs, firstBuyTokens, cost, hooks.
POST /launch/submitJSON { ticket, transaction }, base64. ?reserved=1 in reserved mode.signature, mint, pool, lastValidBlockHeight.
GET /launch/statussignature, mint, lastValidBlockHeight, all from submit.state: pending, failed, expired, confirmed or launched; mint; pool. launched only once the pool reads back under the Patchbay config.

Idempotency

Prepare
Send an Idempotency-Key of 8 to 128 characters (letters, digits and . _ : -). The same key and the same request returns the same ticket, with an idempotent-replay: true header and the remaining expiresInMs, but only within 30 seconds of the moment that prepare began (a transaction’s blockhash lives less than its 120 second ticket) and only while the ticket has more than 10 seconds left. Both are measured at the moment the answer is sent, after the checks below have run, for a repeat that arrives later and for one that arrives while the first prepare is still running (it waits and shares the result). A repeat that fails either test runs a fresh prepare instead, with every check of a real prepare. The same key with a different request is 409 idempotency_conflict for 10 minutes. A request with a key must carry a Content-Length (400 invalid_request otherwise).
Best effort
The keys are kept in memory by each server instance, scoped to the caller’s address. A repeat that reaches another instance, or after a restart, simply runs a normal prepare.
What a replay re-checks
Before it returns a stored answer it checks that launching is open, that the origin is allowed, that the pair is still open, and that the perp backing and hook version 3 gates still allow the hook, using the same guard functions as a real prepare. Keyed requests also count against an address limit (a burst of 6, then 1 every 10 seconds), taken before the body is read.
What a replay does not
It does not count against the per-wallet limit, and it does not repeat the funding check, the image and metadata pinning, the hook registration or the simulation: it does none of that work, and returns what the first prepare produced. Every real prepare, with or without a key, runs all of it.
Submit
Idempotent by transaction signature, as described under the safety rules. It takes no key.
Recipe writes
Idempotent by signed message: a resent message answers its first result and nothing is stored twice.

Rate limits

These are the limits that are enforced today. None is a quota you can buy more of.

WhereLimitAnswer
POST /launch/prepareA burst of 3, then 1 a minute, for each address prefix and separately for each wallet. Per server instance.429 rate_limited with retry-after.
POST /launch/submitA burst of 10, then 1 every 10 seconds, for each address prefix. Per server instance.429 rate_limited with retry-after.
GET /launch/statusA burst of 60, then 1 a second, for each address prefix. Per server instance. An answer is shared for 3 seconds.429 rate_limited with retry-after.
Recipe writes30 a minute for each address, 6 a minute for each wallet and 30 a minute overall.429 rate-limited, wallet-rate-limited or writes-busy.
Recipes per wallet10 new recipes and 30 new versions a day.429 publish-limit or version-limit.
Analytics readsAt most 4 history, payouts or claims answers are computed at once.503 with retry-after.
Launch prepare with an Idempotency-KeyA burst of 6, then 1 every 10 seconds, for each address prefix, counted before the body is read and in addition to the prepare limit. Per server instance.429 rate_limited with retry-after.
GET /hooks/{hash}A burst of 30, then 1 a second, for each address prefix. Per server instance.429 rate_limited with retry-after.
All other readsNo per-caller limit. Answers are shared through the cache windows above.Not applicable.

The launch limits are held per server instance, so they are a floor under abuse and not a quota; the real limit on prepare is that your wallet must hold the launch’s full cost before anything is uploaded. The address prefix is the whole IPv4 address, or the /64 prefix of an IPv6 address. When you get a 429 or a 503, wait for retryAfter seconds. The SDK does not retry on its own.

Revenue sources

Working: trading fees from Meteora DBC pools

This is the only revenue a coin’s holders are paid from today. Each coin trades on its own Meteora Dynamic Bonding Curve pool. The worker claims the pool’s trading fees and books each claim from the claim transaction’s own balance change, once, keyed by its signature. It then splits the claim by the coin’s hook. coins.claims and coins.payouts return those proofs.

Planned: external revenue sources

A typed RevenueSource interface ships in the SDK package as types (RevenueSource, RevenueEvent, RevenueProof, RevenueAttribution and RevenueAsset, exported from patchbay-sdk). It names how an amount is proven to have landed, how it is attributed to one coin and the rule for its idempotency key. The worker does not accept a source through it. Nothing in the worker uses the interface and there is no route to register one. A second source would need a public proof, attribution to a single coin, an idempotent entry in the same books and an independent review of the money path.

Not supported

  • No API keys, accounts or per-caller quotas. There is nothing to sign up for.
  • No webhooks or push. Poll the read endpoints, within the cache windows.
  • No streaming from the public API.
  • Hook version 3 sections stay closed until capabilities() reports them open. Do not build a launch around them before that.
  • No browser launches from other sites, and no token or SOL transfers through the API. The SDK builds and signs nothing on its own.
  • External revenue sources: the interface is a design, not a feature.