Kora Quick Start Guide

Last Updated: 2025-10-31

Kora Basics

Kora is a JSON-RPC server that provides fee payment services for Solana transactions. It allows users to pay transaction fees with SPL tokens instead of SOL, enabling better UX for applications where users may not hold SOL.

Kora RPC validates client requests based on a configuration (kora.toml) that defines allowable programs, wallets, tokens, etc. Once validated, the Kora server will sign the transaction and send it to the network (or return a serialized siged transaction to the client).

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client App    │───▶│   Kora RPC      │───▶│   Solana RPC    │
│                 │    │   Server        │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────────┐
                       │   Kora Private Key   │
                       │ ( or Turnkey/Privy ) │
                       └──────────────────────┘

This quick start will launch a local Kora RPC server and demonstrate client integration for testing fee payment workflows.

Requirements

Solana CLI v2.2.x or greater
Rust/Cargo (for Kora RPC installation)
Node.js v22+ and a package manager (e.g., pnpm, npm)

Install Kora RPC

Install the Kora RPC server globally:

cargo install kora-cli

Important: Kora's main branch is an integration branch and may contain unreleased or beta changes. Always use the latest stable release tag for production and tutorial use. You can find the latest stable release on the Kora releases page.

Create Project

Clone the repository, checkout the latest stable tag, and navigate to the getting started demo directory:

git clone https://github.com/solana-foundation/kora
cd kora
git checkout v2.0.5
cd examples/getting-started/demo

Project Structure

The demo contains three main components:

Client Directory (client/src/)

setup.ts - Local environment setup (creates keypairs & writes them to .env, airdrops SOL, initializes test token)
quick-start.ts - Quick start demonstration script showing establishing a Kora connection and making a simple call to the Kora RPC server
full-demo.ts - Full demo script demonstration multiple Kora RPC methods

Server Directory (server/)

kora.toml - Kora RPC configuration defining validation rules, allowed tokens, and fee parameters
signers.toml - Signers configuration defining signers for the Kora server

Shared Configuration

.env - Environment variables for keypairs and addresses (create .env in root - demo/.env). The environment variables will be created by the setup script.

Setup Environment

First, create .env for your environment :

# Create .env file (will be populated by setup script)
touch .env

Setup Client

Install client dependencies:

# From project root (kora/)
cd examples/getting-started/demo/client
pnpm install --ignore-workspace # use --ignore-workspace to avoid pnpm workspace conflicts

Setup Kora RPC Server

The Kora server requires configuration to specify which tokens can be used for fee payment. Open server/kora.toml and note the validation section. Here we can specify several parameters that will be validated prior to signing a transaction:

max_allowed_lamports: maximum transaction fee you are willing to pay on behalf of the user
max_signatures: maximum number of signatures a transaction can have
price_source: oracle for determining token price ("Mock" or "Jupiter")
allowed_programs: whitelist of program IDs that can be executed (e.g., System Program, Token Program)
allowed_tokens: whitelist of tokens that are allowed to be transferred
allowed_spl_paid_tokens: array of mint addresses your program accepts as payment
disallowed_accounts: blacklist of accounts not allowed to interact with your kora RPC

For now, let's leave the default values--you can come back here and change these later (for more information on the configuration options, see the Kora Configuration documentation).

Setup Signers

Open server/signers.toml and note the signers section. Here we can specify which signers will be used to sign transactions and (if using multiple signers) a strategy for selecting which signer to use. For now, let's use a single-signer using the default values--you can come back here and change these later (for more information on the signers configuration, see the Signers Guide documentation).

Test Server

Open three terminals and run the following commands:

Terminal 1: Start Local Test Validator

# From project root or anywhere
solana-test-validator -r

Terminal 2: Initialize Environment

# From ./client directory
pnpm init-env

This script will:

Generate keypairs and save them to .env
Airdrop SOL to test accounts
Create and initialize a local USDC token
Fund test accounts with tokens

Important Make sure you copy the public key of the new USDC test token from your .env and update the allowed_tokens and allowed_spl_paid_tokens in ./server/kora.toml.

allowed_tokens = [
    "YOUR_USDC_LOCAL_PUBLICK_KEY"    # Update this based on the USDC_LOCAL_KEY public key comment in your .env
]
allowed_spl_paid_tokens = [
    "YOUR_USDC_LOCAL_PUBLICK_KEY"    # Update this based on the USDC_LOCAL_KEY public key comment in your .env
]

Terminal 3: Initialize Payment ATAs (Optional)

In order to receive payments, you'll need to initialize Associated Token Accounts (ATAs) for your payment tokens. You can do this by running the following command:

# From ./server directory
kora rpc initialize-atas --signers-config signers.toml

This command will:

Read your payment address from kora.toml (or if you have not specified a payment address, all of the signers listed in signers.toml)
Create ATAs for all tokens listed in allowed_spl_paid_tokens
Skip any ATAs that already exist
You can optionally specify a customer fee payer for ATA generation by using the fee_payer_key flag.

Terminal 4: Start Kora RPC Server

# From ./server directory
kora rpc start --signers-config signers.toml

Note: For production deployments using price_source = "Jupiter", you must set the JUPITER_API_KEY environment variable. The server will fail to start without it:
JUPITER_API_KEY=your_api_key kora rpc start --signers-config signers.toml

The server reads configuration from kora.toml and signers.toml and uses environment variables from the shared .env file. If you are using a different folder structure than specified here, you may need to use the --config to specify the location of kora.toml and --signers-config to specify the directory of your signers configuration:

kora rpc --config path/to/kora.toml start --signers-config path/to/signers.toml

You can access kora rpc -h for help on the RPC server options.

Terminal 5: Run Client Demo

# From ./client directory
pnpm start

You should see output similar to:

Kora Config: {
  fee_payer: 'Df2UmGQH86TBDsub7XZoSAo7KZa1ZJZr2w1PL1APUjjU',
  validation_config: {
    max_allowed_lamports: 1000000,
    max_signatures: 10,
    allowed_programs: [
      '11111111111111111111111111111111',
      'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA',
      'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL',
      'AddressLookupTab1e1111111111111111111111111',
      'ComputeBudget11111111111111111111111111111111'
    ],
    allowed_tokens: [
      'usdCAEFbouFGxdkbHCRtMTcN7DJHd3aCmP9vqjLgmAp'
    ],
    allowed_spl_paid_tokens: [
      'usdCAEFbouFGxdkbHCRtMTcN7DJHd3aCmP9vqjLgmAp'
    ],
    disallowed_accounts: [],
    price_source: 'Mock',
    fee_payer_policy: {...},
    price: { type: 'margin', margin: 0 }
  },
  enabled_methods: { ... }
 }
}
Blockhash:  C8W8d5w2H4jKXyFg5CEBoiaPvEpJ1am7xLxZ3fym4a2g

This confirms your Kora server is running and properly configured!

Next Steps

Once you have the basic setup working, check out the full Kora flow demo:

→ Kora Complete Gasless Transaction Flow

explore additional Kora RPC methods:

estimateTransactionFee - Calculate fees for transactions
getPayerSigner - Get the payer signer and payment destination
getSupportedTokens - Returns an array of supported payment tokens
signTransaction - Conditionally sign transactions when fees are covered
transferTransaction - Create transfer SOL or SPL token transfer transactions (signed by the Kora feepayer)
signAndSendTransaction - Conditionally signs a transaction with the Kora feepayer and sends it to the configured Solana RPC
getPaymentInstruction - Get a payment instruction for a transaction

Got questions? Ask questions the Solana Stack Exchange with a Kora tag.

Table of Contents