API
Coins and trees
The read routes about coins and the grove: the platform, the feed, one coin with its tree and its pool, trades, candles, holders, the grove's totals and the fruit board.
The platform
GET /v1/platform answers everything a client needs to quote, label and link: the fee, the stage thresholds, the day's length and the curve every coin launches on. Read it once at start. Client method: platform().
curl https://api.kodama.example/v1/platformimport { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const platform = await api.platform(){
"name": "Kodama",
"programId": "<the kodama program>",
"grove": "<its Grove>",
"burner": "<its Burner>",
"cluster": "mainnet",
"platformConfig": "CtekL1ZWQGpZ7pfNdYsvFdt2U2f2ECS3WxabAR86pjcF",
"globalConfig": "6s1xP3hpbAfFoNtUNF8mfHsjr2Bd97JxFJRWLbL6aHuX",
"quoteMint": "So11111111111111111111111111111111111111112",
"quoteDecimals": 9,
"baseDecimals": 6,
"fee": {
"total": 19000,
"fruit": 12000,
"planter": 3000,
"burner": 4000,
"echo": 2000
},
"echoMemoryDays": 30,
"stageThresholds": {
"sprout": 100000,
"sapling": 500000
},
"dayLengthSeconds": 86400,
"curveFees": {
"protocol": 2500,
"platform": 19000,
"creator": 0
},
"curve": {
"supply": "1000000000000000",
"totalBaseSell": "793100000000000",
"totalQuoteFundRaising": "85000000000",
"migrateFee": "0"
},
"cpmm": {
"index": 21,
"ammConfig": "DDjMX8BNVQjprycffhhPFgWaL1SVx6nB8wBVrkcPaskt",
"trade": 2000,
"protocol": 120000,
"fund": 40000,
"creator": 19000,
"creatorShare": 0
},
"lookupTables": [
"AcL1Vo8oy1ULiavEcjSUcwfBSForXMudcZvDZy5nzJkU",
"DJ3h1NymcaW5ck8Vuf4L4H6FgAEkBwwYHyuojWQwR5g1"
]
}| Field | Type | Meaning |
|---|---|---|
namerequired | string | The platform's name. |
clusterrequired | string | mainnet, devnet or localnet. |
programId | string | The address of the kodama program. |
grove | string | The address of the grove account. |
burner | string | The address of the burner account. |
platformConfigrequired | string | The grove's address under a second name. Each tree has its own LaunchLab platform config, which the build routes resolve. |
globalConfigrequired | string | The LaunchLab global config every curve uses. |
quoteMintrequired | string | The mint every curve is quoted in: wrapped SOL. |
quoteDecimalsrequired | number | Decimals of the quote, 9. |
baseDecimalsrequired | number | Decimals of every coin, 6. |
fee.totalrequired | ppm | The fee every trade leaves for the tree's split. |
fee.fruitrequired | ppm | The part of it that becomes fruit. |
fee.planterrequired | ppm | The part set aside for the planter. |
fee.burnerrequired | ppm | The part sent to the burner. |
fee.echorequired | ppm | The part of the burner's share that goes to the echo's kodama on a buy through an echo. |
echoMemoryDaysrequired | number | How many days a browser remembers an echo, kept apart for each tree. |
stageThresholds.sproutrequired | ppm | The share of the curve's SOL target at which a tree becomes Sprout. |
stageThresholds.saplingrequired | ppm | The share at which it becomes Sapling. |
dayLengthSecondsrequired | number | The length of a day. dayIndex is unix seconds divided by it, rounded down. |
curveFees.protocolrequired | ppm | Raydium's own fee on a curve trade. |
curveFees.platformrequired | ppm | The tree's fee on a curve trade, equal to fee.total. |
curveFees.creatorrequired | ppm | The curve's creator fee, 0. |
curve.supplyrequired | u64 amount | Every coin's supply, in coin base units. |
curve.totalBaseSellrequired | u64 amount | The coins the curve sells before graduation. |
curve.totalQuoteFundRaisingrequired | u64 amount | The lamports the curve raises before graduation. |
curve.migrateFeerequired | u64 amount | Lamports Raydium takes from the raise at migration. |
cpmm.indexrequired | number | The index of the Raydium CPMM fee tier graduated coins trade on. |
cpmm.ammConfigrequired | string | That tier's config address. |
cpmm.traderequired | ppm | The tier's trade fee. |
cpmm.protocolrequired | ppm | Raydium's protocol share of the trade fee. |
cpmm.fundrequired | ppm | Raydium's fund share of the trade fee. |
cpmm.creatorrequired | ppm | The tier's creator fee, which is the tree's fee after graduation. |
cpmm.creatorSharerequired | ppm | The tier's creator fee share rate. |
lookupTablesrequired | string[] | The address lookup tables every built transaction uses. |
What the fee is split into is told in Fees and where they go.
Errors: PROGRAM_UNAVAILABLE (409) while the service is waiting, UPSTREAM_UNAVAILABLE (502).
The feed
GET /v1/coins lists coins, a page at a time. Client method: coins(query).
| Parameter | Type | Meaning |
|---|---|---|
sort | string | The order, from the table below. Default new. |
stage | string | Only trees at this stage: seed, sprout, sapling or tree. |
phase | string | Only coins in this phase: curve, migrating or graduated. |
creator | string | Only coins this wallet planted. |
q | string | A search of 1 to 64 characters, trimmed. It matches a name or a symbol that contains it, in any case, or a mint that equals it. |
cursor | string | The page's start. See Pagination. |
limit | number | 1 to 100. Default 24. |
sort | Order | Label on the grove |
|---|---|---|
new | Newest coin first. | New |
watered | Most kodama watered today first. | Most watered today |
ripest | Most fruit today first. | Ripest |
biggest | Largest market cap first. | Biggest |
grown | Graduated trees first, then by SOL raised on the curve. | Grown |
marketCap | The same order as biggest. | |
volume | Most SOL traded in the last 24 hours first. | |
progress | Highest progressBps first. | |
lastTrade | Most recent trade first; coins never traded last. |
Coins equal in the sort are ordered by mint. Filters combine: sort=watered&stage=sprout is the most watered sprouts.
curl "https://api.kodama.example/v1/coins?sort=watered&stage=sprout&limit=2"import { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const page = await api.coins({ sort: 'watered', stage: 'sprout', limit: 2 })
const found = await api.coins({ q: 'dew' })The answer is a page: items holds coin objects, with page and asOf as Pagination has them.
Errors: VALIDATION_ERROR (400) for a parameter outside its values.
One coin
GET /v1/coins/:mint answers one coin with its tree and its live pool. Client method: coin(mint).
| Parameter | Type | Meaning |
|---|---|---|
mintrequired | string | The coin's mint, in the path. |
curl https://api.kodama.example/v1/coins/HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprfimport { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const coin = await api.coin('HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf')
console.log(coin.tree.stage, coin.tree.wateredToday, coin.state?.kind){
"mint": "HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf",
"pool": "ELVJWztp8cJP7qw6MoXsG98V8m4aJVzWzS3mpjJzuzpH",
"name": "Dewdrop",
"symbol": "DEW",
"description": "A little water, a little fruit, every morning.",
"image": "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%…",
"metadataUri": "ipfs://9tAysCNQJpkfyzJTdu8eDH43EPgtBBB5pFPZCCjTfAec",
"links": {
"website": "https://dewdrop.example.com"
},
"creator": "E1156D9eDrbgParGC45zdHreeVD35dhJenP6rwfwMS6t",
"createdAt": "2026-11-10T17:34:02.178Z",
"launchSignature": "3xYdLBoXxpcBP3uYTVQ6Ca1xVwukfkx4LLXAHFUQqHhdQQwuJTPKLVXpWhXKyNsSyH63TSmeAgDy9LRe4NnxSwCw",
"phase": "curve",
"progressBps": 551,
"raisedQuote": "1275502069",
"price": "0.000000030387052788",
"priceUsd": "0.000004630075233307",
"marketCap": "30.387052788",
"marketCapUsd": "4630.07523330756",
"volume24hQuote": "676254620",
"trades24h": 14,
"holders": 19,
"lastTradeAt": "2026-11-15T17:34:14.804Z",
"cpmmPool": null,
"graduatedAt": null,
"tree": {
"stage": "seed",
"planter": "E1156D9eDrbgParGC45zdHreeVD35dhJenP6rwfwMS6t",
"dayIndex": 20772,
"dayClosesAt": "2026-11-16T00:00:00.000Z",
"kodamaCount": 9,
"wateredToday": 4,
"coinsInTree": "4274527783550",
"todayFruitLamports": "10590695",
"carriedFruitLamports": "4",
"lifetimeFruitPaidLamports": "23999996",
"planterClaimedLamports": "4500000",
"planterWaitingLamports": "10147673",
"echoPendingLamports": "0",
"echoPayableLamports": "187500",
"echoReservedLamports": "0"
},
"state": {
"kind": "curve",
"virtualBase": "1073025605596382",
"virtualQuote": "30000852951",
"realBase": "43759778537352",
"realQuote": "1275502069",
"totalBaseSell": "793100000000000"
},
"stateSlot": 383600139,
"asOf": "2026-11-15T17:34:57.855Z"
}The answer is the coin object with three more fields:
| Field | Type | Meaning |
|---|---|---|
staterequired | object or null | The coin's pool, read live. null while the coin is migrating, and while the service is waiting or the chain read does not answer. |
stateSlotrequired | number | The slot state was read at. 0 when no live read was made. |
asOfrequired | string | When the coin was read. |
When state was read live, phase and tree.stage come from that same read.
Errors: NOT_FOUND (404) with No coin with this mint was launched on this platform. A coin planted moments ago answers NOT_FOUND with retryable: true, retryAfterSeconds: 3 and This coin was just launched and is being indexed. until the index holds it. VALIDATION_ERROR (400) for a mint that is not an address.
The coin object
Every route that answers a coin answers this shape.
| Field | Type | Meaning |
|---|---|---|
mintrequired | string | The coin's mint. |
poolrequired | string | The coin's Raydium LaunchLab pool. |
namerequired | string | The coin's name. |
symbolrequired | string | Its ticker. |
descriptionrequired | string | Its description. Empty when none was given. |
imagerequired | string or null | The image's URL. |
metadataUrirequired | string | The metadata URI written on chain. |
linksrequired | object | website, x and telegram, each an http or https URL of at most 200 characters, each present only when given. |
creatorrequired | string | The creator the launch recorded. The planter is tree.planter. |
createdAtrequired | string | When the coin was planted. |
launchSignaturerequired | string | The signature of the transaction that planted it. |
phaserequired | string | curve: trading on the curve. migrating: the curve sold out and the coin is moving to its pool; nothing trades. graduated: trading on its Raydium CPMM pool. |
progressBpsrequired | bps | The share of the curve's coins sold, 0 to 10,000. |
raisedQuoterequired | u64 amount | Lamports raised on the curve so far. |
pricerequired | decimal | SOL per whole coin. |
priceUsdrequired | decimal or null | USD per whole coin. |
marketCaprequired | decimal | The whole supply at price, in whole SOL. |
marketCapUsdrequired | decimal or null | The same in USD. |
volume24hQuoterequired | amount | Lamports traded in the last 24 hours. |
trades24hrequired | number | Trades in the last 24 hours. |
holdersrequired | number | Wallets holding the coin. |
lastTradeAtrequired | string or null | When it last traded. |
cpmmPoolrequired | string or null | The graduated pool's address. null before graduation. |
graduatedAtrequired | string or null | When it graduated. |
treerequired | object | The coin's tree. |
The tree object
Every coin carries its tree. SOL fields are lamports and coin fields are coin base units.
| Field | Type | Meaning |
|---|---|---|
stagerequired | string | seed, sprout, sapling or tree. A graduated coin is tree; before that the stage follows the SOL raised against stageThresholds. |
kodamaCountrequired | number | Wallets with coins in the tree. |
wateredTodayrequired | number | Kodama who have watered in the tree's open day. |
coinsInTreerequired | u64 amount | All coins moved into the tree. |
todayFruitLamportsrequired | u64 amount | Fruit gathered in the open day so far. |
carriedFruitLamportsrequired | u64 amount | Fruit carried into the open day from before. |
dayIndexrequired | number | The tree's open day. On chain it stays on an earlier day until an action or a close_day, which anyone may send, closes that day. |
dayClosesAtrequired | string | The end of the open day. |
lifetimeFruitPaidLamportsrequired | amount | All fruit kodama have picked from this tree. |
planterrequired | string | The wallet that planted the coin. |
planterClaimedLamportsrequired | amount | The planter's share claimed so far. |
planterWaitingLamportsrequired | u64 amount | The planter's share waiting to be claimed. |
echoPendingLamportsrequired | u64 amount | Echo shares recorded by buys and not yet assigned to their wallets. |
echoPayableLamportsrequired | u64 amount | Echo shares assigned and ready to claim. |
echoReservedLamportsrequired | u64 amount | Harvested SOL held for pending echo shares, not yet assigned to wallets. It belongs to the tree's echoes together, not to one wallet. |
Stages are told in The tree and its stages, the day and its fruit in Days and fruit, echo shares in Echoes.
The pool state
state on one coin is the pool as the chain holds it, enough to quote a trade without another request. kind tells the two shapes apart.
On the curve:
| Field | Type | Meaning |
|---|---|---|
kindrequired | string | curve. |
virtualBaserequired | u64 amount | The curve's virtual coin reserve. |
virtualQuoterequired | u64 amount | Its virtual lamport reserve. |
realBaserequired | u64 amount | Coins sold so far. |
realQuoterequired | u64 amount | Lamports raised so far. |
totalBaseSellrequired | u64 amount | Coins the curve sells in all. |
After graduation:
curl https://api.kodama.example/v1/coins/EsVoCQkjhrWwzPrAfggqZFexm4qyqBWRkg3oMqnTiGbU| Field | Type | Meaning |
|---|---|---|
kindrequired | string | cpmm. |
poolrequired | string | The pool's address. |
token0Mintrequired | string | The pool's first token. |
token1Mintrequired | string | Its second token. One of the two is the coin, the other wrapped SOL. |
reserve0required | u64 amount | The first token's reserve, net of the fees the pool still holds. |
reserve1required | u64 amount | The second token's reserve, net the same way. |
creatorFeeOnrequired | number | Which side pays the creator fee: 0 both tokens, 1 token 0 only, 2 token 1 only. |
creatorFeeEnabledrequired | boolean | false when the pool charges no creator fee, whatever its tier's rate. |
Trades
GET /v1/coins/:mint/trades lists a coin's trades, newest first. Client method: trades(mint, query).
| Parameter | Type | Meaning |
|---|---|---|
mintrequired | string | The coin's mint, in the path. |
cursor | string | The page's start. |
limit | number | 1 to 100. Default 24. |
curl "https://api.kodama.example/v1/coins/HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf/trades?limit=2"import { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const trades = await api.trades('HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf', { limit: 2 }){
"items": [
{
"signature": "2Wd1oDTewjo4TZBvPqRNjJfoguYWM6Ziav2v3MH79QfgFur6qGatq6f1twmn4eYtcMALvgWpz8JEihZPqvZZ5zYD",
"mint": "HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf",
"wallet": "B2iFKkzwkJZQdwJnPR4PoyVxFrHXyBJdVYUNXrZwjNFN",
"side": "buy",
"base": "12254219024395",
"quote": "376074000",
"price": "0.000000030029527648",
"priceUsd": "0.000004575599127725",
"venue": "curve",
"slot": 383600031,
"at": "2026-11-15T17:34:14.804Z"
},
…
],
"page": {
"nextCursor": "2",
"hasMore": true
},
"asOf": "2026-11-15T17:34:57.861Z"
}| Field | Type | Meaning |
|---|---|---|
signaturerequired | string | The trade's transaction. |
mintrequired | string | The coin. |
walletrequired | string | The trader. |
siderequired | string | buy or sell. |
baserequired | u64 amount | Coins bought or sold. |
quoterequired | u64 amount | Lamports the trader paid on a buy, fees included, or received on a sell, fees taken. |
pricerequired | decimal | SOL per whole coin at this trade. |
priceUsdrequired | decimal or null | The same in USD. |
venuerequired | string | curve or cpmm. |
slotrequired | number | The slot it landed in. |
atrequired | string | When it landed. |
A mint with no trades, known or not, answers an empty page. Errors: VALIDATION_ERROR (400).
Candles
GET /v1/coins/:mint/candles answers a coin's price candles, oldest first. Client method: candles(mint, query).
| Parameter | Type | Meaning |
|---|---|---|
mintrequired | string | The coin's mint, in the path. |
interval | string | 1m, 5m, 15m, 1h, 4h or 1d. Default 5m. |
from | string | The earliest time, floored to the interval. Default: 300 intervals before to. |
to | string | The latest time. Default: now. |
unit | string | quote for SOL per coin, usd for USD per coin. Default quote. |
One answer holds at most 1,000 candles. An interval with no trade has no candle. With unit=usd, a candle with no recorded SOL price is left out.
curl "https://api.kodama.example/v1/coins/HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf/candles?interval=1h"import { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const candles = await api.candles('HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf', { interval: '1h' }){
"mint": "HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf",
"interval": "1h",
"unit": "quote",
"items": [
{
"time": "2026-11-10T19:00:00.000Z",
"open": "0.000000028006913426",
"high": "0.000000028006913426",
"low": "0.000000028006913426",
"close": "0.000000028006913426",
"volumeQuote": "51282289",
"trades": 1
},
…
],
"asOf": "2026-11-15T17:34:57.864Z"
}| Field | Type | Meaning |
|---|---|---|
mintrequired | string | The coin. |
intervalrequired | string | The interval asked for. |
unitrequired | string | The unit asked for. |
items[].timerequired | string | The candle's start. |
items[].openrequired | decimal | The first price in it. |
items[].highrequired | decimal | The highest. |
items[].lowrequired | decimal | The lowest. |
items[].closerequired | decimal | The last. |
items[].volumeQuoterequired | amount | Lamports traded in it. |
items[].tradesrequired | number | Trades in it. |
asOfrequired | string | When it was read. |
A mint with no trades answers empty items. Errors: VALIDATION_ERROR (400).
Holders
GET /v1/coins/:mint/holders answers the 100 largest holders of a coin, largest first. Client method: holders(mint).
curl https://api.kodama.example/v1/coins/HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf/holdersimport { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const holders = await api.holders('HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf')
const people = holders.items.filter((holder) => !holder.isPool){
"mint": "HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf",
"items": [
{
"wallet": "WLHv2UAZm6z4KyaaELi5pjdbJh6RESMva1Rnn8pJVVh",
"amount": "956240221462648",
"shareBps": 9562,
"isPool": true,
"isCreator": false
},
{
"wallet": "B2iFKkzwkJZQdwJnPR4PoyVxFrHXyBJdVYUNXrZwjNFN",
"amount": "12326676075281",
"shareBps": 123,
"isPool": false,
"isCreator": false
},
…
],
"total": 20,
"asOf": "2026-11-15T17:34:57.867Z"
}| Field | Type | Meaning |
|---|---|---|
mintrequired | string | The coin. |
items[].walletrequired | string | The holder. |
items[].amountrequired | u64 amount | Coins it holds. |
items[].shareBpsrequired | bps | Its share of the supply. |
items[].isPoolrequired | boolean | true for the curve's vault, the graduated pool's vault and the tree's own vault of moved-in coins: holdings that are not a person's. |
items[].isCreatorrequired | boolean | true for the planter. |
totalrequired | number | How many wallets hold the coin. |
asOfrequired | string | When the holders were read. |
Errors: NOT_FOUND (404) for a mint that was not launched here, as on one coin. VALIDATION_ERROR (400).
Grove totals
GET /v1/grove answers the totals of every tree together. Client method: grove().
curl https://api.kodama.example/v1/groveimport { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const grove = await api.grove(){
"treesPlanted": 14,
"kodamaCount": 116,
"fruitPaidLamports": "2499999945",
"planterPaidLamports": "472500000",
"echoPaidLamports": "6562500",
"feesCollectedLamports": "8993768599",
"burnerSentLamports": "1871780231",
"burnerBalanceLamports": "1871780231",
"asOf": "2026-11-15T17:34:57.870Z"
}| Field | Type | Meaning |
|---|---|---|
treesPlantedrequired | number | Trees planted. |
kodamaCountrequired | number | Kodama records with coins in a tree. A wallet living in two trees counts twice. |
feesCollectedLamportsrequired | amount | All fees harvested into trees. |
fruitPaidLamportsrequired | amount | Fruit picked by kodama. Fruit set aside at a day's close and not yet picked is not in it. |
planterPaidLamportsrequired | amount | Planters' shares claimed. |
echoPaidLamportsrequired | amount | Echo shares claimed. |
burnerSentLamportsrequired | amount | SOL sent to the burner. |
burnerBalanceLamportsrequired | amount | What the burner holds. |
asOfrequired | string | When it was read. |
The fruit board
GET /v1/fruit answers where the fruit went: totals by day, the trees whose kodama picked the most today, and the days closed most recently. Client method: fruit().
curl https://api.kodama.example/v1/fruitimport { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const board = await api.fruit()
const today = board.days.find((day) => day.dayIndex === board.dayIndex)| Field | Type | Meaning |
|---|---|---|
dayIndexrequired | number | The current UTC day. |
daysrequired | array | Totals per day, newest first, up to 30 days. Paid amounts are grouped by the day the SOL moved. |
days[].dayIndexrequired | number | The day. |
days[].feesCollectedLamportsrequired | amount | Fees harvested that day. |
days[].fruitPaidLamportsrequired | amount | Fruit picked that day. |
days[].planterPaidLamportsrequired | amount | Planters' shares claimed that day. |
days[].echoPaidLamportsrequired | amount | Echo shares claimed that day. |
days[].burnerSentLamportsrequired | amount | SOL sent to the burner that day. |
topTreesrequired | array | Up to ten trees with the most fruit picked today, most first. |
topTrees[].coinrequired | object | The tree's coin. |
topTrees[].fruitPaidLamportsrequired | amount | Fruit picked from it today. |
recentDaysrequired | array | The 20 days closed most recently, across all trees. |
recentDays[].coinrequired | object | The tree's coin. |
recentDays[].dayrequired | object | The closed day. |
asOfrequired | string | When it was read. |