Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

21.4 KB
Raw Blame
// agent-payments-sdk
// Copyright (c) 2026 nirholas | x.com/nichxbt | github.com/nirholas
// All rights reserved.

/**
 * PumpTradeClient — v2 bonding-curve buy / sell / exact-quote / cashback.
 *
 * All build* methods batch Global + FeeConfig + bondingCurve (+ userAta for buy)
 * into a SINGLE getMultipleAccountsInfo call. No sequential RPC.
 *
 * Routing: reads bondingCurve.quoteMint on-chain → SOL-paired or USDC-paired
 * coins are handled identically. Zero changes needed when USDC coins go live.
 */

import BN from "bn.js";
import {
  ASSOCIATED_TOKEN_PROGRAM_ID,
  NATIVE_MINT,
  TOKEN_2022_PROGRAM_ID,
  TOKEN_PROGRAM_ID,
  createAssociatedTokenAccountIdempotentInstruction,
  getAssociatedTokenAddressSync,
} from "@solana/spl-token";
import {
  Connection,
  PublicKey,
  SystemProgram,
  TransactionInstruction,
} from "@solana/web3.js";
import {
  GLOBAL_PDA,
  GLOBAL_VOLUME_ACCUMULATOR_PDA,
  PUMP_EVENT_AUTHORITY_PDA,
  PUMP_FEE_CONFIG_PDA,
  PUMP_FEE_PROGRAM_ID,
  PUMP_PROGRAM_ID,
  PUMP_SDK,
  bondingCurveMarketCap,
  bondingCurvePda,
  creatorVaultPda,
  feeSharingConfigPda,
  getBuySolAmountFromTokenAmount,
  getBuyTokenAmountFromSolAmount,
  getPumpProgram,
  getSellSolAmountFromTokenAmount,
  userVolumeAccumulatorPda,
} from "@pump-fun/pump-sdk";
import { pickBuybackFeeRecipient, pickFeeRecipient } from "./constants.js";
import type {
  BuyQuote,
  BuyResult,
  ExactQuoteResult,
  SellQuote,
  SellResult,
} from "./types.js";

// ─── Errors ───────────────────────────────────────────────────────────────────

/** Coin has graduated (bondingCurve.complete === true). Use AMM. */
export class CoinGraduatedError extends Error {
  constructor(mint: PublicKey) {
    super(
      `Bonding curve for mint ${mint.toBase58()} is complete — use AMM instead.`,
    );
    this.name = "CoinGraduatedError";
  }
}

/** No bonding curve account exists for the mint. */
export class CoinNotFoundError extends Error {
  constructor(mint: PublicKey) {
    super(`Bonding curve account not found for mint ${mint.toBase58()}.`);
    this.name = "CoinNotFoundError";
  }
}

/** Requested amount exceeds available reserves. */
export class InsufficientLiquidityError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "InsufficientLiquidityError";
  }
}

/** Quote mint is not in the pump.fun whitelist. */
export class UnsupportedQuoteMintError extends Error {
  constructor(quoteMint: PublicKey) {
    super(
      `Quote mint ${quoteMint.toBase58()} is not owned by TOKEN_PROGRAM_ID or TOKEN_2022_PROGRAM_ID.`,
    );
    this.name = "UnsupportedQuoteMintError";
  }
}

// ─── Internal helpers ─────────────────────────────────────────────────────────

const USDC_MINT = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");

const KNOWN_TOKEN_PROGRAMS = new Set([
  TOKEN_PROGRAM_ID.toBase58(),
  TOKEN_2022_PROGRAM_ID.toBase58(),
]);

function resolveQuoteMintFromCurve(quoteMintOnChain: PublicKey): PublicKey {
  if (!quoteMintOnChain || quoteMintOnChain.equals(PublicKey.default)) {
    return NATIVE_MINT;
  }
  return quoteMintOnChain;
}

function clamp(value: number, min: number, max: number): number {
  return Math.min(max, Math.max(min, value));
}

