@tippingchain/sdk

TypeScript SDK for TippingChain v2.6 - a unified multi-chain tipping platform with integrated Relay.link bridging, creator registry, and viewer rewards. Enable users to tip content creators using creator IDs from 9 source chains with automatic USDC payouts on ApeChain.

Version 2.6 Updates

- ✨ Updated Testnet Support: Complete migration from deprecated Holesky/Curtis to active Arbitrum Sepolia (421614) and Base Sepolia (84532)
- 🌐 Enhanced Chain Definitions: Updated all chain configurations with current testnet networks and proper RPC endpoints
- 🔧 Improved Contract Integration: Enhanced thirdweb SDK integration with full function signature resolution for contract methods
- 📊 Updated Fee Calculations: Accurate 5% platform fee for tips, 1% for viewer rewards with tier-based creator splits
- 🧪 Production-Ready Testnet: Full end-to-end cross-chain testing flow with real Relay.link bridging Arbitrum Sepolia → Base Sepolia
- 📦 Package Alignment: Compatible with @tippingchain/contracts-interface v1.6.0 and ui-react v2.6.0
- 🔗 Enhanced Relay Service: Improved ApeChainRelayService with testnet API support and better error handling
- 💰 Updated Token Support: Current testnet token addresses and configurations for USDC on supported chains
- 🔒 Improved Type Safety: Better TypeScript integration with thirdweb v5 and enhanced method resolution
- 🎯 Enhanced Error Handling: Better error messages and debugging support for testnet development

Features

- 🌐 Multi-chain support: 9 source chains (ETH, MATIC, OP, BSC, Abstract, AVAX, Base, Arbitrum, Taiko) → ApeChain
- 🔄 Integrated bridging: Built-in Relay.link functionality in smart contracts (no SDK relay needed)
- 💰 Dual fee structure: 5% for creator tips, 1% for viewer rewards
- 💵 USDC Payouts: All tips and rewards converted to stable USDC on ApeChain
- 🆔 Creator Registry: Simple creator ID system with wallet recovery
- 🎁 Viewer Rewards: Creators can reward audience members with batch support
- 🔑 Thirdweb Integration: Full support for thirdweb account IDs and smart accounts
- 🚀 Easy integration: Simple TypeScript SDK with React support
- 🔒 Type-safe: Full TypeScript support with comprehensive types

Installation

``bash
npm install @tippingchain/sdk thirdweb
`

Quick Start

$3

`typescript
import { ApeChainTippingSDK, SUPPORTED_CHAINS, SUPPORTED_TESTNETS } from '@tippingchain/sdk';

// Production/Mainnet
const sdk = new ApeChainTippingSDK({
clientId: 'your-thirdweb-client-id',
environment: 'production',
// Contract addresses are automatically loaded from @tippingchain/contracts-interface
// Only specify streamingPlatformAddresses if using custom deployments
});

// Testnet
const testnetSdk = new ApeChainTippingSDK({
clientId: 'your-thirdweb-client-id',
environment: 'development',
useTestnet: true // Uses Arbitrum Sepolia (421614) and Base Sepolia (84532) for cross-chain testing
});
`

$3

`typescript
// Register a new creator on all chains and get their ID (requires admin permissions)
const creatorId = await sdk.addCreator({
creatorWallet: '0x1234567890123456789012345678901234567890',
tier: 0, // TIER_1 (60/40 split)
// chainId is optional - if not specified, registers on all deployed chains
});

console.log(Creator registered with ID: ${creatorId});

// Register with thirdweb account ID
const creatorId = await sdk.addCreator({
creatorWallet: '0x1234567890123456789012345678901234567890',
thirdwebId: 'user_abcdef123456',
tier: 0
});

// Or register on a specific chain only
const creatorId = await sdk.addCreator({
creatorWallet: '0x1234567890123456789012345678901234567890',
tier: 0,
chainId: SUPPORTED_CHAINS.POLYGON // Only register on Polygon
});
`

$3

`typescript
// Send native token tip using creator ID (testnet example)
const result = await sdk.sendTip({
sourceChainId: 421614, // Arbitrum Sepolia testnet
creatorId: 1, // Use creator ID instead of wallet address
token: 'native',
amount: '10000000000000000', // 0.01 ETH in wei (testnet amount)
});

if (result.success) {
console.log(🎉 Tip sent! TX: ${result.sourceTransactionHash});
console.log( Creator ID: ${result.creatorId});
console.log( Estimated USDC: ${result.estimatedUsdcAmount});
}
`

$3

`typescript
// Get creator info by ID (testnet example)
const creator = await sdk.getCreator(1, 421614); // Arbitrum Sepolia
console.log(Creator: ${creator.wallet}, Tips: ${creator.totalTips});

