@gasfree-kit/core

Shared types, chain metadata, validation helpers, error classes, and seed phrase utilities used across the gasfree-kit SDK.

@gasfree-kit/core is the foundation package. It does not send transactions by itself. Instead, it gives the rest of the SDK a common language for chains, balances, addresses, and errors.

What This Package Is For

Use this package when you want to:

• share SDK-wide types in your app
• read built-in chain metadata
• validate EVM or TON addresses before making requests
• handle gasfree-kit errors in a consistent way
• generate a seed phrase through WDK

Package Diagram

                 ┌──────────────┐
                 │   Your app   │
                 └──────┬───────┘
                        │
         ┌──────────────┼──────────────┐
         v              v              v
  ┌────────────┐ ┌─────────────┐ ┌──────────┐
  │  evm-4337  │ │ ton-gasless │ │ testing  │
  └──────┬─────┘ └──────┬──────┘ └────┬─────┘
         │              │              │
         └──────────────┼──────────────┘
                        v
                 ┌──────────────┐
                 │     core     │
                 └──────────────┘

Installation

npm install @gasfree-kit/core

Peer dependency:

npm install @tetherto/wdk

If you only use @gasfree-kit/evm-4337 or @gasfree-kit/ton-gasless, this package is usually pulled in for you automatically.

What You Get

| Category | Main exports | Why it matters | | ------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | Types | SupportedChain, EvmChain, SupportedToken, TransactionResult, GaslessTransferParams, GaslessClient | Keeps app code and package integrations consistent | | Chain config | EVM_CHAINS, TON_CHAIN | Gives you built-in chain IDs, RPC URLs, explorer URLs, and USDT addresses | | Validation | validateEvmAddress, validateTonAddress | Fails early on malformed recipient or token addresses | | Errors | GasfreeError, TransactionFailedError, InsufficientBalanceError, UnsupportedChainError, PaymasterError | Makes error handling predictable across packages | | Seed phrase | generateSeedPhrase | Lets you create a new mnemonic through WDK |

Quick Examples

Read chain metadata

import { EVM_CHAINS, TON_CHAIN } from '@gasfree-kit/core';

const base = EVM_CHAINS.base;
console.log(base.chainId); // 8453
console.log(base.usdtAddress);

console.log(TON_CHAIN.endpoint);
console.log(TON_CHAIN.usdtAddress);

Generate a seed phrase

import { generateSeedPhrase } from '@gasfree-kit/core';

const seedPhrase = await generateSeedPhrase();

Validate addresses before submitting work

import { validateEvmAddress, validateTonAddress } from '@gasfree-kit/core';

validateEvmAddress('0x1111111111111111111111111111111111111111', 'base');
validateTonAddress('EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs');

Reuse shared types in your app

import type { GaslessTransferParams, SupportedChain, TransactionResult } from '@gasfree-kit/core';

type TransferJob = {
  chain: SupportedChain;
  params: GaslessTransferParams;
};

function logResult(result: TransactionResult) {
  console.log(result.chain, result.hash, result.success);
}

Handle SDK errors consistently

import { GasfreeError, InsufficientBalanceError, TransactionFailedError } from '@gasfree-kit/core';

try {
  // call into another gasfree-kit package
} catch (error) {
  if (error instanceof InsufficientBalanceError) {
    console.log('Balance issue:', error.message);
  } else if (error instanceof TransactionFailedError) {
    console.log('Transfer failed:', error.message);
  } else if (error instanceof GasfreeError) {
    console.log('SDK error:', error.code, error.message);
  }
}

Export Overview

import {
  EVM_CHAINS,
  TON_CHAIN,
  generateSeedPhrase,
  validateEvmAddress,
  validateTonAddress,
  GasfreeError,
  InsufficientBalanceError,
  UnsupportedChainError,
  TransactionFailedError,
  PaymasterError,
} from '@gasfree-kit/core';

import type {
  SupportedChain,
  EvmChain,
  NonEvmChain,
  SupportedToken,
  TransactionResult,
  WalletResult,
  GaslessTransferParams,
  GaslessClient,
} from '@gasfree-kit/core';

When To Reach For Other Packages

• Use @gasfree-kit/evm-4337 when you want ERC-4337 Safe-based USDT transfers on EVM chains.
• Use @gasfree-kit/ton-gasless when you want gasless USDT transfers on TON.
• Use @gasfree-kit/testing when you want mocks and test helpers inside this monorepo.

License

MIT