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

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.

[official ruby sdk]

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.

Browse Docs

Install

$ bundle add onlyfans --version "~> 0.2.0"

/RUBY/POOLING/BUILT-IN RETRIES

https://github.com/onlyfansapi/onlyfansapi-ruby

[code examples]

Link stats, chats, messages, media

Fetch the dashboard summary for a tracking link and print clicks, subscribers, spenders, ARPS, and lifetime revenue.

require "bundler/setup"
require "onlyfans"

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

# GET /api/{account}/tracking-links/{tracking_link_id}/stats
stats = only_fans_api.tracking_links.get_stats("12345678", account: "acct_XXXXXXXXXXXXX")

summary = stats.data.summary
puts("Clicks: #{summary.clicks_total} · Subs: #{summary.subs_total} · Spenders: #{summary.spenders_total}")

arps = summary.subs_total.to_i.zero? ? 0.0 : summary.revenue_total / summary.subs_total
puts(format("ARPS: $%.2f · Lifetime: $%.2f", arps, summary.revenue_total))
# Output:
# Clicks: 1240 · Subs: 300 · Spenders: 42
# ARPS: $12.40 · Lifetime: $3720.00

List the fans who made purchases through a tracking link, together with what each of them has spent.

require "bundler/setup"
require "onlyfans"

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

# GET /api/{account}/tracking-links/{tracking_link_id}/spenders
spenders = only_fans_api.tracking_links.list_spenders(
  "12345678",
  account: "acct_XXXXXXXXXXXXX",
  limit: 50,
  min_spend: 1
)

spenders.data.each do |fan|
  puts("@#{fan.username} (#{fan.onlyfans_id}) spent $#{fan.revenue.total}")
end
# Output:
# @sarah_k (412938471) spent $189.0

Page through an account's chats sorted by most recent activity and read the unread count per fan.

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}")
# Output:
# Sarah: 3 unread
# Next page: https://app.fansapi.com/api/acct_XXXXXXXXXXXXX/chats?limit=20&offset=20

Load the latest messages from a single chat, newest first, and see who sent each one.

require "bundler/setup"
require "onlyfans"

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

# GET /api/{account}/chats/{chat_id}/messages
messages = only_fans_api.chats.messages.list(
  "123456789",
  account: "acct_XXXXXXXXXXXXX",
  limit: "10",
  order: "desc"
)

messages.data.each do |message|
  puts("[#{message.created_at}] #{message.is_sent_by_me ? "me" : "fan"}: #{message.text}")
end
# Output:
# [2026-09-04T18:22:41+00:00] me: Just posted something new for you 💜

Send a text message with optional media attachments and a price to a fan's chat.

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}")
# Output:
# Message sent #6182934517

Download a file from an expiring OnlyFans CDN URL through the API proxy and write the bytes to disk.

require "bundler/setup"
require "onlyfans"

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

# GET /api/{account}/media/download/{cdnUrl}
# Cached files 302-redirect to cdn.fansapi.com; the client follows the redirect.
cdn_url = "https://cdn2.onlyfans.com/files/x/y/z/file.jpg?Expires=..."

file = only_fans_api.media.download(cdn_url, account: "acct_XXXXXXXXXXXXX")

File.binwrite("file.jpg", file)
puts("Saved #{file.bytesize} bytes")
# Output:
# Saved 1834209 bytes

[features]

An SDK that feels at
home in Ruby

Idiomatic objects, flexible IO, and strong tooling support for growing codebases.

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.

[production ready]

The details that matter
after your first request

Resilient networking and predictable behavior are built into the client, so production code stays focused on your product.

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.

[keep exploring]

Everything you need
for the next step

Move from the quick start to complete endpoint details and source code.

Ruby SDK docs
Installation, configuration, examples, and language-specific guidance.
API reference
Explore endpoints, parameters, response schemas, and error details.
Source on GitHub
Review the SDK source, releases, examples, and contribution guide.