# OnlyFans Ruby SDK

> An idiomatic Ruby client for the OnlyFans API with rich type support, clear errors, and dependable networking — so your integration stays simple as it grows.

- Requires Ruby 3.2.0+
- Source: https://github.com/onlyfansapi/onlyfansapi-ruby
- Gem: `onlyfans` on RubyGems

## Install

```bash
bundle add onlyfans --version "~> 0.2.0"
```

## Quick start

```ruby
require "bundler/setup"
require "onlyfans"

only_fans_api = Onlyfans::Client.new(api_key: ENV["ONLYFANSAPI_API_KEY"])

# GET /api/{account}/chats
chats = only_fans_api.chats.list("acct_XXXXXXXXXXXXX", limit: "20", order: :recent)

chats.data.each do |chat|
  puts("#{chat.fan.display_name}: #{chat.unread_messages_count} unread")
end

puts("Next page: #{chats._pagination&.next_page}")
```

Send a message with media:

```ruby
require "bundler/setup"
require "onlyfans"

only_fans_api = Onlyfans::Client.new(api_key: ENV["ONLYFANSAPI_API_KEY"])

# POST /api/{account}/chats/{chat_id}/messages
message = only_fans_api.chats.messages.send_(
  "123456789",
  account: "acct_XXXXXXXXXXXXX",
  text: "Hey! Thanks for subscribing!",
  media_files: ["ofapi_media_XXXXXXXXXXXXX"],
  price: 0
)

puts("Message sent ##{message.data.id}")
```

Other examples on the page: link stats, link spenders, chat messages (newest first, `is_sent_by_me` flag), and media downloads (`only_fans_api.media.download(cdn_url, account: ...)` — cached files 302-redirect to cdn.fansapi.com and the client follows the redirect).

## Features

- **Ruby-native API** — Readable method calls and objects that fit naturally into Ruby applications.
- **Yard + RBS + RBI / Sorbet** — Discover classes and methods through comprehensive inline documentation.
- **Connection pooling** — Reuse net/http connections efficiently through `connection_pool`.
- **Automatic retries** — Recover from temporary connection, rate-limit, and server failures.
- **Configurable timeouts** — Set client-wide defaults and override behavior for individual calls.
- **Structured errors** — Handle authentication, validation, rate-limit, and server errors separately.
- **Raw responses** — Access headers and underlying response information when you need it.
- **Environment authentication** — Keep credentials out of source control using an environment variable.
- **Custom requests** — Reach additional endpoints without abandoning the SDK client.

## 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 `api_key` when creating the client. Environment-based configuration keeps credentials out of source control.

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

Yes. The gem ships comprehensive Yard docs plus RBS and RBI type definitions, with Sorbet support. Ruby 3.2.0+.

### What happens when a request fails?

A subclass of `Onlyfans::Errors::APIError` is raised — `AuthenticationError`, `RateLimitError`, `APIConnectionError`, and more. Connection errors, timeouts, 429s, and 5xx responses are retried twice automatically with exponential backoff (configurable via `max_retries`).

### Can I upload files?

Yes. Pass raw contents, a `Pathname`, a `StringIO`, or an `Onlyfans::FilePart` to control filename and content type.

### 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-ruby
- API reference: https://docs.onlyfansapi.com/api-reference/overview
- All SDKs: https://onlyfansapi.com/sdk