InstaTip API Documentation

Integrate InstaTip into your applications with our powerful REST API and SDKs

Quick Start

1. Get API Key

Generate your API key in the Settings page of your dashboard

2. Make Requests

Use our REST API or official SDKs to integrate InstaTip

3. Go Live

Deploy your integration and start receiving tips

Base URL

https://api.instatip.me

Authentication & Security

API Key Authentication

All API requests require authentication using your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Wallet-Based Access Control

🔒 Critical Security Feature: You can ONLY access data for your own wallet address.

  • •Each API key is permanently linked to a specific Solana wallet address
  • •All API endpoints validate that the requested walletAddress matches your API key's wallet
  • •Attempting to access another user's data returns 403 Forbidden
  • •This prevents unauthorized access to other users' tips, analytics, and profile data

Permission Levels

✅ Allowed Operations

  • • Read your own tip data
  • • View your analytics
  • • Access your profile information
  • • Retrieve your widget configuration

❌ Blocked Operations

  • • Creating or modifying tip data
  • • Admin operations
  • • Accessing other users' data
  • • Account creation/management

Security Error Example

If you try to access data for a wallet address that doesn't match your API key:

HTTP/1.1 403 Forbidden Content-Type: application/json { "error": "Access denied: You can only access your own data" }

API Endpoints

GET/api/tips

🔒 Retrieve tips for YOUR wallet address only (user-scoped access)

Parameters

NameTypeRequiredDescription
walletAddressstringRequired⚠️ MUST be YOUR wallet address (linked to API key)
limitnumberOptionalNumber of tips to return (default: 50, max: 100)
offsetnumberOptionalNumber of tips to skip for pagination

Example Request

curl -X GET "https://api.instatip.me/api/tips?walletAddress=YOUR_WALLET_ADDRESS&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "tips": [
    {
      "id": "tip_123",
      "amount": 0.5,
      "currency": "SOL",
      "message": "Great content!",
      "senderAddress": "sender_wallet_address",
      "signature": "transaction_signature",
      "timestamp": "2024-01-15T10:30:00Z",
      "status": "confirmed"
    }
  ],
  "total": 150,
  "hasMore": true
}
GET/api/analytics

🔒 Get analytics data for YOUR wallet address only

Parameters

NameTypeRequiredDescription
walletAddressstringRequired⚠️ MUST be YOUR wallet address (linked to API key)
timeframestringOptionalTime period in days (default: 30)

Example Request

curl -X GET "https://api.instatip.me/api/analytics?walletAddress=YOUR_WALLET_ADDRESS&timeframe=30" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "totalTips": 42,
  "totalAmount": 12.5,
  "averageTip": 0.297,
  "topTippers": [
    {
      "address": "sender_wallet_1",
      "totalAmount": 2.5,
      "tipCount": 5
    }
  ],
  "dailyStats": [
    {
      "date": "2024-01-15",
      "tips": 3,
      "amount": 1.2
    }
  ]
}
POST/api/tips

❌ DISABLED - Tip creation not allowed via API

Parameters

NameTypeRequiredDescription
N/AN/AOptionalThis endpoint has been disabled for security

Example Request

# This endpoint returns 403 Forbidden
curl -X POST "https://api.instatip.me/api/tips" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"error": "This endpoint is disabled"}'

Response

{
  "error": "Tip creation via API is disabled",
  "message": "Use the web interface or widget to create tips"
}
GET/api/profiles

🔒 Get profile information for YOUR wallet address only

Parameters

NameTypeRequiredDescription
userIdstringRequired⚠️ MUST be YOUR wallet address (linked to API key)

Example Request

curl -X GET "https://api.instatip.me/api/profiles?userId=YOUR_WALLET_ADDRESS" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "userId": "your_wallet_address",
  "displayName": "Your Creator Name",
  "bio": "Your bio text",
  "avatar": "avatar_url",
  "socialLinks": {
    "twitter": "@yourhandle",
    "youtube": "channel_url"
  },
  "settings": {
    "publicProfile": true,
    "showTipHistory": false
  }
}
GET/api/widget-config

🔒 Get widget configuration for YOUR wallet address only

Parameters

NameTypeRequiredDescription
userIdstringRequired⚠️ MUST be YOUR wallet address (linked to API key)

Example Request

curl -X GET "https://api.instatip.me/api/widget-config?userId=YOUR_WALLET_ADDRESS" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "widgetId": "widget_123",
  "theme": "dark",
  "position": "bottom-right",
  "customization": {
    "primaryColor": "#8B5CF6",
    "borderRadius": "12px",
    "showAvatar": true
  },
  "displayRules": {
    "showOnScroll": 50,
    "hideOnMobile": false
  }
}

Official SDKs

// Install: npm install @instatip/sdk
import { InstaTip } from '@instatip/sdk';

const client = new InstaTip({
  apiKey: 'YOUR_API_KEY',
  network: 'mainnet' // or 'devnet'
});

// 🔒 Get YOUR tips only (wallet-scoped access)
const tips = await client.tips.list({
  walletAddress: 'YOUR_WALLET_ADDRESS', // Must match API key
  limit: 10
});

// 🔒 Get YOUR analytics only
const analytics = await client.analytics.get({
  walletAddress: 'YOUR_WALLET_ADDRESS',
  timeframe: 30
});

// 🔒 Get YOUR profile only
const profile = await client.profiles.get({
  userId: 'YOUR_WALLET_ADDRESS'
});

// ❌ Tip creation via API is disabled for security
// Use the web interface or widget instead

Rate Limits

  • • 1000 requests per hour per API key
  • • 10 requests per second burst limit
  • • Rate limit headers included in responses
  • • Contact support for higher limits

Security

  • • All requests over HTTPS (TLS 1.2+)
  • • API keys are encrypted at rest
  • • Webhook signature verification
  • • IP allowlisting available