Configuration

Wallet Configuration

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

const config = {
  // Required parameters
  tonClient: {
    url: 'https://toncenter.com/api/v2/jsonRPC',
    secretKey: 'your-api-key' // Optional
  },
  tonApiClient: {
    url: 'https://tonapi.io',
    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)

tonClient.url must be a TON Center v2 JSON-RPC endpoint because the module passes it to @ton/ton's TonClient. Set tonApiClient.url to the TON API base URL without /v2; the generated TON API client appends /v2/gasless/... to the base URL.

Account Configuration

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

const accountConfig = {
  // Required parameters
  tonClient: {
    url: 'https://toncenter.com/api/v2/jsonRPC',
    secretKey: 'your-api-key' // Optional
  },
  tonApiClient: {
    url: 'https://tonapi.io',
    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)

Configuration Options

tonClient

The tonClient option configures the TON Center v2 JSON-RPC 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 v2 JSON-RPC endpoint URL
   * @example 'https://toncenter.com/api/v2/jsonRPC'
   */
  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 retries on the next client when a call throws an Error. By default, this includes application errors as well as connection errors. See retries for the retry count.

tonApiClient

The tonApiClient option configures the TON API client used to build and relay gasless transfers. Its URL is the API base URL, not a versioned endpoint. 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 base URL
   * @example 'https://tonapi.io'
   */
  url: string;

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

Required: Yes

Do not include /v2 in tonApiClient.url. Use https://tonapi.io, not https://tonapi.io/v2; otherwise the generated client requests /v2/v2/gasless/....

paymasterToken

The paymasterToken option specifies the Jetton used to pay gasless transfer fees instead of native TON. Its address must match a gas_jettons[].master_id value returned by the configured TON API service's raw /v2/gasless/config endpoint. The generated @ton-api/client exposes the same values as gasJettons[].masterId.

Type:

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

Required: Yes

paymasterToken must be an object with an address field, not a raw address string.

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/v2/jsonRPC' },
    { url: 'https://your-secondary-toncenter.example/api/v2/jsonRPC', secretKey: 'your-secondary-api-key' } // Replace with a real independent provider
  ],
  tonApiClient: [
    { url: 'https://tonapi.io' },
    { url: 'https://your-secondary-tonapi.example' } // Replace with a real independent provider
  ],
  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 is greater than this limit, so an estimate equal to the configured cap is allowed.

Type: number | bigint

Required: No

Example:

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

transactionMaxFee

TonGaslessWalletConfig includes transactionMaxFee for alignment with the shared wallet config shape. The gasless module does not support sendTransaction(), quoteSendTransaction(), or signTransaction(), so this option does not cap gasless Jetton transfers. Use transferMaxFee for transfer() fee enforcement, and use quoteTransfer() to inspect estimated fees before transferring.

Type: number | bigint

Required: No

Complete Configuration Example

Here's a complete configuration example with required clients, failover, and gasless transfer fee protection:

const config = {
  // TON Client (Required) - array enables failover
  tonClient: [
    { url: 'https://toncenter.com/api/v2/jsonRPC', secretKey: 'your-api-key' },
    { url: 'https://your-secondary-toncenter.example/api/v2/jsonRPC' } // Replace with a real independent provider
  ],

  // TON API Client (Required) - array enables failover
  tonApiClient: [
    { url: 'https://tonapi.io', secretKey: 'your-ton-api-key' },
    { url: 'https://your-secondary-tonapi.example' } // Replace with a real independent provider
  ],

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

  // Failover Retries (Optional)
  retries: 3,

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

Network Selection

Use TON Center and TON API endpoints for the same network:

Mainnet: https://toncenter.com/api/v2/jsonRPC and https://tonapi.io
Testnet: https://testnet.toncenter.com/api/v2/jsonRPC and https://testnet.tonapi.io

Do not mix mainnet and testnet clients in one wallet configuration or failover list.

Through @tetherto/wdk-wallet-ton-gasless 1.0.0-beta.8, the inherited getTransactionReceipt() implementation starts its lookup against a hard-coded mainnet TON Center v3 endpoint. getFeeRates() likewise always reads mainnet TON API configuration. Do not rely on these methods for testnet-specific receipts or fee rates.

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.

Security Considerations

Keep API keys and secrets secure and never expose them in client-side code
Use environment variables for sensitive configuration values
Always use HTTPS URLs for API endpoints
Set appropriate transferMaxFee limits to prevent excessive gasless transfer fees
Do not rely on transactionMaxFee for gasless transfers; native send, quote, and sign methods are unsupported in this module
Validate the paymaster token address before using it in configuration