🚥Priority Fee API

What Are Priority Fees on Solana?

Priority fees are an optional fee you can add to your transactions to incentivize block producers (leaders) to include your transaction in the next block. Priority fees are priced in micro-lamports per compute unit. It is recommended to include a priority fee in your transactions, but how much should you pay?

Helius Priority Fee API

The getPriorityFeeEstimate is a new RPC method that provides fee recommendations based on historical data. Most importantly, it considers both global and local fee markets.

To use this API, you need to provide either a serialized transaction or a list of account keys.

To obtain the serialized transaction, you can use the transaction.serialize() method from the @solana/web3.js library. For more details on transaction serialization, refer to the Solana Web3.js documentation.

Here's an example using a serialized transaction::

{
  "jsonrpc": "2.0",
  "id": "helius-example",
  "method": "getPriorityFeeEstimate",
  "params": [
    {
      "transaction": "LxzhDW7TapzziJVHEGPh1QjmZB6kjNqmvuJ9gmihBGEkzw2N8ospDq32UZdVmKWzRZqKuyvhp7xmLvsmmHa3MfxVKpYoLV9cPkw5isHnHgDUwLSMsDaZ4dLEULexXAvuV9k6fLD2LMhFKM6gqH6j69GQLAm1g4e3z5ZVZN6pmJdSmZ4PqKcwNn4sS7E3Abp1hV59uBJB9i4jEdEAh28rZ8WCeNizzEmrJZFhatFFFGSDsk23jDPEjbkMcoRWXKf1WthFScC2S6Wz284Dtjqp7kW8eybV3DpmN9DtBbcfFNQPtUwmiBZCKszdYym5AjJvRHiUKUdMwFpC3toPnMvTmKZ9iHQtzZRkg5xBufRtUN5eVYJfdw2DxzH6RfqhC2rAjfSbfJA4wmaq9f5eUe2iEjmqvne6r85PPcHBJzyqkVtAyUFtTc9DfU8UiM9rFhQ2UB71M6m5UCsC6EwowMw5k8iF8rL7iPCLdubVdy8S58DPLNG4E4rdosev1T63YdRWSgEwBZh7iX4zGBA9AKAm3B9itCSxLSL46Y6uZgVku9UXsMcWWz3URoa6hRbo55CYPLhrVeqjqX5DsXpaG6QkngbEaESQUnkakE1AFkYXmNXEd2m3sLRTYB2o5UTkwkJS2u5sJHyYqAvXr3vFZr7qAYFLD3LwS5tsdb45ZQVQwsbnNddMHgkpmSqLHS6Fv1epxqHbzpRCU1tgMsriApVWC3pj2LLD41HxkV8aKvkVyHgJFACUtbvRBZAasHf1F71Gz3qZNTdh3efWsZJRXnfxKPbATU7NTMaMUL8JjknfoVwp3",
      "options": {
        "recommended": true
      }
    }
  ]
}

And the API will provide you with a recommended fee:

{
    "jsonrpc": "2.0",
    "result": {
        "priorityFeeEstimate": 33549.0
    },
    "id": "helius-example"
}

The estimate is priced in micro-lamports per compute unit.

Alternatively, you can provide a list of account keys.

Here's an example that demonstrates how to extract account keys from a transaction and use them in the API request:

const { Transaction, Connection, ComputeBudgetProgram, PublicKey, TransactionInstruction } = require('@solana/web3.js');

// Initialize Connection object with Helius endpoint
const connection = new Connection("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY");

(async function getPriorityFeeEst() {
  const transaction = new Transaction();

  // A sample instruction to the transaction
  transaction.add(
    new TransactionInstruction({
        programId: new PublicKey("MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr"),
        data: Buffer.from("Experimenting", "utf8"),
        keys: [],
    })
  )

  transaction.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
  transaction.feePayer = new PublicKey("A3r2FvL1BkAGmcv74vQ5fVpFdm7GttDKhn9RhYV3zifL");

  // Extract all account keys from the transaction
  const accountKeys = transaction.compileMessage().accountKeys;

  // Convert PublicKeys to base58 strings
  const publicKeys = accountKeys.map(key => key.toBase58());

  try {
    const response = await fetch(connection.rpcEndpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        jsonrpc: '2.0',
        id: 'helius-example',
        method: 'getPriorityFeeEstimate',
        params: [
          {
            accountKeys: publicKeys,
            options: {
              recommended: true,
            },
          }
        ],
      }),
    });

    const data = await response.json();

    const priorityFeeEstimate = data.result?.priorityFeeEstimate;

    // Add the priority fee to the transaction
    transaction.add(
      ComputeBudgetProgram.setComputeUnitPrice({
          microLamports: priorityFeeEstimate
      }),
    )

    console.log("Estimated priority fee:", priorityFeeEstimate);
    return priorityFeeEstimate;
  } catch (err) {
    console.error(`Error: ${err}`);
    return 10_000;
  }
})();

