08 — API

API reference

Read the launchpad and build ready-to-sign transactions for a trade or a launch. No key and no login: the user's own wallet signs every transaction, and the fees are the same as on this site.

Technical docs

01Overview

Every route answers JSON over HTTPS at https://launchpad.basestocks.finance/api. Reads come from the indexer and live pool reads; the transaction routes return the calls a wallet sends and never sign anything. The same code serves this site, so what works here works for you.

Base URL	https://launchpad.basestocks.finance/api · JSON in and out · Base mainnet (8453) only
Keys	none · no API key and no login · the one cookie is the visitor's eligibility answer
Amounts	integer strings in the smallest unit: a stock has 8 decimals (1 NVDAc = 100000000), a launched token 18
Addresses	any case in, lowercase out
Errors	{ error: { code, message, details? } } with a 4xx or 5xx status · 429 carries retry-after · 451 means the eligibility answer is missing
Signing	never on the server · /api/tx returns calls for the visitor's own wallet, which signs and sends them
From a browser	another site's page may call the API only when its origin is on the partner list · a server may call any route, but then the limits and the eligibility rule apply to the server, not to each visitor
Limits	per caller, a minute: 120 quotes, 30 transaction builds, 120 token reads, 60 wallet reads · over it, `429` with `retry-after`

Partner sites. A listed site may call these from its visitors' browsers, so the limits and the eligibility question apply to each visitor: GET /api/markets, GET /api/stocks, GET /api/tokens/{address}, GET /api/tokens/{address}/swaps, GET /api/tokens/{address}/candles, GET /api/tokens/{address}/holders, GET /api/wallet/{address}, GET /api/activity, GET /api/launch-config, POST /api/quote, POST /api/tx/swap, POST /api/metadata, POST /api/tx/launch, GET /api/region, GET /api/health.

02Quick start

01Ask for the callsPOST /api/tx/swap or /api/tx/launch with the account that will send them.
02Send them in orderHand each call to that wallet: the approval first, when there is one.
03Wait for the receiptThe deadline is ten minutes. If an approval took longer, ask again.

A trade

// 1. Ask for the calls. amountIn is in the input's smallest unit: the stock for a buy, the token for a sell.
const res = await fetch('https://launchpad.basestocks.finance/api/tx/swap', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ token, side: 'buy', amountIn: '100000000', account, slippageBps: 100, builderCode: 'bc_yourcode' }),
});
const tx = await res.json();
if (tx.error) throw new Error(tx.error.message);

// 2. The visitor's wallet sends them in order: the approval first, when there is one.
//    The deadline is ten minutes; if the approval takes longer, ask again before the swap.
for (const call of tx.calls) {
  const hash = await walletClient.sendTransaction({ account, to: call.to, data: call.data, value: BigInt(call.value) });
  await publicClient.waitForTransactionReceipt({ hash });
}

A launch

// 1. Pin the image and profile to IPFS. The answer is the token's contractURI.
const form = new FormData();
form.set('name', 'My Token');
form.set('symbol', 'MYT');
form.set('description', 'What it is about');
form.set('image', file);
const { contractURI } = await (await fetch('https://launchpad.basestocks.finance/api/metadata', { method: 'POST', body: form })).json();

// 2. Ask for the launch calls. The account that sends them is the creator and earns 70% of every fee.
const tx = await (await fetch('https://launchpad.basestocks.finance/api/tx/launch', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ account, name: 'My Token', symbol: 'MYT', contractURI, stock, builderCode: 'bc_yourcode' }),
})).json();

// 3. Send them in order, then open tx.tokenUrl. The token lands at tx.predictedToken.
for (const call of tx.calls) {
  const hash = await walletClient.sendTransaction({ account, to: call.to, data: call.data, value: BigInt(call.value) });
  await publicClient.waitForTransactionReceipt({ hash });
}

03For AI and tools

Machine-readable versions of this page, built from the same list, so a model or a tool reads exactly what you read here.

llms.txtThe short index for language models: what the launchpad is and where everything lives.https://launchpad.basestocks.finance/llms.txtOpen

llms-full.txtThis whole reference in one plain-text file: conventions, every endpoint, examples, contracts, widget options. Paste it into a model's context.https://launchpad.basestocks.finance/llms-full.txtOpen

OpenAPI 3.1Import the URL into Swagger, Postman or a code generator, or give it to an agent as its tool definitions.https://launchpad.basestocks.finance/api/openapi.jsonOpen

