@meteora-ag/referral

TypeScript SDK for the Meteora Referral Staking Program on Solana.

Program ID: refr2gvtDhaFMqEAjnbK8X7xunqysns4MjVuz8PSf7r

Installation

bun add @meteora-ag/referral

Quick Start

Initialize a Staking Pool

import { Connection, Keypair } from "@solana/web3.js";
import BN from "bn.js";
import { Referral } from "@meteora-ag/referral";

const connection = new Connection("https://api.mainnet-beta.solana.com");
const payer = Keypair.generate();
const staking = Keypair.generate();

const transaction = await Referral.initializeStaking(connection, {
  owner: payer.publicKey,
  tokenMint,
  stakingPenaltyFeeReceiver: feeReceiver.publicKey,
  staking,
  payer: payer.publicKey,
  unstakeCooldownSeconds: new BN(86400),
  minStakingAmount: new BN(1_000_000),
  immediateUnstakePenaltyBps: 500, // 5%
});

Interact with an Existing Pool

const referral = await Referral.create(connection, stakingAddress);

// Initialize escrow for a user
const escrowTx = await referral.initializeEscrow({
  owner: user.publicKey,
  payer: payer.publicKey,
});

// Stake tokens
const stakeTx = await referral.stake({
  escrowAddress,
  payer: user.publicKey,
  amount: new BN(10_000_000),
});

// Quote immediate unstake with 1% slippage tolerance
const wrapper = referral.getStakingWrapper();
const { userReceiveAmount, penaltyFeeAmount, minReceiveAmount } =
  wrapper.quoteImmediateUnstake(new BN(10_000_000), 100);

// Immediate unstake (slippageBps auto-calculates minimumOutAmount)
const immUnstakeTx = await referral.immediateUnstake({
  escrowAddress,
  owner: user.publicKey,
  maxAmount: new BN(10_000_000),
  slippageBps: 100, // 1%
  receiver: user.publicKey,
});

// Or unstake with cooldown
const { transaction: unstakeTx, unstakeKeypair } = await referral.unstake({
  escrowAddress,
  owner: user.publicKey,
  payer: user.publicKey,
  maxAmount: new BN(10_000_000),
});

// Withdraw after cooldown
const withdrawTx = await referral.withdraw({
  unstakeAddress: unstakeKeypair.publicKey,
  escrowAddress,
  owner: user.publicKey,
  rentReceiver: user.publicKey,
  receiver: user.publicKey,
});

Staking Flow

User                                    Program
 |                                         |
 |-- initialize_escrow ------------------>|  Create escrow account
 |                                         |
 |-- stake(amount) ---------------------->|  Transfer tokens -> vault
 |                                         |
 |-- unstake(max_amount) ---------------->|  Start cooldown timer
 |         |                               |
 |         |-- withdraw ----------------->|  After cooldown: tokens -> user
 |         |                               |
 |         +-- cancel_unstake ----------->|  Return to staked state
 |                                         |
 +-- immediate_unstake(max_amount) ------>|  Deduct penalty, tokens -> user

Instructions

Permissionless

| Method | Description | | ------------------- | ---------------------------------------------------------------------- | | initializeStaking | Create a staking pool with cooldown, minimum stake, and penalty config | | initializeEscrow | Create a per-user escrow account linked to a staking pool | | stake | Deposit tokens into the vault | | unstake | Begin a time-locked unstake with cooldown | | cancelUnstake | Cancel a pending unstake, returning tokens to staked state | | withdraw | Claim tokens after the unstake cooldown has elapsed | | immediateUnstake | Instantly withdraw staked tokens, paying a penalty fee | | closeEscrow | Close an empty escrow account and reclaim rent | | claimPenaltyFee | Withdraw accumulated penalty fees to the configured fee receiver |

Permissioned (Owner)

| Method | Description | | -------------------------- | ----------------------------------------------------------------- | | updatePenaltyFeeReceiver | Change the account that receives penalty fees | | updateConfig | Modify staking pool parameters (cooldown, min stake, penalty bps) | | transferOwner | Transfer staking pool ownership to a new account |

Account Wrappers

The SDK provides read-only wrappers for convenient state access:

• StakingWrapper — Pool state, config, and metrics
• EscrowWrapper — User escrow balances with isEmpty() / canClose() helpers
• UnstakeWrapper — Unstake record with canWithdraw() / getTimeUntilWithdrawable() cooldown helpers

Development

bun install
bun run build
bun test