Here we are extracting all the account keys from the transaction using compileMessage, parsing the output and then passing all the public keys to the API.

It is crucial to extract and provide all relevant account keys because the local fee market is influenced by the number of transactions trying to interact with specific accounts. Providing all account keys allows the API to assess this local market condition accurately.

By following this method, you ensure that the priority fee estimate is as accurate and relevant as possible for your specific transaction.

Empty Slot Evaluation

The evaluateEmptySlotAsZero flag helps optimize priority fee calculations for accounts with sparse transaction history. When true, this mechanism smooths out fee estimation by treating slots with no transactions for a particular account as having zero fees, rather than excluding them from the calculation.

To implement, add the evaluateEmptySlotAsZero flag to your options parameter:

const response = await fetch(HELIUS_API_BASE, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: '1',
    method: 'getPriorityFeeEstimate',
    params: [{
      transaction: base58EncodedTransaction,
      options: {
        recommended: true,
        evaluateEmptySlotAsZero: true
      }
    }]
  })
});

This approach typically results in more reasonable fee estimates for accounts with infrequent activity. Monitor your transaction success rates when implementing this feature to ensure optimal performance for your specific use case.

How it Works

The method uses a set of predefined priority levels (percentiles) to dictate the returned estimate. Users can optionally specify to receive all the priority levels and adjust the window with which these are calculated via lookbackSlots

fn get_recent_priority_fee_estimate(request: GetPriorityFeeEstimateRequest) -> GetPriorityFeeEstimateResponse

struct GetPriorityFeeEstimateRequest {
  transaction: Option<String>,   // estimate fee for a serialized txn
  accountKeys: Option<Vec<String>>, // estimate fee for a list of accounts
  options: Option<GetPriorityFeeEstimateOptions>
}

struct GetPriorityFeeEstimateOptions {
	priorityLevel: Option<PriorityLevel>, // Default to MEDIUM
	includeAllPriorityFeeLevels: Option<bool>, // Include all priority level estimates in the response
	transactionEncoding: Option<UiTransactionEncoding>, // Default Base58
	lookbackSlots: Option<u8>, // The number of slots to look back to calculate the estimate. Valid numbers are 1-150, default is 150
	recommended: Option<bool>, // The Helius recommended fee for landing transactions
	includeVote: Option<bool>, // Include vote transactions in the priority fee estimate calculation. Default to true 
}

enum PriorityLevel {
	Min, // 0th percentile
	Low, // 25th percentile
	Medium, // 50th percentile
	High, // 75th percentile
	VeryHigh, // 95th percentile
  // labelled unsafe to prevent people from using and draining their funds by accident
	UnsafeMax, // 100th percentile 
	Default, // 50th percentile
}

struct GetPriorityFeeEstimateResponse {
  priority_fee_estimate: Option<MicroLamportPriorityFee>
  priority_fee_levels: Option<MicroLamportPriorityFeeLevels>
}

type MicroLamportPriorityFee = f64

struct MicroLamportPriorityFeeLevels {
	min: f64,
	low: f64,
	medium: f64,
	high: f64,
	veryHigh: f64,
	unsafeMax: f64,
}

Examples

Request all priority fee levels for Jup v6

{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "getPriorityFeeEstimate",
    "params": [{
        "accountKeys": ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"],
        "options": {
            "includeAllPriorityFeeLevels": true
        }
    }]
}

Response

{
    "jsonrpc": "2.0",
    "result": {
        "priorityFeeLevels": {
            "min": 0.0,
            "low": 2.0,
            "medium": 10082.0,
            "high": 100000.0,
            "veryHigh": 1000000.0,
            "unsafeMax": 50000000.0
        }
    },
    "id": "1"
}

Request the high priority level for Jup v6

{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "getPriorityFeeEstimate",
    "params": [{
        "accountKeys": ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"],
        "options": {
            "priorityLevel": "High"
        }
    }]
}

Response

{
    "jsonrpc": "2.0",
    "result": {
        "priorityFeeEstimate": 120000.0
    },
    "id": "1"
}

Sending a transaction with the Priority Fee API (Javascript)

This code snippet showcases how one can transfer SOL from one account to another. In this code, the transaction is passed to the priority fee API which then determines the specified priority fee from all the accounts involved in the transaction.

const {
  Connection,
  SystemProgram,
  Transaction,
  sendAndConfirmTransaction,
  Keypair,
  ComputeBudgetProgram,
} = require("@solana/web3.js");
const bs58 = require("bs58");