04 Markets and tokens

Read what the indexer recorded: tokens, prices, trades, candles, holders and wallets. Every figure comes from confirmed events or a live pool read.

GET/api/marketspartner CORS

List markets

Every launched token with its price, FDV, 24-hour volume and change, newest first or by volume.

Name	In	Type	Description
stock	query	address	Only tokens paired with this stock.
creator	query	address	Only tokens this address launched.
q	query	string	Search name or symbol, up to 64 characters.
limit	query	integer · 1–200 · default 50	Rows to return.
offset	query	integer · 0–10000 · default 0	Rows to skip.
orderBy	query	newest \| volume24h · default newest	Sort order.

Returns: { markets: Market[], asOf } · asOf is when the indexer last advanced
Errors: 400 INVALID_QUERY400 INVALID_STOCK400 INVALID_CREATOR

curl

curl 'https://launchpad.basestocks.finance/api/markets?limit=5'

GET/api/stockspartner CORS

List quote stocks

The Coinbase tokenized stocks a token can pair with, with the latest Chainlink price, feed status and number of launches.

Returns: { stocks: Stock[] }
Errors: 503 STOCKS_UNAVAILABLE

curl

curl 'https://launchpad.basestocks.finance/api/stocks'

GET/api/tokens/{address}partner CORS120/min

Get one token

The market row with fees, lifetime figures, pool reserves and links. A launch that is confirmed but not indexed yet answers status "indexing", read from its factory.

Name	In	Type	Description
address *	path	address	The launched token.

Returns: { status: "indexed", market, details, launch, profile } | { status: "indexing", launch }
Errors: 400 INVALID_ADDRESS400 INVALID_QUERY404 TOKEN_NOT_FOUND429 RATE_LIMITED

curl

curl 'https://launchpad.basestocks.finance/api/tokens/0xb20000000000000000000023b657130129ad33e5'

GET/api/tokens/{address}/swapspartner CORS120/min

List trades

A token's swaps, newest first, with the creator's own trades flagged. Page back with the block and log index of the last row.

Name	In	Type	Description
address *	path	address	The launched token.
limit	query	integer · 1–200 · default 50	Rows to return.
before	query	integer	Only swaps before this block.
beforeLog	query	integer · 0–…	With before: the log index within that block.

Returns: { token, stock, stockUsd, swaps: Swap[] }
Errors: 400 INVALID_ADDRESS400 INVALID_QUERY404 TOKEN_NOT_FOUND429 RATE_LIMITED

curl

curl 'https://launchpad.basestocks.finance/api/tokens/0xb20000000000000000000023b657130129ad33e5/swaps?limit=10'

GET/api/tokens/{address}/candlespartner CORS120/min

Get candles

OHLCV in stock units per bucket, each with the stock's USD price that was live when it printed.

Name	In	Type	Description
address *	path	address	The launched token.
bucket	query	1 \| 5 \| 15 \| 60 \| 240 \| 1440 · default 1	Bucket width in minutes.
from	query	string	ISO date: first bucket.
to	query	string	ISO date: last bucket.
limit	query	integer · 1–2000 · default 500	Buckets to return.

Returns: { token, interval, quote: { symbol, usd }, candles: { time, open, high, low, close, volumeStock, volumeToken, trades, stockUsd }[] }
Errors: 400 INVALID_ADDRESS400 INVALID_QUERY404 TOKEN_NOT_FOUND429 RATE_LIMITED

curl

curl 'https://launchpad.basestocks.finance/api/tokens/0xb20000000000000000000023b657130129ad33e5/candles?bucket=60&limit=24'

GET/api/tokens/{address}/holderspartner CORS120/min

List holders

Balances ranked, with the pool, the creator and burned dust labelled, and how concentrated the supply is.

Name	In	Type	Description
address *	path	address	The launched token.
limit	query	integer · 1–500 · default 100	Rows to return.

Returns: { token, holderCount, concentration, holders: { rank, address, label, balance, sharePercent }[] }
Errors: 400 INVALID_ADDRESS400 INVALID_QUERY404 TOKEN_NOT_FOUND429 RATE_LIMITED

curl

curl 'https://launchpad.basestocks.finance/api/tokens/0xb20000000000000000000023b657130129ad33e5/holders?limit=10'

GET/api/tokens/{address}/image

