Package Exports

soulswap-limit-orders-lib
soulswap-limit-orders-lib/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (soulswap-limit-orders-lib) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

SoulSwap Limit Order SDK

Place limit buy and sell orders on Ethereum, Polygon and Fantom using Gelato Network.

⚠️ ⚠️ ⚠️ Warning ⚠️ ⚠️ ⚠️ : Version 2.0.0 introduced new features and our system changed to an approval/transferFrom flow. You should use the latest version available (>= 2.0.0). If you are using an old version you should update to the latest version immediately. Versions below 2.0.0 are being deprecated.

Demo - Sorbet Finance

Installation

yarn add -D soulswap-limit-orders-lib

npm install --save-dev soulswap-limit-orders-lib

Getting Started

Instantiate GelatoLimitOrders

import {
  GelatoLimitOrders,
  GelatoStopLimitOrders,
  utils,
} from "soulswap-limit-orders-lib";

// Supported networks: Mainnet = 1; Ropsten = 3; Polygon = 137; Fantom = 250; Avalanche = 43114;  BSC = 56
const chainId = 1;
const signerOrProvider = await provider.getSigner();
const handler = "uniswap";
// | "soulswap"
// | "soulswap_stoplimit"
// | "spookyswap"
// | "spookyswap_stoplimit"
// | "uniswap"
// | "uniswap_stoplimit"
// | "quickswap"
// | "quickswap_stoplimit"
// | "soulswap"
// | "soulswap_stoplimit"
// | "spiritswap"
// | "spiritswap_stoplimit"
// | "bombswap"
// | "polydex"
// | "cafeswap"
// | "pancakeswap"
// | "pancakeswap_stoplimit"
// | "traderjoe"
// | "traderjoe_stoplimit"
// | "defyswap"
// | "pangolin"
// | "pangolin_stoplimit";

const gelatoLimitOrders = new GelatoLimitOrders(
  chainId as ChainId,
  signerOrProvider, // optional
  handler // optional
);

const gelatoStopLimitOrders = new GelatoStopLimitOrders(
  chainId as ChainId,
  signerOrProvider, // optional
  handler // required
);

Note: Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE when referring to native blockchain asset (i.e MATIC, FTM or ETH)

Examples

Submit an order

Note: To submit a order with an ERC20 as input you must first approve the erc20OrderRouter. You can get its address via gelatoLimitOrders.erc20OrderRouter.address or call gelatoLimitOrders.approveTokenAmount(inputToken, inputAmount).

// Token to sell
const inputToken = "0x6b175474e89094c44da98b954eedeac495271d0f"; // DAI

// Token to buy
const outputToken = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"; // ETH

// Amount to sell
const inputAmount = ethers.utils.parseUnits("2000", "18");

// Minimum amount of outToken which the users wants to receive back
const minReturn = ethers.utils.parseEther("1");

// Address of user who places the order (must be same as signer address)
const userAddress = "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B";

await gelatoLimitOrders.approveTokenAmount(inputToken, inputAmount);

const tx = await gelatoLimitOrders.submitLimitOrder(
  inputToken,
  outputToken,
  inputAmount,
  minReturn
);

// Maximum amount of outToken which the users wants to receive back => stop-limit price
const maxReturn = ethers.utils.parseEther("1");

const tx = await gelatoStopLimitOrders.submitStopLimitOrder(
  inputToken,
  outputToken,
  inputAmount,
  maxReturn
);

Cancel an order

const tx = await gelatoLimitOrders.cancelLimitOrder(
  order,
  true // Optional: checkIsActiveOrder = true, to check if order to be cancelled actually exists. It is recommended to use this check before trying to cancel an order to avoid faulty cancellations and gas waste.
);
const tx = await gelatoStopLimitOrders.cancelStopLimitOrder(
  order,
  true // Optional: checkIsActiveOrder = true, to check if order to be cancelled actually exists. It is recommended to use this check before trying to cancel an order to avoid faulty cancellations and gas waste.
);

Fetch orders

Note: to display the minimum amount returned (i.e the output amount of the order) you should always use the adjustedMinReturn field of the order.

Note 2: If you instantiated the library by passing an handler, all orders fetched will be filtered accordingly. Otherwise, orders will not be filtered.

const allOrders = await gelatoLimitOrders.getOrders(userAddress);

Types

