Properly initializing the TAC SDK is the first step to building a hybrid dApp. This guide explains how to create and configure a TAC SDK instance for your application. Creating a TAC SDK Instance

The TAC SDK uses a factory pattern for initialization. You’ll need to use the async create method rather than a constructor:

import { TacSdk, Network } from '@tonappchain/sdk';

async function initializeSdk() {
  // Create a new SDK instance
  const tacSdk = await TacSdk.create({
    network: Network.TESTNET
  });
  
  return tacSdk;
}

Always use the async TacSdk.create() method, not the constructor. This ensures proper initialization of all SDK components.

​
Configuration Options

When initializing the SDK, you can provide various configuration options:

import { TacSdk, Network } from '@tonappchain/sdk';

async function initializeWithConfig() {
  const tacSdk = await TacSdk.create({
    // Required: Specify the network
    network: Network.TESTNET, // or Network.MAINNET for production
    
    // Optional: Add delay in seconds for network requests
    delay: 3,
    
    // Optional: Custom TON parameters
    TONParams: {
      // Custom configuration for TON client
    },
    
    // Optional: Custom TAC parameters
    TACParams: {
      // Custom configuration for TAC client
    },
    
    // Optional: Custom Lite Sequencer endpoints
    customLiteSequencerEndpoints: [
      // Your custom endpoints
    ]
  });
  
  return tacSdk;
}

​
Available Configuration Options

The SDKParams type includes the following options:

OptionTypeDescription
networkNetworkRequired. Specifies the TON network (TESTNET or MAINNET)
delaynumberOptional. Delay (in seconds) for requests to the TON client. Default is 0
TONParamsTONParamsOptional. Custom parameters for TON side
TACParamsTACParamsOptional. Custom parameters for TAC side
customLiteSequencerEndpointsstring[]Optional. Custom lite sequencer endpoints for API access

​
Custom TON Client Configuration

You can provide a custom TON client for more control over TON interactions. This is useful for applications that need customized rate limiting or error handling:

import { TacSdk, Network } from '@tonappchain/sdk';
import { TonClient } from '@ton/ton';

async function initializeWithCustomTonClient() {
  const tacSdk = await TacSdk.create({
    network: Network.TESTNET,
    TONParams: {
      contractOpener: new TonClient({
        endpoint: "https://testnet.toncenter.com/api/v2/jsonRPC",
        apiKey: "your_api_key" // Recommended for production
      })
    }
  });
  
  return tacSdk;
}

​
Node.js-Specific Configuration

For Node.js environments, you can use lite clients for improved performance:

import { TacSdk, Network, liteClientOpener } from '@tonappchain/sdk';

async function initializeWithLiteClient() {
  // Your own lite client servers configuration
  const liteClientServers = [/* your lite client servers */];
  
  const tacSdk = await TacSdk.create({
    network: Network.TESTNET,
    TONParams: {
      contractOpener: await liteClientOpener({ 
        liteservers: liteClientServers 
      }),
    },
  });
  
  return tacSdk;
}

When using lite clients, remember to call tacSdk.closeConnections() when you’re done to properly clean up resources. Otherwise, your Node.js script might hang.

​
Resource Cleanup

When using custom contract openers (especially with Node.js), you should close connections when you’re done:

// After you're finished with SDK operations
tacSdk.closeConnections();

​
Default Endpoints

If you don’t specify custom endpoints, the SDK uses these public endpoints:

​
Error Handling

The SDK initialization can throw errors if the configuration is invalid:

try {
  const tacSdk = await TacSdk.create({
    network: Network.TESTNET
  });
  console.log("SDK initialized successfully");
} catch (error) {
  if (error.name === "SettingError") {
    console.error("Settings contract error:", error.message);
  } else {
    console.error("SDK initialization error:", error);
  }
}

Common initialization errors include:

  • SettingError: Settings contract at provided address does not contain required setting key

Was this page helpful?