INSTALLATION

npm i @kanalabs/perpetual-sdk

// Note --> Currently we using APT/USDC --> "marketID: 66" // Note --> Currently we using BTC/USDC --> "marketID: 67" // Note --> Currently we using ETH/USDC --> "marketID: 68"

MODULE IMPORTS

import { PerpsMarkets } from '@kanalabs/perpetual-sdk'; 

const perpsMarketsInstance = new PerpsMarkets(process.env.APTOS_PRIVATEKEY || '', Network.TESTNET, process.env.NODEREAL_TESTNET_URL);

INITIALISING THE SDK

  const config = new AptosConfig({ network: Network.TESTNET });
  const aptos = new Aptos(config);
  const account = Account.fromPrivateKey({
        privateKey: new Ed25519PrivateKey(process.env.APTOS_PRIVATEKEY || ''),
    });

TESTNET APT FAUCET

const amount = 300000000;

const response = await perpsMarketsInstance.aptTestnetFaucet(account.accountAddress, amount);

TESTNET USDC FAUCET

const amount = 300000000;
const payload = await perpsMarketsInstance.usdcTestnetFaucet(amount);
const transactionPayload = await aptos.transaction.build.simple({
     sender: account.accountAddress,
     data: payload.data
  });
const committedTxn = await aptos.transaction.signAndSubmitTransaction({
     transaction: transactionPayload,
     signer: account,
  });
const response = await aptos.waitForTransaction({
     transactionHash: committedTxn.hash,
  });

DEPOSIT QUOTE COIN (checking)

  const marketId = 12;
  const amount = 50000000; //50 USDC
  const payload = perpsMarketsInstance.deposit(marketId, amount)
  const transactionPayload = await aptos.transaction.build.simple({
    sender: account.accountAddress,
    data: payload.data
  });
  const committedTxn = await aptos.transaction.signAndSubmitTransaction({
    transaction: transactionPayload,
    signer: account,
  });
  const response = await aptos.waitForTransaction({
    transactionHash: committedTxn.hash,
  });

WITHDRAW QUOTE COIN

  const marketId = 12;
  const amount = 7989000;
  const payload = perpsMarketsInstance.withdraw(marketId, amount)
  const transactionPayload = await aptos.transaction.build.simple({
    sender: account.accountAddress,
    data: payload.data
  });
  const committedTxn = await aptos.transaction.signAndSubmitTransaction({
    transaction: transactionPayload,
    signer: account,
  });
  const response = await aptos.waitForTransaction({
    transactionHash: committedTxn.hash,
  });

// NOTE : trade-side: true for long side and false for short side direction: false for open position and true for close position

PLACE LIMIT OPEN LONG OR OPEN SHORT

  const marketId = 17;
  const tradeSide = true;
  const direction = false;
  const size = 2000;
  const price = 5000;
  const leverage = 10;
  const takeProfit = 6000;
  const stopLoss = 4000;
  const restriction = undefined;
  const payload = await perpsMarketsInstance.placeLimitOrder(marketId, tradeSide, direction, size, price, leverage, restriction, takeProfit, stopLoss);
  const transactionPayload = await aptos.transaction.build.simple({
    sender: account.accountAddress,
    data: payload.data
  });
  const committedTxn = await aptos.transaction.signAndSubmitTransaction({
    transaction: transactionPayload,
    signer: account,
  });
  const response = await aptos.waitForTransaction({
    transactionHash: committedTxn.hash,
  });

// NOTE : trade-side: true for long side and false for short side direction: false for open position and true for close position

PLACE LIMIT CLOSE LONG OR CLOSE SHORT

  const marketId = 17;
  const tradeSide = true;
  const direction = true;
  const size = 2000;
  const price = 5000;
  const leverage = 10;
  const takeProfit = 6000;
  const stopLoss = 4000;
  const restriction = undefined;
  const payload = await perpsMarketsInstance.placeLimitOrder(marketId, tradeSide, direction, size, price, leverage, restriction, takeProfit, stopLoss);
  const transactionPayload = await aptos.transaction.build.simple({
    sender: account.accountAddress,
    data: payload.data
  });
  const response = await aptos.waitForTransaction({
    transactionHash: committedTxn.hash,
  });

