@ithaca-finance/sdk v5.1.0

Ithaca SDK

This is official JS SDK for Ithaca Protocol

SDK Initialization

import { IthacaSDK, IthacaNetwork } from "@ithaca-finance/sdk";

const wsCallbacks = {
  onClose: (ev: CloseEvent) => { /*do something*/ };
  onError: (ev: Event) => { /*do something*/ };
  onMessage: (payload: SocketOrder) => { /*do something*/ };
  onOpen: (ev: Event) => { /*do something*/ };
}

const ithacaSDK = new IthacaSDK(
  IthacaNetwork.ARBITRUM_GOERLI,
  // Refer: https://wagmi.sh/react/hooks/useWalletClient / https://viem.sh/docs/clients/wallet.html
  walletClient, // optional, if walletClient is undefined SDK will be initialized in Read-Only mode
  wsCallbacks, // optional web socket callbacks
  <BACKEND_API_URL>, // optional backend url override
  <BACKEND_WEBSOCKET_URL> // optional backend websocket url
);

Auth module

• Login - Establishes authenticated session with Ithaca backend. Essential for interacting with Ithaca protocol. Ithaca SDK must be initialized with WalletClient in order to use this method

const result = await ithacaSdk.auth.login();

// Sample output
{
  "authToken": "ynQPpVleu8lQMfXc0Cedc9p6xjXjypFVQTBhRtHsjn0=",
  "clientId": 1723710844499969,
  "ethAddress": "0x7a1dbec6f1203f89942766314be0f36fd4615704"
}

• Logout - Closes authenticated session with Ithaca backend

await ithacaSDK.auth.logout();

• Get session info - Get information about current authenticated session with Ithaca backend

const result = await ithacaSDK.auth.getSession();

// Sample output
{
  "authToken": "ynQPpVleu8lQMfXc0Cedc9p6xjXjypFVQTBhRtHsjn0=",
  "clientId": 1723710844499969,
  "ethAddress": "0x7a1dbec6f1203f89942766314be0f36fd4615704"
}

Calculation module

• Estimate order payoff - Returns graph coordinates object for order payoff, where key is x coordinate and value is y coordinate

1. clientOrderId - unique client order id, use createClientOrderId
2. totalNetPrice - unit price of order, use calculateNetPrice
3. legs - order legs contract id, side and quantity;
4. fwdPrice - should be set to reference price if payoff is Forward (optional)
5. addCollateral - should be set to true if collateral is needed (defaults to false)

const order = {
  clientOrderId: 1739781756044389,
  totalNetPrice: 10,
  legs: [
    {
      contractId: 231117024,
      quantity: "9.999",
      side: "BUY"
    },
    {
      contractId: 231117012,
      quantity: "9.999",
      side: "BUY"
    }
  ],
};
const result = await ithacaSdk.calculation.estimateOrderPayoff(order);

// Sample output
{
  "1170.0000": -0.0010,
  "1299.9999": -0.0010,
  "1300.0000": -10.0000,
  "1300.0001": -10.0000,
  "1350.0000": -10.0000,
  "1399.9999": -10.0000,
  "1400.0000": -0.0010,
  "1400.0001": -0.0010,
  "1594.7050": -0.0010,
  "1789.4099": -0.0010,
  "1789.4100": -0.0010,
  "1789.4101": -0.0010,
  "1968.3510": -0.0010
}

• Estimate order lock - Get numeraire and underlier order lock for the order

1. clientOrderId - unique client order id, use createClientOrderId
2. totalNetPrice - unit price of order, use calculateNetPrice
3. legs - order legs contract id, side and quantity
4. fwdPrice - should be set to reference price if payoff is Forward (optional)
5. addCollateral - should be set to true if collateral is needed (defaults to false)

