API

Transactions

How every action reaches the chain through the API: the build routes for plant, trade, move in, move out, water, pick and both claims, what the wallet signs, the submit route, and following a signature to its end state.

The path of every action

Every action that changes anything is a Solana transaction the wallet signs. The API never holds a wallet's key. It builds the transaction, checks the signed copy, sends it and reports where it stands.

Build Sign Submit Follow POST /v1/…/build the wallet POST …/submit GET …/:id unsigned bytes signed bytes a signature confirmed
Each action takes the same four calls. Only the build route differs.
  1. Build. POST the action's request to its build route. The answer holds one or more unsigned transactions and what the action will do: a quote, a mint, the trees it touches.

  2. Sign. The wallet signs every transaction of the answer in one approval.

  3. Submit. POST /v1/transactions/submit once per transaction, in order, with the signed bytes.

  4. Follow. GET /v1/transactions/:id until the status is confirmed or finalized, then submit the next one.

ActionBuild routeClient methodRequest
PlantPOST /v1/launch/buildbuildLaunchPlant
Buy, sellPOST /v1/trade/buildbuildTradeTrade
Move inPOST /v1/move-in/buildbuildMoveInMove
Move outPOST /v1/move-out/buildbuildMoveOutMove
WaterPOST /v1/water/buildbuildWaterTrees
Pick fruitPOST /v1/pick/buildbuildPickTrees
Claim an echo sharePOST /v1/claim-echo/buildbuildClaimEchoTrees
Claim a planter's sharePOST /v1/claim/buildbuildClaimClaim

A built transaction

Every build answer holds build, and may hold builds. Each is this object:

FieldTypeMeaning
idrequiredstringThe build's id. Submit and follow it by this.
transactionBase64requiredstringThe unsigned transaction, a versioned (v0) Solana transaction with the wallet as fee payer, in base64.
blockhashrequiredstringThe recent blockhash it was built on.
lastValidBlockHeightrequirednumberThe block height after which it can no longer land.
cosignedrequiredbooleantrue when the server adds a signature after the wallet's: the new coin's mint, on the transactions of a plant. Such a transaction is submitted in relay mode only.
simulationstringpassed: simulated when it was built. after-predecessor: it depends on the transaction before it, and is simulated when it is submitted, after that one confirmed.
previousBuildIdstringThe id of the build that must be confirmed before this one is submitted.

The ordered builds array

builds, when present, is the whole list of transactions the action takes, in the order they must land. Its first item is the same object as build. When it is absent, the list is [build].

TypeScript
const list = built.builds ?? [built.build]

Sign the whole list in one approval, with the wallet's signAllTransactions. Then, for each item in order: submit it, follow its id until it is confirmed or finalized, and only then submit the next. An item with previousBuildId is refused until that build has confirmed, and is submitted in relay mode. The list is not atomic: when one item is rejected, fails or expires, stop there. The items before it have landed and stay landed.

Three kinds of action answer more than one item:

ActionIts list
PlantTwo transactions: the first prepares the tree, the second plants the coin.
Water, pick or an echo claim over many treesAs many transactions as the trees need. Each tree's instructions stay together in one transaction when they fit.
A tree action that first closes an earlier dayWhen the harvest, the close and the action do not fit one transaction, the later parts follow with simulation: after-predecessor.

Upload the image and metadata

POST /v1/metadata stores a coin's image and its metadata document, and answers the URI a plant names. Client method: uploadMetadata(image, info). The body is multipart/form-data with two parts:

PartTypeMeaning
imagerequiredfileA PNG, JPG, GIF or WEBP of at most 5 MB (5 × 1024 × 1024 bytes). The type is read from the file's first bytes; a declared type that differs from them is refused.
inforequiredstringThe text fields, as one JSON object.
Field of infoTypeMeaning
namerequiredstring1 to 32 characters after trimming, and at most 32 bytes.
symbolrequiredstringThe ticker: 1 to 10 characters after trimming, and at most 10 bytes.
descriptionstringAt most 1,000 characters. Default empty.
linksobjectwebsite, x and telegram, each an optional http or https URL of at most 200 characters.
Shell
curl -X POST https://api.kodama.example/v1/metadata \
  -F "image=@tree.png;type=image/png" \
  -F 'info={"name":"Dewdrop","symbol":"DEW","description":"A little water, a little fruit, every morning.","links":{"website":"https://dewdrop.example.com"}}'
