README

Gelato Limit Order SDK

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

:warning: :warning: :warning: Warning :warning: :warning: :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 @dojoswap/limit-orders-lib

npm install --save-dev @dojoswap/limit-orders-lib

Getting Started

Instantiate GelatoLimitOrders

import { GelatoLimitOrders, utils } from "@dojoswap/limit-orders-lib";

// Supported networks: Mainnet = 1; Ropsten = 3; Polygon = 137; Fantom = 250
const chainId = 1;
const signerOrProvider = await provider.getSigner();
const handler = "uniswap"; // "spookyswap" | "uniswap" | "quickswap" | "spiritswap" | "bombswap";

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

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

Examples

Submit a limit 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
);

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.

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 {
  static slippageBPS: number;
  static gelatoFeeBPS: 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 type ChainId = 1 | 3 | 137 | 250;

export declare type Handler =
  | "spookyswap"
  | "uniswap"
  | "quickswap"
  | "spiritswap";

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;
  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;
}

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

Usage no npm install needed!