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().

Shell
curl https://api.kodama.example/v1/platform
JSON
{
  "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"
  ]
}
FieldTypeMeaning
namerequiredstringThe platform's name.
clusterrequiredstringmainnet, devnet or localnet.
programIdstringThe address of the kodama program.
grovestringThe address of the grove account.
burnerstringThe address of the burner account.
platformConfigrequiredstringThe grove's address under a second name. Each tree has its own LaunchLab platform config, which the build routes resolve.
globalConfigrequiredstringThe LaunchLab global config every curve uses.
quoteMintrequiredstringThe mint every curve is quoted in: wrapped SOL.
quoteDecimalsrequirednumberDecimals of the quote, 9.
baseDecimalsrequirednumberDecimals of every coin, 6.
fee.totalrequiredppmThe fee every trade leaves for the tree's split.
fee.fruitrequiredppmThe part of it that becomes fruit.
fee.planterrequiredppmThe part set aside for the planter.
fee.burnerrequiredppmThe part sent to the burner.
fee.echorequiredppmThe part of the burner's share that goes to the echo's kodama on a buy through an echo.
echoMemoryDaysrequirednumberHow many days a browser remembers an echo, kept apart for each tree.
stageThresholds.sproutrequiredppmThe share of the curve's SOL target at which a tree becomes Sprout.
stageThresholds.saplingrequiredppmThe share at which it becomes Sapling.
dayLengthSecondsrequirednumberThe length of a day. dayIndex is unix seconds divided by it, rounded down.
curveFees.protocolrequiredppmRaydium's own fee on a curve trade.
curveFees.platformrequiredppmThe tree's fee on a curve trade, equal to fee.total.
curveFees.creatorrequiredppmThe curve's creator fee, 0.
curve.supplyrequiredu64 amountEvery coin's supply, in coin base units.
curve.totalBaseSellrequiredu64 amountThe coins the curve sells before graduation.
curve.totalQuoteFundRaisingrequiredu64 amountThe lamports the curve raises before graduation.
curve.migrateFeerequiredu64 amountLamports Raydium takes from the raise at migration.
cpmm.indexrequirednumberThe index of the Raydium CPMM fee tier graduated coins trade on.
cpmm.ammConfigrequiredstringThat tier's config address.
cpmm.traderequiredppmThe tier's trade fee.
cpmm.protocolrequiredppmRaydium's protocol share of the trade fee.
cpmm.fundrequiredppmRaydium's fund share of the trade fee.
cpmm.creatorrequiredppmThe tier's creator fee, which is the tree's fee after graduation.
cpmm.creatorSharerequiredppmThe tier's creator fee share rate.
lookupTablesrequiredstring[]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).

ParameterTypeMeaning
sortstringThe order, from the table below. Default new.
stagestringOnly trees at this stage: seed, sprout, sapling or tree.
phasestringOnly coins in this phase: curve, migrating or graduated.
creatorstringOnly coins this wallet planted.
qstringA 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.
cursorstringThe page's start. See Pagination.
limitnumber1 to 100. Default 24.
sortOrderLabel on the grove
newNewest coin first.New
wateredMost kodama watered today first.Most watered today
ripestMost fruit today first.Ripest
biggestLargest market cap first.Biggest
grownGraduated trees first, then by SOL raised on the curve.Grown
marketCapThe same order as biggest.
volumeMost SOL traded in the last 24 hours first.
progressHighest progressBps first.
lastTradeMost 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.

Shell
curl "https://api.kodama.example/v1/coins?sort=watered&stage=sprout&limit=2"

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).

