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

# Tip Stack API Overview: Authentication, Payments, and Tips

> Complete reference for the Tip Stack REST API: base URL, authentication patterns, rate limiting, HTTP status codes, and endpoint groups.

The Tip Stack API is a REST API that gives you programmatic access to every feature on the platform — from registering users and recording on-chain tips to triggering payouts and embedding tipping widgets in your own product. All endpoints live under the base URL below and speak JSON in both directions.

## Base URL

```text theme={null}
https://tipstack.fun/api
```

## Request & Response Format

Every request must set `Content-Type: application/json` when sending a body. Every response is also JSON. Successful responses always include `"success": true`; error responses always include an `"error"` field describing what went wrong.

```json theme={null}
{ "error": "Email already in use" }
```

## Authentication

Tip Stack supports two authentication patterns depending on the endpoint group you are calling:

| Pattern            | Used for                                                                  |
| ------------------ | ------------------------------------------------------------------------- |
| **Session cookie** | User-facing endpoints: dashboard, analytics, payouts, profile             |
| **Bearer API key** | SDK / third-party embed endpoints: `/sdk/init`, `/sdk/tip`, `/sdk/events` |

See the [Authentication guide](/api/authentication) for full details on registering, logging in, and passing credentials.

## Rate Limiting

All endpoints are rate-limited to protect the platform. When you exceed the limit, the API returns `429 Too Many Requests` with a `Retry-After` header telling you how many seconds to wait before retrying.

<Note>
  OTP verification endpoints apply a stricter per-email limit of 5 failed attempts within a 15-minute window to prevent brute-force attacks.
</Note>

## HTTP Status Codes

| Code                    | Meaning                                                                          |
| ----------------------- | -------------------------------------------------------------------------------- |
| `200 OK`                | The request succeeded.                                                           |
| `400 Bad Request`       | The request body is missing required fields or contains invalid values.          |
| `401 Unauthorized`      | No valid session or API key was provided.                                        |
| `403 Forbidden`         | Your credentials are valid, but you lack permission for this resource or origin. |
| `404 Not Found`         | The requested resource does not exist.                                           |
| `409 Conflict`          | The resource already exists (for example, duplicate email on registration).      |
| `429 Too Many Requests` | You have exceeded the rate limit. Check the `Retry-After` header.                |
| `500 Server Error`      | An unexpected error occurred on the server.                                      |

## API Groups

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/api/authentication">
    Register, log in, manage sessions, and authenticate via OTP or API key.
  </Card>

  <Card title="Payments" icon="credit-card" href="/api/payments">
    Create payment intents, manage recurring payments, and handle fiat on-ramps.
  </Card>

  <Card title="Tips" icon="coins" href="/api/tips">
    Read and record on-chain tips, stream live tip events, and send tip messages.
  </Card>

  <Card title="SDK" icon="code" href="/api/sdk">
    Initialize embedded tipping widgets and process tips from third-party origins.
  </Card>
</CardGroup>