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):
curl -LO https://patchbay.wtf/sdk/patchbay-sdk-0.1.0.tgz
npm install ./patchbay-sdk-0.1.0.tgzChecking 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 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.
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.
{
"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.
| Code | Status | Meaning |
|---|---|---|
invalid_mint, invalid_address, invalid_mints | 400 | A 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_hash | 400 | A query value or path value is outside what the route accepts. |
unknown_coin, unknown_hook | 404 | No such coin or no registered hook with that hash. |
unavailable | 503 | The data source did not answer in time. Retry after a few seconds. |
bad_upstream | 502 | The data source answered something unreadable. |
invalid_idempotency_key, idempotency_conflict | 400, 409 | Launch 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_large | 503, 403, 429, 413 | Launch 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_refused | 400 | Launch input the route did not accept. |
hook_v3_closed, backing_closed, backing_unavailable, backing_needs_sol_pair, hook_ownership_required, pair_unavailable | 409, 422 | A 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_failed | 400, 502 | The 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, failed | 400, 410, 503 | Submit refusals the server gives before it sends, and the two final outcomes it reads from chain. |
unconfirmed | 500 | Submit 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-busy | 429 | Recipe 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-found | 400, 401, 403, 404, 409 | Recipe 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.
| Endpoint | Parameters | Answers |
|---|---|---|
/coins | limit, cursor | Every coin, larger pot first: mode, source, total, coins, nextCursor. |
/coin/{mint} | mint in the path | One coin with its board, forfeits and recent payouts: coin. 404 unknown_coin. |
/coin/{mint}/history | window: 24h, 7d (default), 30d, all | Totals, the previous window and the series the analytics page charts. Each total is in the coin’s own quote asset. |
/coin/{mint}/payouts | window, cursor | Landed holder payouts with their transactions, newest first. The rows add up to totals.paid of the same window. |
/coin/{mint}/claims | window, cursor | Proven 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}/rewards | address in the path | One 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. |
/earners | limit: 1 to 50; coin: a mint | The 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. |
/payouts | cursor | Every payout and burn across coins, newest first. |
/market | mints: up to 100, comma separated | Market figures per mint, or null for a coin that could not be priced. |
/capabilities | none | Which hook versions and sections can launch now and the numeric limits table. Read it; do not hard-code it. |
/hooks/{hash} | 64 hex characters | A registered hook’s canonical definition: hash, runtime, definition. 404 unknown_hook. |
/templates | category, tier, sort: deployments, rating or new; cursor | A page of 24 recipes with counts per category and tier. |
/templates/{id} | id in the path | One 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.
// 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;{
"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.
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| Action | Path | Lines after wallet |
|---|---|---|
publish | POST /templates | hash, name, summary, category, note |
version | POST /templates/{id}/versions | hash, note. Only the author. |
fork | POST /templates | hash, from, name, summary, category, note. from is id:version. |
rate | POST /templates/{id}/ratings | stars, 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 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
Prepare
launch.prepareposts the details as a multipart form toPOST /api/v1/launch/prepare. The answer holds a sealedticketgood for 120 seconds, the unsignedtransaction, the mint, pool, cost and, for a hook, the binding the server made. - 2
Check
launch.checkruns 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 thepoolin the answer to be the pool account in the transaction’s own create instruction, and fails on a mismatch. Any failure throwsunsafe_transaction: do not sign. - 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
Submit and wait
launch.submitsends the ticket and the signed transaction.launch.waitForLaunchpolls/statusuntil the pool reads back.
// 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.
// 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
submitthrowsLaunchUnconfirmedError, orwaitForLaunchruns 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
statuswith 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
| Endpoint | Body or query | Answers |
|---|---|---|
POST /launch/prepare | Multipart 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/submit | JSON { ticket, transaction }, base64. ?reserved=1 in reserved mode. | signature, mint, pool, lastValidBlockHeight. |
GET /launch/status | signature, 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-Keyof 8 to 128 characters (letters, digits and. _ : -). The same key and the same request returns the same ticket, with anidempotent-replay: trueheader and the remainingexpiresInMs, 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 409idempotency_conflictfor 10 minutes. A request with a key must carry aContent-Length(400invalid_requestotherwise). - 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.
| Where | Limit | Answer |
|---|---|---|
POST /launch/prepare | A 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/submit | A burst of 10, then 1 every 10 seconds, for each address prefix. Per server instance. | 429 rate_limited with retry-after. |
GET /launch/status | A 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 writes | 30 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 wallet | 10 new recipes and 30 new versions a day. | 429 publish-limit or version-limit. |
| Analytics reads | At most 4 history, payouts or claims answers are computed at once. | 503 with retry-after. |
Launch prepare with an Idempotency-Key | A 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 reads | No 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.