Skip to main content
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

​
creatorId
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.
​
originUrl
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.
​
theme
string
default:"dark"
Visual theme for the rendered iframe. Accepted values: dark or light.

​
Response

​
success
boolean
true when the session was created successfully.
​
sessionToken
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.
​
config
object

​
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

StatusErrorCause
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.