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

ParameterTypeMeaning
mintrequiredstringThe coin's mint, in the path.
cursorstringThe page's start. See Pagination.
limitnumber1 to 100. Default 24.
Shell
curl "https://api.kodama.example/v1/coins/HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf/kodama?limit=3"
JSON
{
  "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"
}
FieldTypeMeaning
walletrequiredstringThe kodama's wallet.
coinsInTreerequiredu64 amountCoins it has in the tree.
coinsCountingTodayrequiredu64 amountThe part of them that counts in today's split. Coins moved in today count from tomorrow.
wateredTodayrequiredbooleanWhether 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.

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/days?limit=2"
JSON
{
  "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"
}
FieldTypeMeaning
dayIndexrequirednumberThe day.
fruitLamportsrequiredu64 amountThe fruit the day had to split: its own, plus what was carried into it.
wateredKodamarequirednumberKodama who watered that day.
wateredCoinsrequiredu64 amountTheir counted coins together.
fruitPerMillionCoinsLamportsrequiredamountLamports paid per 1,000,000 whole coins, rounded down. 0 on a day nobody watered.
carriedFruitLamportsrequiredu64 amountFruit carried on to the next day: all of it when nobody watered, otherwise the lamports the split left over.
closedAtrequiredstringWhen 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).

ParameterTypeMeaning
walletrequiredstringThe wallet's address, in the path.
Shell
curl https://api.kodama.example/v1/wallets/CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787/kodama
FieldTypeMeaning
walletrequiredstringThe wallet asked for.
recordsrequiredarrayOne record per tree the wallet has coins in or fruit ready in.
records[].walletrequiredstringThe wallet.
records[].coinrequiredobjectThe tree's coin.
records[].coinsInTreerequiredu64 amountCoins the wallet has in the tree.
records[].coinsCountingTodayrequiredu64 amountThe part of them that counts in today's split.
records[].newerCoinsCountFromDayrequirednumber or nullThe dayIndex from which the coins moved in most recently count. null when every coin in the tree already counts.
records[].wateredTodayrequiredbooleanWhether the wallet has watered this tree today.
records[].fruitReadyLamportsrequiredu64 amountFruit from closed days, ready to pick.
plantedrequiredarrayThe coins this wallet planted. Each planter's share is on its tree: planterWaitingLamports and planterClaimedLamports.
totals.treesrequirednumberRecords with coins in the tree.
totals.wateredTodayrequirednumberRecords watered today.
totals.fruitReadyLamportsrequiredamountFruit ready across all records.
totals.planterWaitingLamportsrequiredamountPlanter's shares waiting across planted.
totals.planterClaimedLamportsrequiredamountPlanter's shares claimed across planted.
asOfrequiredstringWhen 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).

ParameterTypeMeaning
walletrequiredstringThe wallet's address, in the path.
Shell
curl https://api.kodama.example/v1/wallets/CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787/echoes
FieldTypeMeaning
walletrequiredstringThe wallet asked for.
echoesrequiredarrayOne entry per tree the wallet is a kodama of, or has had a buy through its echo in.
echoes[].coinrequiredobjectThe tree's coin.
echoes[].isKodamarequiredbooleanWhether the wallet has coins in the tree now. An echo only earns while it does.
echoes[].buysCountrequirednumberBuys made through this wallet's echo.
echoes[].buyVolumeLamportsrequiredamountSOL those buys spent.
echoes[].pendingLamportsrequiredamountEcho share recorded by those buys and not yet assigned to the wallet. Not claimable yet.
echoes[].payableLamportsrequiredamountEcho share assigned and ready to claim.
echoes[].claimedLamportsrequiredamountEcho share claimed so far.
totalsrequiredobjectbuysCount, buyVolumeLamports, pendingLamports, payableLamports and claimedLamports summed over echoes.
asOfrequiredstringWhen 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).

ParameterTypeMeaning
walletrequiredstringThe wallet's address, in the path.
Shell
curl https://api.kodama.example/v1/portfolio/CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787
FieldTypeMeaning
walletrequiredstringThe wallet asked for.
positionsrequiredarrayOne position per coin the wallet holds, up to 200.
positions[].coinrequiredobjectThe coin.
positions[].amountrequiredu64 amountCoins in the wallet. Coins moved into a tree are on the wallet's kodama records.
positions[].valuerequiredamountWhat amount is worth at the coin's price, in lamports.
positions[].costrequiredamountLamports spent on the coins still held.
positions[].realizedrequiredsigned amountLamports gained or lost on the coins sold. Negative for a loss.
launchedrequiredarrayThe coins this wallet planted, newest first, up to 100.
asOfrequiredstringWhen it was read.

A wallet that holds nothing answers empty positions and launched.

Errors: VALIDATION_ERROR (400).

Where to go next