SDK Guide

The TownSquare SDK (@townsq/mm-sdk) provides developers with tools to interact seamlessly with the protocol — creating accounts, managing loans, depositing, borrowing, repaying, and withdrawing assets — without directly calling smart contracts.

Installation

npm install @townsq/mm-sdk

or

yarn add @townsq/mm-sdk

Initialization

Before using the SDK, you need to configure the core instance and signer.

import { TSCore, NetworkType, TS_CHAIN_ID, CHAIN_VIEM } from "@townsq/mm-sdk";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";

// Select network and chain
const network = NetworkType.TESTNET;
const chain = TS_CHAIN_ID.MONAD_TESTNET;

// Initialize SDK configuration
const tsConfig: TSCoreConfig = { network, provider: { evm: {} } };
TSCore.init(tsConfig);
TSCore.setNetwork(network);

// Create signer (example with private key)
const signer = createWalletClient({
  chain: CHAIN_VIEM[chain],
  transport: http(),
  account: privateKeyToAccount("0x..."), // Replace with private key
});

// Set signer
TSCore.setTSsSigner({ signer, tsChainId: chain });

Reading Loan Information

The SDK provides utilities to fetch and compute detailed information about a loan, including collateral value, debt value, and health factors. This is useful for dashboards, liquidation bots, or analytics.

import {
  NetworkType,
  TSCore,
  TSLoan,
  TS_CHAIN_ID,
  CHAIN_VIEM,
  TSPool,
  TSOracle,
  TSAccount,
  MAINNET_TS_TOKEN_ID,
  MAINNET_LOAN_TYPE_ID,
} from '@townsq/mm-sdk';

import type {
  TSCoreConfig,
  LoanId,
  TSTokenId,
  PoolInfo,
  EvmAddress,
} from '@townsq/mm-sdk';

import { createWalletClient, http } from 'viem';

 // 1. Initialize sdk
  const network = NetworkType.MAINNET;
  const chain = TS_CHAIN_ID.MONAD;

  const tsConfig: TSCoreConfig = {
    network,
    provider: { evm: {} },
  };

  TSCore.init(tsConfig);
  TSCore.setNetwork(network);

  const signer = createWalletClient({
    chain: CHAIN_VIEM[chain],
    transport: http(),
  });

  TSCore.setTSsSigner({ signer, tsChainId: chain });

 // 2. Resolve Account ID from Wallet
  const userAddress = '<USER_EVM_ADDRESS>' as EvmAddress;
  const accountIds = await TSAccount.read.getAccountIdOfAddressOnChain(
    userAddress
  );
  const accountId = accountIds[0].accountId;

  
  // 3. Fetch Loan IDs via Subgraph
  const loanIdsSubgraphEndpoint = '<LOAN_IDS_SUBGRAPH_ENDPOINT>';
  const loanIds = await TSLoan.read.getLoanIds(
    accountId,
    loanIdsSubgraphEndpoint
  );

 // 4. Select Loan ID
  const loanId = '<LOAN_ID>' as LoanId;
  
  // 5. Load Pool Information
  const poolsInfo: Partial<Record<TSTokenId, PoolInfo>> = {};
  await Promise.all(
    Object.values(MAINNET_TS_TOKEN_ID).map(async (tsTokenId) => {
      const poolInfo = await TSPool.read.poolInfo(tsTokenId);
      poolsInfo[tsTokenId] = poolInfo;
    })
  );

  // 6. Load Loan Type Info
  const loanTypeInfo = {
    [MAINNET_LOAN_TYPE_ID.GENERAL]: await TSLoan.read.loanTypeInfo(
      MAINNET_LOAN_TYPE_ID.GENERAL
    ),
  };

 // 7. Load Oracle Prices
  const oraclePrices = await TSOracle.read.oraclePrices();

 //  8. Fetch User Loan & Compute Metrics
  const userLoans = await TSLoan.read.userLoans([loanId]);
  const userLoansInfo = TSLoan.util.userLoansInfo(
    userLoans,
    poolsInfo,
    loanTypeInfo,
    oraclePrices
  ); // Note that the loan type info is based on the loan type id
  
  

  console.dir(userLoansInfo, { depth: null });