Get the token image

The image bytes from this site's own origin, at most 5 MB. Link it with ?v= as the market row gives it: a matching v on an ipfs:// image is cached for good.

Name	In	Type	Description
address *	path	address	The launched token.
v	query	string	First 12 hex of the image URI's sha256.

Returns: image bytes
Errors: 400 INVALID_ADDRESS404 TOKEN_NOT_FOUND404 NO_IMAGE413 IMAGE_TOO_LARGE415 NOT_AN_IMAGE502 IMAGE_UNREACHABLE

curl

curl 'https://launchpad.basestocks.finance/api/tokens/0xb20000000000000000000023b657130129ad33e5/image'

Not runnable from this page: it answers with image bytes.

GET/api/tokens/{address}/dex-paid

DEX Screener paid status

Whether the token has a paid DEX Screener profile: approved, pending, none or unavailable. Cached for five minutes; 20 calls a minute per caller.

Name	In	Type	Description
address *	path	address	The launched token.

Returns: { status }
Errors: 400 INVALID_ADDRESS429 RATE_LIMITED

curl

curl 'https://launchpad.basestocks.finance/api/tokens/0xb20000000000000000000023b657130129ad33e5/dex-paid'

GET/api/tokens/{address}/profile

Get the creator profile

The creator-signed profile of a fixed-profile token: description, image, website, X, Telegram. Null when the creator never signed one.

Name	In	Type	Description
address *	path	address	The launched token.

Returns: { profile: { description, imageUri, website, twitter, telegram, signer, updatedAt } | null }
Errors: 400 INVALID_ADDRESS

curl

curl 'https://launchpad.basestocks.finance/api/tokens/0xb20000000000000000000023b657130129ad33e5/profile'

POST/api/tokens/{address}/profilemultipart

Update the creator profile

Multipart: a payload field with the EIP-712 TokenProfile the creator signed, and the image whose keccak256 it names. Stored only when the signer is the launch creator. A token with an editable profile changes it onchain instead (409).

Name	In	Type	Description
address *	path	address	The launched token.
payload *	form	string	JSON: signer, signature, description, website, twitter, telegram, imageHash, issuedAt.
image	form	file	The new image; its keccak256 must equal imageHash.

Returns: { ok: true, ... }
Errors: 400 INVALID_FORM400 INVALID_PAYLOAD400 INVALID_FIELDS409 ONCHAIN_PROFILE4xx from the signature check

curl

curl -X POST 'https://launchpad.basestocks.finance/api/tokens/0xb20000000000000000000023b657130129ad33e5/profile' \
  -F 'payload={…signed…}' \
  -F image=@logo.png

Not runnable from this page: it uploads to IPFS or stores a write.

GET/api/wallet/{address}partner CORS60/min

Get a wallet

What an address launched, holds, earned as a creator and can claim now, with its recent trades.

Name	In	Type	Description
address *	path	address	Any wallet.

Returns: { wallet, created, holdings, holdingsUsd, claimable, claimableUsd, recentSwaps, ... }
Errors: 400 INVALID_ADDRESS429 RATE_LIMITED503 WALLET_UNAVAILABLE

curl

curl 'https://launchpad.basestocks.finance/api/wallet/0x1111111111111111111111111111111111111111'

GET/api/activitypartner CORS

Activity feed

Launches and swaps as one feed, newest first. Poll it to follow the launchpad; there is no webhook.

Name	In	Type	Description
limit	query	integer · 1–200 · default 50	Rows to return.
token	query	address	Only this token.
actor	query	address	Only this trader or creator.

Returns: { items: { kind: "launch" | "swap", at, txHash, token, name, symbol, ... }[], asOf }
Errors: 400 INVALID_QUERY400 INVALID_TOKEN400 INVALID_ACTOR503 ACTIVITY_UNAVAILABLE

curl

curl 'https://launchpad.basestocks.finance/api/activity?limit=10'

GET/api/stats

Platform totals

Launches, traders, swaps, volume and fees, with the fees and volume per stock.

Returns: { launches, creators, traders, swaps, holders, volumeUsd, feesUsd, volumeByStock, feesByStock, topCreators, asOf, ... }
Errors: 503 STATS_UNAVAILABLE

curl

curl 'https://launchpad.basestocks.finance/api/stats'

GET/api/names

Resolve Basenames

Base names for up to 100 addresses at once, memoised on the server.