function computePriceImpactPct(quoteAmount: BN, marketCap: BN): number {
  if (marketCap.isZero()) return 0;
  return clamp((quoteAmount.toNumber() / marketCap.toNumber()) * 100, 0, 100);
}

// ─── PumpTradeClient ──────────────────────────────────────────────────────────

export class PumpTradeClient {
  /** quoteMint never changes once a coin is created — safe to cache forever. */
  private readonly quoteMintCache = new Map<string, PublicKey>();
  /** Token program for a quote mint (also stable after mint creation). */
  private readonly tokenProgramCache = new Map<string, PublicKey>();

  constructor(private readonly connection: Connection) {}

  // ── resolveQuoteMint ────────────────────────────────────────────────────────

  /** Read bondingCurve.quoteMint from chain, normalize default → NATIVE_MINT. Caches. */
  async resolveQuoteMint(mint: PublicKey): Promise<PublicKey> {
    const key = mint.toBase58();
    const cached = this.quoteMintCache.get(key);
    if (cached) return cached;

    const info = await this.connection.getAccountInfo(bondingCurvePda(mint));
    if (!info) throw new CoinNotFoundError(mint);

    const curve = PUMP_SDK.decodeBondingCurve(info);
    const resolved = resolveQuoteMintFromCurve(curve.quoteMint);
    this.quoteMintCache.set(key, resolved);
    return resolved;
  }

  // ── quoteForBuy ─────────────────────────────────────────────────────────────

  async quoteForBuy(params: {
    mint: PublicKey;
    quoteAmount: BN;
    slippagePct?: number;
  }): Promise<BuyQuote> {
    const { mint, quoteAmount } = params;
    const slippage = params.slippagePct ?? 5;

    const {
      global,
      feeConfig,
      bondingCurve,
      quoteMint,
      quoteTokenProgram,
    } = await this._fetchAndDecode(mint);

    const mintSupply = bondingCurve.tokenTotalSupply;

    const expectedBaseTokens = getBuyTokenAmountFromSolAmount({
      global, feeConfig, mintSupply, bondingCurve, amount: quoteAmount, quoteMint,
    });

    const preciseQuoteAmount = getBuySolAmountFromTokenAmount({
      global, feeConfig, mintSupply, bondingCurve, amount: expectedBaseTokens, quoteMint,
    });

    // Slippage applied in integer BN math: toNumber() on a lamport BN throws
    // above 2^53 (~9M SOL) and loses precision on money below it. bps = slippage%
    // × 100; ceil via (x·(10000+bps) + 9999) / 10000.
    const buyBps = Math.max(0, Math.round(slippage * 100));
    const maxQuoteCost = preciseQuoteAmount.muln(10_000 + buyBps).addn(9_999).divn(10_000);

    const marketCap = bondingCurveMarketCap({
      mintSupply,
      virtualQuoteReserves: bondingCurve.virtualQuoteReserves,
      virtualTokenReserves: bondingCurve.virtualTokenReserves,
    });

    return {
      quoteMint,
      quoteTokenProgram,
      quoteAmount,
      expectedBaseTokens,
      preciseQuoteAmount,
      maxQuoteCost,
      slippagePct: slippage,
      priceImpactPct: computePriceImpactPct(quoteAmount, marketCap),
    };
  }

  // ── quoteForSell ────────────────────────────────────────────────────────────

