Integration

Build on the launchpad.

Every launch, trade and payout is a transaction against the contracts below. Index the factory and the curves and you have the whole state without depending on any Ballast service. The REST API exists for convenience. This page is in English only.

Network and addresses

The launchpad runs on giwa-sepolia (chain id 91342). Addresses change as a whole set when the launchpad is redeployed: tokens from an earlier set keep trading against the set they were launched with, so resolve a token's curve, quote asset and fee recipient from the factory that launched it rather than assuming.

LaunchFactory
0x9E08…F736
LaunchRouter (pool swaps)
0xcc36…1A59
LaunchHook (Uniswap v4)
0x2551…AacC
FeeEscrow
0xe737…B0C6
BuybackVault
0xf6BB…915E
LaunchLocker
0x4988…D490
DojangGate
0x634a…0ad2
HolderFeeDistributorFactory
0x676B…E1D5
MigrationFactory
0x4556…3463
PoolManager
0xc1A1…3216
StateView / Quoter
0xb4DF…8BeE / 0x22F2…ec85
Start block
37850622
Indexer API
https://api.ballast.exchange

ABIs and addresses are generated into the @ballast/sdk workspace package of the repository (packages/sdk), together with the pricing math the site uses. The examples below use viem and the SDK's exports.

Reading a launch

The factory maps a token to its bonding curve. The curve's state() returns everything a client needs to price it in one call: the virtual (phantom) quote reserve, the supply, how much of it is sellable before graduation, what has been collected and sold so far, the opening-window terms and the fee terms the launch was created with. Those terms are fixed for the life of the token, before and after graduation.

typescript
import { createPublicClient, http } from 'viem'
import { bondingCurveAbi, curvePriceWei, curveProgress, giwaSepolia, launchFactoryAbi, getLaunchpadDeployment } from '@ballast/sdk'

const client = createPublicClient({ chain: giwaSepolia, transport: http() })
const d = getLaunchpadDeployment(giwaSepolia.id)!

const curve = await client.readContract({ address: d.factory, abi: launchFactoryAbi, functionName: 'curveOf', args: [token] })
const s = await client.readContract({ address: curve, abi: bondingCurveAbi, functionName: 'state' })

// s.quote          address(0) = ETH, otherwise the ERC-20 the launch is priced in
// s.graduated      true once the curve sold out and the Uniswap v4 pool exists
// s.terms          { feeBps, protocolShareBps, buybackShareBps, creatorTaxBps }

const state = { phantomQuote: s.phantomQuote, supply: s.supply, sellable: s.sellable, quoteReserve: s.quoteReserve, tokensSold: s.tokensSold, graduated: s.graduated }
const priceWei = curvePriceWei(state)      // quote units per 1e18 tokens: (phantom + reserve) * 1e18 / (supply - sold)
const progress = curveProgress(state)      // 0..1, tokensSold / sellable

Price and market cap are in the launch's quote asset. Format amounts with that asset's decimals: ETH and BALLAST use 18, a stablecoin or tokenized stock may not.

Quoting a trade

The curve is a constant-product market over a virtual reserve. A buy pays the base fee, the creator tax and, inside the opening window, the snipe tax on the quote spent before the curve prices it; a sell is priced first and the fees come off the proceeds. The SDK reproduces the contract's arithmetic exactly, and the curve also exposes previewBuy and previewSell views for a one-call answer.

typescript
import { curveQuoteBuy, curveQuoteSell, snipeTaxBps } from '@ballast/sdk'

const fees = { feeBps: BigInt(s.terms.feeBps), creatorTaxBps: BigInt(s.terms.creatorTaxBps), protocolShareBps: BigInt(s.terms.protocolShareBps), buybackShareBps: BigInt(s.terms.buybackShareBps) }

// The snipe tax depends on who pays and who receives: read it from the curve for the actual wallets.
const snipe = await client.readContract({ address: curve, abi: bondingCurveAbi, functionName: 'snipeTaxFor', args: [payer, recipient] })