Name	In	Type	Description
a *	query	string	Comma-separated addresses.

Returns: { names: { [address]: name | null } }

curl

curl 'https://launchpad.basestocks.finance/api/names?a=0x1111111111111111111111111111111111111111'

05 Trading and launching

Quote a trade, pin a profile, and get the exact calls a wallet sends to trade or launch. Nothing here signs or sends a transaction.

GET/api/launch-configpartner CORS

Launch configuration

The factory, hook and router new launches use, the builder code, the deadline and the form limits. The creation fee and opening valuation are left out on purpose: read them from the factory right before the wallet opens, or let POST /api/tx/launch do it.

Returns: { chainId, factory, hook, router, deployBlock, builderCode, deadlineSeconds, limits, urls }
Errors: 503 NOT_CONFIGURED

curl

curl 'https://launchpad.basestocks.finance/api/launch-config'

POST/api/quotepartner CORS120/mineligibilityJSON body

Quote a trade

An exact-input quote from the Uniswap v4 Quoter against the token's own pool, including a launch that is confirmed but not indexed yet.

Name	In	Type	Description
token *	body	address	The launched token.
side *	body	buy \| sell	buy spends the stock, sell spends the token.
amountIn *	body	uint	Input in its smallest unit: 8 decimals for a stock, 18 for a token.

Returns: { amountIn, amountOut, feeBps, midPrice, executionPrice, priceImpactPercent, poolKey, zeroForOne, gasEstimate, liquidity }
Errors: 400 INVALID_BODY404 TOKEN_NOT_FOUND409 NO_LIQUIDITY429 RATE_LIMITED451 REGION_RESTRICTED503 NOT_CONFIGURED

curl

curl -X POST 'https://launchpad.basestocks.finance/api/quote' \
  -H 'content-type: application/json' \
  -d '{"token":"0xb20000000000000000000023b657130129ad33e5","side":"buy","amountIn":"100000000"}'

POST/api/tx/swappartner CORS30/mineligibilityJSON body

Build a swap

The calls for one exact-input trade, for the account that will send them: an approval of exactly amountIn to the token's router when the allowance is short, then swapExactIn with the minimum output and a ten-minute deadline. The swap is simulated when no approval is needed.

Name	In	Type	Description
token *	body	address	The launched token.
side *	body	buy \| sell	buy spends the stock, sell spends the token.
amountIn *	body	uint	Input in its smallest unit.
account *	body	address	The wallet that sends the calls and pays the input.
recipient	body	address	Who receives the output. Defaults to account.
slippageBps	body	integer · 10–500 · default 100	Tolerance below the quote, in basis points.
builderCode	body	string	Your ERC-8021 builder code. It goes on every call beside the launchpad's, so the transaction is attributed to both.

Returns: { calls: { to, data, value, description }[], quote, approval, deadline, expiresAt, simulation, router, tokenIn, tokenOut }
Errors: 400 INVALID_BODY400 INVALID_AMOUNT404 TOKEN_NOT_FOUND409 NO_LIQUIDITY429 RATE_LIMITED451 REGION_RESTRICTED502 TX_FAILED503 NOT_CONFIGURED

curl

curl -X POST 'https://launchpad.basestocks.finance/api/tx/swap' \
  -H 'content-type: application/json' \
  -d '{"token":"0xb20000000000000000000023b657130129ad33e5","side":"buy","amountIn":"100000000","account":"0x1111111111111111111111111111111111111111"}'

POST/api/metadatapartner CORSeligibilitymultipart

Pin a token profile

Multipart: pins the image and the ERC-7572 document to IPFS and returns the contractURI a launch takes. With token, it pins a new profile for an editable token, keeping its name and symbol. 10 pins an hour per caller.

Name	In	Type	Description
name *	form	string	1 to 64 characters.
symbol *	form	string	A to Z and 0 to 9, up to 16.
description	form	string	Up to 1,000 characters.
website	form	string	An https link.
twitter	form	string	An X handle or x.com link.
telegram	form	string	A Telegram handle or t.me link.
image	form	file	PNG, WebP, JPEG or GIF, up to 2 MB.
token	form	address	An editable token to pin a new profile for.

Returns: { contractURI, imageUri, metadata }
Errors: 400 INVALID_FIELDS400 IMAGE_INVALID409 PROFILE_FIXED409 PROFILE_LOCKED429 RATE_LIMITED451 REGION_RESTRICTED502 UPLOAD_FAILED