export class GelatoLimitOrders {
  get gelatoFeeBPS(): number;
  get slippageBPS(): number;
  get chainId(): ChainId;
  get signer(): Signer | undefined;
  get provider(): Provider | undefined;
  get subgraphUrl(): string;
  get handler(): Handler | undefined;
  get handlerAddress(): string | undefined;
  get moduleAddress(): string;
  get contract(): GelatoLimitOrdersContract;
  get erc20OrderRouter(): ERC20OrderRouter;
  constructor(chainId: ChainId, signerOrProvider?: Signer, handler?: Handler);
  encodeLimitOrderSubmission(
    inputToken: string,
    outputToken: string,
    inputAmount: BigNumberish,
    minReturn: BigNumberish,
    owner: string,
    // If inputToken is an ERC20, compare allowance with inputAmount. defaults to `true`
    checkAllowance?: boolean
  ): Promise<TransactionData>;
  encodeLimitOrderSubmissionWithSecret(
    inputToken: string,
    outputToken: string,
    inputAmount: BigNumberish,
    minReturn: BigNumberish,
    owner: string,
    // If inputToken is an ERC20, compare allowance with inputAmount. defaults to `true`
    checkAllowance?: boolean
  ): Promise<TransactionDataWithSecret>;
  submitLimitOrder(
    inputToken: string,
    outputToken: string,
    inputAmount: BigNumberish,
    minReturn: BigNumberish,
    // If inputToken is an ERC20, compare allowance with inputAmount. defaults to `true`
    checkAllowance?: boolean,
    overrides?: Overrides
  ): Promise<ContractTransaction>;
  encodeLimitOrderCancellation(
    order: Order,
    checkIsActiveOrder?: boolean
  ): Promise<TransactionData>;
  cancelLimitOrder(
    order: Order,
    checkIsActiveOrder?: boolean,
    overrides?: Overrides
  ): Promise<ContractTransaction>;
  approveTokenAmount(
    inputToken: string,
    amount: BigNumberish,
    overrides?: Overrides
  ): Promise<ContractTransaction>;
  isActiveOrder(order: Order): Promise<boolean>;
  getExchangeRate(
    inputValue: BigNumberish,
    inputDecimals: number,
    outputValue: BigNumberish,
    outputDecimals: number,
    invert?: boolean
  ): string;
  getFeeAndSlippageAdjustedMinReturn(
    outputAmount: BigNumberish,
    extraSlippageBPS?: number
  ): {
    minReturn: string;
    slippage: string;
    gelatoFee: string;
  };
  getAdjustedMinReturn(
    minReturn: BigNumberish,
    extraSlippageBPS?: number
  ): string;
  getExecutionPrice(
    inputAmount: BigNumberish,
    inputDecimals: number,
    outputAmount: BigNumberish,
    outputDecimals: number,
    isInverted?: boolean
  ): string;
  getOrders(
    owner: string,
    // includeOrdersWithNullHandler defaults to `false`
    includeOrdersWithNullHandler?: boolean
  ): Promise<Order[]>;
  getOpenOrders(
    owner: string,
    // includeOrdersWithNullHandler defaults to `false`
    includeOrdersWithNullHandler?: boolean
  ): Promise<Order[]>;
  getPastOrders(
    owner: string,
    // includeOrdersWithNullHandler defaults to `false`
    includeOrdersWithNullHandler?: boolean
  ): Promise<Order[]>;
  getExecutedOrders(
    owner: string,
    // includeOrdersWithNullHandler defaults to `false`
    includeOrdersWithNullHandler?: boolean
  ): Promise<Order[]>;
  getCancelledOrders(
    owner: string,
    // includeOrdersWithNullHandler defaults to `false`
    includeOrdersWithNullHandler?: boolean
  ): Promise<Order[]>;
}