const order = {
  clientOrderId: 1739781979452517,
  totalNetPrice: 180552.76,
  legs: [
    {
      contractId: 231117001,
      quantity: "100",
      side: "BUY"
    },
    {
      contractId: 231117007,
      quantity: "100",
      side: "BUY"
    },
    {
      contractId: 231117006,
      quantity: "100",
      side: "SELL"
    },
    {
      contractId: 231117008,
      quantity: "20000",
      side: "SELL"
    }
  ]
};
const result = await ithacaSdk.calculation.estimateOrderLock(order);

// Sample output
{
  "currencyPair": "WETH/USDC",
  "underlierAmount": 0.0000000,
  "numeraireAmount": 180552.7600
}

Client module

• FundLock State - Get client's order value, fundLock value, settle value for all tokens supported by Ithaca protocol

const result = await ithacaSdk.client.fundLockState();

// Sample output
[
  {
    currency: "WETH",
    orderValue: 0.0,
    fundLockValue: 0.0,
    settleValue: 0.0
  },
  {
    currency: "USDC",
    orderValue: 0.0,
    fundLockValue: 1451.2353,
    settleValue: 0.0
  }
];

• Client past orders - Get list of client's past orders

const result = await ithacaSdk.client.tradeHistory();

// Sample output
[
  {
    revDate: 1697761296298,
    orderId: 1738439686005861,
    clientId: 1723527729422337,
    orderStatus: "FILLED",
    netPrice: 1.0,
    orderGenesis: "CLIENT_PREDEFINED",
    orderDescr: "Bet",
    collateral: {
      currencyPair: "WETH/USDC",
      underlierAmount: 0.0,
      numeraireAmount: 0.0
    },
    timeInForce: "GOOD_TILL_CANCEL",
    orderClass: "ConditionalOrder",
    details: [
      {
        contractId: 231027020,
        contractDto: {
          contractId: 231027020,
          payoff: "BinaryCall",
          economics: {
            currencyPair: "WETH/USDC",
            expiry: 20231027,
            strike: 1400.0,
            priceCurrency: "USDC",
            qtyCurrency: "USDC"
          },
          tradeable: true
        },
        side: "BUY",
        originalQty: 1.0109,
        remainingQty: 0.0,
        thisFillQty: 1.0109,
        cancelledQty: 0.0,
        avgPrice: 20.9096,
        totalCost: 21.1376,
        execPrice: 20.9097,
        currencyPair: "WETH/USDC",
        expiry: 20231027
      },
      {
        contractId: 231027038,
        contractDto: {
          contractId: 231027038,
          payoff: "BinaryPut",
          economics: {
            currencyPair: "WETH/USDC",
            expiry: 20231027,
            strike: 1200.0,
            priceCurrency: "USDC",
            qtyCurrency: "USDC"
          },
          tradeable: true
        },
        side: "BUY",
        originalQty: 1.0109,
        remainingQty: 0.0,
        thisFillQty: 1.0109,
        cancelledQty: 0.0,
        avgPrice: -19.9204,
        totalCost: -20.1376,
        execPrice: -19.9205,
        currencyPair: "WETH/USDC",
        expiry: 20231027
      }
    ]
  },
  ...
];

Market module

• Reference prices - Get reference prices for all the active contracts on Ithaca protocol. Prices are filtered by expiry and currency pair. Expiry can be set to 0 to get reference prices for contracts with all expiries.

1. expiry - filter by contract expiry, should be formatted as YYYYMMDD
2. currencyPair - should not be empty (e.g. WETH/USDC)

const expiry = 0;
const currencyPair = "WETH/USDC";
const result = await ithacaSdk.market.referencePrices(expiry, currencyPair);

// Sample output
[
  {
    contractId: 231110022,
    referencePrice: 0.0001,
    lowRange: 0.0367,
    highRange: 0.0367,
    lastPrice: 0.0367,
    updatedAt: "2023-10-13T11:50:00Z"
  },
  {
    contractId: 231110023,
    referencePrice: 36.6358,
    lowRange: 256.2437,
    highRange: 256.2437,
    lastPrice: 256.2437,
    updatedAt: "2023-10-13T11:50:00Z"
  },
  {
    contractId: 231110020,
    referencePrice: 1.0,
    lowRange: 0.9987,
    highRange: 0.9987,
    lastPrice: 0.9987,
    updatedAt: "2023-10-13T11:50:00Z"
  },
  ...
];