Creating Account

import { TSAccount } from "@townsq/mm-sdk";

const nonce = "0x"; // bytes4 nonce

// Prepare transaction
const createAccount = await TSAccount.prepare.createAccount(nonce, {
  adapterId: 3,
  returnAdapterId: 3,
});

// Send transaction
const txnReceipt = await TSAccount.write.createAccount(nonce, createAccount);

console.log(txnReceipt);

The account will be created on the chain defined during initialization.

Creating a Loan

TownSquare supports three loan types:

• General Loan → accepts all supported tokens.

• Stable Efficiency Loan → restricted to stablecoin-related assets.

• MON Efficiency Loan → supports MON-related assets only.

import { TSLoan } from "@townsq/mm-sdk";
import { ethers } from "ethers";

const loanName = "My loan";
const encodedLoanName = ethers.encodeBytes32String(loanName);
const nonce = "0x"; // bytes4

// Prepare transaction
const prepareCreateLoan = await TSLoan.prepare.createLoan(
  accountId,
  nonce,
  TESTNET_LOAN_TYPE_ID.GENERAL,
  encodedLoanName,
  { adapterId: 3, returnAdapterId: 3 }
);

// Send transaction
const txnReceipt = await TSLoan.write.createLoan(
  accountId,
  nonce,
  TESTNET_LOAN_TYPE_ID.GENERAL,
  encodedLoanName,
  prepareCreateLoan
);

Deposit

Deposit tokens into a loan.

const poolId = TESTNET_TS_TOKEN_ID.MON;
const loanId = "0xYourLoanId";

// Prepare deposit
const deposit = await TSLoan.prepare.deposit(
  accountId,
  loanId,
  TESTNET_LOAN_TYPE_ID.GENERAL,
  poolId,
  parseUnits("0.1", 18),
  { adapterId: 3, returnAdapterId: 3 }
);

// Send transaction
const txnReceipt = await TSLoan.write.deposit(
  accountId,
  loanId,
  parseUnits("0.1", 18),
  false,
  deposit
);

console.log(txnReceipt);

Borrow

  const borrow = await TSLoan.prepare.borrow(
    accountId,
    loanId,
    TESTNET_TS_TOKEN_ID.aprMON,
    parseUnits('0.05', 18),
    0n,
    TS_CHAIN_ID.MONAD_TESTNET,
    {
      adapterId: 3,
      returnAdapterId: 3,
    } 
  );


  const txnReceipt = await TSLoan.write.borrow(
    accountId,
    loanId,
    TESTNET_TS_TOKEN_ID.aprMON,
    parseUnits('0.05', 18),
    0n,
    TS_CHAIN_ID.MONAD_TESTNET,
    borrow
  );

Repay

const repay = await TSLoan.prepare.repay(
  accountId,
  loanId,
  TESTNET_LOAN_TYPE_ID.GENERAL,
  TESTNET_TS_TOKEN_ID.aprMON,
  parseUnits("0.06", 18), // borrow amount
  parseUnits("0.1", 18),  // repayment amount
  { adapterId: 3, returnAdapterId: 3 }
);

const txnReceipt = await TSLoan.write.repay(
  accountId,
  loanId,
  parseUnits("0.06", 18),
  parseUnits("0.1", 18),
  true,
  repay
);

Withdraw

const withdraw = await TSLoan.prepare.withdraw(
  accountId,
  loanId,
  TESTNET_TS_TOKEN_ID.MON,
  parseUnits("0.05", 18),
  true,
  TESTNET_EVM_TS_CHAIN_ID.MONAD_TESTNET,
  { adapterId: 3, returnAdapterId: 3 }
);

const txnReceipt = await TSLoan.write.withdraw(
  accountId,
  loanId,
  TESTNET_TS_TOKEN_ID.MON,
  parseUnits("0.05", 18),
  true,
  TESTNET_EVM_TS_CHAIN_ID.MONAD_TESTNET,
  withdraw
);