// Find creator by wallet address
const creator2 = await sdk.getCreatorByWallet('0x479945d7931baC3343967bD0f839f8691E54a66e', 421614);

// Update creator wallet (for lost wallet recovery) - requires admin permissions
await sdk.updateCreatorWallet(1, '0xNewWalletAddress', 421614);

// Admin management functions (contract owner only) - testnet examples
await sdk.grantAdmin('0x29aE0362FcF55cc646fD83B6E0DeB433FF7e019b', 421614); // Testnet admin
await sdk.revokeAdmin('0xAdminWalletAddress', 421614);
const isAdmin = await sdk.isAdmin('0x29aE0362FcF55cc646fD83B6E0DeB433FF7e019b', 421614);

// Get platform statistics
const stats = await sdk.getPlatformStats(421614); // Arbitrum Sepolia
console.log(Active Creators: ${stats.activeCreators});
console.log(Total Tips: ${stats.totalTips});

// Get top creators leaderboard
const topCreators = await sdk.getTopCreators(10, 421614);
`

$3

`typescript
// Send a reward to a viewer (creators only) - testnet example
const rewardResult = await sdk.rewardViewer({
viewerAddress: '0x65dF34504D2a5D96f4478544D5279B12b3fbEA87', // Test tipper wallet
amount: '10000000000000000', // 0.01 ETH in wei (testnet amount)
reason: 'Great question during the stream!',
token: 'native',
chainId: 421614 // Arbitrum Sepolia testnet
});

if (rewardResult.success) {
console.log(🎁 Reward sent! TX: ${rewardResult.transactionHash});
console.log( Viewer receives: ${rewardResult.viewerAmount});
console.log( Platform fee (1%): ${rewardResult.platformFee});
console.log( Estimated USDC on ApeChain: ${rewardResult.estimatedUsdcAmount});
}

// Reward using viewer ID (for registered viewers)
const rewardByIdResult = await sdk.rewardViewer({
viewerId: 123, // Use viewer ID instead of address
amount: '100000000000000000',
reason: 'Active participant!'
});

// Reward using thirdweb ID
const rewardByThirdwebId = await sdk.rewardViewer({
thirdwebId: 'user_xyz789', // Thirdweb account ID
amount: '100000000000000000',
reason: 'Great contribution!'
});

// Batch reward multiple viewers (gas efficient) - testnet example
const batchResult = await sdk.batchRewardViewers({
viewers: [
{ address: '0x65dF34504D2a5D96f4478544D5279B12b3fbEA87', amount: '5000000000000000', reason: 'Active participant' },
{ address: '0x29aE0362FcF55cc646fD83B6E0DeB433FF7e019b', amount: '10000000000000000', reason: 'Best question' },
{ address: '0x479945d7931baC3343967bD0f839f8691E54a66e', amount: '7500000000000000', reason: 'Helpful feedback' }
],
chainId: 421614 // Arbitrum Sepolia testnet
});

// Check viewer reward stats
const stats = await sdk.getViewerRewardStats('0x65dF34504D2a5D96f4478544D5279B12b3fbEA87', 421614);
console.log(Total rewards given: ${stats.totalRewardsGiven});
console.log(Total rewards received: ${stats.totalRewardsReceived});
console.log(Number of rewards sent: ${stats.rewardCount});

// Check if viewer rewards are enabled
const enabled = await sdk.areViewerRewardsEnabled(421614); // Arbitrum Sepolia
console.log(Viewer rewards enabled: ${enabled});

// Enable or disable viewer rewards (admin only)
await sdk.setViewerRewardsEnabled(true, 421614);

// Check viewer's USDC balance on Base Sepolia (testnet destination)
const usdcBalance = await sdk.getViewerUsdcBalanceOnApeChain('0x65dF34504D2a5D96f4478544D5279B12b3fbEA87');
console.log(USDC Balance on Base Sepolia: ${(parseFloat(usdcBalance) / 1e6).toFixed(2)} USDC);
`

$3

`typescript
// Get native token balance for a wallet (testnet example)
const balance = await sdk.getNativeBalance('0x65dF34504D2a5D96f4478544D5279B12b3fbEA87', 421614);
console.log(Balance: ${(parseFloat(balance) / 1e18).toFixed(4)} ETH);

// Get ERC20 token balance (testnet USDC)
const tokenBalance = await sdk.getTokenBalance(
'0x65dF34504D2a5D96f4478544D5279B12b3fbEA87', // test wallet address
'0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d', // USDC on Arbitrum Sepolia
421614 // Arbitrum Sepolia
);
console.log(USDC Balance: ${(parseFloat(tokenBalance) / 1e6).toFixed(2)} USDC);

