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.
| Parameter | Type | Meaning |
|---|---|---|
mint | string | Only 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:
event: water
data: {"type":"water","mint":"HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf","wallet":"AtNpubTAmbBB6UrMXiJ85fdgsshLWYXR3z1xka9QHyPa","dayIndex":20772,"at":"2026-11-15T17:35:02.209Z","signature":"3wbhqtUfrXdsNSZdvWoqCmR1wDJkSRM4C2NMPWdgrnpsgN8UvbTB6Hfs9QevHdSnrEUz27r2mX8gKLZQ3xLHbNhT","coinsCountingToday":"1206371213399"}
id: 1794764102209-325A 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.
curl -N "https://api.kodama.example/v1/events?mint=HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf"import { createClient, StreamControl, StreamEvent } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const source = new EventSource(api.eventsUrl('HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf'))
declare function refetch(): void // read again whatever is on screen
source.addEventListener('ready', (message) => {
const control = StreamControl.parse(JSON.parse(message.data))
if (control.type === 'ready') console.log('stream open, platform', control.status)
})
source.addEventListener('resync', refetch)
for (const type of ['trade', 'coin', 'water', 'move-in', 'move-out', 'day-closed', 'harvest', 'pick', 'claim', 'echoed-buy', 'claim-echo']) {
source.addEventListener(type, (message) => {
const event = StreamEvent.parse(JSON.parse(message.data))
if (event.type === 'water') console.log(event.wallet, 'watered', event.mint)
})
}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:
event: ready
data: {"type":"ready","status":"ready"}
id: 1794764098200| Field | Type | Meaning |
|---|---|---|
typerequired | string | ready. |
statusrequired | string | The 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.
| Field | Type | Meaning |
|---|---|---|
typerequired | string | resync. |
reasonrequired | string | reconnected: 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.
event | Sent when |
|---|---|
trade | A buy or a sell landed. |
coin | A coin was planted, or its price, progress, phase or tree changed. |
water | A kodama watered a tree. |
move-in | A wallet moved coins into a tree. |
move-out | A kodama moved coins out. |
day-closed | A tree's day closed. |
harvest | A tree's fees were harvested and split. |
pick | A kodama picked fruit. |
claim | A planter claimed their share. |
echoed-buy | A buy landed through a kodama's echo. |
claim-echo | A kodama claimed an echo share. |
Seven of them carry the same five fields, named the common fields below:
| Field | Type | Meaning |
|---|---|---|
mintrequired | string | The tree's coin. |
walletrequired | string | The wallet that acted. |
dayIndexrequired | number | The tree's day the action landed in. |
atrequired | string | When it landed. |
signaturerequired | string | Its transaction. |
trade
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| Field | Type | Meaning |
|---|---|---|
typerequired | string | trade. |
traderequired | object | The trade, with the fields that route lists: signature, mint, wallet, side, base, quote, price, priceUsd, venue, slot and at. |
coin
| Field | Type | Meaning |
|---|---|---|
typerequired | string | coin. |
coinrequired | object | The 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.
| Field | Type | Meaning |
|---|---|---|
typerequired | string | water. |
mint, wallet, dayIndex, at, signaturerequired | as above | The common fields. wallet is the kodama. |
coinsCountingTodayrequired | u64 amount | The coins the kodama entered today's split with. |
move-in and move-out
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| Field | Type | Meaning |
|---|---|---|
typerequired | string | move-in or move-out. |
mint, wallet, dayIndex, at, signaturerequired | as above | The common fields. |
amountrequired | u64 amount | Coins moved. |
day-closed
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| Field | Type | Meaning |
|---|---|---|
typerequired | string | day-closed. |
mintrequired | string | The tree's coin. |
dayrequired | object | The closed day: dayIndex, fruitLamports, wateredKodama, wateredCoins, fruitPerMillionCoinsLamports, carriedFruitLamports and closedAt. |
atrequired | string | When it closed. |
signaturerequired | string | The transaction that closed it. |
harvest
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| Field | Type | Meaning |
|---|---|---|
typerequired | string | harvest. |
mintrequired | string | The tree's coin. |
dayIndexrequired | number | The day the fruit went into. |
atrequired | string | When it landed. |
signaturerequired | string | Its transaction. |
feesCollectedLamportsrequired | u64 amount | Trade fees pulled into the tree. |
fruitLamportsrequired | u64 amount | What became fruit of the day, liquidityFruitLamports included. |
planterLamportsrequired | u64 amount | What was set aside for the planter. |
burnerLamportsrequired | u64 amount | What went to the burner. |
liquidityFruitLamportsrequired | u64 amount | Fees of the graduated pool's locked liquidity, which are fruit in full and no part of the split trade fees. |
pick
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| Field | Type | Meaning |
|---|---|---|
typerequired | string | pick. |
mint, wallet, dayIndex, at, signaturerequired | as above | The common fields. |
fruitLamportsrequired | u64 amount | Fruit paid to the wallet. |
claim
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| Field | Type | Meaning |
|---|---|---|
typerequired | string | claim. |
mint, wallet, dayIndex, at, signaturerequired | as above | The common fields. wallet is the planter. |
planterLamportsrequired | u64 amount | The planter's share paid. |
echoed-buy
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| Field | Type | Meaning |
|---|---|---|
typerequired | string | echoed-buy. |
mint, wallet, dayIndex, at, signaturerequired | as above | The common fields. wallet is the buyer. |
echoWalletrequired | string | The kodama whose echo the buy came through. |
buyVolumeLamportsrequired | u64 amount | SOL the buy spent. |
shareLamportsrequired | u64 amount | The echo share it set aside for echoWallet. |
claim-echo
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| Field | Type | Meaning |
|---|---|---|
typerequired | string | claim-echo. |
mint, wallet, dayIndex, at, signaturerequired | as above | The common fields. wallet is the kodama claiming. |
echoLamportsrequired | u64 amount | The echo share paid. |
What each event changes
An event is the cue to read again; the reads hold the state.
| Event | Reads it changes |
|---|---|
trade | The coin, its trades, candles and holders, the traders' portfolios. |
coin | The coin and the feed. The event carries the new coin whole. |
water, move-in, move-out | The coin's tree, its kodama, the wallet's kodama records, the feed's watered order. |
day-closed | The coin's days and tree, the fruit board, every kodama's fruit ready in that tree. |
harvest | The coin's tree, the grove's totals, the fruit board. |
pick, claim, claim-echo | The wallet's records or echoes, the coin's tree, the grove's totals, the fruit board. |
echoed-buy | The 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:
curl -N "https://api.kodama.example/v1/events?mint=HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf" \
-H "Last-Event-ID: 1"event: resync
data: {"type":"resync","reason":"reconnected"}
id: 1794764105340
event: ready
data: {"type":"ready","status":"ready"}
id: 1794764098200On
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.When the source gives up, open a new one. A source whose
readyStateis 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.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.