// NOTE : trade-side: true for long side and false for short side direction: false for open position and true for close position

PLACE MARKET OPEN LONG OR OPEN SHORT

  const marketId = 12;
  const tradeSide = false;
  const direction = false;
  const size = 2000; // 2 APT
  const leverage = 10;
  const takeProfit = 4000;
  const stopLoss = 6000;
  const payload = await perpsMarketsInstance.placeMarketOrder(marketId, tradeSide, direction, size, leverage, takeProfit, stopLoss);
  const transactionPayload = await aptos.transaction.build.simple({
    sender: account.accountAddress,
    data: payload.data
  });
  const committedTxn = await aptos.transaction.signAndSubmitTransaction({
    transaction: transactionPayload,
    signer: account,
  });
  const response = await aptos.waitForTransaction({
    transactionHash: committedTxn.hash,
  });

PLACE MARKET CLOSE LONG OR CLOSE SHORT

  const marketId = 12;
  const tradeSide = false;
  const direction = true;
  const size = 2000;
  const leverage = 1;
  const payload = perpsMarketsInstance.placeMarketOrder(marketId, tradeSide, direction, size, leverage);
  const transactionPayload = await aptos.transaction.build.simple({
    sender: account.accountAddress,
    data: payload.data
  });
  const committedTxn = await aptos.transaction.signAndSubmitTransaction({
    transaction: transactionPayload,
    signer: account,
  });
  const response = await aptos.waitForTransaction({
    transactionHash: committedTxn.hash,
  });

// NOTE : trade-side: true for long side and false for short side direction: false for open position and true for close position orderTypes: true for limit orders and false for market orders

PLACE MULTIPLE ORDERS

  const marketId = 17;
  const orderTypes = [true, true]
  const tradeSide = [true, true];
  const direction = [false, false];
  const size = [2000, 5000];
  const price = [5000, 6000];
  const leverage = [10, 8];
  const takeProfit = [6000, 8000];
  const stopLoss = [4000, 3000];
  const restrictions = [undefined, undefined];
  const payload = await perpsMarketsInstance.placeMultipleOrders(marketId, orderTypes, tradeSides, directions, sizes, prices, leverages, restrictions, takeProfits, stopLosses);
  const transactionPayload = await aptos.transaction.build.simple({
    sender: account.accountAddress,
    data: payload.data
  });
  const committedTxn = await aptos.transaction.signAndSubmitTransaction({
    transaction: transactionPayload,
    signer: account,
  });
  const response = await aptos.waitForTransaction({
    transactionHash: committedTxn.hash,
  });

// NOTE : trade-side: true for long side and false for short side direction: false for open position and true for close position orderTypes: true for limit orders and false for market orders

CANCEL AND PLACE MULTIPLE ORDERS

  const marketId = 17;
  const orderIds = ['11529215609061372858372', '11510769146441165185932'];
  const orderSides = [true, false];
  const orderTypes = [true, true]
  const tradeSide = [true, true];
  const direction = [false, false];
  const size = [2000, 5000];
  const price = [5000, 6000];
  const leverage = [10, 8];
  const takeProfit = [6000, 8000];
  const stopLoss = [4000, 3000];
  const restrictions = [undefined, undefined];
  const payload = await perpsMarketsInstance.cancelAndlaceMultipleOrders(marketId, orderIds, orderSides, orderTypes, tradeSides, directions, sizes, prices, leverages, restrictions, takeProfits, stopLosses);
  const transactionPayload = await aptos.transaction.build.simple({
    sender: account.accountAddress,
    data: payload.data
  });
  const committedTxn = await aptos.transaction.signAndSubmitTransaction({
    transaction: transactionPayload,
    signer: account,
  });
  const response = await aptos.waitForTransaction({
    transactionHash: committedTxn.hash,
  });

ADD INSURANCE

  const marketId = 17;
  const amount = 1000;
  const payload = await perpsMarketsInstance.addInsurance(marketId, amount);
  const transactionPayload = await aptos.transaction.build.simple({
    sender: account.accountAddress,
    data: payload.data
  });
  const committedTxn = await aptos.transaction.signAndSubmitTransaction({
    transaction: transactionPayload,
    signer: account,
  });
  const response = await aptos.waitForTransaction({
    transactionHash: committedTxn.hash,
  });

