@derp-trade/sdk

A TypeScript SDK for derp.trade, a Solana-based derivatives trading platform using abstract futures.

The SDK helps you build derp.trade transactions, resolve market metadata, push prices, route order payments, and read market and position state from Solana.

Installation

npm install @derp-trade/sdk

Quickstart

Initialize the SDK

import { DerpSDK, MAINNET_RPC_URL } from "@derp-trade/sdk";
import { Wallet } from "@coral-xyz/anchor";
import { Connection, Keypair } from "@solana/web3.js";

const connection = new Connection(MAINNET_RPC_URL, "confirmed");
const keypair = Keypair.fromSecretKey(/* your secret key bytes */);
const wallet = new Wallet(keypair);

const sdk = new DerpSDK(connection, wallet);

⚠️ Important: The wallet provided when constructing the SDK should have funds (SOL) on it, otherwise some SDK functions will fail.

Place an Order

import BN from "bn.js";
import { PublicKey, Transaction } from "@solana/web3.js";

const mint = new PublicKey("6ogzHhzdrQr9Pgv6hZ2MNze7UrzBMAFyBBWUYp1Fhitx");

const instructions = await sdk.getOrderInstructions(mint, {
  reduceOnly: false,
  side: "long",
  orderAmount: new BN(1_000_000), // 1 USDT, USDT has 6 decimals
  leverageBps: new BN(20_000), // 2x leverage
});

const tx = new Transaction().add(...instructions);
const signature = await sdk.provider.sendAndConfirm(tx);

getOrderInstructions returns everything needed for a normal order: price update instructions followed by the order instruction.

Core Concepts

Amounts

Use BN for all raw on-chain amounts.

• orderAmount: input amount for the selected payment route.
• leverageBps: leverage in basis points, where 10_000 is 1x and 20_000 is 2x.
• Direct USDT and USDC amounts use 6 decimals.
• SOL amounts use lamports.
• Native token amounts use that token's base units.

Sides and Order Modes

await sdk.getOrderInstructions(mint, {
  reduceOnly: false,
  side: "short",
  orderAmount: new BN(5_000_000),
  leverageBps: new BN(15_000),
});

Set reduceOnly: true when the order should only reduce an existing position. Set useSize: true when orderAmount represents position size instead of payment input.

Referrals

const instructions = await sdk.getOrderInstructions(
  mint,
  {
    reduceOnly: false,
    side: "long",
    orderAmount: new BN(1_000_000),
    leverageBps: new BN(20_000),
  },
  {
    referralRecipient: referrerPublicKey,
    referralFeeBps: 25,
  },
);

Routing Payments

Orders can be paid directly with USDT or routed from supported quote assets.

const route = await sdk.buildRoutingContext("USDC", wallet.publicKey, {
  paymentAmountUsd: 25,
});

const instructions = await sdk.getOrderInstructions(mint, {
  reduceOnly: false,
  side: "long",
  orderAmount: route.orderAmount,
  routingContext: route,
  leverageBps: new BN(20_000),
});

Supported route inputs:

| Currency | Use case | Required options | | --- | --- | --- | | USDT | Direct USDT payment | paymentAmountUsd optional | | USDC | Route USDC to USDT | paymentAmountUsd | | SOL | Route SOL to USDT | paymentAmountUsd, solPrice |

Example SOL route:

const route = await sdk.buildRoutingContext("SOL", wallet.publicKey, {
  paymentAmountUsd: 50,
  solPrice: 150,
});

Managing Positions

Close a Position

const closeInstructions = await sdk.getClosePositionInstructions(mint);
await sdk.provider.sendAndConfirm(new Transaction().add(...closeInstructions));

If you already fetched the position, pass it to avoid another RPC read:

const position = await sdk.rawPosition(mint, wallet.publicKey);
const closeInstructions = await sdk.getClosePositionInstructions(mint, position);

Deposit and Withdraw Collateral

const depositIx = await sdk.rawDepositInstruction(
  mint,
  new BN(10_000_000), // 10 USDT
);

const withdrawIx = await sdk.rawWithdrawInstruction(mint);

Market Data

Use converted helpers when you want JavaScript numbers:

const status = await sdk.marketStatus(mint);
const position = await sdk.positionState(mint, wallet.publicKey);

console.log(status.markPrice, status.fundingRate);
console.log(position.side, position.size, position.collateral);

Use raw helpers when you want the Anchor account shape and BN values:

const rawMarket = await sdk.rawMarket(mint);
const rawOracle = await sdk.rawOracle(mint);
const rawPosition = await sdk.rawPosition(mint, wallet.publicKey);
const rawStatus = await sdk.rawMarketStatus(mint);
const config = await sdk.config();

You can also resolve the market type and token standard:

const market = await sdk.resolveMarket(mint);
const launchpad = await sdk.detectMarket(mint);

