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

# GET /sdk/events — Fetch Verified SDK Tip Events

> Retrieve the 50 most recent confirmed tip events for a creator via your SDK API key. Filter by timestamp for incremental polling.

Poll this endpoint to receive a stream of confirmed tip events for a creator. The response includes on-chain details for each tip — token symbol, amount, sender wallet, and Solana transaction signature — so you can trigger rewards, update dashboards, or fan out notifications without subscribing to a WebSocket.

<Note>
  Only tips with status `"confirmed"` are returned. Tips pending on-chain confirmation will not appear.
</Note>

## Endpoint

```
GET https://tipstack.fun/api/sdk/events
```

## Authentication

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

```
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

<ParamField query="creatorId" type="string" required>
  The creator's UUID (as returned in `config.creatorId` from `/sdk/init`). The endpoint returns only tips belonging to this creator.
</ParamField>

<ParamField query="since" type="string">
  An ISO 8601 datetime string (e.g. `2024-06-01T12:00:00.000Z`). When provided, only tips with a `timestamp` strictly after this value are returned. Use this to implement incremental polling without re-processing old events.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` when the request completed successfully.
</ResponseField>

<ResponseField name="events" type="array">
  An array of up to 50 tip event objects, ordered by `timestamp` descending (most recent first).

  <Expandable title="Event object fields">
    <ResponseField name="eventId" type="string">
      The Solana transaction signature for this tip. Identical to `txSignature` — use either as a stable, unique identifier.
    </ResponseField>

    <ResponseField name="type" type="string">
      Always `"tip_completed"` for confirmed on-chain tips.
    </ResponseField>

    <ResponseField name="amountUsdc" type="number">
      The tip amount denominated in USDC. This field is populated only when `tokenSymbol` is `"USDC"`; otherwise it is `0`.
    </ResponseField>

    <ResponseField name="amountRaw" type="number">
      The raw tip amount in the token's native units. Use this field when `tokenSymbol` is `"SOL"` or any non-USDC token.
    </ResponseField>

    <ResponseField name="tokenSymbol" type="string">
      The token used for the tip — for example, `"SOL"` or `"USDC"`.
    </ResponseField>

    <ResponseField name="sender" type="string">
      The supporter's Solana wallet address.
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 datetime string indicating when the tip was confirmed on-chain.
    </ResponseField>

    <ResponseField name="txSignature" type="string">
      The Solana transaction signature. You can look this up on [Solscan](https://solscan.io) or [Explorer](https://explorer.solana.com) to verify the transaction independently.
    </ResponseField>
  </Expandable>
</ResponseField>

## Polling Pattern

For lightweight integrations, poll this endpoint at a regular interval — typically every 30–60 seconds. Pass the `timestamp` of the most recently processed event back as the `since` parameter to receive only new tips on each call.

```javascript Poll events example theme={null}
const lastSeen = new Date(Date.now() - 60_000).toISOString();
const res = await fetch(
  `https://tipstack.fun/api/sdk/events?creatorId=YOUR_CREATOR_ID&since=${lastSeen}`,
  { headers: { Authorization: 'Bearer YOUR_API_KEY' } }
);
const { events } = await res.json();
```

<Tip>
  Store the `timestamp` of the last event you successfully processed in persistent storage (e.g. a database or Redis key). On restart, resume polling from that value to avoid replaying old events or missing any tips that arrived while your service was down.
</Tip>

## Example

### Request

```bash theme={null}
curl "https://tipstack.fun/api/sdk/events\
?creatorId=f47ac10b-58cc-4372-a567-0e02b2c3d479\
&since=2024-06-01T12:00:00.000Z" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json theme={null}
{
  "success": true,
  "events": [
    {
      "eventId": "5KtGhJ2mNpQrVwXyZabc1234defg5678hijkLMNO9012pqrs",
      "type": "tip_completed",
      "amountUsdc": 5.00,
      "amountRaw": 5.00,
      "tokenSymbol": "USDC",
      "sender": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "timestamp": "2024-06-01T13:42:07.000Z",
      "txSignature": "5KtGhJ2mNpQrVwXyZabc1234defg5678hijkLMNO9012pqrs"
    },
    {
      "eventId": "3AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcdefghij",
      "type": "tip_completed",
      "amountUsdc": 0,
      "amountRaw": 0.25,
      "tokenSymbol": "SOL",
      "sender": "9aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890abcdefghij",
      "timestamp": "2024-06-01T12:18:33.000Z",
      "txSignature": "3AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcdefghij"
    }
  ]
}
```

## Error Responses

| Status             | Error                               | Cause                                              |
| ------------------ | ----------------------------------- | -------------------------------------------------- |
| `400 Bad Request`  | `"creatorId is required"`           | The `creatorId` query parameter is missing.        |
| `401 Unauthorized` | `"Missing or invalid API key"`      | The `Authorization` header is absent or malformed. |
| `500 Server Error` | `"Failed to fetch verified events"` | An unexpected server error occurred.               |