UPDATE TAKE PROFIT AND STOP LOSS

  const marketId = 17;
  const newTakeProfitPrice = 7000;
  const newStopLossPrice = 4500;
  const payload = await perpsMarketsInstance.updateTakeProfitAndStopLoss(marketId, newTakeProfitPrice, newStopLossPrice);
  const transactionPayload = await aptos.transaction.build.simple({
    sender: account.accountAddress,
    data: payload.data
  });
  const committedTxn = await aptos.transaction.signAndSubmitTransaction({
    transaction: transactionPayload,
    signer: account,
  });
  const response = await aptos.waitForTransaction({
    transactionHash: committedTxn.hash,
  });

// Note : orderSides: true for long side and false for short side

CANCELING AN MULTIPLE ORDERS

  const marketId = 3;
  const orderIds = ['368935022224564295536', '368935022224564295537'];
  const orderSides = [true, false];
  const payload = perpsMarketsInstance.cancelMultipleOrders(marketId, orderIds, orderSides);
  const transactionPayload = await aptos.transaction.build.simple({
    sender: account.accountAddress,
    data: payload.data
  });
  const committedTxn = await aptos.transaction.signAndSubmitTransaction({
    transaction: transactionPayload,
    signer: account,
  });
  const response = await aptos.waitForTransaction({
    transactionHash: committedTxn.hash,
  });

GET ORDER BOOK

  const marketId = 10;
  const maxAsks = 100;
  const maxBids = 100;
  const orderBook = await perpsMarketsInstance.orderBook(marketId, maxAsks, maxBids);
  const viewOptions = {
       payload: orderBook.data,
  };
  const response = await aptos.view(viewOptions);

Example Response

{
 "asks": [
      {
        "custodian_id": "0",
        "market_id": "12",
        "order_id": "7268018150302766077060",
        "price": "5252",
        "remaining_size": "1888916",
        "side": true,
        "user": "0x7676c6ad191680ee72a03f724aa750a66a9570ca90c7b6861c94a7c2c4ec5515"
      },
      {
        "custodian_id": "0",
        "market_id": "12",
        "order_id": "7304911497704106890377",
        "price": "5257",
        "remaining_size": "2010119",
        "side": true,
        "user": "0x7676c6ad191680ee72a03f724aa750a66a9570ca90c7b6861c94a7c2c4ec5515"
      }
    ],
    "bids": [
      {
        "custodian_id": "0",
        "market_id": "12",
        "order_id": "7249570702494370108524",
        "price": "5228",
        "remaining_size": "1573323",
        "side": false,
        "user": "0x7676c6ad191680ee72a03f724aa750a66a9570ca90c7b6861c94a7c2c4ec5515"
      },
      {
        "custodian_id": "0",
        "market_id": "12",
        "order_id": "7286464612811304604775",
        "price": "5223",
        "remaining_size": "1955227",
        "side": false,
        "user": "0x7676c6ad191680ee72a03f724aa750a66a9570ca90c7b6861c94a7c2c4ec5515"
      }
    ]
  }

GET OPEN ORDERS

  const address = '0xbd9c426a78b43441fd949044963aaefc383678be70dbef773f802f4b1ba34009';
  const orderType = 'open';
  const marketId = 10;
  const openOrders = await perpsMarketsInstance.getOpenOrders(address, orderType, marketId);

Example Response

{
  "asks": [
    {
      "marketOrderId": "534955718883655291784",
      "marketSize": "1000",
      "marketPrice": "5000",
      "counter": "29",
      "leverage": 2,
      "timestamp": "2024-09-29T19:23:56.113842+00:00",
      "tradeType": 1,
      "takeProfit": "6000",
      "stopLoss": "4000",
     }
  ],
  "bids": [
    {
      "marketOrderId": "534955718883655291784",
      "marketSize": "1000",
      "marketPrice": "5000",
      "counter": "29",
      "leverage": 2,
      "timestamp": "2024-09-29T19:23:56.113842+00:00",
      "tradeType": 1,
      "takeProfit": "6000",
      "stopLoss": "4000",
     }
  ]
}

