Configuration

Wallet Configuration

import WalletManagerTonGasless from '@tetherto/wdk-wallet-ton-gasless'

const config = {
  // Required parameters
  tonClient: {
    url: 'https://toncenter.com/api/v3',
    secretKey: 'your-api-key' // Optional
  },
  tonApiClient: {
    url: 'https://tonapi.io/v2',
    secretKey: 'your-ton-api-key' // Optional
  },
  paymasterToken: {
    address: 'EQ...' // Paymaster Jetton master contract address
  },

  // Optional parameters
  retries: 3, // Failover retries when tonClient/tonApiClient are arrays
  transferMaxFee: 10000000 // Maximum fee in paymaster Jetton base units
}

const wallet = new WalletManagerTonGasless(seedPhrase, config)

Account Configuration

import { WalletAccountTonGasless } from '@tetherto/wdk-wallet-ton-gasless'

const accountConfig = {
  // Required parameters
  tonClient: {
    url: 'https://toncenter.com/api/v3',
    secretKey: 'your-api-key' // Optional
  },
  tonApiClient: {
    url: 'https://tonapi.io/v2',
    secretKey: 'your-ton-api-key' // Optional
  },
  paymasterToken: {
    address: 'EQ...' // Paymaster Jetton master contract address
  },

  // Optional parameters
  retries: 3, // Failover retries when tonClient/tonApiClient are arrays
  transferMaxFee: 10000000 // Maximum fee in paymaster Jetton base units
}

const account = new WalletAccountTonGasless(seedPhrase, "0'", accountConfig)

The tonClient option configures the TON Center API client for blockchain interactions. You can pass a single configuration object, a TonClient instance, or an array of configurations or instances to enable failover.

Type:

type TonClientConfig = {
  /**
   * TON Center API endpoint URL
   * @example 'https://toncenter.com/api/v3'
   */
  url: string;

  /**
   * Optional API key for TON Center
   * Required for higher rate limits
   */
  secretKey?: string;
};

// tonClient accepts a single config/instance or an array for failover
type TonClient = TonClientConfig | TonClientInstance | Array<TonClientConfig | TonClientInstance>;

Required: Yes

When you provide an array, the wallet automatically falls back to the next client in the list if a connection error occurs. See retries for the retry count.

tonApiClient

The tonApiClient option configures the TON API client used to build and relay gasless transfers. Like tonClient, it accepts a single configuration object, a TonApiClient instance, or an array of configurations or instances for failover.

Type:

type TonApiClientConfig = {
  /**
   * TON API endpoint URL
   * @example 'https://tonapi.io/v2'
   */
  url: string;

  /**
   * Optional API key for TON API
   */
  secretKey?: string;
};

Required: Yes

paymasterToken

The paymasterToken option specifies the Jetton used to pay gasless transfer fees instead of native TON.

Type:

type PaymasterToken = {
  /**
   * Paymaster Jetton master contract address
   * @example 'EQ...'
   */
  address: string;
};

Required: Yes

Example:

const config = {
  paymasterToken: {
    address: 'EQ...' // Paymaster Jetton master contract address
  }
}

retries

The retries option sets the number of additional failover attempts after the initial call fails, used only when tonClient and tonApiClient are arrays of configurations or instances. Total attempts equal 1 + retries. If retries exceeds the number of clients, failover loops back and retries already-failed clients in round-robin order.

Type: number

Required: No (default: 3)

Example:

const config = {
  tonClient: [
    { url: 'https://toncenter.com/api/v3' },
    { url: 'https://backup.toncenter.com/api/v3', secretKey: 'your-api-key' }
  ],
  tonApiClient: [
    { url: 'https://tonapi.io/v2' },
    { url: 'https://backup.tonapi.io/v2' }
  ],
  retries: 3
}

transferMaxFee

The transferMaxFee option sets the maximum allowed fee in paymaster Jetton base units for transfer operations. A transfer throws if its estimated fee reaches this limit.

Type: number | bigint

Required: No

Example:

const config = {
  transferMaxFee: 10000000 // Maximum fee in paymaster Jetton base units
}

Complete Configuration Example

Here's a complete configuration example with all options, including failover:

const config = {
  // TON Client (Required) - array enables failover
  tonClient: [
    { url: 'https://toncenter.com/api/v3', secretKey: 'your-api-key' },
    { url: 'https://backup.toncenter.com/api/v3' }
  ],

  // TON API Client (Required) - array enables failover
  tonApiClient: [
    { url: 'https://tonapi.io/v2', secretKey: 'your-ton-api-key' },
    { url: 'https://backup.tonapi.io/v2' }
  ],

  // Paymaster Token (Required)
  paymasterToken: {
    address: 'EQ...' // Paymaster Jetton master contract address
  },

  // Failover Retries (Optional)
  retries: 3,

  // Fee Limits (Optional)
  transferMaxFee: 10000000 // Maximum fee in paymaster Jetton base units
}

The default derivation path changed in 1.0.0-beta.5. Accounts now derive at m/44'/607'/{index}' to align with @tetherto/wdk-wallet-ton. Wallets created with 1.0.0-beta.4 or earlier derived getAccount(index) at m/44'/607'/0'/0/{index}, so the same seed produces different addresses after upgrading. Migrate existing accounts using getAccountByPath() with the old path if you need to keep prior addresses.