JSON
{
  "uri": "https://ipfs.io/ipfs/bafkreifvuj33kmxwjwkw2mvzncvxhkgk4xsiqeodj35mur3ful5tl7hg2q",
  "image": "https://ipfs.io/ipfs/bafkreicjo6iji7kgmz3azy4phqaoquwhd7nwnsxijg5or2pn4njhdhqvqe"
}
FieldTypeMeaning
urirequiredstringThe metadata document's URI. Pass it to the plant as metadataUri.
imagerequiredstringThe stored image's URI.

Files are named by the hash of their content, so the same image and fields answer the same URIs. A file the service stores itself is served at GET /media/:name, which answers the file with its content type, or NOT_FOUND (404) with No such file.

Errors: UNSUPPORTED_MEDIA_TYPE (415) for a body that is not multipart. VALIDATION_ERROR (400) for a missing image, a missing or malformed info, or a field outside its limits, with fieldErrors under image, info or info.<field>. IMAGE_INVALID (400). IMAGE_TOO_LARGE (413). CONFIGURATION_REQUIRED (409). UPLOAD_FAILED (502). PAYLOAD_TOO_LARGE (413).

Build a plant

POST /v1/launch/build builds the two transactions that plant a coin. Client method: buildLaunch(body).

FieldTypeMeaning
walletrequiredstringThe planter's wallet.
namerequiredstringThe coin's name, 1 to 32 characters after trimming.
symbolrequiredstringThe ticker, 1 to 10 characters after trimming.
metadataUrirequiredstringThe uri the metadata upload answered. 1 to 200 characters.
firstBuyu64 amountLamports the planter spends on the first buy, on the same terms as any buy. Default "0", no first buy.
slippageBpsbpsHow far the first buy's coins may fall below the quote, 0 to 5,000. Default 100.
preparedMintstringThe mint of a tree this wallet prepared and did not plant, to plant it now.
Shell
curl -X POST https://api.kodama.example/v1/launch/build \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
    "name": "Dewdrop",
    "symbol": "DEW",
    "metadataUri": "https://ipfs.io/ipfs/bafkreifvuj33kmxwjwkw2mvzncvxhkgk4xsiqeodj35mur3ful5tl7hg2q",
    "firstBuy": "500000000"
  }'
JSON
{
  "build": {
    "id": "fx-8e7fc976-137f-4139-af02-923399d35e5b",
    "transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
    "blockhash": "FUCvmboGFHcfibYH2nU2dsHxSjdDZvctYq693bnakMGQ",
    "lastValidBlockHeight": 290000014,
    "cosigned": true,
    "simulation": "passed"
  },
  "builds": [
    {
      "id": "fx-8e7fc976-137f-4139-af02-923399d35e5b",
      "transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
      "blockhash": "FUCvmboGFHcfibYH2nU2dsHxSjdDZvctYq693bnakMGQ",
      "lastValidBlockHeight": 290000014,
      "cosigned": true,
      "simulation": "passed"
    },
    {
      "id": "fx-6741c668-c104-46c8-ad4b-2cbbc1581d81",
      "transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
      "blockhash": "EEuxkdPNWys4hTGBFzn63VkVYtjp8hJbKFghroWbHyNt",
      "lastValidBlockHeight": 290000015,
      "cosigned": true,
      "simulation": "after-predecessor",
      "previousBuildId": "fx-8e7fc976-137f-4139-af02-923399d35e5b"
    }
  ],
  "mint": "7C7p7dTA5fUkpdikwJ7x2hwCk2mW482bMgt6cCgM8dP2",
  "pool": "E853mk5WQN1uWQ4PKRidvghvusVLFgsaQ97JR6G1Cy1J",
  "firstBuy": {
    "quoteIn": "500000000",
    "baseOut": "17217973267643",
    "minimumOut": "17045793534966",
    "fee": "10750000"
  }
}
FieldTypeMeaning
buildrequiredobjectThe first built transaction.
buildsarrayEvery transaction of the plant, in order.
mintrequiredstringThe new coin's mint. Its page is /tree/<mint> once the plant confirms.
poolrequiredstringThe coin's curve pool.
firstBuyrequiredobject or nullThe first buy's quote, or null without one.
firstBuy.quoteInrequiredu64 amountLamports spent.
firstBuy.baseOutrequiredu64 amountCoins the quote expects.
firstBuy.minimumOutrequiredu64 amountThe fewest coins the plant accepts, from slippageBps.
firstBuy.feerequiredu64 amountEvery fee the first buy pays, in lamports.

