API

Live events

The server-sent event stream at /v1/events: how to connect, the ready and resync messages, every event with its exact fields and reconnecting.

The stream

GET /v1/events is one long-lived response of text/event-stream. It carries every trade, every coin that moved and every tree action as it is indexed, for all coins or for one.

ParameterTypeMeaning
mintstringOnly this coin's events. Leave it out for every coin.

Any other parameter, or a mint that is not an address, is a VALIDATION_ERROR (400) answered as JSON before the stream opens.

Each message has three lines. event is the event's type, data is one JSON object that repeats the type as type, and id is the message's id:

Text
event: water
data: {"type":"water","mint":"HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf","wallet":"AtNpubTAmbBB6UrMXiJ85fdgsshLWYXR3z1xka9QHyPa","dayIndex":20772,"at":"2026-11-15T17:35:02.209Z","signature":"3wbhqtUfrXdsNSZdvWoqCmR1wDJkSRM4C2NMPWdgrnpsgN8UvbTB6Hfs9QevHdSnrEUz27r2mX8gKLZQ3xLHbNhT","coinsCountingToday":"1206371213399"}
id: 1794764102209-325

A comment line, : keepalive, is written every 15 seconds while nothing else is, so proxies keep an idle stream open. Clients ignore it.

Connect

In a browser, open an EventSource on the URL the client gives. eventsUrl(mint) returns the stream's address.

Shell
curl -N "https://api.kodama.example/v1/events?mint=HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf"

An EventSource delivers a named event only to a listener added for that name; onmessage receives none of these.

ready and resync

Two control messages share the stream with the events.

ready is the first message of every connection, or the second after a resync:

Text
event: ready
data: {"type":"ready","status":"ready"}
id: 1794764098200
FieldTypeMeaning
typerequiredstringready.
statusrequiredstringThe service's state, as GET /health answers it: ready or waiting.

resync says events were missed. The stream replays nothing, so read again whatever you show.

FieldTypeMeaning
typerequiredstringresync.
reasonrequiredstringreconnected: the request carried a Last-Event-ID header, so this is a connection resumed after a gap. behind: this client read too slowly and 500 events queued for it were dropped.

Every event

Eleven events exist. Amounts follow the API's conventions: Lamports fields are SOL, the rest are coin base units.

eventSent when
tradeA buy or a sell landed.
coinA coin was planted, or its price, progress, phase or tree changed.
waterA kodama watered a tree.
move-inA wallet moved coins into a tree.
move-outA kodama moved coins out.
day-closedA tree's day closed.
harvestA tree's fees were harvested and split.
pickA kodama picked fruit.
claimA planter claimed their share.
echoed-buyA buy landed through a kodama's echo.
claim-echoA kodama claimed an echo share.

Seven of them carry the same five fields, named the common fields below:

FieldTypeMeaning
mintrequiredstringThe tree's coin.
walletrequiredstringThe wallet that acted.
dayIndexrequirednumberThe tree's day the action landed in.
atrequiredstringWhen it landed.
signaturerequiredstringIts transaction.

trade

Text
event: trade
data: {"type":"trade","trade":{"signature":"3aKSJx1wqtH8oVE7wFx5TWRDAMNuc3gyyJhZ1DzKwxrjDjZsnZbW5JxmTzQN8EtB99oLMnXYTHpjUhakujoGY6yW","mint":"HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf","wallet":"4YaSfmBHGj9RPkyRsUcKYvvW93L6S6Sz1Chzvdaedtys","side":"buy","base":"4717843188224","quote":"147186000","price":"0.000000030526979226","priceUsd":"0.000004651395824665","venue":"curve","slot":383600150,"at":"2026-11-15T17:35:02.209Z"}}
id: 1794764102209-322
FieldTypeMeaning
typerequiredstringtrade.
traderequiredobjectThe trade, with the fields that route lists: signature, mint, wallet, side, base, quote, price, priceUsd, venue, slot and at.

coin

FieldTypeMeaning
typerequiredstringcoin.
coinrequiredobjectThe whole coin object as it is now, with its tree. A mint not seen before is a new plant.

water

The sample under The stream is a water message.