GET LIMIT ORDER HISTORY

  const address = '0xbd9c426a78b43441fd949044963aaefc383678be70dbef773f802f4b1ba34009';
  const type = 'limit';
  const marketId = 10;
  const perpsMarketsInstance = new PerpsMarkets(process.env.APTOS_PRIVATEKEY || '', Network.TESTNET);
  const orderHistory = await perpsMarketsInstance.orderHistory(address, type, marketId);

Example Response

[
  {
    "txn_version": 1074962988,
    "event_idx": 0,
    "time": "2024-05-06T17:43:06.581062+00:00",
    "market_id": 10,
    "user": "0x925366e03a856f25f47873222c6707eaeb00f79898fe904c357dc4b15e8718a1",
    "custodian_id": 2,
    "order_id": "1844674548125623391112",
    "side": false,
    "integrator": "0xc0de11113b427d35ece1d8991865a941c0578b0f349acabbe9753863c24109ff",
    "initial_size": 2000,
    "price": 5000,
    "restriction": 0,
    "self_match_behavior": 0,
    "size": 2000
  }
]

GET MARKET ORDER HISTORY

  const address = '0xbd9c426a78b43441fd949044963aaefc383678be70dbef773f802f4b1ba34009';
  const type = 'market';
  const marketId = 10;
  const orderHistory = await perpsMarketsInstance.orderHistory(address, type, marketId);

Example Response

[
  {
    "txn_version": 1074962096,
    "event_idx": 0,
    "market_id": 10,
    "time": "2024-05-06T17:42:24.052761+00:00",
    "order_id": "1826227663297245609984",
    "user": "0x925366e03a856f25f47873222c6707eaeb00f79898fe904c357dc4b15e8718a1",
    "custodian_id": 2,
    "integrator": "0xc0de11113b427d35ece1d8991865a941c0578b0f349acabbe9753863c24109ff",
    "direction": "buy",
    "size": 2000,
    "self_match_behavior": 0
  },
  {
    "txn_version": 1074839427,
    "event_idx": 0,
    "market_id": 10,
    "time": "2024-05-06T16:05:43.990861+00:00",
    "order_id": "1789334175149826506752",
    "user": "0x925366e03a856f25f47873222c6707eaeb00f79898fe904c357dc4b15e8718a1",
    "custodian_id": 2,
    "integrator": "0xc0de11113b427d35ece1d8991865a941c0578b0f349acabbe9753863c24109ff",
    "direction": "sell",
    "size": 2000,
    "self_match_behavior": 0
  }
]

GET ALL ORDER HISTORY

  const address = '0xbd9c426a78b43441fd949044963aaefc383678be70dbef773f802f4b1ba34009';
  const type = 'market';
  const marketId = 10;
  const orderHistory = await perpsMarketsInstance.orderHistory(address, type, marketId);

Example Response

[
  {
    "market_id": 10,
    "order_id": "1844674548125623391112",
    "created_at": "2024-05-06T17:43:06.581062+00:00",
    "last_updated_at": "2024-05-06T19:10:20.215508+00:00",
    "integrator": "0xc0de11113b427d35ece1d8991865a941c0578b0f349acabbe9753863c24109ff",
    "total_filled": 0,
    "remaining_size": 2000,
    "order_status": "cancelled",
    "order_type": "limit",
    "user": "0x925366e03a856f25f47873222c6707eaeb00f79898fe904c357dc4b15e8718a1",
    "direction": "bid",
    "price": 5000,
    "average_execution_price": null,
    "custodian_id": 2,
    "self_match_behavior": 0,
    "restriction": 0,
    "last_increase_stamp": null,
    "min_base": null,
    "max_base": null,
    "min_quote": null,
    "max_quote": null,
    "total_fees_paid_in_quote_subunits": 0
  },
  {
    "market_id": 10,
    "order_id": "1826227663297245609984",
    "created_at": "2024-05-06T17:42:24.052761+00:00",
    "last_updated_at": "2024-05-06T17:42:24.052761+00:00",
    "integrator": "0xc0de11113b427d35ece1d8991865a941c0578b0f349acabbe9753863c24109ff",
    "total_filled": 2000,
    "remaining_size": 0,
    "order_status": "closed",
    "order_type": "market",
    "user": "0x925366e03a856f25f47873222c6707eaeb00f79898fe904c357dc4b15e8718a1",
    "direction": "buy",
    "price": null,
    "average_execution_price": 5000,
    "custodian_id": 2,
    "self_match_behavior": 0,
    "restriction": null,
    "last_increase_stamp": null,
    "min_base": null,
    "max_base": null,
    "min_quote": null,
    "max_quote": null,
    "total_fees_paid_in_quote_subunits": 5000,
    "leverage": 2,
    "trade_type": 2,
    "timestamp": "2024-09-24T13:49:40.000Z"
  }
]