  async quoteForSell(params: {
    mint: PublicKey;
    baseAmount: BN;
    slippagePct?: number;
  }): Promise<SellQuote> {
    const { mint, baseAmount } = params;
    const slippage = params.slippagePct ?? 5;

    const {
      global,
      feeConfig,
      bondingCurve,
      quoteMint,
      quoteTokenProgram,
    } = await this._fetchAndDecode(mint);

    const mintSupply = bondingCurve.tokenTotalSupply;

    const expectedQuoteOut = getSellSolAmountFromTokenAmount({
      global, feeConfig, mintSupply, bondingCurve, amount: baseAmount,
    });

    // Integer BN math (see quoteForBuy): floor via x·(10000−bps) / 10000, with
    // the multiplier clamped at 0 so slippage > 100% floors the bound to zero.
    const sellBps = Math.max(0, Math.round(slippage * 100));
    const minQuoteOut = expectedQuoteOut.muln(Math.max(0, 10_000 - sellBps)).divn(10_000);

    const marketCap = bondingCurveMarketCap({
      mintSupply,
      virtualQuoteReserves: bondingCurve.virtualQuoteReserves,
      virtualTokenReserves: bondingCurve.virtualTokenReserves,
    });

    return {
      quoteMint,
      quoteTokenProgram,
      baseAmount,
      expectedQuoteOut,
      minQuoteOut,
      slippagePct: slippage,
      priceImpactPct: computePriceImpactPct(expectedQuoteOut, marketCap),
    };
  }

  // ── buildBuyInstructions ────────────────────────────────────────────────────

  async buildBuyInstructions(params: {
    mint: PublicKey;
    user: PublicKey;
    quoteAmount: BN;
    slippagePct?: number;
  }): Promise<BuyResult> {
    const { mint, user, quoteAmount } = params;
    const slippage = params.slippagePct ?? 5;

    const baseTokenProgram = await this._baseTokenProgram(mint);
    const userAta = getAssociatedTokenAddressSync(mint, user, true, baseTokenProgram);

    // Single batch RPC: Global + FeeConfig + bondingCurve + userAta
    const bcAddr = bondingCurvePda(mint);
    const [globalInfo, feeConfigInfo, bcInfo, userAtaInfo] =
      await this.connection.getMultipleAccountsInfo([
        GLOBAL_PDA, PUMP_FEE_CONFIG_PDA, bcAddr, userAta,
      ]);

    if (!globalInfo) throw new Error("Global account not found — wrong network?");
    if (!bcInfo) throw new CoinNotFoundError(mint);

    const global = PUMP_SDK.decodeGlobal(globalInfo);
    const feeConfig = feeConfigInfo ? PUMP_SDK.decodeFeeConfig(feeConfigInfo) : null;
    const bondingCurve = PUMP_SDK.decodeBondingCurve(bcInfo);

    if (bondingCurve.complete) throw new CoinGraduatedError(mint);

    const quoteMint = resolveQuoteMintFromCurve(bondingCurve.quoteMint);
    this.quoteMintCache.set(mint.toBase58(), quoteMint);
    const quoteTokenProgram = await this._quoteTokenProgram(quoteMint);

    const mintSupply = bondingCurve.tokenTotalSupply;

    const expectedBaseTokens = getBuyTokenAmountFromSolAmount({
      global, feeConfig, mintSupply, bondingCurve, amount: quoteAmount, quoteMint,
    });

    if (expectedBaseTokens.lte(new BN(0))) {
      throw new InsufficientLiquidityError(
        "Computed token amount is zero — amount too small or reserves exhausted.",
      );
    }

    const preciseQuoteAmount = getBuySolAmountFromTokenAmount({
      global, feeConfig, mintSupply, bondingCurve, amount: expectedBaseTokens, quoteMint,
    });

    const mayhemMode = bondingCurve.isMayhemMode ?? false;
    const feeRecipient = pickFeeRecipient(global, mayhemMode);
    const buybackFeeRecipient = pickBuybackFeeRecipient();

    const instructions = await PUMP_SDK.buyV2Instructions({
      global,
      bondingCurveAccountInfo: bcInfo,
      bondingCurve,
      associatedUserAccountInfo: userAtaInfo ?? null,
      mint,
      user,
      amount: expectedBaseTokens,
      quoteAmount: preciseQuoteAmount,
      slippage,
      tokenProgram: baseTokenProgram,
      quoteTokenProgram,
    });

    return {
      instructions,
      quoteMint,
      quoteTokenProgram,
      expectedBaseTokens,
      preciseQuoteAmount,
      feeRecipient,
      buybackFeeRecipient,
    };
  }

