Typescript

Table of Contents

1. Base URLs

2. Authentication

3. Core Concepts

4. Account Management

5. Market Data

6. Order Management

7. Position Management

8. Trade History

9. Utility Endpoints

Base URLs

const BASE_URLS = {
  TESTNET: "https://perps-tradeapi.kanalabs.io",
  MAINNET: "https://perps-tradeapi.kana.trade"
};

Authentication

All endpoints require an API key passed in the headers:

headers: {
  'x-api-key': process.env.API_KEY
}

Core Concepts

Profile Address

All on-chain trades are executed using your profile address, not your wallet address. You must fetch your profile address first.

Endpoint: GET /getProfileAddress

async function getProfileAddress(userAddress: string): Promise<string> {
  const response = await axios.get(`${BASE_URL}/getProfileAddress`, {
    params: { userAddress },
    headers: { 'x-api-key': API_KEY }
  });
  return response.data;
}

Account Management

Get Wallet Balance

Endpoint: GET /getWalletAccountBalance

async function getWalletBalance(userAddress: string): Promise<number> {
  const response = await axios.get(`${BASE_URL}/getWalletAccountBalance`, {
    params: { userAddress },
    headers: { 'x-api-key': API_KEY }
  });
  return response.data;
}

Get Profile Balance

Endpoint: GET /getProfileBalanceSnapshot

async function getProfileBalance(userAddress: string): Promise<number> {
  const response = await axios.get(`${BASE_URL}/getProfileBalanceSnapshot`, {
    params: { userAddress },
    headers: { 'x-api-key': API_KEY }
  });
  return response.data;
}

Get Net Profile Balance

This endpoint returns the net profile balance, which includes both the available balance in trading account and any pending balances from closed positions on all markets.

Endpoint: GET /getNetProfileBalance

async function getNetProfileBalance(userAddress: string): Promise<number> {
  const response = await axios.get(`${BASE_URL}/getNetProfileBalance`, {
    params: { userAddress },
    headers: { 'x-api-key': API_KEY }
  });
  return response.data;
}

Deposit Funds

Endpoint: GET /deposit

async function depositFunds(userAddress: string, amount: number): Promise<void> {
  const response = await axios.get(`${BASE_URL}/deposit`, {
    params: { userAddress, amount },
    headers: { 'x-api-key': API_KEY }
  });
  
  const payload = response.data.data;
  const transaction = await aptos.transaction.build.simple({
    sender: userAddress,
    data: payload
  });
  await aptos.transaction.signAndSubmitTransaction({
    transaction,
    signer: account
  });
}

Withdraw Funds

Endpoint: GET /withdrawSpecifiMarket

async function withdrawFunds(
  userAddress: string, 
  marketId: number, 
  amount: number
): Promise<void> {
  const response = await axios.get(`${BASE_URL}/withdrawSpecifiMarket`, {
    params: { userAddress, marketId, amount },
    headers: { 'x-api-key': API_KEY }
  });
  
  const payload = response.data.data;
  const transaction = await aptos.transaction.build.simple({
    sender: userAddress,
    data: payload
  });
  const committedTxn = await aptos.transaction.signAndSubmitTransaction({
    transaction,
    signer: account
  });
  await aptos.waitForTransaction({
        transactionHash: committedTxn.hash,
    });
  return committedTxn.hash
}

Market Data

Get Market Info

Endpoint: GET /getMarketInfo

async function getMarketInfo(marketId: number): Promise<void> {
  const response = await axios.get(`${BASE_URL}/getMarketInfo`, {
    params: { marketId },
    headers: { 'x-api-key': API_KEY }
  });
  return response.data;
}

Get Market Price

Endpoint: GET /getMarketPrice

async function getMarketPrice(marketId: number): Promise<void> {
  const response = await axios.get(`${BASE_URL}/getMarketPrice`, {
    params: { marketId },
    headers: { 'x-api-key': API_KEY }
  });
  return response.data;
}

Get Last Execution Price

Endpoint: GET /getLastPlacedPrice

