Installation

Getting started with the taurusSwap SDK takes about 5 minutes. This page covers package installation, peer dependencies, and TypeScript configuration.

Install the Package

npm install @taurus-swap/sdk

Or with yarn:

yarn add @taurus-swap/sdk

Peer Dependencies

The SDK requires algosdk v3.5.0 or later:

npm install algosdk@^3.5.0

algosdk is used for:

• Algod client communication
• Transaction construction
• Address encoding/decoding
• Box storage access

TypeScript Configuration

The SDK uses BigInt literals and modern ES2020 features. Your tsconfig.jsonmust have:

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true
  }
}

If you're using Next.js, these settings are already the default.

Hello World

Here's a minimal example that reads pool state and prints the current reserves:

import { readPoolState } from '@taurus-swap/sdk';
import algosdk from 'algosdk';

const algodClient = new algosdk.Algodv2(
  'YOUR_ALGOD_TOKEN',
  'https://testnet-api.algonode.cloud',
  ''
);

const POOL_APP_ID = 758284478;

async function main() {
  const poolState = await readPoolState(algodClient, POOL_APP_ID);

  console.log('Pool state:');
  console.log('  Tokens:', poolState.n);
  console.log('  Total liquidity:', poolState.totalR);
  console.log('  Reserves (microunits):', poolState.reserves);
}

main().catch(console.error);

Display Units

The SDK returns reserves in microunits. To display in human-readable format:

import { formatTokenAmount } from '@taurus-swap/sdk';

const poolState = await readPoolState(algodClient, POOL_APP_ID);

// USDC has 6 decimals
const usdcReserves = formatTokenAmount(
  poolState.reserves[0],
  6  // decimals
);

console.log(`USDC reserves: ${usdcReserves}`);  // "1,234,567.89"

Wallet Integration

For React apps, use a wallet adapter:

import { useWallet } from '@txnlab/use-wallet-react';

function SwapForm() {
  const { activeAddress, signer } = useWallet();

  const handleSwap = async () => {
    if (!signer) return;

    const { txGroup } = await buildSwapTransactionGroup(
      algodClient,
      POOL_APP_ID,
      activeAddress,
      tradeParams
    );

    const result = await signer.signGroupTransaction(txGroup);
    // Send signed transactions...
  };

  return <button onClick={handleSwap}>Swap</button>;
}

Environment Variables

Recommended setup for environment configuration:

// lib/config.ts
export const config = {
  testnet: {
    algodToken: process.env.NEXT_PUBLIC_ALGOD_TOKEN!,
    algodServer: 'https://testnet-api.algonode.cloud',
    poolAppId: 758284478,
  },
  mainnet: {
    algodToken: process.env.NEXT_PUBLIC_ALGOD_TOKEN!,
    algodServer: 'https://mainnet-api.algonode.cloud',
    poolAppId: 123456789,  // Update after mainnet deploy
  },
};

export const getAlgodClient = (network: 'testnet' | 'mainnet') => {
  const cfg = config[network];
  return new algosdk.Algodv2(cfg.algodToken, cfg.algodServer, '');
};

Troubleshooting

"BigInt is not defined"

Add BigInt to your tsconfig lib:

"lib": ["ES2020", "BigInt"]

"Module not found: @taurus-swap/sdk"

Clear npm cache and reinstall:

rm -rf node_modules package-lock.json
npm install

Box not found errors

Fresh pools may not have all boxes initialized yet. Handle gracefully:

try {
  const state = await readPoolState(algodClient, POOL_APP_ID);
} catch (err) {
  if (err instanceof BoxNotFoundError) {
    console.log('Pool not initialized yet');
  }
}

Next: See Reading Pool State for a deep dive into every field of PoolState.