The two transactions of a plant

OrderWhat it doescosignedsimulation
1Prepares the tree: its account, its purse and its own Raydium LaunchLab platform config. With a first buy it also moves the first buy's SOL into the planter's wrapped SOL account.truepassed
2Plants: creates the coin on its curve with the tree as its home, and makes the first buy.trueafter-predecessor, with previousBuildId naming the first

The wallet signs both in one signAllTransactions approval. The server adds the mint's signature to each after the wallet's, so both are submitted in relay mode: a wallet-sent submission of either is refused. Submit the first, follow it to confirmed, then submit the second. The second is simulated at that moment, on the exact bytes the wallet signed; a refusal answers the program's error and sends nothing.

The server keeps the new mint's key for 5 minutes from the build. A plant signed later than that answers TRANSACTION_EXPIRED on submit; build it again.

Resume a prepared plant

When the first transaction confirmed and the second was rejected, failed or expired, the tree is prepared and the first buy's SOL sits in the planter's wrapped SOL account. Build again with preparedMint set to the mint of the first answer, from the same wallet. With firstBuy at zero the answer holds the plant alone, simulated when it is built. With firstBuy above zero it holds a funding transaction, which moves that amount into the wrapped SOL account again, and then the plant; what the plant does not spend returns to the wallet when the account closes.

Errors of a plant build: VALIDATION_ERROR (400). QUOTE_TOO_SMALL (422) for a first buy too small to buy a coin or larger than the curve can fill. MINT_STOCK_EMPTY (503, retryAfterSeconds: 30) when no mint is ready. With preparedMint: NOT_FOUND (404) when no prepared tree has that mint, NOT_THE_PLANTER (403) when another wallet prepared it, VALIDATION_ERROR when it is already planted, TRANSACTION_EXPIRED (409) when the server no longer holds its key. PROGRAM_UNAVAILABLE (409), SIMULATION_FAILED or CHAIN_REFUSED (422), UPSTREAM_UNAVAILABLE (502), RATE_LIMITED (429).

Build a trade

POST /v1/trade/build builds a buy or a sell and answers its quote. Client method: buildTrade(body). Trades are exact in: a buy spends amount lamports, a sell spends amount coins. The route picks the venue from the coin's phase: the curve, or its pool after graduation.

FieldTypeMeaning
walletrequiredstringThe trader's wallet.
mintrequiredstringThe coin.
siderequiredstringbuy or sell.
amountrequiredpositive u64 amountLamports to spend on a buy, coin base units to sell on a sell.
slippageBpsbpsHow far the result may fall below the quote, 0 to 5,000. Default 100.
echostringThe wallet whose echo brought this buyer. Ignored on a sell.
Shell
curl -X POST https://api.kodama.example/v1/trade/build \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
    "mint": "HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf",
    "side": "buy",
    "amount": "100000000",
    "echo": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787"
  }'
