API INTEGRATION
REST API REFERENCE AND INTEGRATION GUIDE FOR THE TIPCHAIN PLATFORM. TYPE-SAFE CLIENT LIBRARIES, CURL EXAMPLES, FULL ENDPOINT DOCUMENTATION, AND ERROR HANDLING.
GETTING STARTED
Base URLs
https://api.tipchain.dev/v1https://api.staging.tipchain.dev/v1http://localhost:4000Authentication
Protected endpoints require an API key passed via the Authorization header:
Authorization: Bearer tc_your_api_keyObtain an API key by connecting your wallet and generating one from the dashboard settings panel.
@tipchain/api — TypeScript Client
THE @tipchain/api PACKAGE PROVIDES A TYPE-SAFE REST CLIENT FOR THE TIPCHAIN PLATFORM. IT HANDLES AUTHENTICATION, REQUEST SERIALIZATION, AND ERROR PARSING AUTOMATICALLY.
INSTALL
$ npm install @tipchain/apiUSAGE EXAMPLE:
import { TipChainAPI } from "@tipchain/api";
// Initialize the API client
const api = new TipChainAPI("https://api.tipchain.dev/v1", {
apiKey: "your_api_key",
});
// List all creators
const { creators } = await api.creators.list({ sort: "earnings" });
// Get a specific creator
const creator = await api.creators.get("username");
// Create a creator profile
const newCreator = await api.creators.create({
walletAddress: "9xJ4mM3zK9L2pR7vW5qT8nB1cF6dX2yH0aG3sE4r",
username: "rahul",
bio: "Full-stack developer & Solana enthusiast",
});
// List transactions
const { transactions } = await api.transactions.list(walletAddress);
// Create a transaction record
const tx = await api.transactions.create({
senderWallet: "...",
receiverWallet: "...",
amount: 1.0,
token: "SOL",
txHash: "5KtPn1...",
message: "Great work!",
});
// Get analytics
const { overview } = await api.analytics.overview(walletAddress);
const { revenue } = await api.analytics.revenue(walletAddress, 30);THE @tipchain/api CLIENT IS FULLY TYPED WITH COMPLETE TypeScript DEFINITIONS FOR ALL REQUEST AND RESPONSE TYPES. USE IT AS A LIGHTER ALTERNATIVE TO THE FULL SDK WHEN YOU ONLY NEED REST API ACCESS.
ENDPOINTS
CREATORS
(6 routes)/creatorspublic/creators/search?q=&category=&sort=&limit=&offset=public/creator/:walletpublic/creator/by-username/:usernamepublic/creator/creator/:walletTRANSACTIONS
(3 routes)/transactionspublic/transactions/:wallet?limit=public/transactionANALYTICS
(5 routes)/analytics/:wallet/overview/analytics/:wallet/revenue?days=/analytics/:wallet/tips/analytics/:wallet/growth/analytics/:wallet/export?days=LEADERBOARD
(1 routes)/leaderboard?limit=publicBADGES
(3 routes)/badgespublic/badges/supporter/:walletpublic/badges/awardMEMBERSHIPS
(6 routes)/memberships/:walletpublic/memberships/memberships/:id/memberships/:id/memberships/subscribe/memberships/my/:walletSOCIAL
(9 routes)/follow/follow/:follower/:creator/follow/:wallet/followerspublic/follow/:wallet/followingpublic/comments/comments/:walletpublic/updates/updates/:walletpublic/feed/:walletNOTIFICATIONS
(3 routes)/notifications/:wallet/notifications/:id/read/notifications/read-all/:walletREFERRALS
(3 routes)/referrals/:wallet/referrals/referrals/code/:codepublicADMIN
(6 routes)/admin/analytics/admin/creators/admin/users/admin/creators/:wallet/verify/admin/creators/:wallet/feature/admin/healthpublicCATEGORIES
(5 routes)/categoriespublic/creators/trendingpublic/creators/featuredpublic/creators/recentpublic/creators/recommendedpublicCURL EXAMPLES
LIST CREATORS
curl -X GET "https://api.tipchain.dev/v1/creators"
GET CREATOR
curl -X GET "https://api.tipchain.dev/v1/creator/by-username/rahul"
CREATE CREATOR
curl -X POST "https://api.tipchain.dev/v1/creator" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer tc_your_api_key" \
-d '{
"walletAddress": "9xJ4mM3z...",
"username": "rahul",
"bio": "Full-stack developer"
}'RECORD TX
curl -X POST "https://api.tipchain.dev/v1/transaction" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer tc_your_api_key" \
-d '{
"senderWallet": "9xJ4mM3z...",
"receiverWallet": "8yK2nN4a...",
"amount": 1.5,
"token": "SOL",
"message": "Thanks!"
}'GET ANALYTICS
curl -X GET "https://api.tipchain.dev/v1/analytics/9xJ4mM3z.../overview" \ -H "Authorization: Bearer tc_your_api_key"
RESPONSE FORMAT
Standard Response
// Successful response
{
"success": true,
"data": { ... },
"timestamp": "2025-01-15T10:30:00Z"
}
// List response (paginated)
{
"success": true,
"data": [ ... ],
"timestamp": "2025-01-15T10:30:00Z"
}Error Response
// Error response
{
"success": false,
"error": "Creator not found",
"code": "NOT_FOUND",
"timestamp": "2025-01-15T10:30:00Z"
}
// Validation error
{
"success": false,
"error": "Validation failed",
"code": "BAD_REQUEST",
"details": {
"username": "Username already taken"
}
}ERROR CODES
ALL API ERRORS RETURN A STANDARD JSON RESPONSE WITH AN HTTP STATUS CODE, MACHINE-READABLE ERROR CODE, AND HUMAN-READABLE DESCRIPTION.
WEBHOOKS
TIPCHAIN SUPPORTS OUTGOING WEBHOOKS FOR REAL-TIME EVENT NOTIFICATIONS. CONFIGURE WEBHOOK URLs IN THE DASHBOARD TO RECEIVE POST REQUESTS WHEN SPECIFIC EVENTS OCCUR.
Supported Events
tip.receivedA tip was sent to a creator
creator.createdA new creator profile was created
membership.activatedA user subscribed to a membership tier
badge.awardedA badge was awarded to a supporter
Payload Format
{
"event": "tip.received",
"data": {
"id": "tx_abc123",
"senderWallet": "...",
"receiverWallet": "...",
"amount": "0.5",
"token": "SOL",
"message": "Great work!",
"timestamp": "2025-01-15T10:30:00Z"
},
"timestamp": "2025-01-15T10:30:00Z"
}Plugin System
Webhooks are the foundation of the TipChain plugin architecture. Plugins can hook into any event to extend platform functionality — from NFT badge minting to Discord notifications.
FURTHER READING
[ ARCHITECTURE ]
System architecture — backend, database, plugins, and Solana integration.
ARCHITECTURE >>