GET MARKET INFO

  const marketId = 12;
  const response = await perpsMarketsInstance.getMarketInfo(marketId);

Example Response

{
  [
   {
    "market_id": "47",
    "base_name": "APT/USDC",
    "quote_type": "0x197b9c79f40089f150e3c493edb8cf145efec6bd6b0474f3b08ad738549fa1d1::asset::USDC",
    "lot_size": "100000",
    "tick_size": "1",
    "min_lots": "500",
    "quote_precision": "3",
    "base_decimals": "8",
    "quote_decimals": "6",
    "maintenance_margin": "300",
    "max_leverage": "20",
    "counter": "4"
   }
  ]
}

VIEW POSITIONS

  const address = '0xbd9c426a78b43441fd949044963aaefc383678be70dbef773f802f4b1ba34009';
  const response = await perpsMarketsInstance.viewPositions(address, marketId);

Example Response

{
   "longPosition": {
        "position": "1",
        "collateral": "2500000",
        "quote_deposit": "5000000",
        "entry_price": "5000",
        "exit_price": "0",
        "liquidation_price": "2577",
        "oracle_price": "818152674",
        "leverage": "2",
        "open_size": "100000000",
        "close_size": "0",
        "filled_open_size": "100000000",
        "filled_close_size": "0",
        "take_profit_price": "",
        "stop_loss_price": "",
        "close_taker_fee": "0",
        "kana_contribution": "2500000",
        "market_id": "47",
        "open_taker_fee": "0",
        "trade_id": "73786976294838206511",
        "limit_orders": []
    },
  "shortPosition": {
        "position": "2",
        "collateral": "2500000",
        "base_deposit": "100000000",
        "entry_price": "5000",
        "exit_price": "0",
        "liquidation_price": "7282",
        "oracle_price": "818125000",
        "leverage": "2",
        "open_size": "100000000",
        "close_size": "0",
        "filled_open_size": "100000000",
        "filled_close_size": "0",
        "take_profit_price": "",
        "stop_loss_price": "",
        "close_taker_fee": "0",
        "collateral_cover": "2500000",
        "market_id": "47",
        "open_taker_fee": "2500",
        "trade_id": "92233720368547758127",
        "trade_value": "4997500",
        "limit_orders": []
    }
}

UPDATE VIEW POSITION

  const address = '0xbd9c426a78b43441fd949044963aaefc383678be70dbef773f802f4b1ba34009';
  const marketId = 10;
  const updatePnl = await perpsMarketsInstance.updatePosition(address, marketId);
  const viewOptions = {
       payload: updatePnl.data,
  };
  const response = await aptos.view(viewOptions);

CANDLE STICK DATA

  const resolutions = await perpsMarketsInstance.getCandleStickData(900,3)

Example Response

  [
  {
    "market_id": 12,
    "resolution": 900,
    "start_time": "2023-11-06T10:45:00+00:00",
    "open": 6589,
    "high": 6589,
    "low": 6589,
    "close": 6589,
    "volume": 42828500
  },
  {
    "market_id": 12,
    "resolution": 900,
    "start_time": "2023-11-06T10:30:00+00:00",
    "open": 6589,
    "high": 6589,
    "low": 6589,
    "close": 6589,
    "volume": 167505558
  },
  {
    "market_id": 12,
    "resolution": 900,
    "start_time": "2023-11-06T10:15:00+00:00",
    "open": 6589,
    "high": 6589,
    "low": 6589,
    "close": 6589,
    "volume": 42828500
  }
]

