SmoothSend SDK

Multi-chain gasless transaction SDK. Enable gas-free transactions with just 3 lines of code. Supports Aptos and Stellar.

🚀 Features

• Gasless Transactions: Users don't need APT or XLM for gas fees
• Multi-Chain: Aptos + Stellar (same 3-line API)
• 3-Line Integration: Works with Aptos Wallet Adapter and Stellar wallets (Freighter, etc.)
• Type-Safe: Full TypeScript support with comprehensive type definitions
• Testnet & Mainnet: Supports both networks on each chain
• Fee-in-Token: On Aptos mainnet, tiny fee deducted from token (not APT)

📦 Installation

npm install @smoothsend/sdk

⚡ Quick Start - Wallet Adapter (EASIEST - All Transactions Gasless)

The simplest integration — pass transactionSubmitter to your wallet provider and every transaction becomes gasless automatically. Ideal when you want to sponsor all functions.

import { SmoothSendTransactionSubmitter } from '@smoothsend/sdk';
import { AptosWalletAdapterProvider } from '@aptos-labs/wallet-adapter-react';
import { Network } from '@aptos-labs/ts-sdk';

// 1. Create the transaction submitter (one line!)
const transactionSubmitter = new SmoothSendTransactionSubmitter({
  apiKey: 'pk_nogas_your_api_key_here',
  network: 'testnet'
});

// 2. Add to your wallet provider
function App() {
  return (
    <AptosWalletAdapterProvider
      dappConfig={{
        network: Network.TESTNET,
        transactionSubmitter: transactionSubmitter  // <-- That's it!
      }}
    >
      <YourApp />
    </AptosWalletAdapterProvider>
  );
}

// 3. Use normal wallet functions - they're now gasless!
function TransferButton() {
  const { signAndSubmitTransaction } = useWallet();

  const handleTransfer = async () => {
    // This is now gasless! No code changes needed!
    const result = await signAndSubmitTransaction({
      data: {
        function: "0x1::coin::transfer",
        typeArguments: ["0x1::aptos_coin::AptosCoin"],
        functionArguments: [recipientAddress, amount],
      }
    });
    console.log('Gasless transaction:', result.hash);
  };

  return <button onClick={handleTransfer}>Send (Gasless!)</button>;
}

---

🎯 useSmoothSend Hook (Per-Function Routing)

Use useSmoothSend when you want some functions gasless and others not — for example, free to create but user pays to delete. The hook automatically routes each transaction based on your project's sponsored-functions allowlist configured in the dashboard.

import { useSmoothSend, SmoothSendTransactionSubmitter } from '@smoothsend/sdk';

// Create once at module scope (not inside the component)
const submitter = new SmoothSendTransactionSubmitter({
  apiKey: process.env.NEXT_PUBLIC_SMOOTHSEND_API_KEY!,
  network: 'testnet',
});

function MyComponent() {
  // Drop-in replacement for useWallet().signAndSubmitTransaction
  const { signAndSubmitTransaction } = useSmoothSend(submitter);

  const handleAction = async () => {
    // Automatically routed:
    //   function in allowlist  → fee-payer gasless (user pays 0 gas)
    //   function not in list   → walletSignAndSubmit fallback (user pays gas)
    await signAndSubmitTransaction({
      data: {
        function: '0xABC::mymodule::my_function',
        functionArguments: [arg1, arg2],
      }
    });
  };
}

Requirements for useSmoothSend:

• react >= 17
• @aptos-labs/wallet-adapter-react >= 8
• @aptos-labs/ts-sdk >= 5.0.0 ← required for withFeePayer: true support

Do NOT use transactionSubmitter in AptosWalletAdapterProvider when using useSmoothSend — the hook handles all routing directly.

When to use which

Want to...	Use
Make ALL transactions gasless, zero config	transactionSubmitter in AptosWalletAdapterProvider
Sponsor only specific functions (allowlist)	useSmoothSend(submitter) hook
Mainnet free tier — deduct fee from token	ScriptComposerClient

---

💰 Script Composer - Fee-in-Token Transfers

For mainnet with free tier, use Script Composer to deduct fees from the token being transferred:

import { ScriptComposerClient } from '@smoothsend/sdk';

// Create client for mainnet
const client = new ScriptComposerClient({
  apiKey: 'pk_nogas_your_api_key',
  network: 'mainnet'
});

