socialtrade-sdk

Gains SDK Documentation

Getting Started

To initialize the SDK, set up environment variables for PRIVATE_KEY RPC_PROVIDER_URL VAULT_ADDRESS. Then, create an instance of GainsSDK.

import { GainsSDK, parseUnits } from "socialtrade-sdk";
import * as dotenv from "dotenv";
dotenv.config();

const PRIVATE_KEY = process.env.PRIVATE_KEY as string;
const RPC_PROVIDER_URL = process.env.RPC_PROVIDER_URL as string;
const VAULT_ADDRESS = process.env.VAULT_ADDRESS as string;
const gainsSDK = new GainsSDK(RPC_PROVIDER_URL, PRIVATE_KEY, VAULT_ADDRESS);

Supported Chain

The SDK supports the following chain ID:

• Base: 8453

Modify Position

The modifyPosition property provides methods to update trade parameters and close trades.

Methods

• updateTpAndSl: Updates both take profit (TP) and stop loss (SL) values for a trade.
• updateTp: Updates only the take profit value.
• updateSl: Updates only the stop loss value.
• updateLeverage: Adjusts the leverage for a trade.
• updatePositionSize: Changes the position size by increasing or decreasing collateral.
• closeTradeMarket: Closes an open market trade.

Usage

import {
    UpdateTpAndSlTxArgs,
    UpdateTpTxArgs,
    UpdateSlTxArgs,
    UpdateLeverageTxArgs,
    CloseTradeMarketTxArgs,
} from "socialtrade-sdk/types";

const index = BigInt(32);

// Update TP and SL together

type UpdateTpAndSlTxArgs = {
    index: bigint;
    takeProfitPrice: bigint; // 1e10 decimals
    stopLossPrice: bigint; // 1e10 decimals
};

const tpAndSlData: UpdateTpAndSlTxArgs = { index, takeProfitPrice: BigInt(4000), stopLossPrice: BigInt(3500) };
await gainsSDK.modifyPosition.updateTpAndSl(tpAndSlData);

// Update only TP

type UpdateTpTxArgs = {
    index: bigint;
    takeProfitPrice: bigint; // 1e10 decimals
};

const tpData: UpdateTpTxArgs = { index, takeProfitPrice: BigInt(4000) };
await gainsSDK.modifyPosition.updateTp(tpData);

// Update only SL
type UpdateSlTxArgs = {
    index: bigint;
    stopLossPrice: bigint; // 1e10 decimals
};

const slData: UpdateSlTxArgs = { index, stopLossPrice: BigInt(3500) };
await gainsSDK.modifyPosition.updateSl(slData);

// Update leverage
type UpdateLeverageTxArgs = {
    index: bigint;
    leverage: bigint; // 1e3 decimals (e.g., 100 for 1x, 200 for 2x, 2000 for 20x)
};

const leverageData: UpdateLeverageTxArgs = { index, leverage: BigInt(300) }; // 3x leverage
await gainsSDK.modifyPosition.updateLeverage(leverageData);

// Close trade
const closeData: CloseTradeMarketTxArgs = { index };
await gainsSDK.modifyPosition.closeTradeMarket(closeData);

// Update position size
type UpdatePositionSizeTxArgs = {
    index: bigint;
    increase: boolean;
    collateralDelta: bigint;
    leverageDelta: bigint;
    maxSlippageP: bigint;
    expectedPrice: bigint;
};

const positionSizeData: UpdatePositionSizeTxArgs = { index, increase: true, 
collateralDelta: BigInt(400128700), //1e6 decimals
leverageDelta: BigInt(55), //1e3 decimals  
maxSlippageP: BigInt(1), //1e2 decimals
expectedPrice: BigInt(1021892000000000), //1e10 decimals
};
await gainsSDK.modifyPosition.updatePositionSize(positionSizeData);

Modify Order

The modifyOrder property allows users to update orders by changing parameters such as TP, SL, trigger price, and slippage price, as well as cancel open orders.

Methods

• updateTpAndSl: Updates both take profit and stop loss for an order.
• updateTp: Updates only the take profit value.
• updateSl: Updates only the stop loss value.
• updateTriggerPrice: Changes the trigger price for an order.
• updateSlippagePrice: Adjusts the maximum allowed slippage.
• cancelOpenOrder: Cancels an open order by index.

Usage

import { UpdateTpAndSlTxArgs, UpdateTriggerPriceTxArgs, UpdateMaxSlippagePTxArgs } from "socialtrade-sdk/types";

const index = BigInt(32);

// Update both TP and SL for an order
const tpAndSlData: UpdateTpAndSlTxArgs = { index, takeProfitPrice: BigInt(4000), stopLossPrice: BigInt(3500) };
await gainsSDK.modifyOrder.updateTpAndSl(tpAndSlData);

