Integration steps
Get your API key
Open your creator dashboard and navigate to Settings → Developer → API Keys. Generate a new secret key and store it securely in your server-side environment variables (e.g.
.env.local for Next.js)..env.local
Initialize an SDK session
Call A successful response looks like:The
POST /api/sdk/init from your server (an API route, a Server Component, or a Next.js Route Handler). Pass your API key in the Authorization header along with the creator’s ID and the origin URL of the embedding page.app/api/tipstack/session/route.ts
sessionToken (prefixed sdk_sess_) authorizes all subsequent SDK calls for this page load. The embedUrl is a fully hosted checkout page you can render directly in an <iframe> — see Rendering the hosted checkout below.Trigger a tip
Call The response returns an
POST /api/sdk/tip from the client using the sessionToken returned in the previous step. Supply the tip amount, the token mint address, the sender’s wallet address, and the creator’s ID.intentId and a status of requires_action, indicating the user must sign the transaction in their wallet to complete the tip.Listen for confirmed tip events
Poll Each event in the response array has this shape:Up to 50 confirmed tips are returned per request, ordered newest-first.
GET /api/sdk/events with your API key (server-side) to receive a list of confirmed tip events for a creator. Use the optional since query parameter to fetch only events after a given ISO timestamp.app/api/tipstack/events/route.ts
Full React example
The component below combines all three steps into a self-containedTipButton. The /sdk/init call is proxied through your own Next.js API route so the API key never reaches the browser.
TipButton.tsx
Rendering the hosted checkout
If you prefer a fully managed UI instead of building your own, render theembedUrl from /sdk/init inside an <iframe>. Tip Stack hosts and updates the checkout experience — you just provide the container.
EmbedCheckout.tsx
Listening for tip events in the client
To update your UI in real time when a tip is confirmed, poll your own events proxy on a short interval and compare the latesttimestamp.
useTipEvents.ts
API reference
POST /api/sdk/init
POST /api/sdk/init
Initializes a new SDK session and validates the embedding origin.Headers
Body
Response —
| Header | Value |
|---|---|
Authorization | Bearer YOUR_API_KEY |
Content-Type | application/json |
| Field | Type | Required | Description |
|---|---|---|---|
creatorId | string | Yes | Creator handle, wallet address, or user ID. |
originUrl | string | Yes | Full origin of the embedding site, e.g. https://myblog.com. |
theme | string | No | dark (default) or light. |
200 OK| Field | Description |
|---|---|
sessionToken | Short-lived token (sdk_sess_<uuid>) for subsequent calls. |
config.creatorId | The creator’s UUID. |
config.creatorAddress | The creator’s wallet address, masked (e.g. Ab3C...7xYz). |
config.acceptedTokens | Array of accepted token symbols: ["SOL", "USDC"]. |
config.embedUrl | Hosted checkout URL ready to use in an <iframe>. |
POST /api/sdk/tip
POST /api/sdk/tip
Creates a tip intent within the current SDK session.Headers
Body
Response —
| Header | Value |
|---|---|
Authorization | Bearer sdk_sess_<uuid> (session token from /sdk/init) |
Content-Type | application/json |
| Field | Type | Required | Description |
|---|---|---|---|
creatorId | string | Yes | Creator to tip. |
amount | number | Yes | USD amount of the tip. |
inputTokenMint | string | Yes | SPL token mint address. Use EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v for USDC. |
sourceWalletAddress | string | Yes | Sender’s Solana wallet address. |
200 OK| Field | Description |
|---|---|
intentId | Unique tip intent ID (pi_<uuid>). |
status | Always requires_action — the user must sign in their wallet. |
GET /api/sdk/events
GET /api/sdk/events
Returns confirmed tip events for a creator, newest-first.Headers
Query parameters
Response —
| Header | Value |
|---|---|
Authorization | Bearer YOUR_API_KEY |
| Parameter | Required | Description |
|---|---|---|
creatorId | Yes | The creator’s ID to fetch events for. |
since | No | ISO 8601 timestamp. Only events after this time are returned. |
200 OKReturns up to 50 tip_completed events. Each event includes eventId, type, amountUsdc, amountRaw, tokenSymbol, sender, timestamp, and txSignature.