console.log(market.launchpad.launchpad, market.tokenStandard);
console.log(launchpad);

Supported Markets

The SDK supports the market sources used by derp.trade:

| Launchpad | Identifier | Notes | | --- | --- | --- | | Pump.fun | pump | Pump.fun and PumpSwap markets | | LetsBonk / Raydium LaunchLab | bonk | LaunchLab tokens with Raydium CPMM liquidity | | Meteora | meteora | Meteora DBC and DAMM v2 markets | | Raydium AMM v4 | raydiumAmmV4 | Raydium AMM v4 markets | | derp.trade feed | derpFeed | Signed derp.trade price feeds | | External | external | Supported external pool markets |

Market metadata is usually resolved automatically. If you already know the launchpad, or if you are building instructions before metadata is available, pass it explicitly:

await sdk.getOrderInstructions(
  mint,
  {
    reduceOnly: false,
    side: "long",
    orderAmount: new BN(1_000_000),
    leverageBps: new BN(20_000),
  },
  undefined,
  undefined,
  "pump",
);

For launchpads that need extra accounts, pass a LaunchpadData object:

await sdk.getPricePushInstructions(mint, {
  launchpadData: {
    launchpad: "meteora",
    meteoraDbcConfig,
    quoteMint,
  },
});

await sdk.getPricePushInstructions(mint, {
  launchpadData: {
    launchpad: "raydiumAmmV4",
    openbookMarket,
  },
});

Price Push Instructions

Most SDK methods that need fresh prices build the price push instructions for you. You can also build them directly:

const pushInstructions = await sdk.getPricePushInstructions(mint);
const pushInstruction = await sdk.getPricePushInstruction(mint);

Convenience helpers are also available:

const pumpPush = await sdk.rawPricePushPumpInstruction(mint);
const bonkPush = await sdk.rawPricePushBonkInstruction(mint);
const externalPush = await sdk.rawPricePushExternalInstruction(mint);

When market metadata is resolved through the Derp API, pump.fun quote mints and token standards are applied automatically. For explicit pump pushes, pass the quote mint and token standard:

import { USDC_ID } from "@derp-trade/sdk";

const pumpPush = await sdk.getPricePushInstruction(
  mint,
  { launchpad: "pump", quoteMint: USDC_ID, tokenStandard: "token2022" },
  wallet.publicKey,
);

const rawPumpPush = await sdk.rawPricePushPumpInstruction(mint, {
  user: wallet.publicKey,
  quoteMint: USDC_ID,
  tokenStandard: "token2022",
});

Creating Markets

const createInstructions = await sdk.getCreateMarketInstructions(mint, "pump");
await sdk.provider.sendAndConfirm(new Transaction().add(...createInstructions));

Pass tokenStandard for Token-2022 mints:

await sdk.getCreateMarketInstructions(mint, "pump", wallet.publicKey, "token2022");

Low-Level Access

The SDK exposes the underlying typed Anchor program for advanced integrations:

import { getMarketStatePda } from "@derp-trade/sdk";

const program = sdk.program;
const marketPda = getMarketStatePda(mint);

const marketAccount = await program.account.marketState.fetch(marketPda);

Useful exports include:

import {
  DERP_PROGRAM_ID,
  GLOBAL_CONFIG_PDA,
  MAINNET_RPC_URL,
  getMarketStatePda,
  getOracleStatePda,
  getPositionStatePda,
  getAtaAddress,
} from "@derp-trade/sdk";

API Overview

Constructor

new DerpSDK(connection, wallet);

Trading

sdk.getOrderInstructions(mint, params, referralParams?);
sdk.getOrderInstructions(mint, params, referralParams?, undefined, launchpadData?, user?);
sdk.rawOrderRoutedInstruction(mint, params, referralParams?, options?);
sdk.getClosePositionInstructions(mint, positionState?, referralParams?);
sdk.getClosePositionInstructions(mint, positionState?, referralParams?, undefined, launchpadData?, user?, routingContext?);
sdk.rawDepositInstruction(mint, amount, user?);
sdk.rawWithdrawInstruction(mint, user?);

Market and Account Reads

sdk.marketStatus(mint, launchpadData?, user?);
sdk.rawMarketStatus(mint, launchpadData?, user?);
sdk.positionState(mint, user?);
sdk.rawPosition(mint, user?);
sdk.rawMarket(mint);
sdk.rawOracle(mint);
sdk.config();
sdk.resolveMarket(mint, options?);
sdk.detectMarket(mint);

Price Pushes and Market Creation

sdk.getPricePushInstructions(mint, options?);
sdk.getPricePushInstruction(mint, launchpadData?, user?);
sdk.getCreateMarketInstructions(mint, launchpadData, user?, tokenStandard?);

Routing

sdk.buildRoutingContext("USDT" | "USDC" | "SOL", user, options?);

License

MIT