TxFlow SDK (@txflow/sdk)

The easiest way to integrate gasless transactions into your dApp.

📦 Installation

npm install @txflow/sdk viem

Running in Node.js? Check out the Node.js / Backend Guide.

🛠️ Core Functions

| Function | Description | Gasless? | Popup? | Use Case | |----------|-------------|----------|--------|----------| | 1. sendTransactionGasless(tx) | Execute any smart contract function without user paying gas. | ✅ Yes | 🔔 Yes | One-off actions (Mint NFT, Swap) | | 2. createSessionKey() | Register a session key effectively "logging in" the user for a duration. | ❌ No* | 🔔 Yes | Gaming, Social Apps (Start Session) | | 3. executeWithSessionKey(tx) | Execute transactions instantly using the active session key. | ✅ Yes | 🔕 NO | Move Character, Like Post, Follow | | 4. sendTokenGasless() | Transfer ERC-20 tokens (Requires Approval). | ✅ Yes | 🔔 Yes | Standard Tokens (USDT) | | 5. sendTokenGaslessPermit() | Transfer ERC-20 tokens without ETH (EIP-2612). | ✅ Yes | 🔔 Yes | Modern Tokens (USDC, DAI) |

*createSessionKey requires a signature but no gas if using specific relayer setups, usually user pays gas once or signs off-chain.

📚 Usage Examples

1. Initialize SDK

import { TxFlow } from '@txflow/sdk';
import { createWalletClient, custom, publicActions } from 'viem';
import { baseSepolia } from 'viem/chains';

const walletClient = createWalletClient({
    chain: baseSepolia,
    transport: custom(window.ethereum)
}).extend(publicActions); // 👈 Recommended: Add public actions for read support

// Get the active account address
const [address] = await walletClient.requestAddresses();

const sdk = new TxFlow({
    apiKey: 'YOUR_API_KEY',
    chainId: 84532,
    client: walletClient,
    account: address // ⚠️ REQUIRED: Pass the active address
});

2. Send Gasless Transaction (Full Example)

Execute a function on a smart contract (e.g., Minting an NFT) without the user paying any gas.

import { encodeFunctionData, parseAbi, parseEther } from 'viem';

// --- Example: Minting an NFT ---

// 1. Define the Function Interface (ABI)
// "function mint(address to, uint256 amount)"
const abi = parseAbi([
  'function mint(address to, uint256 amount)'
]);

// 2. Encode the transaction data
const data = encodeFunctionData({
  abi: abi,
  functionName: 'mint',
  args: ['0xUserAddress...', 1n] // Arguments: to, amount
});

// 3. Send securely via TxFlow SDK
// The user will be asked to sign a message (EIP-712), NOT a transaction.
// No ETH required for gas!
const result = await sdk.sendTransactionGasless({
    to: '0xNFTContractAddress...', // Verify this address!
    data: data,
    value: 0n // Value in ETH (usually 0 for contract calls)
});

console.log('Gasless Transaction Hash:', result.txHash);

3. Session Keys (Zero Popup)

// 1. Create Key (User signs ONE time)
await sdk.createSessionKey();

// 2. Execute Actions (Loop this! No popups!)
// Example: Validated 'move(uint x, uint y)' in Game Contract
const moveData = encodeFunctionData({
    abi: parseAbi(['function move(uint256 x, uint256 y)']),
    functionName: 'move',
    args: [10n, 20n]
});

await sdk.executeWithSessionKey({
    to: '0xGameContract...',
    data: moveData
});

4. Send Token Gasless (Standard)

Transfer ERC-20 tokens via Relay. Note: User must approve the Relayer first if the token does not support Permit.

import { parseUnits } from 'viem';

// The "sendTokenGasless" helper automatically encodes 'transferFrom'
// and sends it via the Paymaster.
const result = await sdk.sendTokenGasless(
    '0xUSDC_Address...',  // Token Contract
    '0xRecipient...',     // Receiver
    parseUnits('10', 6)   // Amount (e.g. 10 USDC)
);

console.log('Token Transfer Tx:', result.txHash);

5. Send Token Gasless (Permit) 💸

The BEST WAY to send tokens. No prior approval needed! Uses EIP-2612 Permit to sign authorization off-chain.

import { parseUnits } from 'viem';
import { checkPermitSupport } from '@txflow/sdk';

async function sendUSDC() {
    const tokenAddress = '0xUSDC_Address...';

    // 1. Check if token supports Permit
    const supportsPermit = await checkPermitSupport(walletClient, tokenAddress);
    if (!supportsPermit) {
        console.log('Token does not support Permit.');
        return;
    }

    // 2. Send via Permit
    const result = await sdk.sendTokenGaslessPermit(
        tokenAddress, 
        '0xRecipient...',
        parseUnits('50', 6), // Amount
        undefined, // optional deadline
        '2' // Version (Default is '2' for USDC)
    );
    
    console.log('Permit Transfer Hash:', result.txHash);
}