TippingChain SDK - On-chain tipping with USDC payouts on ApeChain
npm install @tippingchain/sdkTypeScript 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.
- โจ 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
- ๐ 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
``bash`
npm install @tippingchain/sdk thirdweb
`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
});
`
`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
});
`
`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}); Creator ID: ${result.creatorId}
console.log(); Estimated USDC: ${result.estimatedUsdcAmount}
console.log();`
}
`typescriptCreator: ${creator.wallet}, Tips: ${creator.totalTips}
// Get creator info by ID (testnet example)
const creator = await sdk.getCreator(1, 421614); // Arbitrum Sepolia
console.log();
// 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});Total Tips: ${stats.totalTips}
console.log();
// Get top creators leaderboard
const topCreators = await sdk.getTopCreators(10, 421614);
`
`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}); Viewer receives: ${rewardResult.viewerAmount}
console.log(); Platform fee (1%): ${rewardResult.platformFee}
console.log(); Estimated USDC on ApeChain: ${rewardResult.estimatedUsdcAmount}
console.log();
}
// 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});Total rewards received: ${stats.totalRewardsReceived}
console.log();Number of rewards sent: ${stats.rewardCount}
console.log();
// 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);`
`typescriptBalance: ${(parseFloat(balance) / 1e18).toFixed(4)} ETH
// Get native token balance for a wallet (testnet example)
const balance = await sdk.getNativeBalance('0x65dF34504D2a5D96f4478544D5279B12b3fbEA87', 421614);
console.log();
// 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
);
`
`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);
`
`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);
`
`typescriptTotal USDC on Base Sepolia: ${destStats.totalUsdc}
// Get Base Sepolia-specific statistics (testnet destination)
const destStats = await sdk.getApeChainStats(84532); // Base Sepolia
console.log();Total from Chain: ${destStats.totalFromChain}
console.log();
// 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});Creator IDs: ${activeCreators.creatorIds}
console.log();Wallets: ${activeCreators.wallets}
console.log();Tip Amounts: ${activeCreators.tipAmounts}
console.log();
// Get information for multiple creators by IDs
const creatorsInfo = await sdk.getCreatorsByIds([1], 421614); // Creator #1 on testnet
console.log(Tip Amounts: ${creatorsInfo.tipAmounts});Wallets: ${creatorsInfo.wallets}
console.log();Active Status: ${creatorsInfo.activeStatus}
console.log();`
Active Testnet Configuration:
| Chain | Chain ID | Native Token | Type | Contract Address |
|-------|----------|--------------|------|-----------------|
| Arbitrum Sepolia | 421614 | ETH | Source | 0x2b50C16877a3E262e0D5B9a4B9f7517634Ba27d8 |0x2b50C16877a3E262e0D5B9a4B9f7517634Ba27d8
| Base Sepolia | 84532 | ETH | Destination | |
| 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.
TippingChain v2.0+ features integrated Relay.link functionality directly in the TippingChain smart contracts:
- โ
No separate bridge contracts needed (50% reduction in complexity)
- โ
Automatic cross-chain bridging on every tip and viewer reward
- โ
Direct USDC conversion and payout to ApeChain
- โ
Simplified deployment - one contract per chain instead of two
- โ
Gas efficient - single transaction handles tip + relay
#### How it works:
1. User sends tip/reward on source chain (e.g., Polygon)
2. Contract automatically deducts platform fee
3. Built-in relay integration bridges remaining tokens to ApeChain
4. Tokens are automatically converted to USDC on ApeChain
5. Recipients receive stable USDC payouts
- Documentation: See the docs folder for detailed guides
- Examples: Check examples/ for usage patterns@tippingchain/contracts-interface` package
- Contract Interface:
MIT License - see LICENSE file for details.