API
Kodama and days
The read routes about who lives in a tree and what its days paid: a coin's kodama, a coin's closed days, a wallet's kodama records with fruit ready and planter's shares, a wallet's echoes and its portfolio.
Kodama of a coin
GET /v1/coins/:mint/kodama lists the wallets with coins in a tree, most coins first. Client method: kodama(mint, query).
| Parameter | Type | Meaning |
|---|---|---|
mintrequired | string | The coin's mint, in the path. |
cursor | string | The page's start. See Pagination. |
limit | number | 1 to 100. Default 24. |
curl "https://api.kodama.example/v1/coins/HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf/kodama?limit=3"import { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const kodama = await api.kodama('HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf', { limit: 3 })
const awake = kodama.items.filter((k) => k.wateredToday){
"items": [
{
"wallet": "AtNpubTAmbBB6UrMXiJ85fdgsshLWYXR3z1xka9QHyPa",
"coinsInTree": "1206371213399",
"coinsCountingToday": "1206371213399",
"wateredToday": true
},
{
"wallet": "E8LgfoLD2PcSFg2N5Tj1VAEKH23RwEqECBGyfkXhLK9P",
"coinsInTree": "1029582425468",
"coinsCountingToday": "1029582425468",
"wateredToday": false
},
{
"wallet": "ARndu241joKJUuAFKhu6dSj8RfuNELWgvSCwYQzfXf6V",
"coinsInTree": "562108289508",
"coinsCountingToday": "562108289508",
"wateredToday": false
}
],
"page": {
"nextCursor": "3",
"hasMore": true
},
"asOf": "2026-11-15T17:34:57.879Z"
}| Field | Type | Meaning |
|---|---|---|
walletrequired | string | The kodama's wallet. |
coinsInTreerequired | u64 amount | Coins it has in the tree. |
coinsCountingTodayrequired | u64 amount | The part of them that counts in today's split. Coins moved in today count from tomorrow. |
wateredTodayrequired | boolean | Whether it has watered today. |
A wallet that moved all its coins out is not listed. Equal amounts are ordered by wallet.
Errors: NOT_FOUND (404) for a mint that was not launched here; a coin planted moments ago answers it with retryable: true and retryAfterSeconds: 3. VALIDATION_ERROR (400).
Days of a coin
GET /v1/coins/:mint/days lists a tree's closed days, newest first. Client method: days(mint, query). The open day is not in the list; it is on the coin's tree object.
| 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/days?limit=2"import { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const days = await api.days('HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf', { limit: 2 }){
"items": [
{
"dayIndex": 20771,
"fruitLamports": "12000004",
"wateredKodama": 8,
"wateredCoins": "4274527783550",
"fruitPerMillionCoinsLamports": "2807328",
"carriedFruitLamports": "4",
"closedAt": "2026-11-15T00:00:00.000Z"
},
{
"dayIndex": 20770,
"fruitLamports": "12000004",
"wateredKodama": 8,
"wateredCoins": "4274527783550",
"fruitPerMillionCoinsLamports": "2807328",
"carriedFruitLamports": "4",
"closedAt": "2026-11-14T00:00:00.000Z"
}
],
"page": {
"nextCursor": "2",
"hasMore": true
},
"asOf": "2026-11-15T17:34:57.883Z"
}| Field | Type | Meaning |
|---|---|---|
dayIndexrequired | number | The day. |
fruitLamportsrequired | u64 amount | The fruit the day had to split: its own, plus what was carried into it. |
wateredKodamarequired | number | Kodama who watered that day. |
wateredCoinsrequired | u64 amount | Their counted coins together. |
fruitPerMillionCoinsLamportsrequired | amount | Lamports paid per 1,000,000 whole coins, rounded down. 0 on a day nobody watered. |
carriedFruitLamportsrequired | u64 amount | Fruit carried on to the next day: all of it when nobody watered, otherwise the lamports the split left over. |
closedAtrequired | string | When the day closed. |
A kodama's fruit from a day is its counted coins times the day's rate. In the sample, a kodama with 1,000,000 whole coins counted on day 20771 gets 2,807,328 lamports. The split is told in Days and fruit.
Errors: the same as kodama of a coin.
Kodama records of a wallet
GET /v1/wallets/:wallet/kodama answers every tree a wallet lives in, the fruit it can pick, and the trees it planted with their planter's shares. Client method: walletKodama(wallet).
| Parameter | Type | Meaning |
|---|---|---|
walletrequired | string | The wallet's address, in the path. |
curl https://api.kodama.example/v1/wallets/CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787/kodamaimport { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const mine = await api.walletKodama('CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787')
const toWater = mine.records.filter((r) => !r.wateredToday && r.coinsCountingToday !== '0').map((r) => r.coin.mint)
const toPick = mine.records.filter((r) => r.fruitReadyLamports !== '0').map((r) => r.coin.mint)
const toClaim = mine.planted.filter((coin) => coin.tree.planterWaitingLamports !== '0').map((coin) => coin.mint)| Field | Type | Meaning |
|---|---|---|
walletrequired | string | The wallet asked for. |
recordsrequired | array | One record per tree the wallet has coins in or fruit ready in. |
records[].walletrequired | string | The wallet. |
records[].coinrequired | object | The tree's coin. |
records[].coinsInTreerequired | u64 amount | Coins the wallet has in the tree. |
records[].coinsCountingTodayrequired | u64 amount | The part of them that counts in today's split. |
records[].newerCoinsCountFromDayrequired | number or null | The dayIndex from which the coins moved in most recently count. null when every coin in the tree already counts. |
records[].wateredTodayrequired | boolean | Whether the wallet has watered this tree today. |
records[].fruitReadyLamportsrequired | u64 amount | Fruit from closed days, ready to pick. |
plantedrequired | array | The coins this wallet planted. Each planter's share is on its tree: planterWaitingLamports and planterClaimedLamports. |
totals.treesrequired | number | Records with coins in the tree. |
totals.wateredTodayrequired | number | Records watered today. |
totals.fruitReadyLamportsrequired | amount | Fruit ready across all records. |
totals.planterWaitingLamportsrequired | amount | Planter's shares waiting across planted. |
totals.planterClaimedLamportsrequired | amount | Planter's shares claimed across planted. |
asOfrequired | string | When it was read. |
A record stays in the list after the wallet moves out for as long as it has fruit to pick. A wallet the platform has never seen answers empty records and planted with zero totals. The three lists the TypeScript sample builds are the mints of a water build, a pick build and the mints to claim.
Errors: VALIDATION_ERROR (400) for a wallet that is not an address.
Echoes of a wallet
GET /v1/wallets/:wallet/echoes answers what a wallet's echoes brought, tree by tree. Client method: walletEchoes(wallet).
| Parameter | Type | Meaning |
|---|---|---|
walletrequired | string | The wallet's address, in the path. |
curl https://api.kodama.example/v1/wallets/CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787/echoesimport { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const mine = await api.walletEchoes('CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787')
const toClaim = mine.echoes.filter((echo) => echo.payableLamports !== '0').map((echo) => echo.coin.mint)| Field | Type | Meaning |
|---|---|---|
walletrequired | string | The wallet asked for. |
echoesrequired | array | One entry per tree the wallet is a kodama of, or has had a buy through its echo in. |
echoes[].coinrequired | object | The tree's coin. |
echoes[].isKodamarequired | boolean | Whether the wallet has coins in the tree now. An echo only earns while it does. |
echoes[].buysCountrequired | number | Buys made through this wallet's echo. |
echoes[].buyVolumeLamportsrequired | amount | SOL those buys spent. |
echoes[].pendingLamportsrequired | amount | Echo share recorded by those buys and not yet assigned to the wallet. Not claimable yet. |
echoes[].payableLamportsrequired | amount | Echo share assigned and ready to claim. |
echoes[].claimedLamportsrequired | amount | Echo share claimed so far. |
totalsrequired | object | buysCount, buyVolumeLamports, pendingLamports, payableLamports and claimedLamports summed over echoes. |
asOfrequired | string | When it was read. |
What an echo earned stays readable, and claimable, after the wallet moves out of the tree. A tree's echoReservedLamports is SOL held for all of its pending echo shares together; a claim build assigns the wallet its part of it before paying. Echoes are told in Echoes.
Errors: VALIDATION_ERROR (400).
The portfolio
GET /v1/portfolio/:wallet answers the coins in a wallet and the coins it planted. Client method: portfolio(wallet).
| Parameter | Type | Meaning |
|---|---|---|
walletrequired | string | The wallet's address, in the path. |
curl https://api.kodama.example/v1/portfolio/CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787import { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const portfolio = await api.portfolio('CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787')
const worth = portfolio.positions.reduce((sum, position) => sum + BigInt(position.value), 0n)| Field | Type | Meaning |
|---|---|---|
walletrequired | string | The wallet asked for. |
positionsrequired | array | One position per coin the wallet holds, up to 200. |
positions[].coinrequired | object | The coin. |
positions[].amountrequired | u64 amount | Coins in the wallet. Coins moved into a tree are on the wallet's kodama records. |
positions[].valuerequired | amount | What amount is worth at the coin's price, in lamports. |
positions[].costrequired | amount | Lamports spent on the coins still held. |
positions[].realizedrequired | signed amount | Lamports gained or lost on the coins sold. Negative for a loss. |
launchedrequired | array | The coins this wallet planted, newest first, up to 100. |
asOfrequired | string | When it was read. |
A wallet that holds nothing answers empty positions and launched.
Errors: VALIDATION_ERROR (400).