Kora Client

Kora Client Integration

Kora is a Solana paymaster: users pay fees in SPL tokens (e.g. USDC) instead of SOL.

Docs: https://launch.solana.com/docs/kora/ · SDK: @solana/kora (npm) Peer deps: @solana/kit v6+, @solana-program/token v0.10+

Where things are

Two client shapes

KoraClient is standalone; koraPlugin composes into a Kit client and returns Kit types (Address, Blockhash) rather than raw strings.

import { KoraClient } from '@solana/kora';
const client = new KoraClient({ rpcUrl, apiKey, hmacSecret, getRecaptchaToken });

// or
import { createEmptyClient } from '@solana/kit';
import { koraPlugin } from '@solana/kora';
const client = createEmptyClient().use(koraPlugin({ endpoint, apiKey, getRecaptchaToken }));
await client.kora.getConfig();

The transaction flow

Build instructions → build an estimate transaction with a noop signer as fee payer → getPaymentInstruction() → rebuild the final transaction with a fresh blockhash including the payment instruction → user partially signs → Kora co-signs via signTransaction or signAndSendTransaction.

Worked end-to-end code is in references/guides.md.

The parts that trip people up:

• The estimate transaction is thrown away. It exists only so Kora can price the transaction. The final transaction needs a new blockhash, not the estimate's.
• Noop signer: createNoopSigner(address(signerAddress)) reserves the fee payer slot before Kora has signed. Get the address from getPayerSigner().
• Signing order: the user signs their own instructions and the payment transfer. Kora only adds the fee payer signature; it will not fix a missing user signature.
• signer_key: optional, but pass it when the node runs a multi-signer pool so estimate and signature come from the same signer.
• user_id: required on signing methods when the operator runs free pricing with usage tracking enabled.

Lighthouse invalidates your signatures

If the operator enables Lighthouse, signTransaction and signBundle may return a transaction with an extra balance-assertion instruction. That changes the message, so any signature already applied is void: re-sign the returned transaction client-side and submit it yourself.

Lighthouse never applies to signAndSendTransaction / signAndSendBundle — Kora broadcasts those itself, so there is no opportunity to re-sign and the assertion is skipped.

Bundles

signBundle / signAndSendBundle take up to 5 transactions and execute atomically via Jito. sign_only_indices restricts which ones Kora signs. estimateBundleFee prices the set.

Authentication

All three can be active together, and the SDK builds the HMAC (SHA256 of timestamp + JSON body) for you. reCAPTCHA is checked only on the methods the operator marked protected, and only after API key / HMAC pass. /liveness always bypasses auth.