Configuration
Configuration options and settings for @tetherto/wdk-wallet-tron-gasfree
Network & Service Providers
| Service | Provider | URL (Mainnet) | URL (Testnet) |
|---|---|---|---|
| RPC Provider | TronGrid | https://api.trongrid.io | https://nile.trongrid.io |
| Gas-Free Service | GasFree.io | https://open.gasfree.io/tron/ | https://open-test.gasfree.io/nile/ |
Note: For the latest connection parameters and contract addresses, please refer to the official GasFree Specification.
Wallet Configuration
import WalletManagerTronGasfree from '@tetherto/wdk-wallet-tron-gasfree'
import TronWeb from 'tronweb'
// Option 1: Using RPC URL
const config = {
// Required parameters
chainId: 728126428, // Blockchain ID
provider: 'https://api.trongrid.io', // Tron RPC endpoint
gasFreeProvider: 'https://open.gasfree.io/tron/', // Gas-free service URL
serviceProvider: 'REPLACE_WITH_PROVIDER_ADDRESS',
verifyingContract: 'TFFAMQLZybALaLb4uxHA9RBE7pxhUAjF3U'
}
const wallet = new WalletManagerTronGasfree(seedPhrase, config)
// Option 2: Using TronWeb instance
const tronWeb = new TronWeb({ fullHost: 'https://api.trongrid.io' })
const config2 = {
chainId: 728126428,
provider: tronWeb,
gasFreeProvider: 'https://open.gasfree.io/tron/',
serviceProvider: 'REPLACE_WITH_PROVIDER_ADDRESS',
verifyingContract: 'TFFAMQLZybALaLb4uxHA9RBE7pxhUAjF3U'
}gasFreeApiKey and gasFreeApiSecret are optional. Omit both when your GasFree provider accepts unsigned requests. If you configure signed GasFree API requests, provide both values together; the constructor rejects partial credentials.
The module performs HMAC request signing in the application process. Never embed gasFreeApiSecret in browser, mobile, or distributed desktop code. For client applications, use unsigned access only when the selected provider explicitly permits it, or route GasFree API requests through an authenticated backend that stores the secret.
Retrieve the current service-provider address from the provider's GET /api/v1/config/provider/all response. Do not substitute the verifying-contract address for serviceProvider.
TronGasfreeWalletConfig includes transferMaxFee and transactionMaxFee for shared wallet type compatibility. The current GasFree runtime does not use either constructor field as a fee cap. Pass transferMaxFee in the second argument to account.transfer(); native transaction methods are unsupported, so transactionMaxFee has no effect.
Account Configuration
Both WalletAccountTronGasfree and WalletAccountReadOnlyTronGasfree share similar configuration requirements:
import { WalletAccountTronGasfree, WalletAccountReadOnlyTronGasfree } from '@tetherto/wdk-wallet-tron-gasfree'
// Full access account
const account = new WalletAccountTronGasfree(
seedPhrase,
"0'/0/0", // BIP-44 derivation path
{
chainId: 728126428,
provider: 'https://api.trongrid.io',
gasFreeProvider: 'https://open.gasfree.io/tron/',
serviceProvider: 'REPLACE_WITH_PROVIDER_ADDRESS',
verifyingContract: 'TFFAMQLZybALaLb4uxHA9RBE7pxhUAjF3U'
}
)
// Read-only account (fee-cap fields are omitted)
const readOnlyAccount = new WalletAccountReadOnlyTronGasfree(
'TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH', // Tron address
{
chainId: 728126428,
provider: 'https://api.trongrid.io',
gasFreeProvider: 'https://open.gasfree.io/tron/',
serviceProvider: 'REPLACE_WITH_PROVIDER_ADDRESS',
verifyingContract: 'TFFAMQLZybALaLb4uxHA9RBE7pxhUAjF3U'
}
)
Configuration Options
Provider
The provider option specifies how to connect to the Tron network.
Type: string | TronWeb
Required: Yes
Examples:
// Option 1: Using RPC URL
const config = {
provider: 'https://api.trongrid.io'
}
// Option 2: Using TronWeb instance
const tronWeb = new TronWeb({ fullHost: 'https://api.trongrid.io' })
const config = {
provider: tronWeb
}
Chain ID
The chainId option specifies the blockchain's ID.
Type: number
Required: Yes
Example:
const config = {
chainId: 728126428 // Tron Mainnet
}
Gas-Free Provider
The gasFreeProvider option specifies the URL of the gas-free service.
Type: string
Required: Yes
Example:
const config = {
gasFreeProvider: 'https://open.gasfree.io/tron/'
}
Gas-Free API Key
The gasFreeApiKey option is your API key for signed requests to the gas-free service.
Type: string
Required: No, unless your GasFree provider requires signed API requests.
Example:
// Trusted server runtime only
const config = {
gasFreeApiKey: process.env.GASFREE_API_KEY,
gasFreeApiSecret: process.env.GASFREE_API_SECRET
}
Provide gasFreeApiKey and gasFreeApiSecret together. Passing only one of them throws during account construction. Because the module uses the secret to sign requests locally, configure these fields only in a trusted server runtime.
Gas-Free API Secret
The gasFreeApiSecret option is your API secret for signed requests to the gas-free service.
Type: string
Required: No, unless your GasFree provider requires signed API requests.
Example:
// Trusted server runtime only
const config = {
gasFreeApiKey: process.env.GASFREE_API_KEY,
gasFreeApiSecret: process.env.GASFREE_API_SECRET
}
Provide gasFreeApiSecret and gasFreeApiKey together. Passing only one of them throws during account construction. Never ship the secret in a browser, mobile, or desktop application bundle.
Service Provider
The serviceProvider option is the Tron address of the gas-free service provider.
Type: string
Required: Yes
Example:
const config = {
serviceProvider: 'REPLACE_WITH_PROVIDER_ADDRESS'
}
Retrieve the current address from the provider's GET /api/v1/config/provider/all response.
Verifying Contract
The verifyingContract option is the Tron address of the contract that verifies gas-free transactions.
Type: string
Required: Yes
Example:
const config = {
verifyingContract: 'TFFAMQLZybALaLb4uxHA9RBE7pxhUAjF3U'
}
Transfer Max Fee
Pass transferMaxFee in the optional second argument to account.transfer() to cap one GasFree TRC20 transfer. The constructor-level field exists in TronGasfreeWalletConfig but is not used as a default by the current runtime.
Type: number | bigint
Required: No (optional)
Unit: Token base units
Example:
const config = {
transferMaxFee: 5000n
}
const result = await account.transfer({
token: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
recipient: 'TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH',
amount: 1000000n
}, config)
The transfer is rejected only when the quoted total fee is greater than the cap. A fee equal to transferMaxFee is allowed. Use an integer or bigint value because the runtime converts the cap with BigInt().
Transaction Max Fee
transactionMaxFee is present in the public config type for base-wallet compatibility.
Type: number | bigint
Required: No (optional)
The GasFree module does not support quoteSendTransaction(), signTransaction(), or sendTransaction(). Those methods always throw, so this field does not control a runtime operation in the current release. Use the base @tetherto/wdk-wallet-tron package for native TRX transactions.
Network-Specific Configurations
Tron Mainnet
const mainnetConfig = {
chainId: 728126428,
provider: 'https://api.trongrid.io',
gasFreeProvider: 'https://open.gasfree.io/tron/',
serviceProvider: 'REPLACE_WITH_PROVIDER_ADDRESS',
verifyingContract: 'TFFAMQLZybALaLb4uxHA9RBE7pxhUAjF3U' // Official mainnet contract
}
Tron Nile Testnet
const nileConfig = {
chainId: 3448148188, // Nile Testnet (Specific ID required for GasFree)
provider: 'https://nile.trongrid.io',
gasFreeProvider: 'https://open-test.gasfree.io/nile/',
serviceProvider: 'REPLACE_WITH_PROVIDER_ADDRESS',
verifyingContract: 'THQGuFzL87ZqhxkgqYEryRAd7gqFqL5rdc' // Official Nile testnet contract
}Node.js Quickstart
Get started with WDK in a Node.js environment
React Native Quickstart
Build mobile wallets with React Native Expo
WDK Tron Gasfree Wallet Usage
Get started with WDK's Tron Gasfree Wallet Usage
WDK Tron Gasfree Wallet API
Get started with WDK's Tron Gasfree Wallet API