Skip to main content
Get started with the TAC SDK by installing the package and configuring your development environment. The SDK works in both browser and Node.js environments with full TypeScript support.

​
Installation

Install the TAC SDK using your preferred package manager: 
 npm install @tonappchain/sdk

​
Basic Import and Setup

Import the core SDK components you’ll need for your application: 
import {
  TacSdk,
  SenderFactory,
  OperationTracker,
  Network,
  AssetType,
} from "@tonappchain/sdk";

​
Environment Configuration

​
Network Selection

The SDK supports both testnet and mainnet environments. Always start development on testnet: 
// For development and testing
const tacSdk = await TacSdk.create({
  network: Network.TESTNET,
});

// For production
const tacSdk = await TacSdk.create({
  network: Network.MAINNET,
});
Always test your integration thoroughly on testnet before deploying to mainnet. Cross-chain operations are irreversible once confirmed.

​
Environment Variables

For security, store sensitive configuration in environment variables: 
# .env file
TVM_MNEMONICS=your_wallet_mnemonic_here
TAC_NETWORK=testnet
TON_CONNECT_MANIFEST_URL=https://yourapp.com/tonconnect-manifest.json
Access these in your application: 
const network =
  process.env.TAC_NETWORK === "mainnet" ? Network.MAINNET : Network.TESTNET;

const tacSdk = await TacSdk.create({ network });

​
Framework Integration

​
React Integration

For React applications, wrap the SDK in a context provider: 
// contexts/TacSdkContext.js
import React, { createContext, useContext, useEffect, useState } from "react";
import { TacSdk, Network } from "@tonappchain/sdk";

const TacSdkContext = createContext(null);

export const TacSdkProvider = ({ children }) => {
  const [tacSdk, setTacSdk] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const initializeSdk = async () => {
      try {
        const sdk = await TacSdk.create({
          network: Network.TESTNET,
          delay: 1,
        });
        setTacSdk(sdk);
      } catch (error) {
        console.error("Failed to initialize TAC SDK:", error);
      } finally {
        setLoading(false);
      }
    };

    initializeSdk();

    return () => {
      if (tacSdk) {
        tacSdk.closeConnections();
      }
    };
  }, []);

  return (
    <TacSdkContext.Provider value={{ tacSdk, loading }}>
      {children}
    </TacSdkContext.Provider>
  );
};

export const useTacSdk = () => {
  const context = useContext(TacSdkContext);
  if (!context) {
    throw new Error("useTacSdk must be used within a TacSdkProvider");
  }
  return context;
};
Use the context in your components: 
// components/CrossChainTransaction.js
import { useTacSdk } from "../contexts/TacSdkContext";

export const CrossChainTransaction = () => {
  const { tacSdk, loading } = useTacSdk();

  if (loading) return <div>Initializing TAC SDK...</div>;

  const handleTransaction = async () => {
    // Use tacSdk for cross-chain operations
    const result = await tacSdk.sendCrossChainTransaction(/* ... */);
  };

  return (
    <button onClick={handleTransaction}>Send Cross-Chain Transaction</button>
  );
};

​
Next.js Integration

For Next.js applications, handle client-side initialization: 
// hooks/useTacSdk.js
import { useEffect, useState } from "react";
import { TacSdk, Network } from "@tonappchain/sdk";

export const useTacSdk = () => {
  const [tacSdk, setTacSdk] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    // Only initialize on client side
    if (typeof window !== "undefined") {
      const initializeSdk = async () => {
        try {
          const sdk = await TacSdk.create({
            network: Network.TESTNET,
          });
          setTacSdk(sdk);
        } catch (error) {
          console.error("SDK initialization failed:", error);
        } finally {
          setLoading(false);
        }
      };

      initializeSdk();
    }
  }, []);

  return { tacSdk, loading };
};

​
Vue.js Integration

For Vue applications, create a composable: 
// composables/useTacSdk.js
import { ref, onMounted, onUnmounted } from "vue";
import { TacSdk, Network } from "@tonappchain/sdk";