curl

curl -X POST 'https://launchpad.basestocks.finance/api/metadata' \
  -F 'name=Example Token' \
  -F 'symbol=EXMPL' \
  -F image=@logo.png

Not runnable from this page: it uploads to IPFS or stores a write.

POST/api/tx/launchpartner CORS30/mineligibilityJSON body

Build a launch

The calls that launch a token from the account: an approval of exactly stockIn to the factory when a buy at launch needs one, then launchWithOptions or launchAndBuy with the creation fee as value. The account is the creator and earns 70% of every fee. Send the same salt to keep the same token address.

Name	In	Type	Description
account *	body	address	The creator's wallet, which sends the calls.
name *	body	string	1 to 64 bytes.
symbol *	body	string	A to Z and 0 to 9, up to 16.
contractURI *	body	string	ipfs://, as POST /api/metadata returns it.
stock *	body	address	The stock it trades against.
metadataEditable	body	boolean · default false	Let the creator point the token at a new profile later. Needs a bare-CID contractURI.
salt	body	bytes32	Fixes the token address; random when absent.
buy	body	object	A buy for the creator in the same transaction.
buy.stockIn *	body	uint	Stock to spend, 8 decimals.
buy.toleranceBps	body	integer · 50–500 · default 200	How far the opening price may move before the launch reverts.
buy.acknowledgeShare	body	boolean	Required once the buy is 15% of the supply or more.
builderCode	body	string	Your ERC-8021 builder code. It goes on every call beside the launchpad's, so the transaction is attributed to both.

Returns: { calls, functionName, predictedToken, salt, creationFee, openingFdvUsd8, buy, approval, deadline, expiresAt, simulation, tokenUrl }
Errors: 400 INVALID_BODY400 UNKNOWN_STOCK409 STOCK_NOT_ENABLED409 BUY_TOO_LARGE409 SHARE_UNCONFIRMED409 SHARE_LIMIT429 RATE_LIMITED451 REGION_RESTRICTED502 TX_FAILED503 NOT_CONFIGURED

curl

curl -X POST 'https://launchpad.basestocks.finance/api/tx/launch' \
  -H 'content-type: application/json' \
  -d '{"account":"0x1111111111111111111111111111111111111111","name":"Example Token","symbol":"EXMPL","contractURI":"ipfs://bafkreibm6jg3ux5qumhcn2b3flc3tyu6dmlb4xa7u5bf44yegnrjhc4yeq","stock":"0xb20000000000000000000078ee7ce2fe4908108c"}'

06 Eligibility

Where the caller connects from, and the "not a US person" answer that quotes, pins and transaction builds wait for in a restricted country.

GET/api/regionpartner CORS

Where the caller is

The country the host reports, the mode, and whether quotes, pins and transaction builds wait for the eligibility answer.

Returns: { country, blocked, mode, blockedCountry, attested, restricted }

curl

curl 'https://launchpad.basestocks.finance/api/region'

POST/api/regionJSON body

Give the eligibility answer

The visitor's own statement that they do not live in the United States and are not a US citizen or resident, kept as a cookie for 30 days. Refused from another site's page. A site that asks in its own UI sends x-bstocks-eligibility: confirmed on each request instead.

Name	In	Type	Description
confirm *	body	boolean	true to confirm, false to withdraw.

Returns: the same as GET, and a Set-Cookie
Errors: 400 INVALID_BODY403 CROSS_SITE

curl

curl -X POST 'https://launchpad.basestocks.finance/api/region' \
  -H 'content-type: application/json' \
  -d '{}'

Not runnable from this page: it sets a cookie.

07 Service

Health of the indexer and the database, and this reference in machine-readable form.

GET/api/healthpartner CORS

Health

Database, schema version, contracts, indexer lag and chain head. ok is false while the schema is behind or a launch hook is not configured.

Returns: { ok, database, schema, contracts, deployments, indexer, head }

curl

curl 'https://launchpad.basestocks.finance/api/health'

GET/api/openapi.jsonpartner CORS

OpenAPI spec

This reference as OpenAPI 3.1, for Swagger, Postman, code generators and AI agents. Any origin may fetch it.

Returns: OpenAPI 3.1 document

curl

curl 'https://launchpad.basestocks.finance/api/openapi.json'

Not runnable from this page: it is the spec itself; open it from Resources above.