JSON
{
  "build": {
    "id": "fx-3b388b2f-c03f-4d86-971f-42cd0b7a8c1b",
    "transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
    "blockhash": "HbyxnXpHFEA7DaVysDEhVxeLsstxYiU6mzk4bNuo8Zzu",
    "lastValidBlockHeight": 290000016,
    "cosigned": false,
    "simulation": "passed"
  },
  "builds": [
    {
      "id": "fx-3b388b2f-c03f-4d86-971f-42cd0b7a8c1b",
      "transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
      "blockhash": "HbyxnXpHFEA7DaVysDEhVxeLsstxYiU6mzk4bNuo8Zzu",
      "lastValidBlockHeight": 290000016,
      "cosigned": false,
      "simulation": "passed"
    }
  ],
  "quote": {
    "venue": "curve",
    "amountIn": "100000000",
    "amountOut": "3210078506005",
    "minimumOut": "3177977720944",
    "fee": "2150000",
    "priceImpactBps": 31,
    "echo": {
      "wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
      "shareLamports": "200000"
    }
  }
}
FieldTypeMeaning
buildrequiredobjectThe built transaction.
buildsarrayThe ordered list, when the trade takes it.
quote.venuerequiredstringcurve or cpmm.
quote.amountInrequiredu64 amountWhat the trade spends: lamports on a buy, coins on a sell.
quote.amountOutrequiredu64 amountWhat the quote expects back: coins on a buy, lamports on a sell.
quote.minimumOutrequiredu64 amountThe least the transaction accepts, from slippageBps. Below it the trade fails and nothing moves.
quote.feerequiredu64 amountEvery fee the trade pays, in lamports: the tree's 1.9% and Raydium's own.
quote.priceImpactBpsrequirednumberHow far the trade moves the price.
quote.echorequiredobject or nullThe echo the build accepted, or null.
quote.echo.walletrequiredstringThe kodama the buy is attributed to.
quote.echo.shareLamportsrequiredu64 amountThe echo share the buy sets aside: amountIn times fee.echo over 1,000,000.

A buy through an echo

Pass the echo's wallet as echo on a buy. When that wallet has coins in the tree, quote.echo names it and its share, and the buy is made through the kodama program, which records the share for it. When it has none, quote.echo is null and the buy is a plain buy. A wallet may pass its own address. The buyer's fee and the coins received are the same either way.

Whether the echo's wallet still has coins in the tree is checked again when the buy lands, so quote.echo is what the build expects, settled on chain. A malformed echo is a VALIDATION_ERROR. The echo and its share are told in Echoes.

Errors of a trade build: VALIDATION_ERROR (400). NOT_FOUND (404) for a mint without a tree or one not launched here. CURVE_COMPLETE (409, retryable: true, retryAfterSeconds: 15) while the coin is migrating or its pool is not open yet. QUOTE_TOO_SMALL (422) when the amount buys or returns nothing after fees. CHAIN_REFUSED (422) when a program refuses the trade in simulation, for example a sell of more coins than the wallet holds. SIMULATION_FAILED (422), PROGRAM_UNAVAILABLE (409), UPSTREAM_UNAVAILABLE (502), RATE_LIMITED (429).

Build a move in or a move out

POST /v1/move-in/build moves coins from the wallet into a tree; POST /v1/move-out/build moves them back. Client methods: buildMoveIn(body) and buildMoveOut(body). Both take the same body.

FieldTypeMeaning
walletrequiredstringThe wallet moving.
mintrequiredstringThe tree's coin.
amountrequiredpositive u64 amountCoins to move, in coin base units. A coin has 6 decimals.
Shell
curl -X POST https://api.kodama.example/v1/move-in/build \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
    "mint": "HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf",
    "amount": "1000000000"
  }'