export function useTacSdk() {
  const tacSdk = ref(null);
  const loading = ref(true);

  onMounted(async () => {
    try {
      tacSdk.value = await TacSdk.create({
        network: Network.TESTNET,
      });
    } catch (error) {
      console.error("TAC SDK initialization failed:", error);
    } finally {
      loading.value = false;
    }
  });

  onUnmounted(() => {
    if (tacSdk.value) {
      tacSdk.value.closeConnections();
    }
  });

  return { tacSdk, loading };
}

​
TON Connect Integration

For browser applications, integrate with TON Connect for wallet connectivity:

​
Install TON Connect

npm install @tonconnect/ui

​
Configure TON Connect

import { TonConnectUI } from "@tonconnect/ui";

// Initialize TON Connect
const tonConnectUI = new TonConnectUI({
  manifestUrl: "https://yourapp.com/tonconnect-manifest.json",
  buttonRootId: "ton-connect-button",
});

// Create sender from TON Connect
import { SenderFactory } from "@tonappchain/sdk";

const sender = await SenderFactory.getSender({
  tonConnect: tonConnectUI,
});

​
TON Connect Manifest

Create a manifest file for your application: 
{
  "url": "https://yourapp.com",
  "name": "Your dApp Name",
  "iconUrl": "https://yourapp.com/icon.png",
  "termsOfUseUrl": "https://yourapp.com/terms",
  "privacyPolicyUrl": "https://yourapp.com/privacy"
}

​
TypeScript Configuration

If using TypeScript, ensure your tsconfig.json includes proper module resolution: 
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

​
SDK Configuration Options

The SDK accepts several configuration options during initialization: 
const tacSdk = await TacSdk.create({
  network: Network.TESTNET, // Network selection
  delay: 1000, // Delay between operations (milliseconds)
  TONParams: {
    // TON-specific configuration
    contractOpener: tonClient, // Custom TonClient instance
  },
  TACParams: {
    // TAC-specific configuration
    provider: customProvider, // Custom provider
  },
});
Network Options:
  • Network.TESTNET - For development and testing
  • Network.MAINNET - For production applications
Timing Options:
  • delay - Delay between operations in milliseconds (default: 1000)
TON Parameters:
  • contractOpener - Custom TonClient instance for TON operations
TAC Parameters:
  • provider - Custom provider for TAC operations

​
Verification

Test your installation with a simple initialization: 
import { TacSdk, Network } from "@tonappchain/sdk";

async function testInstallation() {
  try {
    const tacSdk = await TacSdk.create({
      network: Network.TESTNET,
    });

    console.log("✅ TAC SDK initialized successfully");
    console.log("Network:", tacSdk.network);

    // Clean up
    tacSdk.closeConnections();
  } catch (error) {
    console.error("❌ Installation test failed:", error);
  }
}

testInstallation();

​
Common Issues and Solutions

If you encounter module resolution errors, ensure you’re using a modern bundler that supports ES modules:Webpack 5:
// webpack.config.js
module.exports = {
  resolve: {
    fallback: {
      crypto: require.resolve("crypto-browserify"),
      stream: require.resolve("stream-browserify"),
      buffer: require.resolve("buffer"),
    },
  },
};
Vite:
// vite.config.js
export default {
  define: {
    global: "globalThis",
  },
  resolve: {
    alias: {
      crypto: "crypto-browserify",
      stream: "stream-browserify",
      buffer: "buffer",
    },
  },
};
If you experience network connection issues:
  1. Check your network configuration: 
    const tacSdk = await TacSdk.create({
  network: Network.TESTNET,
  TONParams: {
    contractOpener: TonClient({
      endpoint: "https://testnet.toncenter.com/api/v2/jsonRPC",
    }),
  },
});
  2. Verify firewall settings - Ensure your environment can access TON and TAC endpoints
  3. Use environment-specific configuration - Different environments may require different endpoints
For TypeScript type errors:
  1. Install type definitions: 
    npm install --save-dev @types/node
  2. Update your tsconfig.json: 
    {
  "compilerOptions": {
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true
  }
}
  3. Use explicit imports: 
    import type { TacSdk, Network } from "@tonappchain/sdk";

​
Next Steps

With the SDK installed and configured, you’re ready to start building hybrid dApps:

SDK Initialization

Learn how to properly initialize and configure the SDK

Wallet Integration

Connect TON wallets and manage user authentication
Start with the Quick Start guide to send your first cross-chain transaction and see the SDK in action.
⌘I