> ## 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 /solana/tips/create — Record an On-Chain Tip

> Record a confirmed Solana tip transaction in Tip Stack. Call this after the supporter signs and submits the transaction from a payment intent.

After the supporter signs and submits the transaction produced by [`POST /payments/intent`](/api/payments/intent), call this endpoint to record the tip in Tip Stack. The tip is stored immediately with a `pending` status and transitions to `confirmed` once the transaction is verified on-chain. This endpoint is idempotent — submitting the same `txSignature` twice returns the existing record rather than creating a duplicate.

## Request

**`POST https://tipstack.fun/api/solana/tips/create`**

<ParamField body="creatorWallet" type="string" required>
  The creator's Solana wallet address (base58). This must match the `payoutAddress` resolved during the payment intent creation.
</ParamField>

<ParamField body="tipAmount" type="number" required>
  The tip amount in the token's raw base units (lamports for SOL, or the token's smallest denomination for SPL tokens). For example, `100000000` represents 0.1 SOL.
</ParamField>

<ParamField body="senderWallet" type="string" required>
  The supporter's wallet public key (base58). Used to associate the tip with an existing Tip Stack account, if one exists.
</ParamField>

<ParamField body="txSignature" type="string" required>
  The confirmed Solana transaction signature returned by `connection.sendRawTransaction()`. This is the primary identifier for the tip record and is used to prevent duplicate submissions.
</ParamField>

<ParamField body="message" type="string">
  An optional message from the supporter to the creator. Displayed in the creator's dashboard and tip notification stream.
</ParamField>

<ParamField body="tokenSymbol" type="string" default="SOL">
  The symbol of the token sent (e.g. `SOL`, `USDC`, `BONK`). Defaults to `SOL` when omitted. Used to normalize the stored amount: SOL values are divided by `1e9` for display; all other tokens are stored as-is.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` when the tip was recorded (or already existed).
</ResponseField>

<ResponseField name="tip" type="object">
  <Expandable title="tip fields">
    <ResponseField name="tip.id" type="string">
      The transaction signature, used as the unique tip ID.
    </ResponseField>

    <ResponseField name="tip.status" type="string">
      `pending` for newly created tips. `confirmed` once on-chain verification completes. If the tip was already recorded, returns the existing status.
    </ResponseField>

    <ResponseField name="tip.recipientId" type="string">
      The Tip Stack user ID of the creator, if their wallet is associated with a registered account.
    </ResponseField>

    <ResponseField name="tip.amount" type="number">
      The raw amount passed in `tipAmount`.
    </ResponseField>

    <ResponseField name="tip.tokenSymbol" type="string">
      The token symbol associated with the tip.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable status message, e.g. `"Tip recorded successfully"` or `"Tip already recorded"`.
</ResponseField>

## Example request

```json JSON theme={null}
{
  "creatorWallet": "9xRT3m1KZJPHQQaFGpvDJckJcNhHMbDdBfHHVdFGQS7b",
  "tipAmount": 100000000,
  "senderWallet": "8xRT3m1KZJPHQQaFGpvDJckJcNhHMbDdBfHHVdFGQS7a",
  "txSignature": "5UfgJ9H7Kp2mRd8NqWx4vYzA1bEc3sFt6LiOoP7rTkVhXy8wMnCjDuZe0pQaBcI",
  "message": "Keep up the great work!",
  "tokenSymbol": "SOL"
}
```

## Example response — new tip

```json JSON theme={null}
{
  "success": true,
  "tip": {
    "id": "5UfgJ9H7Kp2mRd8NqWx4vYzA1bEc3sFt6LiOoP7rTkVhXy8wMnCjDuZe0pQaBcI",
    "recipientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": 100000000,
    "tokenSymbol": "SOL",
    "status": "pending"
  },
  "message": "Tip recorded successfully"
}
```

## Example response — duplicate submission

```json JSON theme={null}
{
  "success": true,
  "tip": {
    "id": "5UfgJ9H7Kp2mRd8NqWx4vYzA1bEc3sFt6LiOoP7rTkVhXy8wMnCjDuZe0pQaBcI",
    "status": "confirmed"
  },
  "message": "Tip already recorded"
}
```

<Note>
  Tips remain in `pending` status until verified on-chain. This typically takes a few seconds on Solana mainnet.
</Note>

<Warning>
  Always wait for a transaction to land on-chain before calling this endpoint. Submitting an unconfirmed or failed transaction signature will create a `pending` tip record that will never transition to `confirmed`.
</Warning>