// Get multiple token balances at once
const balances = await sdk.getMultipleTokenBalances(
'0x65dF34504D2a5D96f4478544D5279B12b3fbEA87',
['native', '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d'], // Native + USDC on Arbitrum Sepolia
421614
);
console.log(Balances:, balances);

// Check if token approval is needed (testnet example)
const needsApproval = await sdk.needsApproval(
'0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d', // USDC on Arbitrum Sepolia
'0x65dF34504D2a5D96f4478544D5279B12b3fbEA87',
'0x2b50C16877a3E262e0D5B9a4B9f7517634Ba27d8', // TippingChain contract
'1000000', // 1 USDC in smallest units
421614 // Arbitrum Sepolia
);

// Approve token spending
const approval = await sdk.approveToken(
'0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d', // USDC on Arbitrum Sepolia
'0x2b50C16877a3E262e0D5B9a4B9f7517634Ba27d8', // TippingChain contract
'1000000', // 1 USDC
421614
);

// Approve unlimited token spending
const maxApproval = await sdk.approveTokenMax(
'0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d', // USDC on Arbitrum Sepolia
'0x2b50C16877a3E262e0D5B9a4B9f7517634Ba27d8', // TippingChain contract
421614
);
`

$3

`typescript
// Add an authorized relayer for cross-chain operations (admin only) - testnet example
await sdk.addAuthorizedRelayer('0x29aE0362FcF55cc646fD83B6E0DeB433FF7e019b', 421614);

// Remove an authorized relayer (admin only)
await sdk.removeAuthorizedRelayer('0xRelayerAddress', 421614);

// Manually relay pending ETH to Base Sepolia (admin only)
await sdk.manualRelayETH(421614); // Arbitrum Sepolia

// Manually relay pending token to Base Sepolia (admin only)
await sdk.manualRelayToken('0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d', 421614); // USDC

// Set auto-relay mode for cross-chain operations (admin only)
await sdk.setAutoRelay(true, 421614);
`

$3

`typescript
// Pause contract operations (admin only) - testnet example
await sdk.pause(421614); // Arbitrum Sepolia

// Unpause contract operations (admin only)
await sdk.unpause(421614);

// Perform an emergency withdrawal of funds (admin only)
await sdk.emergencyWithdraw(421614);
`

$3

`typescript
// Get Base Sepolia-specific statistics (testnet destination)
const destStats = await sdk.getApeChainStats(84532); // Base Sepolia
console.log(Total USDC on Base Sepolia: ${destStats.totalUsdc});
console.log(Total from Chain: ${destStats.totalFromChain});

// Get all active creators with pagination (testnet example)
const activeCreators = await sdk.getAllActiveCreators(0, 10, 421614); // Arbitrum Sepolia
console.log(Total Active Creators: ${activeCreators.totalActive});
console.log(Creator IDs: ${activeCreators.creatorIds});
console.log(Wallets: ${activeCreators.wallets});
console.log(Tip Amounts: ${activeCreators.tipAmounts});

// Get information for multiple creators by IDs
const creatorsInfo = await sdk.getCreatorsByIds([1], 421614); // Creator #1 on testnet
console.log(Tip Amounts: ${creatorsInfo.tipAmounts});
console.log(Wallets: ${creatorsInfo.wallets});
console.log(Active Status: ${creatorsInfo.activeStatus});
`

Supported Chains

$3

| Chain | Chain ID | Native Token | Type | Contract Address |
|-------|----------|--------------|------|-----------------|
| Arbitrum Sepolia | 421614 | ETH | Source | 0x2b50C16877a3E262e0D5B9a4B9f7517634Ba27d8 |
| Base Sepolia | 84532 | ETH | Destination | 0x2b50C16877a3E262e0D5B9a4B9f7517634Ba27d8 |
| Polygon Amoy | 80002 | MATIC | Source (additional) | Available |

Testnet Network Details:

Arbitrum Sepolia:
- RPC: https://sepolia-rollup.arbitrum.io/rpc
- Explorer: https://sepolia.arbiscan.io
- Faucet: https://faucet.quicknode.com/arbitrum/sepolia
- USDC: 0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d

Base Sepolia:
- RPC: https://sepolia.base.org
- Explorer: https://sepolia.basescan.org
- Faucet: https://faucet.quicknode.com/base/sepolia
- USDC: 0x036CbD53842c5426634e7929541eC2318f3dCF7e

Note: Current testnet setup uses Arbitrum Sepolia → Base Sepolia for end-to-end cross-chain testing with real Relay.link bridging.

Fee Structure

$3

- Documentation: See the docs folder for detailed guides
- Examples: Check examples/ for usage patterns
- Contract Interface: @tippingchain/contracts-interface` package

License

MIT License - see LICENSE file for details.