const buy = curveQuoteBuy(state, quoteIn, fees, snipe)   // { tokensOut, fee, creatorTax, refund, net, graduates }: a buy that
                                                         // crosses the sellable allocation is filled to the edge, the rest refunded
const sell = curveQuoteSell(state, tokensIn, fees)       // { ethOut, fee, creatorTax }: proceeds in quote units, net of fees

// Or ask the curve directly (same numbers):
const [tokensOut, spent, fee] = await client.readContract({ address: curve, abi: bondingCurveAbi, functionName: 'previewBuy', args: [quoteIn, recipient] })

The snipe tax starts at the rate the creator picked (at most 50%) and falls linearly to zero over the opening window. It is waived when both the payer and the recipient hold a Dojang Verified Address, and for the launch's own buybacks. Size minOut from the rate you were quoted, not the total: the last buy of a launch can be partially filled and still succeed.

Buying and selling

Before graduation, trade against the curve. For an ETH launch send the amount as value; for a custom pair approve the curve for the ERC-20 first and send no value. After graduation the curve reverts, and the router swaps through the Uniswap v4 pool with the same fee terms (the pool itself charges nothing; the hook takes the fee).

typescript
// on the curve
await wallet.writeContract({ address: curve, abi: bondingCurveAbi, functionName: 'buy', args: [quoteIn, minOut, recipient], value: isEth ? quoteIn : 0n })
await wallet.writeContract({ address: curve, abi: bondingCurveAbi, functionName: 'sell', args: [tokensIn, minOut, recipient] })

// after graduation, through the router (approve the token or the quote ERC-20 to the router first)
const deadline = BigInt(Math.floor(Date.now() / 1000) + 120)
await wallet.writeContract({ address: d.router, abi: launchRouterAbi, functionName: 'buy', args: [token, quoteIn, minOut, recipient, deadline], value: isEth ? quoteIn : 0n })
await wallet.writeContract({ address: d.router, abi: launchRouterAbi, functionName: 'sell', args: [token, tokensIn, minOut, recipient, deadline] })

Any Uniswap v4 router can trade a graduated pool as well; the hook only requires that the pool was registered by the factory. Pass the recipient as 32 bytes of hookData if you want the fee events to carry it.

Launching a token

One call creates the token, its curve and, optionally, the creator's first buy in the same transaction, so nothing can trade in between. The launch fee travels as value; for an ETH launch the first buy is added to it. Pin the economics you were quoted: if the owner changes a launch config between your read and your transaction, the launch reverts instead of settling on terms you never saw.

typescript
const configId = 0n
const pairToken = '0x0000000000000000000000000000000000000000'   // ETH; or an approved ERC-20

const [canLaunch, launchFee, maxTax, expectedEconomics] = await Promise.all([
  client.readContract({ address: d.factory, abi: launchFactoryAbi, functionName: 'canLaunch', args: [me] }),
  client.readContract({ address: d.factory, abi: launchFactoryAbi, functionName: 'launchFee' }),
  client.readContract({ address: d.factory, abi: launchFactoryAbi, functionName: 'maxCreatorTaxBps' }),
  client.readContract({ address: d.factory, abi: launchFactoryAbi, functionName: 'previewLaunchEconomics', args: [configId, pairToken] }),
])

const firstBuy = parseEther('0.05')
await wallet.writeContract({
  address: d.factory,
  abi: launchFactoryAbi,
  functionName: 'launchToken',
  args: [
    {
      name: 'Example', symbol: 'EXMPL',
      logo: 'ipfs://…', description: 'An example launch.',
      socials: { twitter: '', telegram: '', website: '' },
      creatorFeeRecipient: zeroAddress,   // zero = the caller
      creatorTaxBps: 100,                 // optional, at most maxCreatorTaxBps()
      buybackEnabled: true,
      snipeTaxBps: 2500,                  // opening-window tax, 0 = off, at most 5000
      expectedEconomics,
      salt: toHex(crypto.getRandomValues(new Uint8Array(32))),
    },
    configId,
    pairToken,
    firstBuy,                             // 0n for no first buy
    minOut,
  ],
  value: launchFee + firstBuy,            // ETH launch; a custom pair sends only the fee and approves the factory
})