GET PYTH ORACLE PRICE

  const marketId = 17;
  const getPythOraclePrice = await perpsMarketsInstance.getPythOraclePrice(marketId);

Example Response

{
  "success": "true",
  "message": "Fetched Latest Pyth Oracle Price Successfully",
  "data": "885514423"
}

GET LAST PLACED EXECUTION PRICE

  const marketId = 17;
  const getLastPrice = await perpsMarketsInstance.getLastExecutionPrice(marketId);

Example Response

{
  "success": "true",
  "message": "Fetched Last Execution Price Successfully",
  "data": "10900"
}

GET MARKET ORDER BEST BIDS AND ASKS

  const marketId = 17;
  const price = await perpsMarketsInstance.getMarketPrice(marketId);

Example Response

{
  "success": "true",
  "message": "Fetched Market Price Successfully",
  "bestAskPrice": "BigNumber { s: 1, e: 4, c: [ 11000 ] }",
  "bestBidPrice": "BigNumber { s: 1, e: 4, c: [ 10900 ] }"
}

GET TRADING ACCOUNT BALANCE

  const marketId = 17;
  const address = '0x4d6dc68e391e86991e58ab4d548b7e92872430d1f51bc666fe0c206bad7ff770';
  const accountBalance = await perpsMarketsInstance.getTradingAccountBalance(marketId,address);

Example Response

{
  "success": true,
  "message": "Fetched Trading Account Balance Successfully",
  "data": "47500000"
}

GET TRANSACTIONS FOR GIVEN ORDER ID

    const marketId = 36;
    const orderId = '10957365979783473659904';
    const type = 'taker';
    const getTransactionsForOrderId = await perpsMarketsInstance.getTransactionsForOrderId(marketId,orderId, type);

Example Response

[
    {
        "txn_version": "6027200785",
        "event_idx": "1",
        "emit_address": "0x4d6dc68e391e86991e58ab4d548b7e92872430d1f51bc666fe0c206bad7ff770",
        "time": "2024-09-23T04:54:02.663068+00:00",
        "maker_address": "0x9b557d73eb93298afeee7bf6b12764d67d3712a8d514f6d35d1c50ebd1ec2385",
        "maker_custodian_id": "15",
        "maker_order_id": "9832115154275799138304",
        "maker_side": "true",
        "market_id": "36",
        "price": "7719",
        "sequence_number_for_trade": "0",
        "size": "1000",
        "taker_address": "0x4d6dc68e391e86991e58ab4d548b7e92872430d1f51bc666fe0c206bad7ff770",
        "taker_custodian_id": "15",
        "taker_order_id": "10957365979783473659904",
        "taker_quote_fees_paid": "3859"
    },
    {
        "txn_version": "6027200785",
        "event_idx": "2",
        "emit_address": "0x9b557d73eb93298afeee7bf6b12764d67d3712a8d514f6d35d1c50ebd1ec2385",
        "time": "2024-09-23T04:54:02.663068+00:00",
        "maker_address": "0x9b557d73eb93298afeee7bf6b12764d67d3712a8d514f6d35d1c50ebd1ec2385",
        "maker_custodian_id": "15",
        "maker_order_id": "9832115154275799138304",
        "maker_side": "true",
        "market_id": "36",
        "price": "7719",
        "sequence_number_for_trade": "0",
        "size": "1000",
        "taker_address": "0x4d6dc68e391e86991e58ab4d548b7e92872430d1f51bc666fe0c206bad7ff770",
        "taker_custodian_id": "15",
        "taker_order_id": "10957365979783473659904",
        "taker_quote_fees_paid": "3859"
    }
]

COLLAPSE

  const marketId = 66;
  const updatePnl = await perpsMarketsInstance.collapse(marketId);
  const collapsePayload = await perpsMarketsInstance.collapse(marketId);
  const transactionPayload = await aptos.transaction.build.simple({
      sender: account.accountAddress,
      data: collapsePayload.data
  });
  const committedTxn = await aptos.transaction.signAndSubmitTransaction({
      transaction: transactionPayload,
      signer: account,
  });
  const response = await aptos.waitForTransaction({
      transactionHash: committedTxn.hash,
  });