• Spot prices - Get spot prices for all pairs supported by Ithaca protocol

const result = await ithacaSdk.market.spotPrices();

// Sample output
{
  "WETH/USDC":1788.1900
}

Orders module

• Client open orders - Get list of client's all open orders

const result = await ithacaSdk.orders.clientOpenOrders();

// Sample output
[
  {
    revDate: 1699007234041,
    orderId: 1739783398981733,
    clientId: 1723710844499969,
    orderStatus: "NEW",
    netPrice: 10.0,
    orderGenesis: "CLIENT_PREDEFINED",
    orderDescr: "Bet",
    collateral: {
      currencyPair: "WETH/USDC",
      underlierAmount: 0.0,
      numeraireAmount: 0.0
    },
    timeInForce: "GOOD_TILL_CANCEL",
    orderClass: "ConditionalOrder",
    details: [
      {
        contractId: 231110005,
        contractDto: {
          contractId: 231110005,
          payoff: "BinaryCall",
          economics: {
            currencyPair: "WETH/USDC",
            expiry: 20231110,
            strike: 1600.0,
            priceCurrency: "USDC",
            qtyCurrency: "USDC"
          },
          tradeable: true
        },
        side: "BUY",
        originalQty: 10.0422,
        remainingQty: 10.0422,
        cancelledQty: 0.0,
        avgPrice: 0.0,
        totalCost: 0.0,
        currencyPair: "WETH/USDC",
        expiry: 20231110
      },
      {
        contractId: 231110024,
        contractDto: {
          contractId: 231110024,
          payoff: "BinaryPut",
          economics: {
            currencyPair: "WETH/USDC",
            expiry: 20231110,
            strike: 1200.0,
            priceCurrency: "USDC",
            qtyCurrency: "USDC"
          },
          tradeable: true
        },
        side: "BUY",
        originalQty: 10.0422,
        remainingQty: 10.0422,
        cancelledQty: 0.0,
        avgPrice: 0.0,
        totalCost: 0.0,
        currencyPair: "WETH/USDC",
        expiry: 20231110
      }
    ]
  },
  ...
];

• Create new order - New order is submitted to Ithaca backend. Backend will validate the order and open new position for client. To check id order was created successfully call ithacaSdk.orders.orderStatus

1. clientOrderId - unique client order id, use createClientOrderId
2. totalNetPrice - unit price of order, use calculateNetPrice
3. legs - order legs contract id, side and quantity
4. fwdPrice - should be set to reference price if payoff is Forward (optional)
5. orderDescr - name of strategy (e.g. Bet, Earn, Position builder)

const order = {
  clientOrderId: 1739783398981733,
  totalNetPrice: "10.0000",
  legs: [
    {
      contractId: 231110005,
      side: "BUY",
      quantity: "10.0422"
    },
    {
      contractId: 231110024,
      side: "BUY",
      quantity: "10.0422"
    }
  ]
};
const orderDescr = "Bet";

await ithacaSdk.orders.newOrder(order, orderDescr);

• Check order status - Get currenct status of an order

1. clientOrderId - order id

const clientOrderId = 1739783398981733;
const result = await ithacaSdk.orders.orderStatus(clientOrderId);

