@tipchain/sdk
UNIVERSAL JAVASCRIPT SDK FOR INTEGRATING TIPCHAIN INTO YOUR APPLICATION. SUPPORTS BOTH BROWSER AND NODE.JS ENVIRONMENTS. TYPE-SAFE, FULLY TYPED, AND OPTIMIZED FOR THE SOLANA ECOSYSTEM.
INSTALLATION
$ npm install @tipchain/sdkREQUIREMENTS: NODE.JS >= 18.0.0, TYPESCRIPT >= 4.5 (RECOMMENDED)
CLIENT CONFIGURATION
The TipChain client accepts a configuration object with the following options:
Environment URLs
https://api.tipchain.dev/v1https://api.staging.tipchain.dev/v1http://localhost:4000QUICKSTART
GET UP AND RUNNING IN MINUTES. THE FOLLOWING EXAMPLE DEMONSTRATES THE CORE WORKFLOW: INITIALIZE THE CLIENT, FETCH A CREATOR, LIST TOP CREATORS, SEND A TIP, AND RETRIEVE ANALYTICS.
import { TipChain } from "@tipchain/sdk";
// Initialize the client
const client = new TipChain({
apiKey: "tc_your_api_key",
environment: "production",
});
// Fetch a creator profile
const { creator } = await client.creators.get("username");
console.log(creator.displayName, "-", creator.totalTips);
// List top creators
const { creators } = await client.creators.list({
sort: "earnings",
limit: 20,
});
// Send a tip
const { transaction } = await client.tips.send({
to: creator.walletAddress,
amount: 0.5,
token: "SOL",
message: "Great work!",
});
// Fetch analytics
const { overview } = await client.analytics.overview(creator.walletAddress);
console.log("Total earnings:", overview.totalEarnings);API MODULES
CREATORS API
client.creators.list(options?)List all creators with optional search, category, sort, limit, and offset.
RETURNS: Promise<Creator[]>
client.creators.get(username)Get a single creator by their username.
RETURNS: Promise<CreatorDetail>
client.creators.getByWallet(wallet)Look up a creator by their Solana wallet address.
RETURNS: Promise<CreatorDetail>
client.creators.create(data)Create a new creator profile. Requires walletAddress and username.
RETURNS: Promise<{ creator: Creator }>
client.creators.update(wallet, data)Update an existing creator profile. Only the wallet owner can update.
RETURNS: Promise<{ creator: Creator }>
TIPS API
client.tips.send(input)Send a tip to a creator. Records transaction both on-chain and off-chain.
RETURNS: Promise<{ transaction: TipResult }>
client.tips.list(wallet?, limit?)Get transaction history for a wallet. If no wallet provided, returns all.
RETURNS: Promise<{ transactions: TipResult[] }>
ANALYTICS API
client.analytics.overview(wallet)Get dashboard overview with total earnings, transactions, and supporter counts.
RETURNS: Promise<{ overview: AnalyticsOverview }>
client.analytics.revenue(wallet, days?)Get revenue chart data for the specified number of days (default: 30).
RETURNS: Promise<{ revenue: RevenuePoint[] }>
client.analytics.exportCSV(wallet, days?)Export transaction data as a CSV file for the specified period.
RETURNS: Promise<Response>
TYPE DEFINITIONS
THE SDK IS FULLY TYPED. KEY INTERFACES ARE EXPORTED FOR TYPE-SAFE INTEGRATION WITH YOUR APPLICATION.
interface TipChainConfig {
apiKey?: string;
environment?: "production" | "staging" | "development";
baseUrl?: string;
}
interface Creator {
walletAddress: string;
username: string;
displayName?: string | null;
bio: string;
avatarUrl: string | null;
socialLinks: Record<string, string>;
totalTips: string;
supporterCount: number;
verified: boolean;
createdAt: string;
}
interface TipInput {
to: string;
amount: number;
token?: "SOL" | "USDC";
message?: string;
}
interface TipResult {
id: string;
senderWallet: string;
receiverWallet: string;
amount: string;
token: string;
txHash?: string;
timestamp: string;
}
interface AnalyticsOverview {
totalEarnings: string;
totalTransactions: number;
totalSupporters: number;
monthlyEarnings: string;
}SELF-HOSTED DEPLOYMENT
FOR SELF-HOSTED INSTANCES, CONFIGURE THE SDK TO POINT TO YOUR OWN BACKEND BY PROVIDING A CUSTOM BASE URL. THIS IS USEFUL FOR PRIVATE DEPLOYMENTS, ENTERPRISE INSTALLATIONS, OR DEVELOPMENT.
import { TipChain } from "@tipchain/sdk";
// Point to your self-hosted backend
const client = new TipChain({
baseUrl: "https://tipchain.yourcompany.com",
});
// All API calls will route to your custom endpoint
const creators = await client.creators.list();
const { transaction } = await client.tips.send({
to: "9xJ4mM3zK9L2pR7vW5qT8nB1cF6dX2yH0aG3sE4r",
amount: 1.0,
token: "SOL",
});https://api.tipchain.dev/v1Default for environment: 'production'https://api.staging.tipchain.dev/v1Default for environment: 'staging'http://localhost:4000Default for environment: 'development'Your URLOverride via baseUrl config optionERROR HANDLING
ALL SDK METHODS THROW A TipChainError ON FAILURE. ERRORS INCLUDE THE HTTP STATUS CODE AND A MACHINE-READABLE ERROR CODE FOR PROGRAMMATIC HANDLING.
import { TipChain, TipChainError } from "@tipchain/sdk";
const client = new TipChain({ apiKey: "tc_..." });
try {
const creator = await client.creators.get("unknown-user");
} catch (error) {
if (error instanceof TipChainError) {
console.error(`[${error.code}] ${error.message}`);
// TipChainError.status — HTTP status code
// TipChainError.code — Machine-readable error code
// TipChainError.message — Human-readable description
}
}ALWAYS WRAP API CALLS IN TRY/CATCH BLOCKS. THE SDK DOES NOT SWALLOW ERRORS — IT PROPAGATES THEM WITH RICH CONTEXT FOR DEBUGGING AND USER FEEDBACK.
FURTHER READING
[ ARCHITECTURE ]
System architecture overview — backend, database, Solana integration.
ARCHITECTURE >>