canLaunch(address) is true while public launching is open and, while it is closed, only for whitelisted wallets. Pair tokens must be approved by the owner; read the accepted ones from the indexer's /quotes or the factory's PairTokenSet events.

Creator fees

Fees are credited to the escrow as they are earned, never pushed, so a recipient that cannot receive a transfer blocks nobody else. A creator holds one balance per quote asset and claims each separately. The fee recipient can hand future fees to another wallet, or to the token's holder distributor (permanent).

typescript
const owedEth = await client.readContract({ address: d.escrow, abi: feeEscrowAbi, functionName: 'balanceOf', args: [creator, zeroAddress] })
await wallet.writeContract({ address: d.escrow, abi: feeEscrowAbi, functionName: 'claim', args: [zeroAddress] })      // ETH
await wallet.writeContract({ address: d.escrow, abi: feeEscrowAbi, functionName: 'claim', args: [quoteToken] })      // a custom pair

// who is paid, and moving it (current recipient only)
const recipient = await client.readContract({ address: d.factory, abi: launchFactoryAbi, functionName: 'creatorFeeRecipientOf', args: [token] })
await wallet.writeContract({ address: d.factory, abi: launchFactoryAbi, functionName: 'transferCreatorFeeRecipient', args: [token, newRecipient] })
await wallet.writeContract({ address: d.factory, abi: launchFactoryAbi, functionName: 'setBuybackEnabled', args: [token, false] })

A protocol-proposed recipient change (community takeover) is public before it takes effect: pendingCreatorFeeRecipient(token) returns the proposed wallet with its effective and expiry times.

Holder epochs

When a creator sends fees to holders, the token's distributor publishes an epoch every few hours: a Merkle root over every holder's share and a URI (IPFS) with the full list. A holder claims any number of open epochs in one call with the shares and proofs from that list. Epochs stay claimable for 90 days, then roll into the next one.

typescript
const n = await client.readContract({ address: distributor, abi: holderFeeDistributorAbi, functionName: 'epochCount' })
const epoch = await client.readContract({ address: distributor, abi: holderFeeDistributorAbi, functionName: 'getEpoch', args: [n - 1n] })
// epoch.root, epoch.quoteAmount, epoch.coinAmount, epoch.uri → { shares: [{ account, quoteAmount, coinAmount, proof }] }

const list = await fetch(gatewayUrl(epoch.uri)).then((r) => r.json())
const mine = list.shares.find((s) => s.account.toLowerCase() === me.toLowerCase())
await wallet.writeContract({
  address: distributor, abi: holderFeeDistributorAbi, functionName: 'claimMany',
  args: [[{ epochId: n - 1n, account: me, quoteAmount: BigInt(mine.quoteAmount), coinAmount: BigInt(mine.coinAmount), proof: mine.proof }]],
})

// verify a list yourself
import { holderLeaf, verifyHolderProof } from '@ballast/sdk'
verifyHolderProof(epoch.root, { account: me, quoteAmount: …, coinAmount: … }, mine.proof)

claimMany is all-or-nothing: a share that cannot be paid reverts the batch, so drop that entry and resend the rest. The distributor's address is on the token row of the indexer (distributor) and in the factory's DistributorCreated event.

Uniswap v4 pools

A graduated launch is a single full-range Uniswap v4 position held by the locker forever. The pool key is the token and its quote asset sorted by address, fee 0, tick spacing 200 and the Ballast hook; the hook charges the launch's fee terms on every swap and distributes them.

typescript
import { launchPoolId, launchPoolPrice, quoteIsCurrency0, stateViewAbi } from '@ballast/sdk'

const poolId = launchPoolId(token, quote, d.hook)                       // keccak of the PoolKey
const [sqrtPriceX96] = await client.readContract({ address: d.stateView, abi: stateViewAbi, functionName: 'getSlot0', args: [poolId] })
const priceWei = launchPoolPrice(sqrtPriceX96, quoteIsCurrency0(quote, token))   // quote units per 1e18 tokens

Events to index

