API
Conventions
The rules every route of the Kodama API shares: the base URL, amounts, addresses, time, pagination, the error envelope, CORS, the typed client and the OpenAPI document.
The base URL and the /v1 prefix
The API is one HTTP service. Every route sits under /v1, except GET /health.
The samples on these pages write the base URL as https://api.kodama.example and import the typed client from the repository root:
import { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')Every route
| Route | Client method | Told on |
|---|---|---|
GET /health | health() | Health |
GET /v1/platform | platform() | Coins and trees |
GET /v1/coins | coins(query) | Coins and trees |
GET /v1/coins/:mint | coin(mint) | Coins and trees |
GET /v1/coins/:mint/trades | trades(mint, query) | Coins and trees |
GET /v1/coins/:mint/candles | candles(mint, query) | Coins and trees |
GET /v1/coins/:mint/holders | holders(mint) | Coins and trees |
GET /v1/grove | grove() | Coins and trees |
GET /v1/fruit | fruit() | Coins and trees |
GET /v1/coins/:mint/kodama | kodama(mint, query) | Kodama and days |
GET /v1/coins/:mint/days | days(mint, query) | Kodama and days |
GET /v1/wallets/:wallet/kodama | walletKodama(wallet) | Kodama and days |
GET /v1/wallets/:wallet/echoes | walletEchoes(wallet) | Kodama and days |
GET /v1/portfolio/:wallet | portfolio(wallet) | Kodama and days |
POST /v1/metadata | uploadMetadata(image, info) | Transactions |
POST /v1/launch/build | buildLaunch(body) | Transactions |
POST /v1/trade/build | buildTrade(body) | Transactions |
POST /v1/move-in/build | buildMoveIn(body) | Transactions |
POST /v1/move-out/build | buildMoveOut(body) | Transactions |
POST /v1/water/build | buildWater(body) | Transactions |
POST /v1/pick/build | buildPick(body) | Transactions |
POST /v1/claim-echo/build | buildClaimEcho(body) | Transactions |
POST /v1/claim/build | buildClaim(body) | Transactions |
POST /v1/transactions/submit | submit(body) | Transactions |
GET /v1/transactions/:id | status(id) | Transactions |
GET /v1/events | eventsUrl(mint) | Live events |
Those are the 26 operations of the contract. One more route exists outside it: GET /media/:name, told with the metadata upload.
Health
GET /health says which state the service is in. Client method: health().
| Field | Type | Meaning |
|---|---|---|
status | string | ready: the program, the grove and the lookup tables exist on chain and every route works. waiting: the service is up and they do not exist yet. |
While the status is waiting, the read routes answer from the index, with empty lists where nothing is indexed. GET /v1/platform, every build route and POST /v1/transactions/submit answer PROGRAM_UNAVAILABLE (409, retryable: true).
curl https://api.kodama.example/healthimport { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const { status } = await api.health(){
"status": "ready"
}Requests and responses
Bodies and answers are JSON. A POST with a body sends Content-Type: application/json; anything else is refused with UNSUPPORTED_MEDIA_TYPE (415). The one exception is POST /v1/metadata, which takes multipart/form-data.
Bodies and query strings are strict: a field or parameter the route does not define is a VALIDATION_ERROR (400), as is a missing or malformed one. The largest body any route takes is 8,388,608 bytes; a larger one is PAYLOAD_TOO_LARGE (413).
Every response carries these headers:
| Header | Holds |
|---|---|
X-Request-Id | An id for this request. An INTERNAL_ERROR repeats it as requestId. |
X-Contract-Version | The contract version the service runs, 0.4.0. The client exports the same value as CONTRACT_VERSION. |
Cache-Control | no-store. The stream sets no-cache. |
X-Content-Type-Options | nosniff. |
Retry-After | Seconds, on an error whose envelope has retryAfterSeconds. |
Each client may send 60 POST requests under /v1 per minute. The next one answers RATE_LIMITED (429) with retryAfterSeconds set to the rest of the minute. GET requests are not counted.
Amounts
Every amount is a decimal integer string in base units. A coin has 6 decimals, so "1000000" is one coin. SOL has 9, so "1000000000" is 1SOL. A field whose name ends in Lamports is SOL. Do arithmetic in BigInt, never in Number.
Every curve quotes in SOL, so the quote amounts that do not carry the suffix are lamports too: raisedQuote, volume24hQuote, a trade's quote, a build's amountIn, amountOut, minimumOut and fee on the SOL side, and a position's value, cost and realized.
| Type on these pages | Written as | Limits |
|---|---|---|
| amount | Unsigned integer string: digits only, no leading zero | At most 78 digits. |
| u64 amount | The same | At most 18446744073709551615. |
| positive u64 amount | The same | Greater than zero. |
| signed amount | Integer string with an optional leading - | At most 79 characters. |
| decimal | Decimal number string: digits, then optionally a point and more digits | At most 96 characters. Used for prices and market caps. |
| ppm | Integer, parts per million | 0 to 1,000,000. 10000 ppm is 1%. |
| bps | Integer, hundredths of a percent | 0 to 10,000. |
const LAMPORTS_PER_SOL = 10n ** 9n
/** "5944134" lamports as "0.005944134". */
function sol(lamports: string): string {
const value = BigInt(lamports)
const whole = value / LAMPORTS_PER_SOL
const part = (value % LAMPORTS_PER_SOL).toString().padStart(9, '0').replace(/0+$/, '')
return part ? `${whole}.${part}` : `${whole}`
}A coin's price is SOL per whole coin and marketCap is whole SOL, both as decimal strings. priceUsd and marketCapUsd are null when no SOL price is recorded.
Addresses, signatures and transactions
| Value | Encoding | Limits |
|---|---|---|
| Address (a wallet, a mint, a pool) | base58 | 32 bytes, 32 to 44 characters. |
| Signature | base58 | 64 bytes, 64 to 88 characters. |
| Transaction | base64 | The standard alphabet, with = padding. |
An address in a path that does not decode to 32 bytes is a VALIDATION_ERROR, with the messages under fieldErrors.form.
Time
Times are ISO 8601 strings in UTC, ending in Z: 2026-11-16T00:00:00.000Z. Every read answers asOf, the moment it was read.
A day is named by its dayIndex: floor(unix seconds / dayLengthSeconds), with dayLengthSeconds from the platform. A day closes at 00:00 UTC. A tree's dayClosesAt is the end of its open day. The day itself is told in Days and fruit.
Pagination
Four routes answer pages: the feed, a coin's trades, a coin's kodama and a coin's days.
| Parameter | Type | Meaning |
|---|---|---|
cursor | string | Where the page starts: the nextCursor of the page before. Digits only, at most 12 characters. Leave it out for the first page. |
limit | number | Items per page, 1 to 100. Default 24. |
| Field | Type | Meaning |
|---|---|---|
items | array | The page's items, in the route's order. |
page.nextCursor | string or null | The cursor of the next page, or null on the last one. |
page.hasMore | boolean | Whether a next page exists. |
asOf | string | When the page was read. |
import { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const mint = 'HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf'
let cursor: string | undefined
do {
const page = await api.days(mint, { cursor, limit: 100 })
for (const day of page.items) console.log(day.dayIndex, day.fruitLamports)
cursor = page.page.nextCursor ?? undefined
} while (cursor)The error envelope
Every failed request answers one shape, with the HTTP status of its code. The codes, their statuses and what raises each are on Errors.
| Field | Type | Meaning |
|---|---|---|
error.coderequired | string | The stable code to branch on. |
error.messagerequired | string | One sentence that can be shown as it is. |
error.retryablerequired | boolean | Whether sending the same request again can succeed. |
error.stagerequired | string | Where the flow failed: validation, auth, read, upload, build, wallet, co_sign, simulation, send or confirmation. |
error.fieldErrors | object | Messages per field, keyed by the field's path (mints.1, info.name). form holds messages about the input as a whole. |
error.programError | object | The program that refused a transaction: programId, name and, when it has one, number. |
error.retryAfterSeconds | number | How long to wait before trying again. Sent as the Retry-After header too. |
error.requestId | string | The request's id, on an INTERNAL_ERROR. |
curl "https://api.kodama.example/v1/coins?limit=500"{
"error": {
"code": "VALIDATION_ERROR",
"message": "Check the highlighted fields.",
"retryable": false,
"stage": "validation",
"fieldErrors": {
"limit": [
"Too big: expected number to be <=100"
]
}
}
}CORS
A browser may call the API from the origins the service allows, matched exactly as scheme://host:port.
| Rule | Value |
|---|---|
| Methods | GET, POST, PUT, PATCH, DELETE, OPTIONS |
| Request headers | Content-Type, Last-Event-ID |
| Exposed response headers | X-Request-Id, Retry-After, X-Contract-Version |
| Preflight cache | 600 seconds |
| Credentials | Not allowed. The API keeps no cookie. |
A request whose Origin header names any other origin is refused with ORIGIN_NOT_ALLOWED (403) before it reaches a route. A request with no Origin header, from a server or from curl, passes.
The typed client
backend/src/contract/ is the contract: the zod schemas the service validates every request with, and a client that parses every response with the same schemas. It imports nothing but zod, and runs in a browser, in Node and in scripts. The web app carries a copy at web/src/launchpad/contract/.
function createClient(baseUrl: string, options?: ClientOptions): LaunchpadClient| Option | Type | Meaning |
|---|---|---|
fetch | function | The fetch to call with. Default: the global one. |
credentials | string | The credentials mode of every request. Not set by default. |
headers | object | Headers sent with every request. |
Every method takes a last argument for one call:
| Call option | Type | Meaning |
|---|---|---|
signal | AbortSignal | Cancels the request. |
headers | object | Headers for this call, over the client's. |
query | object | Query parameters. The methods that take a query set it themselves. |
A method resolves with the parsed response, typed by its schema, or throws ApiClientError:
| Property | Type | Meaning |
|---|---|---|
status | number | The HTTP status. |
code | string | body.error.code. |
message | string | body.error.message. |
body | object | The whole error envelope. |
A response that is not JSON, or an error status with a body that is not the envelope, is thrown as one too: UPSTREAM_UNAVAILABLE and retryable: true for a status of 500 or above, INTERNAL_ERROR below it, with the message The API answered HTTP <status>. A response that does not match its schema throws a ZodError.
import { ApiClientError, createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
try {
await api.coins({ limit: 500 })
} catch (error) {
if (!(error instanceof ApiClientError)) throw error
console.log(error.status, error.code, error.body.error.fieldErrors)
}The same module exports every schema and its type (Coin, Tree, Day, TradeBuild, StreamEvent and the rest), the error table as errors.status and CONTRACT_VERSION.
The OpenAPI document
backend/openapi.json is an OpenAPI 3.1.0 document titled Kodama API, version 0.4.0. It is written from the same schemas, so it holds the 26 operations in the table above with the request, the response and the error envelope of each.