async function getLastExecutionPrice(marketId: number): Promise<number> {
  const response = await axios.get(`${BASE_URL}/getLastPlacedPrice`, {
    params: { marketId },
    headers: { 'x-api-key': API_KEY }
  });
  return response.data;
}

Get Perpetual Market Info

Retrieves information about perpetual market, optionally filtered by market ID or base name.

Endpoint: GET /getPerpetualAssetsInfo

async function getAssetInfo(marketId?: number, baseName?: string): Promise<any> {
  const response = await axios.get(`${BASE_URL}/getPerpetualAssetsInfo`, {
    params: { marketId, baseName },
    headers: { 'x-api-key': API_KEY }
  });
  return response.data;
}

Get All Markets

Retrieves information about all available markets.

Endpoint: GET /getPerpetualAssetsInfo/allMarkets

async function getAllMarkets(): Promise<any[]> {
  const response = await axios.get(`${BASE_URL}/getPerpetualAssetsInfo/allMarkets`, {
    headers: { 'x-api-key': API_KEY }
  });
  return response.data;
}

Order Management

Place Limit Order

Places a limit order on the exchange.

Endpoint: GET /placeLimitOrder

interface PlaceLimitOrderParams {
  marketId: number;
  tradeSide: boolean; // true = long, false = short
  direction: boolean; // false = open, true = close
  size: number;
  price: number;
  leverage: number;
  restriction?: number; // optional
  takeProfit?: number;  // optional
  stopLoss?: number;    // optional
}

async function placeLimitOrder(params: PlaceLimitOrderParams): Promise<void> {
  const response = await axios.get(`${BASE_URL}/placeLimitOrder`, {
    params,
    headers: { 'x-api-key': API_KEY }
  });
  
  const payload = response.data.data;
  const transaction = await aptos.transaction.build.simple({
    sender: userAddress,
    data: payload
  });
  await aptos.transaction.signAndSubmitTransaction({
    transaction,
    signer: account
  });
}

Place Market Order

Endpoint: GET /placeMarketOrder

interface PlaceMarketOrderParams {
  marketId: number;
  tradeSide: boolean; // true = long, false = short
  direction: boolean; // false = open, true = close
  size: number;
  leverage: number;
  restriction?: number; // optional
  takeProfit?: number;  // optional
  stopLoss?: number;    // optional
}
async function placeMarketOrder(params: PlaceMarketOrderParams): Promise<void> {
  const response = await axios.get(`${BASE_URL}/placeMarketOrder`, {
    params,
    headers: { 'x-api-key': API_KEY }
  });
  
  const payload = response.data.data;
  const transaction = await aptos.transaction.build.simple({
    sender: userAddress,
    data: payload
  });
  await aptos.transaction.signAndSubmitTransaction({
    transaction,
    signer: account
  });
}

Place Multiple Orders

Places multiple orders in a single transaction.

Endpoint: POST /placeMultipleOrders

interface PlaceMultipleOrdersParams {
    marketId: number;
    orderTypes: boolean[]; // true = limit, false = market
    tradeSides: boolean[]; // true = long, false = short
    directions: boolean[]; // false = open, true = close
    sizes: number[];
    prices: number[];
    leverages: number[];
    restrictions?: any[]; // optional
    takeProfits?: any[]; // optional
    stopLosses?: any[]; // optional
}
async function PlaceMultipleOrders(params: PlaceMarketOrdersParams): Promise<void> {
  const response = await axios.get(`${BASE_URL}/placeMultipleOrders`, {
    params,
    headers: { 'x-api-key': API_KEY }
  });
  
  const payload = response.data.data;
  const transaction = await aptos.transaction.build.simple({
    sender: userAddress,
    data: payload
  });
  await aptos.transaction.signAndSubmitTransaction({
    transaction,
    signer: account
  });
}

Cancel Orders

Endpoint: POST /cancelMultipleOrders

