@gasfree-kit/ton-gasless 0.3.0 → 1.0.0

package/README.md

@@ -1,12 +1,24 @@
 # @gasfree-kit/ton-gasless
 
+> **⚠️ Deprecation notice (v2.0.0)** — the positional methods
+> `TonTransfer.transferUSDT`, `TonTransfer.checkBalance`, and
+> `TonTransfer.getTransactionEstimateFee` are **deprecated** in favour of
+> the options-object methods `TonTransfer.send`, `TonTransfer.getBalance`,
+> and `TonTransfer.estimateFee`.
+>
+> **The legacy positional methods will be removed three weeks after the
+> v2.0.0 publish date** in the next major release. The new methods throw
+> on failure and return a flat result (no `{ success, message, data }`
+> wrapper). Public TON endpoints are used by default — API keys are now
+> optional but recommended for production traffic.
+
 Gasless USDT transfers on TON through a sponsored relay.
 
 With this package, the user only needs USDT. The relay pays the TON gas and charges a small fee back in USDT.
 
 ## What This Package Does
 
-- creates a WDK-backed TON wallet
+- creates a TON wallet from a seed phrase
 - quotes the relay fee in USDT
 - checks that balance covers transfer amount plus fee
 - submits the gasless transfer
@@ -26,7 +38,7 @@ With this package, the user only needs USDT. The relay pays the TON gas and char
         │             │
         v             v
  ┌────────────┐ ┌───────────────┐
- │  WDK TON   │ │  Relay fee    │
+ │  TON       │ │  Relay fee    │
  │  wallet    │ │  quote (USDT) │
  └──────┬─────┘ └───────┬───────┘
         │               │
@@ -62,23 +74,27 @@ This package depends on [`@gasfree-kit/core`](../core/README.md) for:
 npm install @gasfree-kit/ton-gasless @gasfree-kit/core
 ```
 
-Peer dependencies:
-
-```bash
-npm install @tetherto/wdk-wallet-ton-gasless tonweb
-```
+After installing, your package manager will prompt you to install the peer dependencies listed in `package.json`.
 
 ## Configuration
 
+All URL/API-key fields are optional — the SDK falls back to the public
+endpoints exported as `TON_PUBLIC_ENDPOINTS`. For production traffic,
+register keys with toncenter.com / tonapi.io and pass them in.
+
 ```ts
 import type { TonGaslessClientConfig } from '@gasfree-kit/ton-gasless';
 
+// Minimal — uses public endpoints with no API keys.
+const minimalConfig: TonGaslessClientConfig = {};
+
+// Production — bring your own keys.
 const config: TonGaslessClientConfig = {
-  tonCenterUrl: 'https://toncenter.com/api/v2',
   tonCenterApiKey: 'your-toncenter-api-key',
-  tonApiUrl: 'https://tonapi.io',
   tonApiSecretKey: 'your-tonapi-secret-key',
-  // Optional:
+  // Optional URL overrides (default to public endpoints):
+  // tonCenterUrl: 'https://toncenter.com/api/v2/jsonRPC',
+  // tonApiUrl: 'https://tonapi.io',
   // transferMaxFee: 1_000_000,
   // usdtAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
 };