The factory announces every launch; each curve and the hook report every trade in the same shape, so one handler covers both venues. Amounts are in the launch's quote asset.

LaunchFactory.TokenLaunched
token, deployer, pairToken, curve, creatorFeeRecipient, configId, name, symbol, supply, sellable, phantomQuote, graduationThreshold, snipeTaxBps, terms, buybackEnabled
BondingCurve.Trade / LaunchHook.Trade
token, trader, recipient, isBuy, onCurve, quoteAmount (buy: gross spend; sell: net proceeds), tokenAmount, fee (base fee, snipe tax included), creatorTax, quoteReserve, tokensSold
BondingCurve.SnipeTax
token, recipient, amount: the part of a buy’s fee that was snipe tax
LaunchFactory.PoolGraduated
token, poolId, quoteAmount, tokenAmount: the pool exists; route trades to it
LaunchFactory.CreatorFeeRecipientUpdated / …ChangeProposed / …ChangeCancelled
who is paid, and takeovers in flight
LaunchFactory.BuybackEnabledUpdated
token, enabled
BuybackVault.Buyback
token, quoteSpent, tokensBurned, onCurve: every buyback burns what it buys
HolderFeeDistributor.EpochPublished / HolderFeeClaimed / EpochRolledOver
holder fee epochs and claims
FeeEscrow.Credited / Claimed
creator and treasury balances accruing and being withdrawn
LaunchToken.Transfer
holder balances; burns go to the zero address

Use the start block above as the lower bound. The public RPC rejects very wide log ranges, so backfill in bounded chunks.

REST API

The indexer serves a read-only JSON API over everything above, rate limited per IP, with every bigint as a decimal string. It is the same API the site uses. It trails the chain by a second or two; /lag says by how much.

GET /tokens
sort=new|mcap|volume|active|progress|graduated, filter=curve|graduated, quote=<asset>, q=<search>, ids=a,b, spark=1, limit, offset
GET /tokens/:address
one token with its live curve state, fees (and what of the creator’s the escrow has paid out), buybacks and takeover status
GET /tokens/:address/trades
newest first; limit≤100, before=<unix> pages back
GET /tokens/:address/candles
interval=60|300|900|3600|14400|86400, since=<unix>
GET /tokens/:address/holders
top 100 holders; /holders/all for every holder
GET /tokens/:address/holder-epochs
published epochs of a token
GET /accounts/:address
holdings with cost basis, closed positions, trades, launches, trader totals
GET /accounts/:address/value
range=7d|30d|90d|all: holdings value per bucket, per quote asset
GET /accounts/:address/holder-epochs
open epochs the wallet has a share in, and what it claimed
GET /trades/recent
latest trades across the launchpad
GET /stats, /stats/series, /stats/leaders
protocol totals, hourly/daily buckets, leaderboards
GET /quotes, /configs, /distributors
accepted pair assets, launch configs, holder-fee tokens
GET /migrations, /migrations/:address
community migrations
GET /lag
last indexed block vs chain head, and the last run of the buyback keeper and the holder fee publisher

Errors

The contracts use custom errors. The ones an integration is most likely to surface:

Slippage(out, minOut)
the trade could not meet minOut at the price available
Graduated_
the curve has closed; route to the pool
NotReady
graduation was requested before the curve sold out
BadValue / NativeValueMismatch / UnexpectedNativeValue
the ETH sent does not match the amount, or ETH was sent to a custom-pair launch
LaunchEconomicsMismatch
the pinned terms changed; re-read previewLaunchEconomics
LaunchFeeNotPaid
value is below launchFee()
CreatorTaxTooHigh / InvalidSnipeTax
the tax exceeds the protocol cap
PairTokenNotApproved / PairTokenDecimalsMismatch
the quote asset is not accepted, or reports different decimals
LaunchConfigDisabled
the config id is no longer open for launches
NotWhitelisted
public launching is closed and the wallet is not whitelisted
NotCreatorFeeRecipient
only the current fee recipient may do this
TimelockNotElapsed / TimelockExpired
a proposed recipient change executed too early or too late