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.
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.
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).
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).
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]
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 directorykora 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.
# From ./server directorykora 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.