JSON
{
  "build": {
    "id": "fx-a3c37cb9-eb45-44e7-ba95-37721a65868c",
    "transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
    "blockhash": "Bu2DMRYbQG4fXz2NYH3bDTxotLF38C4yn5gNy18LuesW",
    "lastValidBlockHeight": 290000018,
    "cosigned": false,
    "simulation": "passed"
  },
  "builds": [
    {
      "id": "fx-a3c37cb9-eb45-44e7-ba95-37721a65868c",
      "transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
      "blockhash": "Bu2DMRYbQG4fXz2NYH3bDTxotLF38C4yn5gNy18LuesW",
      "lastValidBlockHeight": 290000018,
      "cosigned": false,
      "simulation": "passed"
    }
  ],
  "mints": [
    "HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf"
  ],
  "dayIndex": 20772,
  "closesPreviousDay": false
}

The answer is a tree action build.

Errors of a move in: NOT_FOUND (404) for a mint without a tree, CHAIN_REFUSED (422) when the wallet holds fewer coins than amount. Errors of a move out: NOT_A_KODAMA (409) when the wallet has no record in the tree, AMOUNT_ABOVE_COINS_IN_TREE (422) when amount is more than it has there. Both: VALIDATION_ERROR (400), SIMULATION_FAILED (422), PROGRAM_UNAVAILABLE (409), UPSTREAM_UNAVAILABLE (502), RATE_LIMITED (429).

Build water, pick or an echo claim

Three routes act on one tree or many in one request: POST /v1/water/build, POST /v1/pick/build and POST /v1/claim-echo/build. Client methods: buildWater(body), buildPick(body) and buildClaimEcho(body). They take the same body.

FieldTypeMeaning
walletrequiredstringThe kodama's wallet.
mintsrequiredstring[]The trees' coins. At least one, each named once.
Shell
curl -X POST https://api.kodama.example/v1/pick/build \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
    "mints": [
      "HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf",
      "HuxV1uq4nPT3MjvevFyEfTAD4DHp2aMLHhsKHVGNKGgU"
    ]
  }'
JSON
{
  "build": {
    "id": "fx-a367b0c7-f089-4979-a8fa-2699b3b23bb0",
    "transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
    "blockhash": "5boTEoGvstdVTc3UTwKeiEJeFbhsdETU7YzDJw5ZxFar",
    "lastValidBlockHeight": 290000020,
    "cosigned": false,
    "simulation": "passed"
  },
  "builds": [
    {
      "id": "fx-a367b0c7-f089-4979-a8fa-2699b3b23bb0",
      "transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
      "blockhash": "5boTEoGvstdVTc3UTwKeiEJeFbhsdETU7YzDJw5ZxFar",
      "lastValidBlockHeight": 290000020,
      "cosigned": false,
      "simulation": "passed"
    }
  ],
  "mints": [
    "HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf",
    "HuxV1uq4nPT3MjvevFyEfTAD4DHp2aMLHhsKHVGNKGgU"
  ],
  "dayIndex": 20772,
  "closesPreviousDay": false
}

The answer is a tree action build. The request is checked tree by tree, and one tree that cannot take the action refuses the whole request, so build with the mints that can: the lists a wallet's kodama records and its echoes give.

ActionWhat it doesRefused with
WaterPuts the kodama into today's split of each tree with its counted coins. Once per tree per day.NOT_A_KODAMA (409): no coins in the tree. ALREADY_WATERED_TODAY (409). NO_COINS_COUNTING_TODAY (409): every coin was moved in today.
Pick fruitPays the fruit ready in each tree to the wallet.NOT_A_KODAMA (409): no record in the tree. NOTHING_TO_PICK (409).
Claim an echo sharePays the echo share ready in each tree to the wallet.NOT_A_KODAMA (409): no record in the tree. NOTHING_TO_CLAIM_ECHO (409).

All three also answer NOT_FOUND (404) for a mint without a tree, VALIDATION_ERROR (400), SIMULATION_FAILED or CHAIN_REFUSED (422), PROGRAM_UNAVAILABLE (409), UPSTREAM_UNAVAILABLE (502) and RATE_LIMITED (429).

Build a claim

POST /v1/claim/build claims the planter's share waiting in one tree. Client method: buildClaim(body).