const HeliusURL = "https://mainnet.helius-rpc.com/?api-key=<YOUR_API_KEY>";
const connection = new Connection(HeliusURL);
const fromKeypair = Keypair.fromSecretKey(Uint8Array.from("[Your secret key]")); // Replace with your own private key
const toPubkey = "CckxW6C1CjsxYcXSiDbk7NYfPLhfqAm3kSB5LEZunnSE"; // Replace with the public key that you want to send SOL to

async function getPriorityFeeEstimate(priorityLevel, transaction) {
  const response = await fetch(HeliusURL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "getPriorityFeeEstimate",
      params: [
        {
          transaction: bs58.encode(transaction.serialize()), // Pass the serialized transaction in Base58
          options: { priorityLevel: priorityLevel },
        },
      ],
    }),
  });
  const data = await response.json();
  console.log(
    "Fee in function for",
    priorityLevel,
    " :",
    data.result.priorityFeeEstimate
  );
  return data.result;
}
async function sendTransactionWithPriorityFee(priorityLevel) {
  const transaction = new Transaction();
  const transferIx = SystemProgram.transfer({
    fromPubkey: fromKeypair.publicKey,
    toPubkey,
    lamports: 100,
  });
  transaction.add(transferIx);

  let feeEstimate = { priorityFeeEstimate: 0 };
  if (priorityLevel !== "NONE") {
    feeEstimate = await getPriorityFeeEstimate(priorityLevel, transaction);
    const computePriceIx = ComputeBudgetProgram.setComputeUnitPrice({
      microLamports: feeEstimate.priorityFeeEstimate,
    });
    transaction.add(computePriceIx);
  }
  
  transaction.recentBlockhash = (
    await connection.getLatestBlockhash()
  ).blockhash;
  transaction.sign(fromKeypair);

  try {
    const txid = await sendAndConfirmTransaction(connection, transaction, [
      fromKeypair,
    ]);
    console.log(`Transaction sent successfully with signature ${txid}`);
  } catch (e) {
    console.error(`Failed to send transaction: ${e}`);
  }
}

sendTransactionWithPriorityFee("High"); // Choose between "Min", "Low", "Medium", "High", "VeryHigh", "UnsafeMax"

Calculating the Percentiles (v1)

To calculate the percentiles, we need to consider the global and local fee market over transactions in the last N slots

For example,

priority_estimate(p: Percentile, accounts: Accounts) = 
	max(
		percentile(txn_fees, p), 
		percentile(account_fees(accounts), p)
	)

where txn_fees are the txn_fees from the last 150 blocks, and account_fees(accounts) are the fees for transactions containing these accounts from the last 150 blocks. Here, we are considering the total set of fees seen for accounts and transactions as opposed to the minimum.

Global Fee Market Estimate

The global fee market estimate is a percentile of priority fees paid for transactions in the last N slots.

Local Fee Market Estimate

The local fee market is influenced by the number of people trying to obtain a lock on an account. We can estimate this similarly to the global fee market but instead use the percentile of fees paid for transactions involving a given account(s). If a user requests an estimate for multiple accounts in the same transaction, we will take the max of the percentiles across those accounts.

Priority Fee Estimate

The priority_fee_estimate will be the max of the global and local fee market estimates.

Extensions

This method could also be integrated into simulateTransaction and returned with the response context. This way, developers using simulateTransaction can eliminate an extra RPC call.

Version 2 (V2)

The v2 logic more closely mimics the way the Agave scheduler prioritizes transactions. The algorithm is as follows

Updated Algorithm

The new algorithm for priority_estimate is as follows:

priority_estimate(p: Percentile, accounts: Accounts) = 
	max(
		percentile(txn_fees, p), 
		percentile(writable_account_fees(account1), p),
		percentile(writable_account_fees(account2), p),
		...,
		percentile(writable_account_fees(accountN), p)
	)

How to Access V2 Algorithm

The V2 algorithm will become the canonical version on September 30th. To access it before then you can by adding priority-fee-version=2.0 to the query params of your request.

NOTE: You can double check that you are correctly hitting the new endpoint if you see x-priority-fee-version=2.0 in your response headers.

Key Differences from V1

Individual Account Consideration: Instead of calculating a single percentile for all accounts involved (account_fees(accounts)), v2 calculates the percentile for each account separately.
Exclude readonly accounts: Local fee markets kick in when there is high demand to write to an account, so the calculation only considers historical fees for writable accounts. If you supply accounts in the request payload it will assume that all accounts are writable in the calculation. If you supply a transaction in the request payload it will only consider the writable accounts in the calculation.
Potential for Higher Estimates: In scenarios where one account has significantly higher fees than others, the v2 algorithm is more likely to capture this, potentially resulting in higher priority fee estimates compared to v1.

PreviousSending Transactions on Solana NextHelius RPCs Overview

Last updated 12 days ago