  // ── buildSellInstructions ───────────────────────────────────────────────────

  async buildSellInstructions(params: {
    mint: PublicKey;
    user: PublicKey;
    baseAmount: BN;
    slippagePct?: number;
  }): Promise<SellResult> {
    const { mint, user, baseAmount } = params;
    const slippage = params.slippagePct ?? 5;

    const baseTokenProgram = await this._baseTokenProgram(mint);

    // Single batch RPC: Global + FeeConfig + bondingCurve
    const bcAddr = bondingCurvePda(mint);
    const [globalInfo, feeConfigInfo, bcInfo] =
      await this.connection.getMultipleAccountsInfo([
        GLOBAL_PDA, PUMP_FEE_CONFIG_PDA, bcAddr,
      ]);

    if (!globalInfo) throw new Error("Global account not found — wrong network?");
    if (!bcInfo) throw new CoinNotFoundError(mint);

    const global = PUMP_SDK.decodeGlobal(globalInfo);
    const feeConfig = feeConfigInfo ? PUMP_SDK.decodeFeeConfig(feeConfigInfo) : null;
    const bondingCurve = PUMP_SDK.decodeBondingCurve(bcInfo);

    if (bondingCurve.complete) throw new CoinGraduatedError(mint);

    const quoteMint = resolveQuoteMintFromCurve(bondingCurve.quoteMint);
    this.quoteMintCache.set(mint.toBase58(), quoteMint);
    const quoteTokenProgram = await this._quoteTokenProgram(quoteMint);

    const mintSupply = bondingCurve.tokenTotalSupply;

    const expectedQuoteOut = getSellSolAmountFromTokenAmount({
      global, feeConfig, mintSupply, bondingCurve, amount: baseAmount,
    });

    const instructions = await PUMP_SDK.sellV2Instructions({
      global,
      bondingCurveAccountInfo: bcInfo,
      bondingCurve,
      mint,
      user,
      amount: baseAmount,
      quoteAmount: expectedQuoteOut,
      slippage,
      tokenProgram: baseTokenProgram,
      quoteTokenProgram,
    });

    return { instructions, quoteMint, quoteTokenProgram, expectedQuoteOut };
  }

  // ── buildBuyExactQuoteInInstructions ────────────────────────────────────────