async function cancelMultipleOrders(
  marketId: number,
  orderIds: string[],
  orderSides: boolean[]
): Promise<void> {
  const response = await axios.post(`${BASE_URL}/cancelMultipleOrders`, {
    marketId,
    cancelOrderIds: orderIds,
    orderSides
  }, {
    headers: { 
      'x-api-key': API_KEY,
      'Content-Type': 'application/json'
    }
  });
  
  const payload = response.data.data;
  const transaction = await aptos.transaction.build.simple({
    sender: userAddress,
    data: payload
  });
  await aptos.transaction.signAndSubmitTransaction({
    transaction,
    signer: account
  });
}

Cancel And Place Multiple Orders

Endpoint: POST /cancelAndPlaceMultipleOrders

interface CancelAndPlaceMultipleOrdersParams {
    marketId: number;
    cancelOrderIds: any[];
    orderSides: boolean[]; // true = long, false = short
    orderTypes: boolean[]; // true = limit, false = market
    tradeSides: boolean[]; // true = long, false = short
    directions: boolean[]; // false = open, true = close
    sizes: number[];
    prices: number[];
    leverages: number[];
    restrictions?: any[]; // optional
    takeProfits?: any[]; // optional
    stopLosses?: any[]; // optional
}
async function cancelAndPlaceMultipleOrders(params: CancelAndPlaceMultipleOrdersParams): Promise<void> {
  const response = await axios.get(`${BASE_URL}/cancelAndPlaceMultipleOrders`, {
    params,
    headers: { 'x-api-key': API_KEY }
  });
  
  const payload = response.data.data;
  const transaction = await aptos.transaction.build.simple({
    sender: userAddress,
    data: payload
  });
  await aptos.transaction.signAndSubmitTransaction({
    transaction,
    signer: account
  });
}

Position Management

Get Positions

Endpoint: GET /getPositions

interface Position {
  market_id: string;
  leverage: number;
  size: string;
  entry_price: string;
  liq_price: string;
  // ... other fields
}

async function getPositions(userAddress: string, marketId?: number): Promise<Position[]> {
  const response = await axios.get(`${BASE_URL}/getPositions`, {
    params: { userAddress, marketId },
    headers: { 'x-api-key': API_KEY }
  });
  return response.data;
}

Update Take Profit

Endpoint: GET /updateTakeProfit

async function updateTakeProfit(
  marketId: number,
  tradeSide: boolean,
  newTakeProfitPrice: number
): Promise<void> {
  const response = await axios.get(`${BASE_URL}/updateTakeProfit`, {
    params: { marketId, tradeSide, newTakeProfitPrice },
    headers: { 'x-api-key': API_KEY }
  });
  
  const payload = response.data.data;
  const transaction = await aptos.transaction.build.simple({
    sender: userAddress,
    data: payload
  });
  await aptos.transaction.signAndSubmitTransaction({
    transaction,
    signer: account
  });
}

Update Stop Loss

Endpoint: GET /updateStopLoss

async function updateStopLoss(
  marketId: number,
  tradeSide: boolean,
  newStopLossPrice: number
): Promise<void> {
  const response = await axios.get(`${BASE_URL}/updateStopLoss`, {
    params: { marketId, tradeSide, newStopLossPrice },
    headers: { 'x-api-key': API_KEY }
  });
  
  const payload = response.data.data;
  const transaction = await aptos.transaction.build.simple({
    sender: userAddress,
    data: payload
  });
  await aptos.transaction.signAndSubmitTransaction({
    transaction,
    signer: account
  });
}

Trade History

Get Open Orders

Endpoint: GET /getOpenOrders

interface OpenOrder {
  market_id: string;
  price: string;
  size: string;
  order_type: number; // see order_type explanation
  // ... other fields
}

async function getOpenOrders(userAddress: string, marketId?: number): Promise<OpenOrder[]> {
  const response = await axios.get(`${BASE_URL}/getOpenOrders`, {
    params: { userAddress, marketId },
    headers: { 'x-api-key': API_KEY }
  });
  return response.data;
}

Get All Open Order Ids

Endpoint: GET /getAllOpenOrderIds