FieldTypeMeaning
typerequiredstringwater.
mint, wallet, dayIndex, at, signaturerequiredas aboveThe common fields. wallet is the kodama.
coinsCountingTodayrequiredu64 amountThe coins the kodama entered today's split with.

move-in and move-out

Text
event: move-in
data: {"type":"move-in","mint":"HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf","wallet":"AtNpubTAmbBB6UrMXiJ85fdgsshLWYXR3z1xka9QHyPa","dayIndex":20772,"at":"2026-11-15T17:35:02.209Z","signature":"3wbhqtUfrXdsNSZdvWoqCmR1wDJkSRM4C2NMPWdgrnpsgN8UvbTB6Hfs9QevHdSnrEUz27r2mX8gKLZQ3xLHbNhT","amount":"1000000"}
id: 1794764102209-326
FieldTypeMeaning
typerequiredstringmove-in or move-out.
mint, wallet, dayIndex, at, signaturerequiredas aboveThe common fields.
amountrequiredu64 amountCoins moved.

day-closed

Text
event: day-closed
data: {"type":"day-closed","mint":"HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf","day":{"dayIndex":20771,"fruitLamports":"12000004","wateredKodama":8,"wateredCoins":"4274527783550","fruitPerMillionCoinsLamports":"2807328","carriedFruitLamports":"4","closedAt":"2026-11-15T00:00:00.000Z"},"at":"2026-11-15T00:00:00.000Z","signature":"3wbhqtUfrXdsNSZdvWoqCmR1wDJkSRM4C2NMPWdgrnpsgN8UvbTB6Hfs9QevHdSnrEUz27r2mX8gKLZQ3xLHbNhT"}
id: 1794764102209-332
FieldTypeMeaning
typerequiredstringday-closed.
mintrequiredstringThe tree's coin.
dayrequiredobjectThe closed day: dayIndex, fruitLamports, wateredKodama, wateredCoins, fruitPerMillionCoinsLamports, carriedFruitLamports and closedAt.
atrequiredstringWhen it closed.
signaturerequiredstringThe transaction that closed it.

harvest

Text
event: harvest
data: {"type":"harvest","mint":"HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf","dayIndex":20772,"at":"2026-11-15T17:35:02.209Z","signature":"rNCe1pud3C7EmBLDrESpgDrgWuxQQyN7u66VRkKpz5ZokCtzFZRetMU9ewbrFUjingxHnRq1HbPQhJD5GfbFGuf","feesCollectedLamports":"2796534","fruitLamports":"1766232","planterLamports":"441558","burnerLamports":"588744","liquidityFruitLamports":"0"}
id: 1794764102209-324
FieldTypeMeaning
typerequiredstringharvest.
mintrequiredstringThe tree's coin.
dayIndexrequirednumberThe day the fruit went into.
atrequiredstringWhen it landed.
signaturerequiredstringIts transaction.
feesCollectedLamportsrequiredu64 amountTrade fees pulled into the tree.
fruitLamportsrequiredu64 amountWhat became fruit of the day, liquidityFruitLamports included.
planterLamportsrequiredu64 amountWhat was set aside for the planter.
burnerLamportsrequiredu64 amountWhat went to the burner.
liquidityFruitLamportsrequiredu64 amountFees of the graduated pool's locked liquidity, which are fruit in full and no part of the split trade fees.

pick

Text
event: pick
data: {"type":"pick","mint":"HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf","wallet":"AtNpubTAmbBB6UrMXiJ85fdgsshLWYXR3z1xka9QHyPa","dayIndex":20772,"at":"2026-11-15T17:35:02.209Z","signature":"3wbhqtUfrXdsNSZdvWoqCmR1wDJkSRM4C2NMPWdgrnpsgN8UvbTB6Hfs9QevHdSnrEUz27r2mX8gKLZQ3xLHbNhT","fruitLamports":"10000"}
id: 1794764102209-328
FieldTypeMeaning
typerequiredstringpick.
mint, wallet, dayIndex, at, signaturerequiredas aboveThe common fields.
fruitLamportsrequiredu64 amountFruit paid to the wallet.

claim