ParameterTypeMeaning
mintrequiredstringThe coin's mint, in the path.
Shell
curl https://api.kodama.example/v1/coins/HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf
JSON
{
  "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:

FieldTypeMeaning
staterequiredobject or nullThe coin's pool, read live. null while the coin is migrating, and while the service is waiting or the chain read does not answer.
stateSlotrequirednumberThe slot state was read at. 0 when no live read was made.
asOfrequiredstringWhen 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.

FieldTypeMeaning
mintrequiredstringThe coin's mint.
poolrequiredstringThe coin's Raydium LaunchLab pool.
namerequiredstringThe coin's name.
symbolrequiredstringIts ticker.
descriptionrequiredstringIts description. Empty when none was given.
imagerequiredstring or nullThe image's URL.
metadataUrirequiredstringThe metadata URI written on chain.
linksrequiredobjectwebsite, x and telegram, each an http or https URL of at most 200 characters, each present only when given.
creatorrequiredstringThe creator the launch recorded. The planter is tree.planter.
createdAtrequiredstringWhen the coin was planted.
launchSignaturerequiredstringThe signature of the transaction that planted it.
phaserequiredstringcurve: 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.
progressBpsrequiredbpsThe share of the curve's coins sold, 0 to 10,000.
raisedQuoterequiredu64 amountLamports raised on the curve so far.
pricerequireddecimalSOL per whole coin.
priceUsdrequireddecimal or nullUSD per whole coin.
marketCaprequireddecimalThe whole supply at price, in whole SOL.
marketCapUsdrequireddecimal or nullThe same in USD.
volume24hQuoterequiredamountLamports traded in the last 24 hours.
trades24hrequirednumberTrades in the last 24 hours.
holdersrequirednumberWallets holding the coin.
lastTradeAtrequiredstring or nullWhen it last traded.
cpmmPoolrequiredstring or nullThe graduated pool's address. null before graduation.
graduatedAtrequiredstring or nullWhen it graduated.
treerequiredobjectThe coin's tree.

The tree object

Every coin carries its tree. SOL fields are lamports and coin fields are coin base units.

FieldTypeMeaning
stagerequiredstringseed, sprout, sapling or tree. A graduated coin is tree; before that the stage follows the SOL raised against stageThresholds.
kodamaCountrequirednumberWallets with coins in the tree.
wateredTodayrequirednumberKodama who have watered in the tree's open day.
coinsInTreerequiredu64 amountAll coins moved into the tree.
todayFruitLamportsrequiredu64 amountFruit gathered in the open day so far.
carriedFruitLamportsrequiredu64 amountFruit carried into the open day from before.
dayIndexrequirednumberThe 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.
dayClosesAtrequiredstringThe end of the open day.
lifetimeFruitPaidLamportsrequiredamountAll fruit kodama have picked from this tree.
planterrequiredstringThe wallet that planted the coin.
planterClaimedLamportsrequiredamountThe planter's share claimed so far.
planterWaitingLamportsrequiredu64 amountThe planter's share waiting to be claimed.
echoPendingLamportsrequiredu64 amountEcho shares recorded by buys and not yet assigned to their wallets.
echoPayableLamportsrequiredu64 amountEcho shares assigned and ready to claim.
echoReservedLamportsrequiredu64 amountHarvested 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 Dewdrop tree of the sample above: a seed with nine kodama, four of them watered today.

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:

FieldTypeMeaning
kindrequiredstringcurve.
virtualBaserequiredu64 amountThe curve's virtual coin reserve.
virtualQuoterequiredu64 amountIts virtual lamport reserve.
realBaserequiredu64 amountCoins sold so far.
realQuoterequiredu64 amountLamports raised so far.
totalBaseSellrequiredu64 amountCoins the curve sells in all.

After graduation:

Shell
curl https://api.kodama.example/v1/coins/EsVoCQkjhrWwzPrAfggqZFexm4qyqBWRkg3oMqnTiGbU
FieldTypeMeaning
kindrequiredstringcpmm.
poolrequiredstringThe pool's address.
token0MintrequiredstringThe pool's first token.
token1MintrequiredstringIts second token. One of the two is the coin, the other wrapped SOL.
reserve0requiredu64 amountThe first token's reserve, net of the fees the pool still holds.
reserve1requiredu64 amountThe second token's reserve, net the same way.
creatorFeeOnrequirednumberWhich side pays the creator fee: 0 both tokens, 1 token 0 only, 2 token 1 only.
creatorFeeEnabledrequiredbooleanfalse 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).