  /**
   * Build buy_exact_quote_in_v2. Drives the Anchor program directly because
   * the SDK has no JS helper for this instruction. Mirrors
   * swap/scripts/build-buy-exact-quote-in-v2-tx.mjs exactly.
   */
  async buildBuyExactQuoteInInstructions(params: {
    mint: PublicKey;
    user: PublicKey;
    spendableQuoteIn: BN;
    minBaseOut: BN;
  }): Promise<ExactQuoteResult> {
    const { mint, user, spendableQuoteIn, minBaseOut } = params;

    const baseTokenProgram = await this._baseTokenProgram(mint);

    // Single batch RPC: Global + FeeConfig + bondingCurve
    const bcAddr = bondingCurvePda(mint);
    const [globalInfo, _feeConfigInfo, bcInfo] =
      await this.connection.getMultipleAccountsInfo([
        GLOBAL_PDA, PUMP_FEE_CONFIG_PDA, bcAddr,
      ]);

    if (!globalInfo) throw new Error("Global account not found — wrong network?");
    if (!bcInfo) throw new CoinNotFoundError(mint);

    const global = PUMP_SDK.decodeGlobal(globalInfo);
    const bondingCurve = PUMP_SDK.decodeBondingCurve(bcInfo);

    if (bondingCurve.complete) throw new CoinGraduatedError(mint);

    const quoteMint = resolveQuoteMintFromCurve(bondingCurve.quoteMint);
    this.quoteMintCache.set(mint.toBase58(), quoteMint);
    const quoteTokenProgram = await this._quoteTokenProgram(quoteMint);

    const creator = bondingCurve.creator;
    const mayhemMode = bondingCurve.isMayhemMode ?? false;

    const feeRecipient = pickFeeRecipient(global, mayhemMode);
    const buybackFeeRecipient = pickBuybackFeeRecipient();

    const ata = (owner: PublicKey, tkProg: PublicKey) =>
      getAssociatedTokenAddressSync(quoteMint, owner, true, tkProg);

    const associatedQuoteFeeRecipient = ata(feeRecipient, quoteTokenProgram);
    const associatedQuoteBuybackFeeRecipient = ata(buybackFeeRecipient, quoteTokenProgram);
    const associatedBaseBondingCurve = getAssociatedTokenAddressSync(
      mint, bcAddr, true, baseTokenProgram,
    );
    const associatedQuoteBondingCurve = ata(bcAddr, quoteTokenProgram);
    const associatedBaseUser = getAssociatedTokenAddressSync(
      mint, user, true, baseTokenProgram,
    );
    const associatedQuoteUser = ata(user, quoteTokenProgram);
    const creatorVault = creatorVaultPda(creator);
    const associatedCreatorVault = ata(creatorVault, quoteTokenProgram);
    const userVolAcc = userVolumeAccumulatorPda(user);
    const associatedUserVolumeAccumulator = ata(userVolAcc, quoteTokenProgram);

    const program = getPumpProgram(this.connection);
    const buyExactIx = await program.methods
      .buyExactQuoteInV2(spendableQuoteIn, minBaseOut, { 0: false })
      .accountsPartial({
        global: GLOBAL_PDA,
        baseMint: mint,
        quoteMint,
        baseTokenProgram,
        quoteTokenProgram,
        associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
        feeRecipient,
        associatedQuoteFeeRecipient,
        buybackFeeRecipient,
        associatedQuoteBuybackFeeRecipient,
        bondingCurve: bcAddr,
        associatedBaseBondingCurve,
        associatedQuoteBondingCurve,
        user,
        associatedBaseUser,
        associatedQuoteUser,
        creatorVault,
        associatedCreatorVault,
        sharingConfig: feeSharingConfigPda(mint),
        globalVolumeAccumulator: GLOBAL_VOLUME_ACCUMULATOR_PDA,
        userVolumeAccumulator: userVolAcc,
        associatedUserVolumeAccumulator,
        feeConfig: PUMP_FEE_CONFIG_PDA,
        feeProgram: PUMP_FEE_PROGRAM_ID,
        systemProgram: SystemProgram.programId,
        eventAuthority: PUMP_EVENT_AUTHORITY_PDA,
        program: PUMP_PROGRAM_ID,
      })
      .instruction();

    const isNative = quoteMint.equals(NATIVE_MINT);
    const ataIxs: TransactionInstruction[] = [
      createAssociatedTokenAccountIdempotentInstruction(
        user, associatedBaseUser, user, mint, baseTokenProgram,
      ),
      ...(isNative
        ? []
        : [
            createAssociatedTokenAccountIdempotentInstruction(
              user, associatedQuoteUser, user, quoteMint, quoteTokenProgram,
            ),
          ]),
    ];

    return {
      instructions: [...ataIxs, buyExactIx],
      quoteMint,
      quoteTokenProgram,
    };
  }

  // ── buildClaimCashbackInstructions ──────────────────────────────────────────

  /**
   * Auto-discovers claimable quote mints by calling getTokenAccountsByOwner on
   * the UserVolumeAccumulator PDA. Any non-zero ATA → claimable cashback.
   * Pass quoteMints to skip discovery.
   */
  async buildClaimCashbackInstructions(params: {
    user: PublicKey;
    quoteMints?: PublicKey[];
  }): Promise<TransactionInstruction[]> {
    const { user } = params;
    let quoteMints = params.quoteMints;

    if (!quoteMints) {
      quoteMints = await this._discoverCashbackMints(user);
    }

    const ixs: TransactionInstruction[] = [];
    for (const quoteMint of quoteMints) {
      const quoteTokenProgram = await this._quoteTokenProgram(quoteMint);
      ixs.push(
        await PUMP_SDK.claimCashbackV2Instruction({
          user,
          quoteMint,
          quoteTokenProgram,
        }),
      );
    }
    return ixs;
  }

