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:

client.ts
import { createClient } from './backend/src/contract/index.js'

const api = createClient('https://api.kodama.example')

Every route

RouteClient methodTold on
GET /healthhealth()Health
GET /v1/platformplatform()Coins and trees
GET /v1/coinscoins(query)Coins and trees
GET /v1/coins/:mintcoin(mint)Coins and trees
GET /v1/coins/:mint/tradestrades(mint, query)Coins and trees
GET /v1/coins/:mint/candlescandles(mint, query)Coins and trees
GET /v1/coins/:mint/holdersholders(mint)Coins and trees
GET /v1/grovegrove()Coins and trees
GET /v1/fruitfruit()Coins and trees
GET /v1/coins/:mint/kodamakodama(mint, query)Kodama and days
GET /v1/coins/:mint/daysdays(mint, query)Kodama and days
GET /v1/wallets/:wallet/kodamawalletKodama(wallet)Kodama and days
GET /v1/wallets/:wallet/echoeswalletEchoes(wallet)Kodama and days
GET /v1/portfolio/:walletportfolio(wallet)Kodama and days
POST /v1/metadatauploadMetadata(image, info)Transactions
POST /v1/launch/buildbuildLaunch(body)Transactions
POST /v1/trade/buildbuildTrade(body)Transactions
POST /v1/move-in/buildbuildMoveIn(body)Transactions
POST /v1/move-out/buildbuildMoveOut(body)Transactions
POST /v1/water/buildbuildWater(body)Transactions
POST /v1/pick/buildbuildPick(body)Transactions
POST /v1/claim-echo/buildbuildClaimEcho(body)Transactions
POST /v1/claim/buildbuildClaim(body)Transactions
POST /v1/transactions/submitsubmit(body)Transactions
GET /v1/transactions/:idstatus(id)Transactions
GET /v1/eventseventsUrl(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().

FieldTypeMeaning
statusstringready: 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).

Shell
curl https://api.kodama.example/health
JSON
{
  "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:

HeaderHolds
X-Request-IdAn id for this request. An INTERNAL_ERROR repeats it as requestId.
X-Contract-VersionThe contract version the service runs, 0.4.0. The client exports the same value as CONTRACT_VERSION.
Cache-Controlno-store. The stream sets no-cache.
X-Content-Type-Optionsnosniff.
Retry-AfterSeconds, 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 pagesWritten asLimits
amountUnsigned integer string: digits only, no leading zeroAt most 78 digits.
u64 amountThe sameAt most 18446744073709551615.
positive u64 amountThe sameGreater than zero.
signed amountInteger string with an optional leading -At most 79 characters.
decimalDecimal number string: digits, then optionally a point and more digitsAt most 96 characters. Used for prices and market caps.
ppmInteger, parts per million0 to 1,000,000. 10000 ppm is 1%.
bpsInteger, hundredths of a percent0 to 10,000.
amounts.ts
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

ValueEncodingLimits
Address (a wallet, a mint, a pool)base5832 bytes, 32 to 44 characters.
Signaturebase5864 bytes, 64 to 88 characters.
Transactionbase64The 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.

ParameterTypeMeaning
cursorstringWhere the page starts: the nextCursor of the page before. Digits only, at most 12 characters. Leave it out for the first page.
limitnumberItems per page, 1 to 100. Default 24.
FieldTypeMeaning
itemsarrayThe page's items, in the route's order.
page.nextCursorstring or nullThe cursor of the next page, or null on the last one.
page.hasMorebooleanWhether a next page exists.
asOfstringWhen the page was read.
pages.ts
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.

FieldTypeMeaning
error.coderequiredstringThe stable code to branch on.
error.messagerequiredstringOne sentence that can be shown as it is.
error.retryablerequiredbooleanWhether sending the same request again can succeed.
error.stagerequiredstringWhere the flow failed: validation, auth, read, upload, build, wallet, co_sign, simulation, send or confirmation.
error.fieldErrorsobjectMessages per field, keyed by the field's path (mints.1, info.name). form holds messages about the input as a whole.
error.programErrorobjectThe program that refused a transaction: programId, name and, when it has one, number.
error.retryAfterSecondsnumberHow long to wait before trying again. Sent as the Retry-After header too.
error.requestIdstringThe request's id, on an INTERNAL_ERROR.
Shell
curl "https://api.kodama.example/v1/coins?limit=500"
JSON
{
  "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.

RuleValue
MethodsGET, POST, PUT, PATCH, DELETE, OPTIONS
Request headersContent-Type, Last-Event-ID
Exposed response headersX-Request-Id, Retry-After, X-Contract-Version
Preflight cache600 seconds
CredentialsNot 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/.

TypeScript
function createClient(baseUrl: string, options?: ClientOptions): LaunchpadClient
OptionTypeMeaning
fetchfunctionThe fetch to call with. Default: the global one.
credentialsstringThe credentials mode of every request. Not set by default.
headersobjectHeaders sent with every request.

Every method takes a last argument for one call:

Call optionTypeMeaning
signalAbortSignalCancels the request.
headersobjectHeaders for this call, over the client's.
queryobjectQuery parameters. The methods that take a query set it themselves.

A method resolves with the parsed response, typed by its schema, or throws ApiClientError:

PropertyTypeMeaning
statusnumberThe HTTP status.
codestringbody.error.code.
messagestringbody.error.message.
bodyobjectThe 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.

errors.ts
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.

Where to go next