ParameterTypeMeaning
mintrequiredstringThe coin's mint, in the path.
cursorstringThe page's start.
limitnumber1 to 100. Default 24.
Shell
curl "https://api.kodama.example/v1/coins/HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf/trades?limit=2"
JSON
{
  "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"
}
FieldTypeMeaning
signaturerequiredstringThe trade's transaction.
mintrequiredstringThe coin.
walletrequiredstringThe trader.
siderequiredstringbuy or sell.
baserequiredu64 amountCoins bought or sold.
quoterequiredu64 amountLamports the trader paid on a buy, fees included, or received on a sell, fees taken.
pricerequireddecimalSOL per whole coin at this trade.
priceUsdrequireddecimal or nullThe same in USD.
venuerequiredstringcurve or cpmm.
slotrequirednumberThe slot it landed in.
atrequiredstringWhen 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).

ParameterTypeMeaning
mintrequiredstringThe coin's mint, in the path.
intervalstring1m, 5m, 15m, 1h, 4h or 1d. Default 5m.
fromstringThe earliest time, floored to the interval. Default: 300 intervals before to.
tostringThe latest time. Default: now.
unitstringquote 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.

Shell
curl "https://api.kodama.example/v1/coins/HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf/candles?interval=1h"
JSON
{
  "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"
}
FieldTypeMeaning
mintrequiredstringThe coin.
intervalrequiredstringThe interval asked for.
unitrequiredstringThe unit asked for.
items[].timerequiredstringThe candle's start.
items[].openrequireddecimalThe first price in it.
items[].highrequireddecimalThe highest.
items[].lowrequireddecimalThe lowest.
items[].closerequireddecimalThe last.
items[].volumeQuoterequiredamountLamports traded in it.
items[].tradesrequirednumberTrades in it.
asOfrequiredstringWhen 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).

Shell
curl https://api.kodama.example/v1/coins/HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf/holders
JSON
{
  "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"
}
FieldTypeMeaning
mintrequiredstringThe coin.
items[].walletrequiredstringThe holder.
items[].amountrequiredu64 amountCoins it holds.
items[].shareBpsrequiredbpsIts share of the supply.
items[].isPoolrequiredbooleantrue 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[].isCreatorrequiredbooleantrue for the planter.
totalrequirednumberHow many wallets hold the coin.
asOfrequiredstringWhen 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().

Shell
curl https://api.kodama.example/v1/grove
JSON
{
  "treesPlanted": 14,
  "kodamaCount": 116,
  "fruitPaidLamports": "2499999945",
  "planterPaidLamports": "472500000",
  "echoPaidLamports": "6562500",
  "feesCollectedLamports": "8993768599",
  "burnerSentLamports": "1871780231",
  "burnerBalanceLamports": "1871780231",
  "asOf": "2026-11-15T17:34:57.870Z"
}
FieldTypeMeaning
treesPlantedrequirednumberTrees planted.
kodamaCountrequirednumberKodama records with coins in a tree. A wallet living in two trees counts twice.
feesCollectedLamportsrequiredamountAll fees harvested into trees.
fruitPaidLamportsrequiredamountFruit picked by kodama. Fruit set aside at a day's close and not yet picked is not in it.
planterPaidLamportsrequiredamountPlanters' shares claimed.
echoPaidLamportsrequiredamountEcho shares claimed.
burnerSentLamportsrequiredamountSOL sent to the burner.
burnerBalanceLamportsrequiredamountWhat the burner holds.
asOfrequiredstringWhen 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().

Shell
curl https://api.kodama.example/v1/fruit
FieldTypeMeaning
dayIndexrequirednumberThe current UTC day.
daysrequiredarrayTotals per day, newest first, up to 30 days. Paid amounts are grouped by the day the SOL moved.
days[].dayIndexrequirednumberThe day.
days[].feesCollectedLamportsrequiredamountFees harvested that day.
days[].fruitPaidLamportsrequiredamountFruit picked that day.
days[].planterPaidLamportsrequiredamountPlanters' shares claimed that day.
days[].echoPaidLamportsrequiredamountEcho shares claimed that day.
days[].burnerSentLamportsrequiredamountSOL sent to the burner that day.
topTreesrequiredarrayUp to ten trees with the most fruit picked today, most first.
topTrees[].coinrequiredobjectThe tree's coin.
topTrees[].fruitPaidLamportsrequiredamountFruit picked from it today.
recentDaysrequiredarrayThe 20 days closed most recently, across all trees.
recentDays[].coinrequiredobjectThe tree's coin.
recentDays[].dayrequiredobjectThe closed day.
asOfrequiredstringWhen it was read.

Where to go next