> ## 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/tip — Initiate a Tip from an SDK Session

> Initiate a tipping flow within an active SDK session. Returns a payment intent ID to track the transaction status.

Use this endpoint after a successful [`POST /sdk/init`](/api/sdk/init) call to register a tip intent on behalf of a supporter. The response gives you an `intentId` you can use to track the transaction, while the actual payment is completed by the supporter inside the `embedUrl` iframe.

## Endpoint

```
POST https://tipstack.fun/api/sdk/tip
```

## Authentication

Pass the `sessionToken` returned by `/sdk/init` as a Bearer token. Session tokens always begin with `sdk_sess_`.

```
Authorization: Bearer sdk_sess_<uuid>
```

<Info>
  Session tokens are scoped to a single creator and origin. Do not share tokens across multiple creator embeds or reuse them after the session expires.
</Info>

## Request Body

<ParamField body="creatorId" type="string" required>
  The creator's UUID as returned in `config.creatorId` from the `/sdk/init` response.
</ParamField>

<ParamField body="amount" type="number" required>
  The tip amount in USD. Must be a positive number greater than zero.
</ParamField>

<ParamField body="inputTokenMint" type="string" required>
  The Solana mint address for the token the supporter is paying with. For SOL use the native mint (`So11111111111111111111111111111111111111112`); for USDC use `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`.
</ParamField>

<ParamField body="sourceWalletAddress" type="string" required>
  The supporter's Solana wallet address. This address is recorded with the tip event and displayed to the creator.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` when the tip intent was registered successfully.
</ResponseField>

<ResponseField name="intentId" type="string">
  A unique payment intent ID in the format `pi_<hex>`. Store this value to reconcile the tip against events returned by [`GET /sdk/events`](/api/sdk/events).
</ResponseField>

<ResponseField name="status" type="string">
  Always `"requires_action"` on success. This means the intent has been created but the supporter must still complete the on-chain transaction inside the checkout iframe.
</ResponseField>

## Completing the Payment

After you receive `"status": "requires_action"`, render the `embedUrl` from your `/sdk/init` response inside an `<iframe>`. The supporter connects their wallet and approves the Solana transaction directly inside the iframe — no further server-side calls are needed to execute the payment.

```javascript theme={null}
// After calling /sdk/tip, embed the checkout
const iframe = document.createElement('iframe');
iframe.src = sdkInitResponse.config.embedUrl;
iframe.width = '400';
iframe.height = '600';
document.getElementById('tip-container').appendChild(iframe);
```

Once the transaction is confirmed on-chain, the tip will appear in [`GET /sdk/events`](/api/sdk/events) with `type: "tip_completed"`.

## Example

### Request

```bash theme={null}
curl -X POST https://tipstack.fun/api/sdk/tip \
  -H "Authorization: Bearer sdk_sess_a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "creatorId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "amount": 5.00,
    "inputTokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "sourceWalletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "intentId": "pi_a1b2c3d4e5f67890abcdef1234567890",
  "status": "requires_action"
}
```

## Error Responses

| Status             | Error                                                                       | Cause                                                                  |
| ------------------ | --------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `400 Bad Request`  | `"amount, inputTokenMint, sourceWalletAddress, and creatorId are required"` | One or more required body fields are missing.                          |
| `401 Unauthorized` | `"Missing or invalid SDK session token"`                                    | The `Authorization` header is absent or not a valid `sdk_sess_` token. |
| `500 Server Error` | `"Failed to initiate tip flow"`                                             | An unexpected server error occurred.                                   |