# OnlyFans TypeScript SDK

> A modern, fully typed SDK for server-side JavaScript and TypeScript. Get editor autocomplete, predictable errors, and simple access to every OnlyFans API endpoint.

- Runs on Node.js, Deno, and Bun; TypeScript 4.5+ (bundled declarations)
- Source: https://github.com/onlyfansapi/onlyfansapi-typescript-sdk
- Package: `@onlyfansapi/onlyfans-sdk` on npm

## Install

```bash
npm install @onlyfansapi/onlyfans-sdk
```

## Quick start

```ts
import OnlyFansAPI from '@onlyfansapi/onlyfans-sdk';

const client = new OnlyFansAPI(); // reads ONLYFANSAPI_API_KEY

// GET /api/{account}/chats
const { data: chats, _pagination } = await client.chats.list('acct_XXXXXXXXXXXXX', {
  filter: 'unread',
  order: 'recent',
  limit: '25',
});

for (const chat of chats ?? []) {
  console.log(`@${chat.fan?.username} (${chat.unreadMessagesCount} unread): ${chat.lastMessage?.text}`);
}
console.log(_pagination?.next_page);
```

Send a message with media:

```ts
import OnlyFansAPI from '@onlyfansapi/onlyfans-sdk';

const client = new OnlyFansAPI();

// POST /api/{account}/chats/{chat_id}/messages
const { data: message } = await client.chats.messages.send('987654321', {
  account: 'acct_XXXXXXXXXXXXX',
  text: 'Hey! Thanks for subscribing 💜',
  mediaFiles: ['ofapi_media_XXXXXXXXXXXXX'],
  price: 9.99,
});

console.log(`Message sent #${message?.id}`);
```

Other examples on the page: link stats, link spenders, chat messages (newest first), and raw media downloads via `client.media.download(encodeURIComponent(cdnUrl), { account }).asResponse()`.

## Features

- **Fully typed** — TypeScript definitions for every request and response, with docs on hover in your editor.
- **Automatic retries** — Failed requests retry twice with exponential backoff, including rate limits and timeouts.
- **Flexible uploads** — Pass a web `File`, a `fetch` `Response`, an `fs.ReadStream`, or use the `toFile` helper.

## Built for real products

Use one consistent client across dashboards, internal operations, and automated workflows: analytics dashboards, media workflows, internal automation, multi-account tools, reporting pipelines, and custom integrations.

## FAQ

### How do I authenticate?

Set the `ONLYFANSAPI_API_KEY` environment variable or pass `apiKey` when creating the client. Environment-based configuration keeps credentials out of source control.

### Does the SDK include request and response types?

Yes. Every request parameter and response field is fully typed. The package ships with bundled TypeScript declarations and works with TypeScript 4.5+.

### What happens when a request fails?

A subclass of `OnlyFansAPI.APIError` is thrown — `APIConnectionError`, `RateLimitError`, `APIStatusError` with `status` and `response`. Connection errors, timeouts, 429s, and 5xx responses are retried twice automatically with exponential backoff (configurable via `maxRetries`).

### Can I upload files?

Yes. Pass a `Buffer`, a readable stream, or a `Blob`. The client handles multipart encoding automatically.

### Can I call an endpoint that is not documented yet?

Yes. Use the client's custom-request support to hit undocumented endpoints and parameters while keeping authentication and retries.

## Links

- Get your API key: https://app.onlyfansapi.com/register
- Source on GitHub: https://github.com/onlyfansapi/onlyfansapi-typescript-sdk
- API reference: https://docs.onlyfansapi.com/api-reference/overview
- All SDKs: https://onlyfansapi.com/sdk