// Sample output
{
  "revDate": 1699007234041,
  "orderId": 1739783398981733,
  "clientId": 1723710844499969,
  "orderStatus": "NEW",
  "netPrice": 10.0000,
  "orderGenesis": "CLIENT_PREDEFINED",
  "orderDescr": "Bet",
  "collateral": {
      "currencyPair": "WETH/USDC",
      "underlierAmount": 0.0000000,
      "numeraireAmount": 0.0000
  },
  "timeInForce": "GOOD_TILL_CANCEL",
  "orderClass": "ConditionalOrder",
  "details": [
      {
          "contractId": 231110005,
          "contractDto": {
              "contractId": 231110005,
              "payoff": "BinaryCall",
              "economics": {
                  "currencyPair": "WETH/USDC",
                  "expiry": 20231110,
                  "strike": 1600.0000,
                  "priceCurrency": "USDC",
                  "qtyCurrency": "USDC"
              },
              "tradeable": true
          },
          "side": "BUY",
          "originalQty": 10.0422,
          "remainingQty": 10.0422,
          "cancelledQty": 0.0000,
          "avgPrice": 0.0000,
          "totalCost": 0.0000,
          "currencyPair": "WETH/USDC",
          "expiry": 20231110
      },
      {
          "contractId": 231110024,
          "contractDto": {
              "contractId": 231110024,
              "payoff": "BinaryPut",
              "economics": {
                  "currencyPair": "WETH/USDC",
                  "expiry": 20231110,
                  "strike": 1200.0000,
                  "priceCurrency": "USDC",
                  "qtyCurrency": "USDC"
              },
              "tradeable": true
          },
          "side": "BUY",
          "originalQty": 10.0422,
          "remainingQty": 10.0422,
          "cancelledQty": 0.0000,
          "avgPrice": 0.0000,
          "totalCost": 0.0000,
          "currencyPair": "WETH/USDC",
          "expiry": 20231110
      }
  ]
}

• Cancel an order - Cancel an open order created by client. To check id order was cancelled successfully call ithacaSdk.orders.orderStatus

1. clientOrderId - order id

const clientOrderId = 1739783398981733;
await ithacaSdk.orders.orderCancel(clientOrderId);

Protocol module

• System info - Get details of networks, tokens and contract addresses of Ithaca protocol

const result = await ithacaSdk.protocol.systemInfo();

// Sample output
{
  "chainId": 421613,
  "fundlockAddress": "0xc50d980ee2835868a1e7ec37bb0fd4543d6fe536",
  "tokenManagerAddress": "0xc218b1f70e0e9c464ef78fb50e67004f2cd6e581",
  "tokenAddress": {
      "WETH": "0x43aeb2b2bc97d32d3e5418b4441225a164eb3726",
      "USDC": "0x5c96109d6535e8ad49189950aee836b84a1bc10b"
  },
  "tokenDecimals": {
      "WETH": 18,
      "USDC": 6
  },
  "currencyPrecision": {
      "WETH": 7,
      "USDC": 4
  },
  "networks": [
      {
          "name": "Polygon-mumbai",
          "blockchainId": 80001,
          "rpcUrl": "https://rpc-mumbai.maticvigil.com/",
          "tokenmanagerAddress": "0x269fbcfc001e0cec2c37887b681820591a90d4c8",
          "fundlockAddress": "0x66861b2af3909bcb0503fb6453272c2a9f77c0f1",
          "symbols": {
              "WETH": "WETH",
              "USDC": "USDC"
          },
          "addresses": {
              "WETH": "0x0E0E490D83E126B30690fB798832A0AFfbc670fA",
              "USDC": "0xF17Ff9343E62A2A0EB0431e4088a1cd86cf5a3C0"
          }
      }
  ]
}

• Next auction - Get unix timestamp of next auction

const nextAuction = await ithacaSdk.protocol.nextAuction();

• Contract list - Get list of all active contracts on Ithaca protocol

const result = await ithacaSdk.protocol.contractList();

// Sample output
[
 {
  contractId: 231104001,
  payoff: "Forward",
  economics: {
    currencyPair: "WETH/USDC",
    expiry: 20231104,
    priceCurrency: "USDC",
    qtyCurrency: "WETH"
  },
  tradeable: true
 },
 {
  contractId: 231104002,
  payoff: "Forward",
  economics: {
    currencyPair: "WETH/USDC",
    expiry: 20231104,
    priceCurrency: "USDC",
    qtyCurrency: "WETH"
  },
  tradeable: true
 },
 {
  contractId: 231110001,
  payoff: "Forward",
  economics: {
    currencyPair: "WETH/USDC",
    expiry: 20231110,
    priceCurrency: "USDC",
    qtyCurrency: "WETH"
  },
  tradeable: true
 },
  ...
];