  // ── Private helpers ─────────────────────────────────────────────────────────

  private async _discoverCashbackMints(user: PublicKey): Promise<PublicKey[]> {
    const userVolAcc = userVolumeAccumulatorPda(user);
    const [splResult, t22Result] = await Promise.all([
      this.connection.getTokenAccountsByOwner(userVolAcc, {
        programId: TOKEN_PROGRAM_ID,
      }),
      this.connection.getTokenAccountsByOwner(userVolAcc, {
        programId: TOKEN_2022_PROGRAM_ID,
      }),
    ]);

    const mints: PublicKey[] = [];
    for (const { account } of [...splResult.value, ...t22Result.value]) {
      // SPL token account layout: mint = bytes 0–31, amount = bytes 64–71 (LE u64)
      const mintPk = new PublicKey(account.data.slice(0, 32));
      const amount = account.data.readBigUInt64LE(64);
      if (amount > 0n) mints.push(mintPk);
    }
    return mints;
  }

  private async _baseTokenProgram(mint: PublicKey): Promise<PublicKey> {
    const cacheKey = `base:${mint.toBase58()}`;
    const cached = this.tokenProgramCache.get(cacheKey);
    if (cached) return cached;
    const info = await this.connection.getAccountInfo(mint);
    if (!info) throw new Error(`Mint account not found: ${mint.toBase58()}`);
    const program = KNOWN_TOKEN_PROGRAMS.has(info.owner.toBase58())
      ? info.owner
      : TOKEN_PROGRAM_ID;
    this.tokenProgramCache.set(cacheKey, program);
    return program;
  }

  private async _quoteTokenProgram(quoteMint: PublicKey): Promise<PublicKey> {
    if (quoteMint.equals(NATIVE_MINT)) return TOKEN_PROGRAM_ID;
    const key = quoteMint.toBase58();
    const cached = this.tokenProgramCache.get(key);
    if (cached) return cached;
    const info = await this.connection.getAccountInfo(quoteMint, "confirmed");
    if (!info) throw new Error(`Quote mint not found: ${quoteMint.toBase58()}`);
    if (!KNOWN_TOKEN_PROGRAMS.has(info.owner.toBase58())) {
      throw new UnsupportedQuoteMintError(quoteMint);
    }
    this.tokenProgramCache.set(key, info.owner);
    return info.owner;
  }

  /**
   * Convenience: fetch + decode + throw in one call for quote methods.
   * Does NOT batch with userAta (quote methods don't need it).
   */
  private async _fetchAndDecode(mint: PublicKey) {
    const bcAddr = bondingCurvePda(mint);
    const [globalInfo, feeConfigInfo, bcInfo] =
      await this.connection.getMultipleAccountsInfo([
        GLOBAL_PDA, PUMP_FEE_CONFIG_PDA, bcAddr,
      ]);

    if (!globalInfo) throw new Error("Global account not found — wrong network?");
    if (!bcInfo) throw new CoinNotFoundError(mint);

    const global = PUMP_SDK.decodeGlobal(globalInfo);
    const feeConfig = feeConfigInfo ? PUMP_SDK.decodeFeeConfig(feeConfigInfo) : null;
    const bondingCurve = PUMP_SDK.decodeBondingCurve(bcInfo);

    if (bondingCurve.complete) throw new CoinGraduatedError(mint);

    const quoteMint = resolveQuoteMintFromCurve(bondingCurve.quoteMint);
    this.quoteMintCache.set(mint.toBase58(), quoteMint);
    const quoteTokenProgram = await this._quoteTokenProgram(quoteMint);

    return { global, feeConfig, bondingCurve, quoteMint, quoteTokenProgram };
  }

  /** Exported for convenience; USDC mainnet address. */
  static readonly USDC_MINT = USDC_MINT;
}