@@ -86,14 +102,14 @@ const config: TonGaslessClientConfig = {
 
 ### Config fields
 
-| Field             | Purpose                                            |
-| ----------------- | -------------------------------------------------- |
-| `tonCenterUrl`    | TON Center endpoint used by the wallet client      |
-| `tonCenterApiKey` | TON Center API key                                 |
-| `tonApiUrl`       | TON API endpoint                                   |
-| `tonApiSecretKey` | TON API secret key                                 |
-| `transferMaxFee`  | Maximum fee limit in base units, capped by the SDK |
-| `usdtAddress`     | Optional override for the TON USDT root            |
+| Field             | Purpose                                                  |
+| ----------------- | -------------------------------------------------------- |
+| `tonCenterUrl`    | TON Center endpoint. Defaults to `TON_PUBLIC_ENDPOINTS`. |
+| `tonCenterApiKey` | TON Center API key. Optional; recommended for prod.      |
+| `tonApiUrl`       | TON API endpoint. Defaults to `TON_PUBLIC_ENDPOINTS`.    |
+| `tonApiSecretKey` | TON API secret key. Optional; recommended for prod.      |
+| `transferMaxFee`  | Maximum fee limit in base units, capped by the SDK.      |
+| `usdtAddress`     | Optional override for the TON USDT root.                 |
 
 ## Quick Start
 
@@ -126,39 +142,46 @@ const walletResult = await setupTonGaslessWallet(seedPhrase, config, "0'/0/0");
 ```ts
 import { TonTransfer } from '@gasfree-kit/ton-gasless';
 
-const balance = await TonTransfer.checkBalance(seedPhrase, config);
+const balance = await TonTransfer.getBalance({ seedPhrase, config });
 
-console.log(balance.data.usdBalance);
-console.log(balance.data.tokenBalance);
+console.log(balance.balance); // "42.50"
+console.log(balance.balanceRaw); // 42500000n
+console.log(balance.address); // wallet address
 ```
 
 ### 4. Estimate the fee
 
 ```ts
-const estimate = await TonTransfer.getTransactionEstimateFee(
+const estimate = await TonTransfer.estimateFee({
   seedPhrase,
   config,
-  '10.00',
-  'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
-);
+  to: 'EQRecipient...',
+  amount: '10.00',
+});
 
-console.log(estimate.data.fee);
+console.log(estimate.fee); // "0.05" (gasless commission in USDT)
 ```
 
 ### 5. Execute the gasless transfer
 
 ```ts
-const result = await TonTransfer.transferUSDT(
+const result = await TonTransfer.send({
   seedPhrase,
   config,
-  '50.00',
-  'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
-);
+  to: 'EQRecipient...',
+  amount: '50.00',
+});
 
-console.log(result.data.transactionHash);
-console.log(result.data.fee);
+console.log(result.transactionHash);
+console.log(result.fee); // bigint, base units
+console.log(result.submittedAt);
 ```
 
+> The legacy positional methods (`transferUSDT`, `checkBalance`,
+> `getTransactionEstimateFee`) remain available and return the previous
+> `{ success, message, data }` envelope. They are marked `@deprecated` and
+> wrap the new methods above.
+
 ## How The Flow Behaves
 
 1. The SDK validates the recipient address.
@@ -169,15 +192,15 @@ console.log(result.data.fee);
 
 ## Main Exports
 
-| Export                   | What it does                                               |
-| ------------------------ | ---------------------------------------------------------- |
-| `setupTonGaslessWallet`  | Creates the WDK-backed TON wallet and resolves the address |
-| `TonTransfer`            | Checks balances, estimates fees, and sends transfers       |
-| `getTonGaslessConfig`    | Expands and validates the runtime config                   |
-| `tonUsdtTokenRoot`       | Built-in TON USDT root address                             |
-| `usdtTonBaseUnits`       | Converts human-readable USDT to base units                 |
-| `fromTonBaseUnitsToUsdt` | Converts base units back to readable USDT                  |
-| `getTonUsdtValue`        | Utility helper for TON to USDT conversions                 |
+| Export                   | What it does                                                       |
+| ------------------------ | ------------------------------------------------------------------ |
+| `setupTonGaslessWallet`  | Creates the TON wallet from a seed phrase and resolves the address |
+| `TonTransfer`            | Checks balances, estimates fees, and sends transfers               |
+| `getTonGaslessConfig`    | Expands and validates the runtime config                           |
+| `tonUsdtTokenRoot`       | Built-in TON USDT root address                                     |
+| `usdtTonBaseUnits`       | Converts human-readable USDT to base units                         |
+| `fromTonBaseUnitsToUsdt` | Converts base units back to readable USDT                          |
+| `getTonUsdtValue`        | Utility helper for TON to USDT conversions                         |
 
 ## Safety Notes
 

package/dist/index.d.mts

@@ -1,6 +1,19 @@
 import * as _tetherto_wdk_wallet_ton_gasless from '@tetherto/wdk-wallet-ton-gasless';
 
 declare const tonUsdtTokenRoot = "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs";
+/**
+ * Public TON mainnet RPC endpoints — used as defaults when the caller
+ * omits `tonCenterUrl` / `tonApiUrl`.
+ *
+ * Public endpoints are rate-limited and unauthenticated. For production
+ * traffic, register a key with toncenter.com / tonapi.io and pass it in
+ * via {@link TonGaslessClientConfig.tonCenterApiKey} and
+ * {@link TonGaslessClientConfig.tonApiSecretKey}.
+ */
+declare const TON_PUBLIC_ENDPOINTS: {
+    readonly tonCenterUrl: "https://toncenter.com/api/v2/jsonRPC";
+    readonly tonApiUrl: "https://tonapi.io";
+};
 type TonGaslessNetworkConfig = {
     tonClient: {
         url: string;
@@ -16,20 +29,24 @@ type TonGaslessNetworkConfig = {
     };
 };
 type TonGaslessClientConfig = {
-    tonCenterUrl: string;
-    tonCenterApiKey: string;
-    tonApiUrl: string;
-    tonApiSecretKey: string;
+    /** Toncenter JSON-RPC URL. Defaults to {@link TON_PUBLIC_ENDPOINTS.tonCenterUrl}. */
+    tonCenterUrl?: string;
+    /** Toncenter API key. Optional for public endpoints; recommended for prod. */
+    tonCenterApiKey?: string;
+    /** Ton API URL. Defaults to {@link TON_PUBLIC_ENDPOINTS.tonApiUrl}. */
+    tonApiUrl?: string;
+    /** Ton API secret key. Optional for public endpoints; recommended for prod. */
+    tonApiSecretKey?: string;
     transferMaxFee?: number;
     usdtAddress?: string;
 };
 declare function getTonGaslessConfig(config: TonGaslessClientConfig): TonGaslessNetworkConfig;
 
 /**
- * Set up a TON gasless wallet via WDK.
+ * Set up a TON gasless wallet.
  *
- * Uses legacy derivation path (m/44'/607'/0'/0/{index}) for compatibility
- * with wallets created by wdk-wallet-ton <= beta.5.
+ * Pins the BIP-44 derivation path at m/44'/607'/0'/0/{index} so the
+ * resulting address stays stable across underlying-library upgrades.
  */
 declare function setupTonGaslessWallet(seedPhrase: string, config: TonGaslessClientConfig, derivationPath?: string): Promise<{
     wallet: _tetherto_wdk_wallet_ton_gasless.default;
@@ -37,24 +54,99 @@ declare function setupTonGaslessWallet(seedPhrase: string, config: TonGaslessCli
     address: string;
 }>;
 
+/** Result of a successful gasless USDT transfer on TON. */
+interface TonTransferResult {
+    transactionHash: string;
+    /** Gasless commission paid in USDT base units. */
+    fee: bigint;
+    /** Sender wallet address. */
+    from: string;
+    /** Recipient wallet address. */
+    to: string;
+    /** Human-readable amount transferred. */
+    amount: string;
+    /** Wall-clock time when the transfer was submitted (ms since epoch). */
+    submittedAt: number;
+}
+/** Result of a TON USDT balance query. */
+interface TonBalanceResult {
+    /** Human-readable balance (e.g. `"42.50"`). */
+    balance: string;
+    /** Raw balance in base units (USDT = 6 decimals). */
+    balanceRaw: bigint;
+    decimals: number;
+    /** Wallet address that holds the balance. */
+    address: string;
+}
+/** Result of a TON gasless transfer fee estimate. */
+interface TonFeeEstimate {
+    /** Human-readable fee in USDT (paymaster token). */
+    fee: string;
+    feeRaw: bigint;
+}
+/** Options for `TonTransfer.send`. */
+interface TonSendOptions {
+    seedPhrase: string;
+    config: TonGaslessClientConfig;
+    to: string;
+    /** Human-readable USDT amount (e.g. `"10.00"`). */
+    amount: string;
+}
+/** Options for `TonTransfer.getBalance`. */
+interface TonBalanceOptions {
+    seedPhrase: string;
+    config: TonGaslessClientConfig;
+    /** Override the USDT jetton root. Defaults to the canonical mainnet USDT. */
+    tokenAddress?: string;
+}
+/** Options for `TonTransfer.estimateFee`. */
+interface TonEstimateFeeOptions {
+    seedPhrase: string;
+    config: TonGaslessClientConfig;
+    to: string;
+    amount: string;
+}
+
 declare class TonTransfer {
     /**
-     * Get transaction fee estimate for a gasless USDT transfer on TON.
-     * The gasless commission is returned in USDT (paymaster token units).
+     * Execute a gasless USDT transfer on TON.
+     *
+     * Throws `InsufficientBalanceError` / `TransactionFailedError` on failure;
+     * resolves with a flat `TonTransferResult` on success.
+     *
+     * @example
+     * ```ts
+     * const receipt = await TonTransfer.send({
+     *   seedPhrase,
+     *   config: { tonCenterApiKey, tonApiSecretKey }, // uses public endpoints by default
+     *   to: 'UQ...',
+     *   amount: '10.00',
+     * });
+     * ```
+     */
+    static send(options: TonSendOptions): Promise<TonTransferResult>;
+    /** Query the USDT balance on TON for the wallet derived from `seedPhrase`. */
+    static getBalance(options: TonBalanceOptions): Promise<TonBalanceResult>;
+    /** Estimate the gasless commission (USDT) for a transfer. */
+    static estimateFee(options: TonEstimateFeeOptions): Promise<TonFeeEstimate>;
+    /**
+     * @deprecated Use {@link TonTransfer.estimateFee} instead. Returns the
+     * legacy `{ success, message, data: { fee } }` shape.
      */
     static getTransactionEstimateFee(seedPhrase: string, config: TonGaslessClientConfig, amountInUsdt: string, recipientAddress: string): Promise<{
         message: string;
-        success: boolean;
+        success: true;
         data: {
             fee: string;
         };
     }>;
     /**
-     * Check USDT balance on TON.
+     * @deprecated Use {@link TonTransfer.getBalance} instead. Returns the
+     * legacy `{ success, message, data }` shape.
      */
     static checkBalance(seedPhrase: string, config: TonGaslessClientConfig, tokenAddress?: string): Promise<{
         message: string;
-        success: boolean;
+        success: true;
         data: {
             tokenBalance: string;
             decimals: number;
@@ -62,17 +154,16 @@ declare class TonTransfer {
         };
     }>;
     /**
-     * Execute a gasless USDT transfer on TON.
-     *
-     * The relay pays Toncoin gas and deducts a small USDT commission.
-     * User only needs USDT — balance must cover amount + gas commission.
+     * @deprecated Use {@link TonTransfer.send} instead — accepts an options
+     * object and returns a flat `TonTransferResult` (no `success`/`message`
+     * wrapper).
      */
     static transferUSDT(seedPhrase: string, config: TonGaslessClientConfig, amountInUsdt: string, recipientAddress: string): Promise<{
         message: string;
-        success: boolean;
+        success: true;
         data: {
             transactionHash: string;
-            fee: unknown;
+            fee: bigint;
             tonTransferContext: {
                 wdkHash: string;
                 walletAddress: string;
@@ -98,4 +189,4 @@ declare function fromTonBaseUnitsToUsdt(amount: bigint, dec?: number): string;
  */
 declare function getTonUsdtValue(amountInBaseUnits: bigint, exchangeRate: number): number;
 
-export { type TonGaslessClientConfig, type TonGaslessNetworkConfig, TonTransfer, fromTonBaseUnitsToUsdt, getTonGaslessConfig, getTonUsdtValue, setupTonGaslessWallet, tonUsdtTokenRoot, usdtTonBaseUnits };
+export { TON_PUBLIC_ENDPOINTS, type TonBalanceOptions, type TonBalanceResult, type TonEstimateFeeOptions, type TonFeeEstimate, type TonGaslessClientConfig, type TonGaslessNetworkConfig, type TonSendOptions, TonTransfer, type TonTransferResult, fromTonBaseUnitsToUsdt, getTonGaslessConfig, getTonUsdtValue, setupTonGaslessWallet, tonUsdtTokenRoot, usdtTonBaseUnits };

package/dist/index.d.ts

@@ -1,6 +1,19 @@
 import * as _tetherto_wdk_wallet_ton_gasless from '@tetherto/wdk-wallet-ton-gasless';
 
 declare const tonUsdtTokenRoot = "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs";
+/**
+ * Public TON mainnet RPC endpoints — used as defaults when the caller
+ * omits `tonCenterUrl` / `tonApiUrl`.
+ *
+ * Public endpoints are rate-limited and unauthenticated. For production
+ * traffic, register a key with toncenter.com / tonapi.io and pass it in
+ * via {@link TonGaslessClientConfig.tonCenterApiKey} and
+ * {@link TonGaslessClientConfig.tonApiSecretKey}.
+ */
+declare const TON_PUBLIC_ENDPOINTS: {
+    readonly tonCenterUrl: "https://toncenter.com/api/v2/jsonRPC";
+    readonly tonApiUrl: "https://tonapi.io";
+};
 type TonGaslessNetworkConfig = {
     tonClient: {
         url: string;
@@ -16,20 +29,24 @@ type TonGaslessNetworkConfig = {
     };
 };
 type TonGaslessClientConfig = {
-    tonCenterUrl: string;
-    tonCenterApiKey: string;
-    tonApiUrl: string;
-    tonApiSecretKey: string;
+    /** Toncenter JSON-RPC URL. Defaults to {@link TON_PUBLIC_ENDPOINTS.tonCenterUrl}. */
+    tonCenterUrl?: string;
+    /** Toncenter API key. Optional for public endpoints; recommended for prod. */
+    tonCenterApiKey?: string;
+    /** Ton API URL. Defaults to {@link TON_PUBLIC_ENDPOINTS.tonApiUrl}. */
+    tonApiUrl?: string;
+    /** Ton API secret key. Optional for public endpoints; recommended for prod. */
+    tonApiSecretKey?: string;
     transferMaxFee?: number;
     usdtAddress?: string;
 };
 declare function getTonGaslessConfig(config: TonGaslessClientConfig): TonGaslessNetworkConfig;
 
 /**
- * Set up a TON gasless wallet via WDK.
+ * Set up a TON gasless wallet.
  *
- * Uses legacy derivation path (m/44'/607'/0'/0/{index}) for compatibility
- * with wallets created by wdk-wallet-ton <= beta.5.
+ * Pins the BIP-44 derivation path at m/44'/607'/0'/0/{index} so the
+ * resulting address stays stable across underlying-library upgrades.
  */
 declare function setupTonGaslessWallet(seedPhrase: string, config: TonGaslessClientConfig, derivationPath?: string): Promise<{
     wallet: _tetherto_wdk_wallet_ton_gasless.default;
@@ -37,24 +54,99 @@ declare function setupTonGaslessWallet(seedPhrase: string, config: TonGaslessCli
     address: string;
 }>;
 
+/** Result of a successful gasless USDT transfer on TON. */
+interface TonTransferResult {
+    transactionHash: string;
+    /** Gasless commission paid in USDT base units. */
+    fee: bigint;
+    /** Sender wallet address. */
+    from: string;
+    /** Recipient wallet address. */
+    to: string;
+    /** Human-readable amount transferred. */
+    amount: string;
+    /** Wall-clock time when the transfer was submitted (ms since epoch). */
+    submittedAt: number;
+}
+/** Result of a TON USDT balance query. */
+interface TonBalanceResult {
+    /** Human-readable balance (e.g. `"42.50"`). */
+    balance: string;
+    /** Raw balance in base units (USDT = 6 decimals). */
+    balanceRaw: bigint;
+    decimals: number;
+    /** Wallet address that holds the balance. */
+    address: string;
+}
+/** Result of a TON gasless transfer fee estimate. */
+interface TonFeeEstimate {
+    /** Human-readable fee in USDT (paymaster token). */
+    fee: string;
+    feeRaw: bigint;
+}
+/** Options for `TonTransfer.send`. */
+interface TonSendOptions {
+    seedPhrase: string;
+    config: TonGaslessClientConfig;
+    to: string;
+    /** Human-readable USDT amount (e.g. `"10.00"`). */
+    amount: string;
+}
+/** Options for `TonTransfer.getBalance`. */
+interface TonBalanceOptions {
+    seedPhrase: string;
+    config: TonGaslessClientConfig;
+    /** Override the USDT jetton root. Defaults to the canonical mainnet USDT. */
+    tokenAddress?: string;
+}
+/** Options for `TonTransfer.estimateFee`. */
+interface TonEstimateFeeOptions {
+    seedPhrase: string;
+    config: TonGaslessClientConfig;
+    to: string;
+    amount: string;
+}
+
 declare class TonTransfer {
     /**
-     * Get transaction fee estimate for a gasless USDT transfer on TON.
-     * The gasless commission is returned in USDT (paymaster token units).
+     * Execute a gasless USDT transfer on TON.
+     *
+     * Throws `InsufficientBalanceError` / `TransactionFailedError` on failure;
+     * resolves with a flat `TonTransferResult` on success.
+     *
+     * @example
+     * ```ts
+     * const receipt = await TonTransfer.send({
+     *   seedPhrase,
+     *   config: { tonCenterApiKey, tonApiSecretKey }, // uses public endpoints by default
+     *   to: 'UQ...',
+     *   amount: '10.00',
+     * });
+     * ```
+     */
+    static send(options: TonSendOptions): Promise<TonTransferResult>;
+    /** Query the USDT balance on TON for the wallet derived from `seedPhrase`. */
+    static getBalance(options: TonBalanceOptions): Promise<TonBalanceResult>;
+    /** Estimate the gasless commission (USDT) for a transfer. */
+    static estimateFee(options: TonEstimateFeeOptions): Promise<TonFeeEstimate>;
+    /**
+     * @deprecated Use {@link TonTransfer.estimateFee} instead. Returns the
+     * legacy `{ success, message, data: { fee } }` shape.
      */
     static getTransactionEstimateFee(seedPhrase: string, config: TonGaslessClientConfig, amountInUsdt: string, recipientAddress: string): Promise<{
         message: string;
-        success: boolean;
+        success: true;
         data: {
             fee: string;
         };
     }>;
     /**
-     * Check USDT balance on TON.
+     * @deprecated Use {@link TonTransfer.getBalance} instead. Returns the
+     * legacy `{ success, message, data }` shape.
      */
     static checkBalance(seedPhrase: string, config: TonGaslessClientConfig, tokenAddress?: string): Promise<{
         message: string;
-        success: boolean;
+        success: true;
         data: {
             tokenBalance: string;
             decimals: number;
@@ -62,17 +154,16 @@ declare class TonTransfer {
         };
     }>;
     /**
-     * Execute a gasless USDT transfer on TON.
-     *
-     * The relay pays Toncoin gas and deducts a small USDT commission.
-     * User only needs USDT — balance must cover amount + gas commission.
+     * @deprecated Use {@link TonTransfer.send} instead — accepts an options
+     * object and returns a flat `TonTransferResult` (no `success`/`message`
+     * wrapper).
      */
     static transferUSDT(seedPhrase: string, config: TonGaslessClientConfig, amountInUsdt: string, recipientAddress: string): Promise<{
         message: string;
-        success: boolean;
+        success: true;
         data: {
             transactionHash: string;
-            fee: unknown;
+            fee: bigint;
             tonTransferContext: {
                 wdkHash: string;
                 walletAddress: string;
@@ -98,4 +189,4 @@ declare function fromTonBaseUnitsToUsdt(amount: bigint, dec?: number): string;
  */
 declare function getTonUsdtValue(amountInBaseUnits: bigint, exchangeRate: number): number;
 
-export { type TonGaslessClientConfig, type TonGaslessNetworkConfig, TonTransfer, fromTonBaseUnitsToUsdt, getTonGaslessConfig, getTonUsdtValue, setupTonGaslessWallet, tonUsdtTokenRoot, usdtTonBaseUnits };
+export { TON_PUBLIC_ENDPOINTS, type TonBalanceOptions, type TonBalanceResult, type TonEstimateFeeOptions, type TonFeeEstimate, type TonGaslessClientConfig, type TonGaslessNetworkConfig, type TonSendOptions, TonTransfer, type TonTransferResult, fromTonBaseUnitsToUsdt, getTonGaslessConfig, getTonUsdtValue, setupTonGaslessWallet, tonUsdtTokenRoot, usdtTonBaseUnits };

package/dist/index.js

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  TON_PUBLIC_ENDPOINTS: () => TON_PUBLIC_ENDPOINTS,
   TonTransfer: () => TonTransfer,
   fromTonBaseUnitsToUsdt: () => fromTonBaseUnitsToUsdt,
   getTonGaslessConfig: () => getTonGaslessConfig,
@@ -42,6 +43,10 @@ module.exports = __toCommonJS(index_exports);
 
 // src/tonNetworkConfiguration.ts
 var tonUsdtTokenRoot = "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs";
+var TON_PUBLIC_ENDPOINTS = {
+  tonCenterUrl: "https://toncenter.com/api/v2/jsonRPC",
+  tonApiUrl: "https://tonapi.io"
+};
 var MAX_TRANSFER_FEE = 5e7;
 var DEFAULT_TRANSFER_FEE = 1e6;
 function getTonGaslessConfig(config) {
@@ -53,16 +58,16 @@ function getTonGaslessConfig(config) {
   }
   return {
     tonClient: {
-      url: config.tonCenterUrl,
-      secretKey: config.tonCenterApiKey
+      url: config.tonCenterUrl ?? TON_PUBLIC_ENDPOINTS.tonCenterUrl,
+      secretKey: config.tonCenterApiKey ?? ""
     },
     transferMaxFee: fee,
     paymasterToken: {
       address: config.usdtAddress ?? tonUsdtTokenRoot
     },
     tonApiClient: {
-      url: config.tonApiUrl,
-      secretKey: config.tonApiSecretKey
+      url: config.tonApiUrl ?? TON_PUBLIC_ENDPOINTS.tonApiUrl,
+      secretKey: config.tonApiSecretKey ?? ""
     }
   };
 }
@@ -113,123 +118,190 @@ function getTonUsdtValue(amountInBaseUnits, exchangeRate) {
 
 // src/tonGaslessTetherTransfer.ts
 var TonTransfer = class {
-  /**
-   * Get transaction fee estimate for a gasless USDT transfer on TON.
-   * The gasless commission is returned in USDT (paymaster token units).
-   */
-  static async getTransactionEstimateFee(seedPhrase, config, amountInUsdt, recipientAddress) {
-    (0, import_core.validateTonAddress)(recipientAddress, "recipient address");
-    const amount = usdtTonBaseUnits(amountInUsdt);
-    const { account, wallet } = await setupTonGaslessWallet(seedPhrase, config);
-    try {
-      const transferQuote = await account.quoteTransfer({
-        token: tonUsdtTokenRoot,
-        recipient: recipientAddress,
-        amount
-      });
-      const feeInUsdt = fromTonBaseUnitsToUsdt(transferQuote.fee);
-      return {
-        message: "Transaction fee estimate retrieved successfully",
-        success: true,
-        data: { fee: feeInUsdt }
-      };
-    } finally {
-      account.dispose();
-      wallet.dispose();
-    }
-  }
-  /**
-   * Check USDT balance on TON.
-   */
-  static async checkBalance(seedPhrase, config, tokenAddress = tonUsdtTokenRoot) {
-    const { account, wallet } = await setupTonGaslessWallet(seedPhrase, config);
-    try {
-      const balance = await account.getTokenBalance(tokenAddress);
-      const usdBalance = fromTonBaseUnitsToUsdt(balance);
-      return {
-        message: "TON balances retrieved successfully",
-        success: true,
-        data: {
-          tokenBalance: balance.toString(),
-          decimals: 6,
-          usdBalance: String(usdBalance)
-        }
-      };
-    } finally {
-      account.dispose();
-      wallet.dispose();
-    }
-  }
+  // -----------------------------------------------------------------------
+  // New ergonomic API (v1)
+  // -----------------------------------------------------------------------
   /**
    * Execute a gasless USDT transfer on TON.
    *
-   * The relay pays Toncoin gas and deducts a small USDT commission.
-   * User only needs USDT — balance must cover amount + gas commission.
+   * Throws `InsufficientBalanceError` / `TransactionFailedError` on failure;
+   * resolves with a flat `TonTransferResult` on success.
+   *
+   * @example
+   * ```ts
+   * const receipt = await TonTransfer.send({
+   *   seedPhrase,
+   *   config: { tonCenterApiKey, tonApiSecretKey }, // uses public endpoints by default
+   *   to: 'UQ...',
+   *   amount: '10.00',
+   * });
+   * ```
    */
-  static async transferUSDT(seedPhrase, config, amountInUsdt, recipientAddress) {
-    const amount = usdtTonBaseUnits(amountInUsdt);
+  static async send(options) {
+    const { seedPhrase, config, to, amount } = options;
+    const amountRaw = usdtTonBaseUnits(amount);
     const {
       account,
       wallet,
       address: walletAddress
     } = await setupTonGaslessWallet(seedPhrase, config);
     try {
-      (0, import_core.validateTonAddress)(recipientAddress, "recipient address");
-      if (recipientAddress.toLowerCase() === walletAddress.toLowerCase()) {
+      (0, import_core.validateTonAddress)(to, "recipient address");
+      if (to.toLowerCase() === walletAddress.toLowerCase()) {
         throw new import_core.TransactionFailedError("ton", "Cannot transfer to your own address");
       }
       const balance = await account.getTokenBalance(tonUsdtTokenRoot);
       const quote = await account.quoteTransfer({
         token: tonUsdtTokenRoot,
-        recipient: recipientAddress,
-        amount
+        recipient: to,
+        amount: amountRaw
       });
-      if (balance < amount + quote.fee) {
+      if (balance < amountRaw + quote.fee) {
         throw new import_core.InsufficientBalanceError("ton", "USDT (amount + gas fee)");
       }
       const result = await account.transfer({
         token: tonUsdtTokenRoot,
-        recipient: recipientAddress,
-        amount
+        recipient: to,
+        amount: amountRaw
       });
       return {
-        message: "USDT transfer on TON successful (gasless)",
-        success: true,
-        data: {
-          transactionHash: result.hash,
-          fee: result.fee,
-          tonTransferContext: {
-            wdkHash: result.hash,
-            walletAddress,
-            recipientAddress,
-            amountBaseUnits: amount.toString(),
-            transferTimestamp: Date.now()
-          }
-        }
+        transactionHash: result.hash,
+        fee: BigInt(result.fee),
+        from: walletAddress,
+        to,
+        amount,
+        submittedAt: Date.now()
       };
     } catch (error) {
       if (error instanceof import_core.InsufficientBalanceError || error instanceof import_core.TransactionFailedError) {
         throw error;
       }
-      let message = "Failed to transfer USDT on TON";
-      if (error instanceof Error) {
-        if (error.message.includes("insufficient balance") || error.message.includes("Failed to unpack account state")) {
-          message = "Insufficient USDT balance for network fees";
-        } else if (error.message.includes("invalid address")) {
-          message = "The recipient TON address is invalid";
-        } else if (error.message.includes("timeout")) {
-          message = "Network timeout - please try again";
-        }
-      }
-      throw new import_core.TransactionFailedError("ton", message);
+      throw new import_core.TransactionFailedError("ton", mapTonError(error));
+    } finally {
+      account.dispose();
+      wallet.dispose();
+    }
+  }
+  /** Query the USDT balance on TON for the wallet derived from `seedPhrase`. */
+  static async getBalance(options) {
+    const { seedPhrase, config } = options;
+    const tokenAddress = options.tokenAddress ?? tonUsdtTokenRoot;
+    const { account, wallet, address } = await setupTonGaslessWallet(seedPhrase, config);
+    try {
+      const raw = await account.getTokenBalance(tokenAddress);
+      return {
+        balance: String(fromTonBaseUnitsToUsdt(raw)),
+        balanceRaw: BigInt(raw),
+        decimals: 6,
+        address
+      };
+    } finally {
+      account.dispose();
+      wallet.dispose();
+    }
+  }
+  /** Estimate the gasless commission (USDT) for a transfer. */
+  static async estimateFee(options) {
+    const { seedPhrase, config, to, amount } = options;
+    (0, import_core.validateTonAddress)(to, "recipient address");
+    const amountRaw = usdtTonBaseUnits(amount);
+    const { account, wallet } = await setupTonGaslessWallet(seedPhrase, config);
+    try {
+      const quote = await account.quoteTransfer({
+        token: tonUsdtTokenRoot,
+        recipient: to,
+        amount: amountRaw
+      });
+      return {
+        fee: String(fromTonBaseUnitsToUsdt(quote.fee)),
+        feeRaw: BigInt(quote.fee)
+      };
     } finally {
       account.dispose();
       wallet.dispose();
     }
   }
+  // -----------------------------------------------------------------------
+  // Legacy positional API — preserved for backwards compatibility.
+  // -----------------------------------------------------------------------
+  /**
+   * @deprecated Use {@link TonTransfer.estimateFee} instead. Returns the
+   * legacy `{ success, message, data: { fee } }` shape.
+   */
+  static async getTransactionEstimateFee(seedPhrase, config, amountInUsdt, recipientAddress) {
+    const result = await this.estimateFee({
+      seedPhrase,
+      config,
+      to: recipientAddress,
+      amount: amountInUsdt
+    });
+    return {
+      message: "Transaction fee estimate retrieved successfully",
+      success: true,
+      data: { fee: result.fee }
+    };
+  }
+  /**
+   * @deprecated Use {@link TonTransfer.getBalance} instead. Returns the
+   * legacy `{ success, message, data }` shape.
+   */
+  static async checkBalance(seedPhrase, config, tokenAddress = tonUsdtTokenRoot) {
+    const result = await this.getBalance({ seedPhrase, config, tokenAddress });
+    return {
+      message: "TON balances retrieved successfully",
+      success: true,
+      data: {
+        tokenBalance: result.balanceRaw.toString(),
+        decimals: result.decimals,
+        usdBalance: result.balance
+      }
+    };
+  }
+  /**
+   * @deprecated Use {@link TonTransfer.send} instead — accepts an options
+   * object and returns a flat `TonTransferResult` (no `success`/`message`
+   * wrapper).
+   */
+  static async transferUSDT(seedPhrase, config, amountInUsdt, recipientAddress) {
+    const result = await this.send({
+      seedPhrase,
+      config,
+      to: recipientAddress,
+      amount: amountInUsdt
+    });
+    return {
+      message: "USDT transfer on TON successful (gasless)",
+      success: true,
+      data: {
+        transactionHash: result.transactionHash,
+        fee: result.fee,
+        tonTransferContext: {
+          wdkHash: result.transactionHash,
+          walletAddress: result.from,
+          recipientAddress: result.to,
+          amountBaseUnits: usdtTonBaseUnits(result.amount).toString(),
+          transferTimestamp: result.submittedAt
+        }
+      }
+    };
+  }
 };
+function mapTonError(error) {
+  if (!(error instanceof Error)) return "Failed to transfer USDT on TON";
+  if (error.message.includes("insufficient balance") || error.message.includes("Failed to unpack account state")) {
+    return "Insufficient USDT balance for network fees";
+  }
+  if (error.message.includes("invalid address")) {
+    return "The recipient TON address is invalid";
+  }
+  if (error.message.includes("timeout")) {
+    return "Network timeout - please try again";
+  }
+  return "Failed to transfer USDT on TON";
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  TON_PUBLIC_ENDPOINTS,
   TonTransfer,
   fromTonBaseUnitsToUsdt,
   getTonGaslessConfig,

package/dist/index.mjs

@@ -1,5 +1,9 @@
 // src/tonNetworkConfiguration.ts
 var tonUsdtTokenRoot = "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs";
+var TON_PUBLIC_ENDPOINTS = {
+  tonCenterUrl: "https://toncenter.com/api/v2/jsonRPC",
+  tonApiUrl: "https://tonapi.io"
+};
 var MAX_TRANSFER_FEE = 5e7;
 var DEFAULT_TRANSFER_FEE = 1e6;
 function getTonGaslessConfig(config) {
@@ -11,16 +15,16 @@ function getTonGaslessConfig(config) {
   }
   return {
     tonClient: {
-      url: config.tonCenterUrl,
-      secretKey: config.tonCenterApiKey
+      url: config.tonCenterUrl ?? TON_PUBLIC_ENDPOINTS.tonCenterUrl,
+      secretKey: config.tonCenterApiKey ?? ""
     },
     transferMaxFee: fee,
     paymasterToken: {
       address: config.usdtAddress ?? tonUsdtTokenRoot
     },
     tonApiClient: {
-      url: config.tonApiUrl,
-      secretKey: config.tonApiSecretKey
+      url: config.tonApiUrl ?? TON_PUBLIC_ENDPOINTS.tonApiUrl,
+      secretKey: config.tonApiSecretKey ?? ""
     }
   };
 }
@@ -75,122 +79,189 @@ function getTonUsdtValue(amountInBaseUnits, exchangeRate) {
 
 // src/tonGaslessTetherTransfer.ts
 var TonTransfer = class {
-  /**
-   * Get transaction fee estimate for a gasless USDT transfer on TON.
-   * The gasless commission is returned in USDT (paymaster token units).
-   */
-  static async getTransactionEstimateFee(seedPhrase, config, amountInUsdt, recipientAddress) {
-    validateTonAddress(recipientAddress, "recipient address");
-    const amount = usdtTonBaseUnits(amountInUsdt);
-    const { account, wallet } = await setupTonGaslessWallet(seedPhrase, config);
-    try {
-      const transferQuote = await account.quoteTransfer({
-        token: tonUsdtTokenRoot,
-        recipient: recipientAddress,
-        amount
-      });
-      const feeInUsdt = fromTonBaseUnitsToUsdt(transferQuote.fee);
-      return {
-        message: "Transaction fee estimate retrieved successfully",
-        success: true,
-        data: { fee: feeInUsdt }
-      };
-    } finally {
-      account.dispose();
-      wallet.dispose();
-    }
-  }
-  /**
-   * Check USDT balance on TON.
-   */
-  static async checkBalance(seedPhrase, config, tokenAddress = tonUsdtTokenRoot) {
-    const { account, wallet } = await setupTonGaslessWallet(seedPhrase, config);
-    try {
-      const balance = await account.getTokenBalance(tokenAddress);
-      const usdBalance = fromTonBaseUnitsToUsdt(balance);
-      return {
-        message: "TON balances retrieved successfully",
-        success: true,
-        data: {
-          tokenBalance: balance.toString(),
-          decimals: 6,
-          usdBalance: String(usdBalance)
-        }
-      };
-    } finally {
-      account.dispose();
-      wallet.dispose();
-    }
-  }
+  // -----------------------------------------------------------------------
+  // New ergonomic API (v1)
+  // -----------------------------------------------------------------------
   /**
    * Execute a gasless USDT transfer on TON.
    *
-   * The relay pays Toncoin gas and deducts a small USDT commission.
-   * User only needs USDT — balance must cover amount + gas commission.
+   * Throws `InsufficientBalanceError` / `TransactionFailedError` on failure;
+   * resolves with a flat `TonTransferResult` on success.
+   *
+   * @example
+   * ```ts
+   * const receipt = await TonTransfer.send({
+   *   seedPhrase,
+   *   config: { tonCenterApiKey, tonApiSecretKey }, // uses public endpoints by default
+   *   to: 'UQ...',
+   *   amount: '10.00',
+   * });
+   * ```
    */
-  static async transferUSDT(seedPhrase, config, amountInUsdt, recipientAddress) {
-    const amount = usdtTonBaseUnits(amountInUsdt);
+  static async send(options) {
+    const { seedPhrase, config, to, amount } = options;
+    const amountRaw = usdtTonBaseUnits(amount);
     const {
       account,
       wallet,
       address: walletAddress
     } = await setupTonGaslessWallet(seedPhrase, config);
     try {
-      validateTonAddress(recipientAddress, "recipient address");
-      if (recipientAddress.toLowerCase() === walletAddress.toLowerCase()) {
+      validateTonAddress(to, "recipient address");
+      if (to.toLowerCase() === walletAddress.toLowerCase()) {
         throw new TransactionFailedError("ton", "Cannot transfer to your own address");
       }
       const balance = await account.getTokenBalance(tonUsdtTokenRoot);
       const quote = await account.quoteTransfer({
         token: tonUsdtTokenRoot,
-        recipient: recipientAddress,
-        amount
+        recipient: to,
+        amount: amountRaw
       });
-      if (balance < amount + quote.fee) {
+      if (balance < amountRaw + quote.fee) {
         throw new InsufficientBalanceError("ton", "USDT (amount + gas fee)");
       }
       const result = await account.transfer({
         token: tonUsdtTokenRoot,
-        recipient: recipientAddress,
-        amount
+        recipient: to,
+        amount: amountRaw
       });
       return {
-        message: "USDT transfer on TON successful (gasless)",
-        success: true,
-        data: {
-          transactionHash: result.hash,
-          fee: result.fee,
-          tonTransferContext: {
-            wdkHash: result.hash,
-            walletAddress,
-            recipientAddress,
-            amountBaseUnits: amount.toString(),
-            transferTimestamp: Date.now()
-          }
-        }
+        transactionHash: result.hash,
+        fee: BigInt(result.fee),
+        from: walletAddress,
+        to,
+        amount,
+        submittedAt: Date.now()
       };
     } catch (error) {
       if (error instanceof InsufficientBalanceError || error instanceof TransactionFailedError) {
         throw error;
       }
-      let message = "Failed to transfer USDT on TON";
-      if (error instanceof Error) {
-        if (error.message.includes("insufficient balance") || error.message.includes("Failed to unpack account state")) {
-          message = "Insufficient USDT balance for network fees";
-        } else if (error.message.includes("invalid address")) {
-          message = "The recipient TON address is invalid";
-        } else if (error.message.includes("timeout")) {
-          message = "Network timeout - please try again";
-        }
-      }
-      throw new TransactionFailedError("ton", message);
+      throw new TransactionFailedError("ton", mapTonError(error));
+    } finally {
+      account.dispose();
+      wallet.dispose();
+    }
+  }
+  /** Query the USDT balance on TON for the wallet derived from `seedPhrase`. */
+  static async getBalance(options) {
+    const { seedPhrase, config } = options;
+    const tokenAddress = options.tokenAddress ?? tonUsdtTokenRoot;
+    const { account, wallet, address } = await setupTonGaslessWallet(seedPhrase, config);
+    try {
+      const raw = await account.getTokenBalance(tokenAddress);
+      return {
+        balance: String(fromTonBaseUnitsToUsdt(raw)),
+        balanceRaw: BigInt(raw),
+        decimals: 6,
+        address
+      };
+    } finally {
+      account.dispose();
+      wallet.dispose();
+    }
+  }
+  /** Estimate the gasless commission (USDT) for a transfer. */
+  static async estimateFee(options) {
+    const { seedPhrase, config, to, amount } = options;
+    validateTonAddress(to, "recipient address");
+    const amountRaw = usdtTonBaseUnits(amount);
+    const { account, wallet } = await setupTonGaslessWallet(seedPhrase, config);
+    try {
+      const quote = await account.quoteTransfer({
+        token: tonUsdtTokenRoot,
+        recipient: to,
+        amount: amountRaw
+      });
+      return {
+        fee: String(fromTonBaseUnitsToUsdt(quote.fee)),
+        feeRaw: BigInt(quote.fee)
+      };
     } finally {
       account.dispose();
       wallet.dispose();
     }
   }
+  // -----------------------------------------------------------------------
+  // Legacy positional API — preserved for backwards compatibility.
+  // -----------------------------------------------------------------------
+  /**
+   * @deprecated Use {@link TonTransfer.estimateFee} instead. Returns the
+   * legacy `{ success, message, data: { fee } }` shape.
+   */
+  static async getTransactionEstimateFee(seedPhrase, config, amountInUsdt, recipientAddress) {
+    const result = await this.estimateFee({
+      seedPhrase,
+      config,
+      to: recipientAddress,
+      amount: amountInUsdt
+    });
+    return {
+      message: "Transaction fee estimate retrieved successfully",
+      success: true,
+      data: { fee: result.fee }
+    };
+  }
+  /**
+   * @deprecated Use {@link TonTransfer.getBalance} instead. Returns the
+   * legacy `{ success, message, data }` shape.
+   */
+  static async checkBalance(seedPhrase, config, tokenAddress = tonUsdtTokenRoot) {
+    const result = await this.getBalance({ seedPhrase, config, tokenAddress });
+    return {
+      message: "TON balances retrieved successfully",
+      success: true,
+      data: {
+        tokenBalance: result.balanceRaw.toString(),
+        decimals: result.decimals,
+        usdBalance: result.balance
+      }
+    };
+  }
+  /**
+   * @deprecated Use {@link TonTransfer.send} instead — accepts an options
+   * object and returns a flat `TonTransferResult` (no `success`/`message`
+   * wrapper).
+   */
+  static async transferUSDT(seedPhrase, config, amountInUsdt, recipientAddress) {
+    const result = await this.send({
+      seedPhrase,
+      config,
+      to: recipientAddress,
+      amount: amountInUsdt
+    });
+    return {
+      message: "USDT transfer on TON successful (gasless)",
+      success: true,
+      data: {
+        transactionHash: result.transactionHash,
+        fee: result.fee,
+        tonTransferContext: {
+          wdkHash: result.transactionHash,
+          walletAddress: result.from,
+          recipientAddress: result.to,
+          amountBaseUnits: usdtTonBaseUnits(result.amount).toString(),
+          transferTimestamp: result.submittedAt
+        }
+      }
+    };
+  }
 };
+function mapTonError(error) {
+  if (!(error instanceof Error)) return "Failed to transfer USDT on TON";
+  if (error.message.includes("insufficient balance") || error.message.includes("Failed to unpack account state")) {
+    return "Insufficient USDT balance for network fees";
+  }
+  if (error.message.includes("invalid address")) {
+    return "The recipient TON address is invalid";
+  }
+  if (error.message.includes("timeout")) {
+    return "Network timeout - please try again";
+  }
+  return "Failed to transfer USDT on TON";
+}
 export {
+  TON_PUBLIC_ENDPOINTS,
   TonTransfer,
   fromTonBaseUnitsToUsdt,
   getTonGaslessConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gasfree-kit/ton-gasless",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "Gasless USDT transfers on TON via sponsored relay",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -17,12 +17,25 @@
     "README.md"
   ],
   "dependencies": {
-    "@gasfree-kit/core": "0.2.0"
+    "@gasfree-kit/core": "0.2.1"
   },
   "peerDependencies": {
     "@tetherto/wdk-wallet-ton-gasless": "^1.0.0-beta.4",
     "tonweb": "^0.0.66"
   },
+  "keywords": [
+    "gasless",
+    "gas-free",
+    "ton",
+    "toncoin",
+    "usdt",
+    "transfer",
+    "sponsored",
+    "relay",
+    "web3",
+    "sdk",
+    "meta-transactions"
+  ],
   "license": "MIT",
   "publishConfig": {
     "access": "public"