FieldTypeMeaning
walletrequiredstringThe planter's wallet.
mintrequiredstringThe tree's coin.
Shell
curl -X POST https://api.kodama.example/v1/claim/build \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
    "mint": "HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf"
  }'
JSON
{
  "build": {
    "id": "fx-23e89f21-b8cc-4ce8-94d0-7539aea644bd",
    "transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
    "blockhash": "EqsGQDHRgc5t57hTM9DPe1JNsAMYPnRsdb5mQp9cXYQh",
    "lastValidBlockHeight": 290000021,
    "cosigned": false,
    "simulation": "passed"
  },
  "builds": [
    {
      "id": "fx-23e89f21-b8cc-4ce8-94d0-7539aea644bd",
      "transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
      "blockhash": "EqsGQDHRgc5t57hTM9DPe1JNsAMYPnRsdb5mQp9cXYQh",
      "lastValidBlockHeight": 290000021,
      "cosigned": false,
      "simulation": "passed"
    }
  ],
  "mints": [
    "HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf"
  ],
  "dayIndex": 20772,
  "closesPreviousDay": false
}

The answer is a tree action build. The sample's wallet planted this tree. From any other wallet the same request answers:

JSON
{
  "error": {
    "code": "NOT_THE_PLANTER",
    "message": "You are not the planter of this tree.",
    "retryable": false,
    "stage": "build"
  }
}

Errors: NOT_THE_PLANTER (403), NOTHING_TO_CLAIM (409), NOT_FOUND (404) for a mint without a tree, VALIDATION_ERROR (400), SIMULATION_FAILED or CHAIN_REFUSED (422), PROGRAM_UNAVAILABLE (409), UPSTREAM_UNAVAILABLE (502), RATE_LIMITED (429).

A tree action build

Move in, move out, water, pick and both claims answer the same shape.

FieldTypeMeaning
buildrequiredobjectThe first built transaction.
buildsarrayEvery transaction of the action, in order.
mintsrequiredstring[]The trees the action touches, as asked.
dayIndexrequirednumberThe day the action lands in.
closesPreviousDayrequiredbooleantrue when a tree's open day is an earlier day: the transaction first harvests and closes that day, then acts.

A day closes with the first action of the next day, so closesPreviousDay is true on the first build after 00:00 UTC for a tree nobody has touched since.

What the wallet signs

transactionBase64 decodes to an unsigned versioned transaction whose fee payer is the request's wallet. It already holds its compute limit and priority fee, and resolves its accounts through the platform's lookupTables. The wallet signs it as it is, as the fee payer; no other signature is asked of the wallet.

The buildSign withSubmit as
One transaction, cosigned: false, no previousBuildIdsignTransaction, or signAndSendTransactionrelay with the signed bytes, or wallet-sent with the signature the wallet returned
cosigned: true, or with previousBuildIdsignTransactionrelay
A builds list of severalsignAllTransactions, oncerelay, one at a time, in order

Wallets may add their own instructions before signing. A relayed copy is accepted as long as the fee payer is unchanged and has signed, the action's own instruction is still there, and no program the action does not use was added. On a co-signed transaction, nothing the mint's signature covers may change. Anything else answers VALIDATION_ERROR with the stage wallet or co_sign, and the copy is not sent.

Submit

POST /v1/transactions/submit hands a signed transaction to the service, or reports one the wallet sent. Client method: submit(body). The body is one of two shapes, told apart by mode.

Relay: the service checks the signed copy, co-signs it when the build needs it, simulates those exact bytes, records them and broadcasts them.

FieldTypeMeaning
moderequiredstringrelay.
buildIdrequiredstringThe build's id.
signedTransactionBase64requiredstringThe transaction as the wallet signed it, in base64.
idempotencyKeyrequiredstringA key of 8 to 64 characters you make up for this submission, for example a UUID.

Wallet-sent: the wallet broadcast the transaction itself, and the service follows its signature.