• Contract list by contract id - Get contract list filtered by contract ids

1. ids - list of contract ids

const ids = [231110002];
const result = await ithacaSdk.protocol.contractListByIds(ids);

// Sample output
[
  {
    contractId: 231110002,
    payoff: "Call",
    economics: {
      currencyPair: "WETH/USDC",
      expiry: 20231110,
      strike: 1400.0,
      priceCurrency: "USDC",
      qtyCurrency: "WETH"
    },
    tradeable: true
  }
];

• Historical contracts - Get list of expired contracts

1. expiry - contract expiry, should be formatted as YYYYMMDD

const expiry = 20231110;
const result = await ithacaSdk.protocol.historicalContracts();

// Sample output
[
 {
  contractId: 231110003,
  payoff: "Call",
  economics: {
    currencyPair: "WETH/USDC",
    expiry: 20231110,
    strike: 1600.0,
    priceCurrency: "USDC",
    qtyCurrency: "WETH"
  },
  tradeable: true
 },
  ...
];

• Matched orders - Get a list of client's matched orders

const result = await ithacaSdk.protocol.matchedOrders();

// Sample output
[
  {
    revDate: 1697761296298,
    orderId: 1738439686005861,
    clientId: 1723527729422337,
    orderStatus: "FILLED",
    netPrice: 1.0,
    orderGenesis: "CLIENT_PREDEFINED",
    orderDescr: "Bet",
    collateral: {
      currencyPair: "WETH/USDC",
      underlierAmount: 0.0,
      numeraireAmount: 0.0
    },
    timeInForce: "GOOD_TILL_CANCEL",
    orderClass: "ConditionalOrder",
    details: [
    {
      contractId: 231027020,
      contractDto: {
        contractId: 231027020,
        payoff: "BinaryCall",
        economics: {
          currencyPair: "WETH/USDC",
          expiry: 20231027,
          strike: 1400.0,
          priceCurrency: "USDC",
          qtyCurrency: "USDC"
        },
        tradeable: true
      },
      side: "BUY",
      originalQty: 1.0109,
      remainingQty: 0.0,
      thisFillQty: 1.0109,
      cancelledQty: 0.0,
      avgPrice: 20.9096,
      totalCost: 21.1376,
      execPrice: 20.9097,
      currencyPair: "WETH/USDC",
      expiry: 20231027
    },
    {
      contractId: 231027038,
      contractDto: {
        contractId: 231027038,
        payoff: "BinaryPut",
        economics: {
          currencyPair: "WETH/USDC",
          expiry: 20231027,
          strike: 1200.0,
          priceCurrency: "USDC",
          qtyCurrency: "USDC"
        },
        tradeable: true
      },
      side: "BUY",
      originalQty: 1.0109,
      remainingQty: 0.0,
      thisFillQty: 1.0109,
      cancelledQty: 0.0,
      avgPrice: -19.9204,
      totalCost: -20.1376,
      execPrice: -19.9205,
      currencyPair: "WETH/USDC",
      expiry: 20231027
    }
    ]
  },
  ...
];

Helper functions

• Unit price (net price) - Calculate unit price for an order

1. legs - order legs with contract id, side and quantity
2. referencePrices - reference prices for all contract ids
3. precision - strike currency precision of selected currency pair
4. unitSize - unit size (defaults to 1)

import { calculateNetPrice } from "@ithaca-finance/sdk";

const unitPrice = calculateNetPrice(legs, referencePrices, precision, unitSize);

• Client order id - Creates a unique client order id

import { createClientOrderId } from "@ithaca-finance/sdk";

const clientOrderId = createClientOrderId();

• Calculate collateral requirement - Get required collateral for the order

1. leg - order leg contract id, side and quantity
2. payoff - order payoff e.g. Call, Put
3. strike - order strike
4. precision - precision of strike currency

const collateral = ithacaSdk.calculation.calcCollateralRequirement(leg, payoff, strike, precision);