// Update trigger price
const triggerPriceData: UpdateTriggerPriceTxArgs = { index, triggerPrice: BigInt(3900) };
await gainsSDK.modifyOrder.updateTriggerPrice(triggerPriceData);

// Update slippage price
const slippageData: UpdateMaxSlippagePTxArgs = { index, maxSlippageP: BigInt(1) };
await gainsSDK.modifyOrder.updateSlippagePrice(slippageData);

// Cancel open order
await gainsSDK.modifyOrder.cancelOpenOrder(index);

Market Trade

The marketTrade property enables users to open long and short market trades.

Methods

• marketLong: Opens a long market trade.
• marketShort: Opens a short market trade.

Usage

import { OpenTradeTxArgs } from "socialtrade-sdk/types";

// Open a long market trade
const longData: OpenTradeTxArgs = {
    pairIndex: BigInt(0), // BTC/USDC
    collateralAmount: parseUnits("22", 6), // 1e6 decimals
    openPrice: parseUnits("74900", 10), // 1e10 decimals
    leverage: BigInt(2), // 1e3 decimals
    tp: BigInt(0), // 1e10 decimals
    sl: BigInt(0), // 1e10 decimals
    maxSlippage: BigInt(1), // 1e2 decimals
};
const { response, currentIndex } = await gainsSDK.marketTrade.marketLong(longData);
console.log(`Index: ${currentIndex}
Response: ${response}`);

Limit Trade

The limitTrade property provides methods to place limit orders and cancel open orders.

Methods

• limitLongTrade: Places a long limit order.
• limitShortTrade: Places a short limit order.

Usage

const limitData: OpenTradeTxArgs = {
    pairIndex: BigInt(0),
    collateralAmount: parseUnits("22", 6),
    openPrice: parseUnits("74900", 10),
    leverage: BigInt(200),
    tp: BigInt(0),
    sl: BigInt(0),
    maxSlippage: BigInt(1),
};
const { response, currentIndex } = await gainsSDK.limitTrade.limitLongTrade(limitData);
console.log(`Index: ${currentIndex}
Response: ${response}`);

Fees and Balance

The feesAndBalance property provides methods to get fees and balance.

Methods

• getUSDCBalance: Gets the balance of USDC in the vault.
• getFeesToClaim: Gets the fees to claim.
• claimFees: Claims the fees.

Usage

const usdcBalance = await gainsSDK.feesAndBalance.getUSDCBalance();
console.log(`USDC Balance: ${usdcBalance}`); // 1e6 decimals

const feesToClaim = await gainsSDK.feesAndBalance.getFeesToClaim();
console.log(`Fees to Claim: ${feesToClaim}`); // 1e18 decimals

const claimFees = await gainsSDK.feesAndBalance.claimFees();
console.log(`Claim Fees: ${claimFees}`); // 1e18 decimals

View

The view property provides various read-only methods to get details about trades, counters, and liquidation parameters.

Methods

• getCounters: Retrieves trade counters for a user.
• getPendingOrders: Fetches all pending orders for a user.
• getTrade: Gets details of a specific trade.
• getTrades: Lists all trades for a user.
• getTradeInfo: Retrieves information for a specific trade.
• getTradeInfos: Lists information for all trades.
• getTradeLiquidationParams: Gets liquidation parameters for a trade.
• getTradesLiquidationParams: Lists liquidation parameters for all trades.
• getPairMinFeeUsd: Retrieves the minimum trading fee in USD for a pair.
• getFeesInfo: Gets details of a fee group.
• getPairsInfo: Retrieves information of a trading pair.
• getPriceByPairId: Fetches the price for a specified pair ID.
• calculatePnL: Calculates profit and loss for a trade based on the current price and position details.

Usage

import { CounterType } from "socialtrade-sdk/types";

const counters = await gainsSDK.view.getCounters(await gainsSDK.signer.getAddress(), CounterType.TRADE);
const pendingOrders = await gainsSDK.view.getPendingOrders(await gainsSDK.signer.getAddress());
const tradeInfo = await gainsSDK.view.getTradeInfo(await gainsSDK.signer.getAddress(), BigInt(32));
console.log(counters, pendingOrders, tradeInfo);

Utilities

The utils property provides utility functions for unit conversions.

Methods

• parseUnits: Converts a string representation of an amount to BigInt based on decimals.
• formatUnits: Converts a BigInt amount to a human-readable string.

Usage

import { parseUnits, formatUnits } from "socialtrade-sdk/utils";

const amount = parseUnits("100", 6); // Convert to BigInt
console.log(formatUnits(amount, 6)); // Convert from BigInt to string