Documentation

@burnkit/sdk

Add token payments, programmable burns, treasury splits, and verifiable receipts to any Solana app. Bring your own RPC, plug in your own price provider, and own transaction signing in your app.

Installation

Install the package with your preferred package manager.

terminal

$pnpm add @burnkit/sdk

Create client

Construction is cheap and side-effect free - no network calls happen until you call a method. The default price provider is a deterministic mock, so this runs with zero configuration.

lib/burnkit.ts

import { createBurnkitClient } from "@burnkit/sdk"; export const burnkit = createBurnkitClient({  network: "devnet", // "mainnet-beta" | "devnet" | "localnet"  rpcUrl: process.env.SOLANA_RPC_URL, // optional - defaults per network});

Quote token amount

Convert a USD utility price into a precise token amount. The result includes both a UI amount and a base-unit string so you never lose precision.

quote.ts

const quote = await burnkit.quote({  mint: "So11111111111111111111111111111111111111112",  usdAmount: 2.5,}); // {//   uiAmount: 0.0166...,//   baseAmount: "16666666",//   unitPriceUsd: 150,//   decimals: 9,//   source: "mock",// }

Create burn intent

A burn intent validates input, quotes the price, and computes the exact burn and split amounts, returning a ready-to-execute plan your app builds and signs - keeping full control of submission.

intent.ts

const intent = await burnkit.createBurnIntent({  mint: "TOKEN_MINT",  payer: wallet.publicKey.toBase58(),  usdAmount: 2.5,  burnPercent: 100,  action: "generate_meme_pack",  metadata: { project: "BurnMarket" },}); const plan = burnkit.planTransaction(intent);// plan.operations -> [{ kind: "burn", baseAmount, ... }]

Burn percentage

burnPercent defaults to 100 for a full burn. The burn amount is floored; any rounding dust stays with the remainder so the parts always sum back to the total.

burn-amount.ts

const { burnBaseAmount, remainderBaseAmount } =  await burnkit.getBurnAmount({    mint: "TOKEN_MINT",    usdAmount: 5,    burnPercent: 80,  });

Treasury split

Route the non-burned remainder to one or more wallets. burnPercent plus all split percents must sum to 100.

split.ts

await burnkit.createBurnIntent({  mint: "TOKEN_MINT",  payer: "USER_WALLET",  usdAmount: 5,  burnPercent: 80,  splits: [    { type: "treasury", wallet: "TREASURY_WALLET", percent: 20 },  ],  action: "unlock_brand_kit",});

Protocol-fee splits (type: "protocol_fee") are supported but disabled by default. Pass enableProtocolFee: true to the client to opt in - no fee is ever taken otherwise.

Build the transaction

The core SDK is dependency-free and stops at describing intent. The optional @burnkit/sdk/web3 subpath turns a plan into signable SPL instructions - a burn from the payer's token account plus an idempotent ATA-create and transfer per split. It requires the @solana/web3.js and @solana/spl-token optional peer dependencies.

build.ts

import { buildBurnInstructions } from "@burnkit/sdk/web3";import { Transaction } from "@solana/web3.js"; const plan = burnkit.planTransaction(intent);const instructions = buildBurnInstructions(plan); const { blockhash } = await connection.getLatestBlockhash();const tx = new Transaction({  feePayer,  recentBlockhash: blockhash,}).add(...instructions); // sign & send with your wallet adapter

Your app fetches the blockhash, signs, and submits. Pass createDestinationAccounts: false to skip ATA creation, or a Token-2022 program id for Token-2022 mints.

Receipts

Every action can produce a receipt your app can store, display, or verify. Receipts carry a deterministic digest; re-verifying recomputes it to detect tampering. Attach the transaction signature once the burn is submitted.

receipts.ts

const receipt = burnkit.issueReceipt(intent, {  signature: txSignature,}); const json = burnkit.serializeReceipt(receipt); // store thisconst parsed = burnkit.parseReceipt(json);const result = burnkit.verifyReceipt(parsed); if (!result.valid) {  console.warn(result.reason);}

For cryptographic proof of who issued a receipt, attach an Ed25519 attestation. The built-in Ed25519ReceiptSigner needs no @solana/web3.js; ReceiptSigner is pluggable for wallets or an HSM. You can also anchor the digest on-chain with an SPL Memo instruction.

signing.ts

import { createBurnkitClient, Ed25519ReceiptSigner } from "@burnkit/sdk";import { buildReceiptAnchorInstruction } from "@burnkit/sdk/web3"; const signer = Ed25519ReceiptSigner.fromSecretKey(issuerSecretKey);const burnkit = createBurnkitClient({ network: "mainnet-beta", receiptSigner: signer }); let receipt = burnkit.issueReceipt(intent, { signature });receipt = await burnkit.signReceipt(receipt); burnkit.verifyReceipt(receipt);// { valid: true, signed: true, signer: "<base58 pubkey>" } // Co-locate the proof with the burn:const anchor = buildReceiptAnchorInstruction(receipt, { signers: [payer] });

After the transaction lands, read the anchor back by signature and cross-check a stored receipt against it - no @solana/web3.js required.

lookup.ts

const ref = await burnkit.lookupReceipt(txSignature);// { digest, attestation, slot, blockTime, memo } | null const result = await burnkit.verifyAnchoredReceipt(txSignature, receipt);// { valid, anchored, digestMatches, signed, signer, onChain }

Error handling

Every error extends BurnkitError and carries a stable code, so you can branch without parsing messages.

errors.ts

import { BurnkitError } from "@burnkit/sdk"; try {  await burnkit.createBurnIntent(input);} catch (err) {  if (err instanceof BurnkitError) {    switch (err.code) {      case "VALIDATION":        // bad input        break;      case "PRICE_UNAVAILABLE":        // no price for mint        break;      default:        throw err;    }  }}

Price providers

Live providers backed by Jupiter and DexScreener ship in the box, with price caching, request timeouts, and on-chain decimals resolution. Chain them with FallbackPriceProvider so quoting stays resilient, and a deterministic provider backs local development with zero configuration.

pricing.ts

import {  createBurnkitClient,  JupiterPriceProvider,  DexScreenerPriceProvider,  FallbackPriceProvider,  MockPriceProvider,} from "@burnkit/sdk"; const burnkit = createBurnkitClient({  network: "mainnet-beta",  rpcUrl: process.env.SOLANA_RPC_URL,  priceProvider: new FallbackPriceProvider([    new JupiterPriceProvider({ rpcUrl: process.env.SOLANA_RPC_URL }),    new DexScreenerPriceProvider({ rpcUrl: process.env.SOLANA_RPC_URL }),    new MockPriceProvider(),  ]),});

To implement your own oracle or fixed price, satisfy the PriceProvider interface: an id and an async getUnitPrice(mint, network) returning { unitPriceUsd, decimals }.

Roadmap

Shipped: first-class Jupiter / DexScreener price providers with a fallback chain.
Shipped: optional transaction builder behind a @solana/web3.js peer dependency.
Shipped: Ed25519-signed receipts and on-chain anchoring via the Memo program.
Shipped: on-chain receipt lookup and cross-check by transaction signature.

← Quickstart Home →