Text
event: claim
data: {"type":"claim","mint":"HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf","wallet":"AtNpubTAmbBB6UrMXiJ85fdgsshLWYXR3z1xka9QHyPa","dayIndex":20772,"at":"2026-11-15T17:35:02.209Z","signature":"3wbhqtUfrXdsNSZdvWoqCmR1wDJkSRM4C2NMPWdgrnpsgN8UvbTB6Hfs9QevHdSnrEUz27r2mX8gKLZQ3xLHbNhT","planterLamports":"2500"}
id: 1794764102209-329
FieldTypeMeaning
typerequiredstringclaim.
mint, wallet, dayIndex, at, signaturerequiredas aboveThe common fields. wallet is the planter.
planterLamportsrequiredu64 amountThe planter's share paid.

echoed-buy

Text
event: echoed-buy
data: {"type":"echoed-buy","mint":"HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf","wallet":"AtNpubTAmbBB6UrMXiJ85fdgsshLWYXR3z1xka9QHyPa","dayIndex":20772,"at":"2026-11-15T17:35:02.209Z","signature":"3wbhqtUfrXdsNSZdvWoqCmR1wDJkSRM4C2NMPWdgrnpsgN8UvbTB6Hfs9QevHdSnrEUz27r2mX8gKLZQ3xLHbNhT","echoWallet":"AtNpubTAmbBB6UrMXiJ85fdgsshLWYXR3z1xka9QHyPa","buyVolumeLamports":"5000000","shareLamports":"10000"}
id: 1794764102209-330
FieldTypeMeaning
typerequiredstringechoed-buy.
mint, wallet, dayIndex, at, signaturerequiredas aboveThe common fields. wallet is the buyer.
echoWalletrequiredstringThe kodama whose echo the buy came through.
buyVolumeLamportsrequiredu64 amountSOL the buy spent.
shareLamportsrequiredu64 amountThe echo share it set aside for echoWallet.

claim-echo

Text
event: claim-echo
data: {"type":"claim-echo","mint":"HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf","wallet":"AtNpubTAmbBB6UrMXiJ85fdgsshLWYXR3z1xka9QHyPa","dayIndex":20772,"at":"2026-11-15T17:35:02.209Z","signature":"3wbhqtUfrXdsNSZdvWoqCmR1wDJkSRM4C2NMPWdgrnpsgN8UvbTB6Hfs9QevHdSnrEUz27r2mX8gKLZQ3xLHbNhT","echoLamports":"10000"}
id: 1794764102209-331
FieldTypeMeaning
typerequiredstringclaim-echo.
mint, wallet, dayIndex, at, signaturerequiredas aboveThe common fields. wallet is the kodama claiming.
echoLamportsrequiredu64 amountThe echo share paid.

What each event changes

An event is the cue to read again; the reads hold the state.

EventReads it changes
tradeThe coin, its trades, candles and holders, the traders' portfolios.
coinThe coin and the feed. The event carries the new coin whole.
water, move-in, move-outThe coin's tree, its kodama, the wallet's kodama records, the feed's watered order.
day-closedThe coin's days and tree, the fruit board, every kodama's fruit ready in that tree.
harvestThe coin's tree, the grove's totals, the fruit board.
pick, claim, claim-echoThe wallet's records or echoes, the coin's tree, the grove's totals, the fruit board.
echoed-buyThe echo wallet's echoes and the coin's tree.

Reconnecting

An EventSource reconnects by itself and sends the last id it saw as Last-Event-ID. The stream answers that header with resync and then ready:

Shell
curl -N "https://api.kodama.example/v1/events?mint=HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf" \
  -H "Last-Event-ID: 1"
Text
event: resync
data: {"type":"resync","reason":"reconnected"}
id: 1794764105340

event: ready
data: {"type":"ready","status":"ready"}
id: 1794764098200
  1. On resync, read again. Refetch what is on screen: the coin, the feed, the wallet's records. Nothing that happened during the gap is sent later.

  2. When the source gives up, open a new one. A source whose readyState is closed does not retry. Open another after a pause, and read again when it opens. The web app starts at 1 second and doubles the pause up to 30.

  3. Close it when nobody is looking. The web app closes its stream 15 seconds after the tab is hidden and opens it again, with a refetch, when the tab is shown.

A browser sends the Origin header on the stream too, so the page's origin must be one the service allows.

Where to go next