// Step 1: Build transfer (fee calculated automatically)
const { transactionBytes, fee, totalAmount } = await client.buildTransfer({
  sender: wallet.address,
  recipient: '0x123...',
  amount: '1000000',     // 1 USDC
  assetType: '0xf22bede...::usdc::USDC',
  decimals: 6,
  symbol: 'USDC'
});

console.log(`Sending 1 USDC, fee: ${fee} (deducted from token)`);

// Step 2: Sign with wallet
const signedTx = await wallet.signTransaction(transactionBytes);

// Step 3: Submit
const result = await client.submitSignedTransaction({
  transactionBytes: signedTx.transactionBytes,
  authenticatorBytes: signedTx.authenticatorBytes
});

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

When to Use Each Method

Scenario	Method	Why
Testnet (any tier)	TransactionSubmitter	Always free on testnet
Mainnet + Free tier	ScriptComposerClient	Fee deducted from token ($0.01/tx)
Mainnet + Paid tier	TransactionSubmitter	Zero fees included in subscription
Swaps, NFTs, contracts	TransactionSubmitter	Script Composer only supports transfers
Token transfers (monetize)	ScriptComposerClient	Pass fee to users

Script Composer Methods

// Estimate fee without building transaction
const estimate = await client.estimateFee({
  sender: '0x...',
  recipient: '0x...',
  amount: '1000000',
  assetType: USDC_ADDRESS,
  decimals: 6,
  symbol: 'USDC'
});

console.log('Fee:', estimate.estimation.formatted.fee);
console.log('Total:', estimate.estimation.formatted.totalAmount);

// Or use the convenience method for complete flow
const result = await client.transfer(transferParams, wallet);

---

⚠️ Important Security Update

For Aptos transactions, the SDK uses a secure serialized transaction approach that requires proper wallet integration using the Aptos Wallet Standard.

See the Wallet Adapter Integration section for the recommended implementation.

🔑 Authentication

SmoothSend uses API keys for authentication. There are two types of keys:

Public Keys (pk_nogas_*)

• Safe for frontend applications - Can be embedded in client-side code
• CORS-protected - Only work from configured domains
• Use in: React apps, Vue apps, browser extensions, mobile apps

Secret Keys (sk_nogas_*)

• Server-side only - Must never be exposed in client-side code
• No CORS restrictions - Work from any server environment
• Use in: Node.js backends, serverless functions, API servers

Getting Your API Keys

1. Sign up at dashboard.smoothsend.xyz
2. Create a project
3. Generate an API key pair - you'll receive both a public and secret key
4. Configure CORS origins for your public key

Security Best Practices

⚠️ Never commit secret keys to version control ⚠️ Never expose secret keys in client-side code ✅ Use public keys for frontend applications ✅ Use secret keys for backend services ✅ Configure CORS origins for production domains

🏁 Classic SDK Usage

If you prefer more control over the transaction flow, you can use the classic SDK approach:

Frontend Example (Public Key)

import { SmoothSendSDK } from '@smoothsend/sdk';

// Initialize with public key (safe for frontend)
const smoothSend = new SmoothSendSDK({
  apiKey: 'pk_nogas_your_public_key_here',
  network: 'testnet',
  timeout: 30000,
  retries: 3
});

// Create a transfer request
const transferRequest = {
  from: '0x742d35cc6634c0532925a3b8d2d2d2d2d2d2d2d2',
  to: '0x742d35cc6634c0532925a3b8d2d2d2d2d2d2d2d3',
  token: 'USDC',
  amount: '1000000', // 1 USDC (6 decimals)
  chain: 'aptos-testnet' as const
};

// Execute transfer (with wallet signer)
try {
  const result = await smoothSend.transfer(transferRequest, walletSigner);
  console.log('Transfer successful:', result.txHash);
} catch (error) {
  console.error('Transfer failed:', error.message);
}

Backend Example (Secret Key)

import { SmoothSendSDK } from '@smoothsend/sdk';

// Initialize with secret key (server-side only)
const smoothSend = new SmoothSendSDK({
  apiKey: 'sk_nogas_your_secret_key_here',
  network: 'mainnet',
  timeout: 30000,
  retries: 3
});

