> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tipstack.fun/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /sdk/init — Initialize an SDK Embed Session

> Initialize a Tip Stack SDK session for an embedded widget. Returns a session token and iframe URL for rendering the checkout inside your application.

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.

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

## 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

<ParamField body="creatorId" type="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.
</ParamField>

<ParamField body="originUrl" type="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.
</ParamField>

<ParamField body="theme" type="string" default="dark">
  Visual theme for the rendered iframe. Accepted values: `dark` or `light`.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` when the session was created successfully.
</ResponseField>

<ResponseField name="sessionToken" type="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`](/api/sdk/tip).
</ResponseField>

<ResponseField name="config" type="object">
  <Expandable title="config fields">
    <ResponseField name="config.creatorId" type="string">
      The creator's internal UUID — use this value as `creatorId` in `/sdk/tip` and `/sdk/events` requests.
    </ResponseField>

    <ResponseField name="config.creatorAddress" type="string">
      A masked representation of the creator's Solana wallet address (e.g. `Ab3D...`). Suitable for display; do not use for on-chain operations.
    </ResponseField>

    <ResponseField name="config.acceptedTokens" type="array">
      List of token symbols the creator accepts. Always `["SOL", "USDC"]` for the current platform version.
    </ResponseField>

    <ResponseField name="config.embedUrl" type="string">
      The fully-constructed iframe URL for the tipping checkout, including the requested theme. Render this URL inside an `<iframe>` in your frontend.
    </ResponseField>
  </Expandable>
</ResponseField>

## 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**.

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

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

## Example

### Request

```bash theme={null}
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

```json theme={null}
{
  "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.               |