FieldTypeMeaning
moderequiredstringwallet-sent.
buildIdrequiredstringThe build's id.
signaturerequiredstringThe signature the wallet returned.
idempotencyKeyrequiredstringA key of 8 to 64 characters.

The answer is a transaction status, submitted with the transaction's signature.

Sending the same body again with the same idempotencyKey answers the current status and sends nothing twice, so a request that timed out is safe to repeat. A second submission of a build under another key answers IDEMPOTENCY_CONFLICT (409).

Errors: NOT_FOUND (404, retryable: true) with This transaction was not built here, or it has been forgotten. Build it again. IDEMPOTENCY_CONFLICT (409). VALIDATION_ERROR (400) for a wallet-sent submission of a co-signed or dependent build, for a dependent build whose predecessor has not confirmed (retryable: true), and for a signed copy the wallet changed. TRANSACTION_EXPIRED (409, retryable: true) for a plant signed after the server let go of its mint key. A simulation the chain refuses answers CHAIN_REFUSED or SIMULATION_FAILED (422), or the action's own code such as ALREADY_WATERED_TODAY, with programError naming the program; nothing is sent. PROGRAM_UNAVAILABLE (409), UPSTREAM_UNAVAILABLE (502), RATE_LIMITED (429).

Follow a transaction

GET /v1/transactions/:id answers where a submitted build stands. Client method: status(id). Read it until the status is one of the four end states.

ParameterTypeMeaning
idrequiredstringThe build's id, in the path. 1 to 64 characters.
FieldTypeMeaning
idrequiredstringThe build's id.
statusrequiredstringOne of the six statuses below.
signaturestringThe transaction's signature, from submit on.
errorobjectWhy it failed or expired.
error.stagerequiredstringbuild, wallet-rejected, wallet-changed, simulation, send or confirm.
error.messagerequiredstringWhat happened, in one sentence.
error.nextStepstringWhat to do about it.
error.retryablerequiredbooleanWhether building and sending again can succeed.
error.programobjectThe program that failed the transaction: address, code (number or null) and name (string or null).
statusMeaningEnd state
submittedSent, not seen on chain yet. Keep reading.
unconfirmedA wallet-sent transaction that has not been seen and whose build has outlived its blockhash. It may still land. Keep reading.
confirmedLanded and confirmed. Its effects are in the reads. Submit the next item of a list now.yes
finalizedLanded and finalized.yes
failedLanded and failed on chain. error names the stage and the program. Nothing but the network fee was spent.yes
expiredA relayed transaction whose blockhash ran out before it landed. error.message is The transaction expired without landing. Nothing was spent. Build it again.yes

Each read does the work of following: it checks the signature, and re-sends a relayed transaction's same bytes while its blockhash lives. Never submit a build a second time to hurry it. The web app reads every 1,200 ms for up to 90 seconds.

Errors: NOT_FOUND (404) with Unknown transaction. VALIDATION_ERROR (400) for an id outside its length. UPSTREAM_UNAVAILABLE (502).

A worked sequence: water two trees

