POST /sdk/init — Initialize an SDK Embed Session

Call this endpoint from your server before rendering a tipping widget. It authenticates your API key against a specific creator, validates that the embedding origin is on your whitelist, and returns a short-lived session token plus a ready-to-use embedUrl for the checkout iframe.

Call /sdk/init from your server, not from client-side JavaScript. Your API key must never be exposed in the browser.

Endpoint

POST https://tipstack.fun/api/sdk/init

Authentication

Pass your API key as a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Request Body

string

required

The creator’s wallet address, SNS handle (e.g. alice.sol), or Tip Stack user ID. The API resolves all three formats automatically.

string

required

The full origin of the site embedding the widget — for example, https://myblog.com. This value is checked against the list of domains you have whitelisted in your creator dashboard. localhost and 127.0.0.1 origins are allowed automatically for local development.

string

default:"dark"

Visual theme for the rendered iframe. Accepted values: dark or light.

Response

boolean

true when the session was created successfully.

string

A short-lived session token in the format sdk_sess_<uuid>. Pass this as the Bearer token on subsequent calls to POST /sdk/tip.

object

Show config fields

string

The creator’s internal UUID — use this value as creatorId in /sdk/tip and /sdk/events requests.

string

A masked representation of the creator’s Solana wallet address (e.g. Ab3D...). Suitable for display; do not use for on-chain operations.

array

List of token symbols the creator accepts. Always ["SOL", "USDC"] for the current platform version.

string

The fully-constructed iframe URL for the tipping checkout, including the requested theme. Render this URL inside an <iframe> in your frontend.

Origin Security

When you call /sdk/init, the server checks the originUrl you provide against the whitelisted domains stored in your creator account. If the origin is not found, the request is rejected with 403 Unauthorized Origin. Add domains in your Creator Dashboard → Embed Settings → Allowed Origins.

During development, localhost and 127.0.0.1 are always allowed regardless of your whitelist, so you can prototype locally without any configuration changes.

The checkout widget is served with clickjacking protections scoped to your whitelisted originUrl, so only your approved domains can frame it.

Example

Request

curl -X POST https://tipstack.fun/api/sdk/init \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "creatorId": "alice.sol",
    "originUrl": "https://myblog.com",
    "theme": "dark"
  }'

Response

{
  "success": true,
  "sessionToken": "sdk_sess_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "config": {
    "creatorId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "creatorAddress": "Ab3D...",
    "acceptedTokens": ["SOL", "USDC"],
    "embedUrl": "https://tipstack.fun/checkout/f47ac10b-58cc-4372-a567-0e02b2c3d479?theme=dark"
  }
}

Error Responses

Status	Error	Cause
`400 Bad Request`	`"creatorId and originUrl are required"`	One or both required body fields are missing.
`401 Unauthorized`	`"Missing or invalid API key"`	The `Authorization` header is absent or malformed.
`403 Forbidden`	`"Unauthorized Origin"`	`originUrl` is not on your creator whitelist.
`404 Not Found`	`"Creator not found"`	No creator matches the provided `creatorId`.
`500 Server Error`	`"Failed to initialize SDK session"`	An unexpected server error occurred.

Overview

Payments

Tips

SDK

Payouts

POST /sdk/init — Initialize an SDK Embed Session

Endpoint

Authentication

Request Body

Response

Origin Security

Example

Request

Response

Error Responses

​Endpoint

​Authentication

​Request Body

​Response

​Origin Security

​Example

​Request

​Response

​Error Responses

Endpoint

Authentication

Request Body

Response

Origin Security

Example

Request

Response

Error Responses