export declare class GelatoBase {
  get gelatoFeeBPS(): number;
  get slippageBPS(): number;
  get chainId(): ChainId;
  get signer(): Signer | undefined;
  get provider(): Provider | undefined;
  get subgraphUrl(): string;
  get handler(): Handler | undefined;
  get handlerAddress(): string | undefined;
  get moduleAddress(): string;
  get contract(): GelatoBaseContract;
  get erc20OrderRouter(): ERC20OrderRouter;
  get abiEncoder(): any;
  constructor(
    chainId: ChainId,
    moduleAddress: string,
    signerOrProvider?: Signer | Provider,
    handler?: Handler,
    handlerAddress?: string
  );
  encodeLimitOrderCancellation(
    order: StopLimitOrder,
    checkIsActiveOrder?: boolean
  ): Promise<TransactionData>;
  cancelStopLimitOrder(
    order: StopLimitOrder,
    checkIsActiveOrder?: boolean,
    overrides?: Overrides
  ): Promise<ContractTransaction>;
  approveTokenAmount(
    inputToken: string,
    amount: BigNumberish,
    overrides?: Overrides
  ): Promise<ContractTransaction>;
  isActiveOrder(order: StopLimitOrder): Promise<boolean>;
  getExchangeRate(
    inputValue: BigNumberish,
    inputDecimals: number,
    outputValue: BigNumberish,
    outputDecimals: number,
    invert?: boolean
  ): string;
  getFeeAndSlippageAdjustedMinReturn(
    outputAmount: BigNumberish,
    extraSlippageBPS?: number
  ): {
    minReturn: string;
    slippage: string;
    gelatoFee: string;
  };
  getAdjustedMinReturn(
    minReturn: BigNumberish,
    extraSlippageBPS?: number
  ): string;
  getExecutionPrice(
    inputAmount: BigNumberish,
    inputDecimals: number,
    outputAmount: BigNumberish,
    outputDecimals: number,
    isInverted?: boolean
  ): string;
  getPastStopLimitOrders(owner: string): Promise<StopLimitOrder[]>;
}

class GelatoStopLimitOrders extends GelatoBase {
  constructor(
    chainId: ChainId,
    signerOrProvider?: Signer | Provider,
    handler?: Handler
  );
  submitStopLimitOrder(
    inputToken: string,
    outputToken: string,
    inputAmount: BigNumberish,
    maxReturn: BigNumberish,
    checkAllowance?: boolean,
    overrides?: Overrides
  ): Promise<ContractTransaction>;
  encodeStopLimitOrderSubmission(
    inputToken: string,
    outputToken: string,
    inputAmount: BigNumberish,
    maxReturn: BigNumberish,
    owner: string,
    checkAllowance?: boolean
  ): Promise<TransactionData>;
  encodeStopLimitOrderSubmissionWithSecret(
    inputToken: string,
    outputToken: string,
    inputAmount: BigNumberish,
    maxReturnToBeParsed: BigNumberish,
    owner: string,
    checkAllowance?: boolean
  ): Promise<TransactionDataWithSecret>;
  getOpenStopLimitOrders(owner: string): Promise<StopLimitOrder[]>;
  getStopLimitOrders(owner: string): Promise<StopLimitOrder[]>;
  getExecutedStopLimitOrders(owner: string): Promise<StopLimitOrder[]>;
  getCancelledStopLimitOrders(owner: string): Promise<StopLimitOrder[]>;
}

export declare type ChainId = 1 | 3 | 56 | 137 | 250 | 43114;

export type Handler =
  | "spookyswap"
  | "spookyswap_stoplimit"
  | "uniswap"
  | "uniswap_stoplimit"
  | "quickswap"
  | "quickswap_stoplimit"
  | "soulswap"
  | "soulswap_stoplimit"
  | "spiritswap"
  | "spiritswap_stoplimit"
  | "bombswap"
  | "polydex"
  | "cafeswap"
  | "pancakeswap"
  | "pancakeswap_stoplimit"
  | "traderjoe"
  | "traderjoe_stoplimit"
  | "defyswap"
  | "pangolin"
  | "pangolin_stoplimit";

export interface TransactionData {
  to: string;
  data: BytesLike;
  value: BigNumberish;
}

export interface TransactionDataWithSecret {
  payload: TransactionData;
  secret: string;
  witness: string;
  order: PartialOrder;
}

export interface Order {
  id: string;
  owner: string;
  inputToken: string;
  outputToken: string;
  minReturn: string;
  maxReturn?: string;
  adjustedMinReturn: string;
  module: string;
  witness: string;
  secret: string;
  inputAmount: string;
  vault: string;
  bought: string | null;
  auxData: string | null;
  status: string;
  createdTxHash: string;
  executedTxHash: string | null;
  cancelledTxHash: string | null;
  blockNumber: string;
  createdAt: string;
  updatedAt: string;
  updatedAtBlock: string;
  updatedAtBlockHash: string;
  data: string;
  inputData: string;
  handler: string | null;
  isExpired: boolean;
}

export interface PartialOrder {
  owner: string;
  inputToken: string;
  outputToken: string;
  minReturn: string;
  adjustedMinReturn: string;
  module: string;
  witness: string;
  secret: string;
  inputAmount: string;
  data: string;
  inputData: string;
  handler?: string;
}

Need help?

Reach out to us on Telegram, Discord or Twitter