The whole path for one action. The wallet lives in four trees and has watered one today.

  1. Build. Ask for one water over two trees.

    Shell
    curl -X POST https://api.kodama.example/v1/water/build \
      -H "Content-Type: application/json" \
      -d '{
        "wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
        "mints": [
          "HuxV1uq4nPT3MjvevFyEfTAD4DHp2aMLHhsKHVGNKGgU",
          "HFCLo3EN66ksS5dFEDCbmR9RAXjT1yy5KxgN9QDp5UCM"
        ]
      }'
    JSON
    {
      "build": {
        "id": "fx-1fe6fd17-78bd-47b2-810b-756596eafb8d",
        "transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
        "blockhash": "776R8fFxFoKHwJ3uSUGD28jPuewBa7bsprDVx9MHr4Fz",
        "lastValidBlockHeight": 290000023,
        "cosigned": false,
        "simulation": "passed"
      },
      "builds": [
        {
          "id": "fx-1fe6fd17-78bd-47b2-810b-756596eafb8d",
          "transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
          "blockhash": "776R8fFxFoKHwJ3uSUGD28jPuewBa7bsprDVx9MHr4Fz",
          "lastValidBlockHeight": 290000023,
          "cosigned": false,
          "simulation": "passed"
        }
      ],
      "mints": [
        "HuxV1uq4nPT3MjvevFyEfTAD4DHp2aMLHhsKHVGNKGgU",
        "HFCLo3EN66ksS5dFEDCbmR9RAXjT1yy5KxgN9QDp5UCM"
      ],
      "dayIndex": 20772,
      "closesPreviousDay": false
    }

    One transaction waters both trees. closesPreviousDay is false: both trees are already on today.

  2. Sign. The wallet signs build.transactionBase64.

  3. Submit. Send the signed bytes with a key of your own.

    Shell
    curl -X POST https://api.kodama.example/v1/transactions/submit \
      -H "Content-Type: application/json" \
      -d '{
        "mode": "relay",
        "buildId": "fx-1fe6fd17-78bd-47b2-810b-756596eafb8d",
        "signedTransactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046d2F0ZXI6ZngtMWZlNmZkMTctNzhiZC00N2IyLTgxMGItNzU2NTk2ZWFmYjhk",
        "idempotencyKey": "docs-water-0001"
      }'
    JSON
    {
      "id": "fx-1fe6fd17-78bd-47b2-810b-756596eafb8d",
      "status": "submitted",
      "signature": "3TvcRMQnwr1CYL7DWkZ9nE18XDmYKNHoT8ZYXv3v1Uy2MPewQ1rtvhx7STayQZwaVJdbSrU1J5oQKZivZnvo9Sty"
    }
  4. Follow. Read the status until it is an end state.

    Shell
    curl https://api.kodama.example/v1/transactions/fx-1fe6fd17-78bd-47b2-810b-756596eafb8d
    JSON
    {
      "id": "fx-1fe6fd17-78bd-47b2-810b-756596eafb8d",
      "status": "confirmed",
      "signature": "3TvcRMQnwr1CYL7DWkZ9nE18XDmYKNHoT8ZYXv3v1Uy2MPewQ1rtvhx7STayQZwaVJdbSrU1J5oQKZivZnvo9Sty"
    }

    The water is confirmed. The wallet's kodama records now read wateredToday: true for both trees, and its totals.wateredToday went from 1 to 3. The same build submitted again under another key answers:

    JSON
    {
      "error": {
        "code": "IDEMPOTENCY_CONFLICT",
        "message": "This transaction was already submitted.",
        "retryable": false,
        "stage": "send"
      }
    }

The same sequence with the client. signAll stands for the wallet's signAllTransactions:

water.ts
import { createClient, type TxStatus } from './backend/src/contract/index.js'
import { fromBase64, toBase64 } from './backend/src/contract/encoding.js'

declare function signAll(transactions: Uint8Array[]): Promise<Uint8Array[]>

const api = createClient('https://api.kodama.example')
const END_STATES: TxStatus['status'][] = ['confirmed', 'finalized', 'failed', 'expired']

async function water(wallet: string, mints: string[]): Promise<TxStatus> {
  const built = await api.buildWater({ wallet, mints })
  const list = built.builds ?? [built.build]
  const signed = await signAll(list.map((build) => fromBase64(build.transactionBase64)))

  let last: TxStatus | undefined
  for (const [i, build] of list.entries()) {
    last = await api.submit({
      mode: 'relay',
      buildId: build.id,
      signedTransactionBase64: toBase64(signed[i]!),
      idempotencyKey: crypto.randomUUID(),
    })
    while (!END_STATES.includes(last.status)) {
      await new Promise((resolve) => setTimeout(resolve, 1_200))
      last = await api.status(build.id)
    }
    if (last.status === 'failed' || last.status === 'expired') break
  }
  return last!
}

Where to go next