// Execute Aptos transfer from backend
const result = await smoothSend.executeGaslessTransfer({
  transactionBytes: signedTx.transactionBytes,
  authenticatorBytes: signedTx.authenticatorBytes,
  chain: 'aptos-mainnet',
  network: 'mainnet'
});

// Or Stellar - submit signed XDR
const stellarResult = await smoothSend.submitStellarTransaction(signedXdr);

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

⭐ Stellar - Gasless XLM & USDC

Same 3-line API for Stellar. Use with Freighter, Stellar Wallets Kit, or any Stellar-compatible wallet.

import { SmoothSendSDK } from '@smoothsend/sdk';

const sdk = new SmoothSendSDK({ apiKey: 'pk_nogas_xxx', network: 'testnet' });

// Option 1: Full transfer (build + sign + submit)
const result = await sdk.transfer(
  { from: 'G...', to: 'G...', amount: '100', token: 'XLM', chain: 'stellar-testnet' },
  stellarWallet
);

// Option 2: Submit pre-signed XDR
const signedXdr = await wallet.signTransaction(tx);
const result = await sdk.submitStellarTransaction(signedXdr);

Stellar wallet interface:

const stellarWallet = {
  buildTransaction: (params) => buildPaymentTransaction(params.from, params.to, params.amount, params.token),
  signTransaction: (tx) => walletKit.signTransaction(tx.toXDR()).then(r => r.signedTxXdr),
};

🔧 Supported Networks

Network	Status	Features
Aptos Testnet	✅ Active	Gasless transactions, Ed25519 signatures
Aptos Mainnet	✅ Active	Gasless transactions, Fee-in-token option
Stellar Testnet	✅ Active	Gasless XLM, USDC, EURC via Fee Bump
Stellar Mainnet	✅ Active	Gasless XLM, USDC, EURC via Fee Bump

📚 API Reference

SmoothSendTransactionSubmitter

The recommended way to integrate - works with Aptos Wallet Adapter.

import { SmoothSendTransactionSubmitter } from '@smoothsend/sdk';

const submitter = new SmoothSendTransactionSubmitter({
  apiKey: 'pk_nogas_your_api_key',
  network: 'testnet' // or 'mainnet'
});

// Pass to AptosWalletAdapterProvider
<AptosWalletAdapterProvider
  dappConfig={{
    network: Network.TESTNET,
    transactionSubmitter: submitter
  }}
>

ScriptComposerClient

For mainnet transfers with fee-in-token (fee deducted from transferred amount).

import { ScriptComposerClient } from '@smoothsend/sdk';

const client = new ScriptComposerClient({
  apiKey: 'pk_nogas_your_api_key',
  network: 'mainnet'
});

// Build transfer
const { transactionBytes, fee } = await client.buildTransfer({
  sender: '0x...',
  recipient: '0x...',
  amount: '1000000',
  assetType: USDC_ADDRESS,
  decimals: 6,
  symbol: 'USDC'
});

// Estimate fee
const estimate = await client.estimateFee(transferParams);

// Submit signed transaction  
const result = await client.submitSignedTransaction({
  transactionBytes,
  authenticatorBytes
});

SmoothSendSDK (Classic)

Direct SDK usage for more control. Works for both Aptos and Stellar.

import { SmoothSendSDK } from '@smoothsend/sdk';

const smoothSend = new SmoothSendSDK({
  apiKey: 'pk_nogas_your_api_key',
  network: 'testnet',
  timeout: 30000,
  retries: 3
});

// Aptos - execute gasless transfer
const result = await smoothSend.executeGaslessTransfer({
  transactionBytes: signedTx.transactionBytes,
  authenticatorBytes: signedTx.authenticatorBytes,
  chain: 'aptos-testnet',
  network: 'testnet'
});

// Stellar - submit signed XDR
const stellarResult = await smoothSend.submitStellarTransaction(signedXdr);

🔐 Security

• All transactions require user signature approval
• Private keys never leave the client
• Rate limiting and validation on relayer endpoints
• Comprehensive input validation
• Public keys are CORS-protected (safe for frontend)
• Secret keys for backend only

🔗 Links

• Dashboard: dashboard.smoothsend.xyz
• Documentation: docs.smoothsend.xyz
• GitHub: github.com/smoothsend

📄 License

MIT

---

Built with ❤️ by the SmoothSend team