async function getAllOpenOrderIds(userAddress: string, marketId: number): Promise<any[]> {
  const response = await axios.get(`${BASE_URL}/getAllOpenOrderIds`, {
    params: { userAddress, marketId },
    headers: { 'x-api-key': API_KEY }
  });
  return response.data;
}

Get Order Status By Order Id

Endpoint: GET /getOrderStatusByOrderId

async function getOrderStatusByOrderId(marketId: number, orderId: string): Promise<any[]> {
  const response = await axios.get(`${BASE_URL}/getOrderStatusByOrderId`, {
    params: { marketId, orderId },
    headers: { 'x-api-key': API_KEY }
  });
  return response.data;
}

Get Order History

Endpoint: GET /getOrderHistory

async function getOrderHistory(userAddress: string, marketId?: number): Promise<any[]> {
  const response = await axios.get(`${BASE_URL}/getOrderHistory`, {
    params: { userAddress, marketId },
    headers: { 'x-api-key': API_KEY }
  });
  return response.data;
}

Get All Trades

Endpoint: GET /getAllTrades

async function getAllTrades(marketId: number): Promise<any[]> {
  const response = await axios.get(`${BASE_URL}/getAllTrades`, {
    params: { marketId },
    headers: { 'x-api-key': API_KEY }
  });
  return response.data;
}

Collapse Position

Endpoint: GET /collapsePosition

async function collapsePosition(
  marketId: number
): Promise<void> {
  const response = await axios.get(`${BASE_URL}/collapsePosition`, {
    params: { marketId },
    headers: { 'x-api-key': API_KEY }
  });
  
  const payload = response.data.data;
  const transaction = await aptos.transaction.build.simple({
    sender: userAddress,
    data: payload
  });
  await aptos.transaction.signAndSubmitTransaction({
    transaction,
    signer: account
  });
}

Add Margin

Endpoint: GET /addMargin

async function addMargin(
  marketId: number,
  tradeSide: boolean,
  amount: number
): Promise<void> {
  const response = await axios.get(`${BASE_URL}/addMargin`, {
    params: { marketId, tradeSide, amount },
    headers: { 'x-api-key': API_KEY }
  });
  
  const payload = response.data.data;
  const transaction = await aptos.transaction.build.simple({
    sender: userAddress,
    data: payload
  });
  await aptos.transaction.signAndSubmitTransaction({
    transaction,
    signer: account
  });
}

Settle Pnl

This API returns a transaction payload used to manually (or automatically, on user interactions) refresh the user's position and settle the Pnl for a specific market, allowing the user to claim any unreleased Pnl.

Endpoint: GET /settlePnl

async function settlePnl(
  marketId: number,
  userAddress: string
): Promise<void> {
  const response = await axios.get(`${BASE_URL}/settlePnl`, {
    params: { marketId, userAddress },
    headers: { 'x-api-key': API_KEY }
  });
  
  const payload = response.data.data;
  const transaction = await aptos.transaction.build.simple({
    sender: userAddress,
    data: payload
  });
  await aptos.transaction.signAndSubmitTransaction({
    transaction,
    signer: account
  });
}

Utility Endpoints

Get Account APT Balance

Endpoint: GET /getAccountAptBalance

async function getAptBalance(userAddress: string): Promise<number> {
  const response = await axios.get(`${BASE_URL}/getAccountAptBalance`, {
    params: { userAddress },
    headers: { 'x-api-key': API_KEY }
  });
  return response.data.data;
}

Helper Types

// Order type explanations
enum OrderType {
  OPEN_LONG = 1,
  OPEN_SHORT = 2,
  INCREASE_LONG = 3,
  INCREASE_SHORT = 4,
  DECREASE_LONG = 5,
  DECREASE_SHORT = 6,
  CLOSE_LONG = 7,
  CLOSE_SHORT = 8
}

// Restriction types
enum RestrictionType {
  NO_RESTRICTION = 0,
  FILL_OR_ABORT = 1,
  POST_OR_ABORT = 3
}