Skip to content
Fans API logo, maker of the OnlyFans API SDK for TypeScript, Python, PHP and Ruby

Fans API · APIs and developer tools

OnlyFans API SDKs for TS, Python, PHP and Ruby

TL;DR

  • Fans API publishes a free, open source OnlyFans API SDK for TypeScript, Python, PHP and Ruby, each wrapping its REST API of more than 320 endpoints in a typed client.
  • Each SDK reads your key from an environment variable, retries failed requests twice with backoff, and raises a typed error per failure.
  • Skip them if your backend runs Go, Java or C#, or if you wanted to call the service from browser code.
Price
Free with Fans API
Product
Fans API
Platforms
Node.js 20+, Bun and Deno; Python 3.9+; PHP 8.1+; Ruby 3.2+
Free trial
The SDKs are free; calls use credits from a Fans API plan, including the Free plan

What the Fans API SDKs are

The Fans API SDKs are four free client libraries, for TypeScript, Python, PHP and Ruby, that let your code call Fans API without writing raw HTTP requests. Each OnlyFans API SDK wraps the same REST API, which has more than 320 endpoints for accounts, chats, fans, media, posts, tracking links, payouts and data exports. You install one package, set your key, and call methods like client.accounts.list().

Each library follows the habits of its language. TypeScript gets full types and runs on Node.js, Bun and Deno. Python gets a sync client and an async client. PHP gets named arguments and value objects, and Ruby gets a thread-safe client with RBS and RBI types. The SDKs belong to our OnlyFans developer tools category, next to the API for OnlyFans they call.

Key features of each OnlyFans API SDK

All four packages share the same core behavior, so code written in one language translates cleanly to another. Here is what you get and why it saves time.

Four languages, one set of resources

The table below lists each package, where it is installed from, and what it needs to run. Every package is open source under Apache 2.0, with its code public on GitHub under the onlyfansapi organization.

Language Package Install from Runs on
TypeScript @onlyfansapi/onlyfans-sdk npm Node.js 20+, Bun, Deno
Python onlyfans (import onlyfansapi) PyPI Python 3.9+, sync or async
PHP onlyfansapi/onlyfansapi-php Packagist PHP 8.1+ with a PSR-18 client
Ruby onlyfans RubyGems Ruby 3.2+

Two details catch people out. The Python package installs as onlyfans but imports as onlyfansapi. The PHP package doesn’t bundle an HTTP client, so add Guzzle or another PSR-18 client if your project has none.

Key from the environment

Each client reads your key from the ONLYFANSAPI_API_KEY environment variable, or you can pass it to the constructor. That keeps the key out of source control and lets the same code run locally and in production with different keys.

Retries and typed errors

Connection errors, timeouts, 429s and 5xx responses are retried twice with exponential backoff before your code sees them. If a request still fails, you get a separate error class for authentication, validation, rate-limit, connection and server problems. You can catch the cases you can act on and log the rest.

Many accounts from one client

One key reaches every creator account connected to your team. You pass the account ID on each call, so a single client can power an agency dashboard, a nightly report or a job that loops over many creators. List endpoints return pages, and you keep loading while hasMore is true.

Uploads and custom requests

Every SDK uploads media from file paths, streams or raw contents in the form its language expects. For endpoints the typed client doesn’t cover yet, custom requests keep the same authentication and retries. If you need events pushed to you instead of polling, pair the SDK with OnlyFans webhooks.

OnlyFans API SDK code sample

This install line and first call come from the TypeScript SDK docs. The package is published on npm as @onlyfansapi/onlyfans-sdk, and pnpm, yarn and bun work with the same name.

npm install @onlyfansapi/onlyfans-sdk
import OnlyFansAPI from "@onlyfansapi/onlyfans-sdk";

// Reads ONLYFANSAPI_API_KEY from the environment
const client = new OnlyFansAPI();

// GET /api/accounts: every OnlyFans account connected to your API key
const accounts = await client.accounts.list();

for (const account of accounts) {
  console.log(`${account.id} · @${account.onlyfans_username}`);
}

The call lists every creator account your key can reach, with its ID and username. The Python, PHP and Ruby versions of the same call look almost identical: create a client, call accounts.list, and loop over the results. Node.js doesn’t load .env files by itself, so run node --env-file=.env on Node 22.18 or later, while Next.js and Bun load the file for you.

Are the SDKs safe to use?

The SDKs are thin, readable clients, and the main risk is where you put your key. All four are open source, so your team can review the code before it runs. The TypeScript package has no dependencies, which leaves less third-party code in your build.

Keep every call on a server. A key in browser code is visible to anyone who opens the page, and it reaches every account connected to your team. When you receive webhooks, verify the HMAC signature against the raw request body, as the TypeScript docs show for Next.js, Express and Hono. OnlyFans doesn’t offer a public developer API, and Fans API is an independent service, so the accounts you reach are the ones connected to Fans API. We know of no independent security audit of the SDKs. If you want to see how creators connect their accounts inside your own app, read about the OF Auth npm package.

Pricing

The SDKs are free to install, and you pay only for the API calls they make. Those calls run on your Fans API plan. The Free plan includes 100 welcome credits, paid plans cost $69 and $299 a month, and Enterprise is priced on request. See Fans API pricing for what each plan includes.

Every response reports what it cost in a _meta field, along with your remaining credits and whether the answer came from cache. Cached responses cost 0 credits. That makes it easy to log spending per job, so you can see which script uses the most credits before your bill grows.

Who it’s for, and who should skip it

The SDKs are for developers building their own tools on Fans API in TypeScript, Python, PHP or Ruby. They suit agency teams writing dashboards, reporting jobs, CRM imports or internal automation, and SaaS builders who want typed responses instead of guessing at JSON. They help most once you call more than a handful of endpoints, because the retries, errors and pagination are already handled.

Skip them if your backend runs Go, Java, C# or another language without a package, and call the REST API directly instead. Skip them as well if you want the work done without code. The OnlyFans data export tool produces CSV and Excel files from the dashboard. And if you were hoping to call the service from a browser or a mobile app, you still need a server in between to hold the key.

Pros and cons

Pros

  • One package per language, installed from npm, PyPI, Packagist or RubyGems
  • Typed requests and responses in all four languages, from TypeScript types to Ruby RBS and RBI files
  • Automatic retries for timeouts, connection errors, 429s and 5xx responses
  • One client and one key reach every creator account connected to your team
  • Open source under Apache 2.0, so you can read the code that runs in your app

Cons

  • Only four languages; Go, Java, C# and other stacks have to call the REST API directly
  • Server-side only, because putting your API key in browser code exposes it
  • The Ruby gem is still on a 0.2 version line, so expect changes before a 1.0 release
  • The SDKs are free, but every call still spends credits from your Fans API plan

Frequently Asked Questions

Short answers to the questions agencies ask most.

Which OnlyFans API SDK should I use?

Pick the SDK that matches your backend language. All four call the same API with the same resources, so nothing is gained by switching stacks. TypeScript fits Node.js, Bun and Deno projects, including Next.js and Express. Python fits Django, Flask and FastAPI. PHP fits Laravel. Ruby fits Rails and Sidekiq jobs. If your team runs several services in different languages, each one can use its own SDK with the same API key.

Do the Fans API SDKs cost anything?

No. The packages are open source under the Apache 2.0 license and free to install. What costs money is the work they do. Every request runs on your Fans API plan and spends credits from it. The Free plan includes 100 welcome credits, so you can install a package and make your first calls before you choose a paid plan at $69 or $299 a month.

Is there a separate JavaScript SDK?

No. The TypeScript package is also the JavaScript SDK. It ships compiled JavaScript for both ES modules and CommonJS, plus the type definitions, so a plain Node.js project can use it without TypeScript. It has no dependencies, because it uses the fetch function built into Node.js 20 and later, Bun and Deno. There is no separate types package to install.

Can I call an SDK from the browser?

Not with your API key. Any code that runs in a browser exposes the key to whoever opens the page, and that key can reach every account on your team. Call the SDK from server code instead, such as a route handler, a background job or your own API server, and send the frontend only the data it needs. In Next.js, the TypeScript docs suggest importing server-only to enforce this.

What happens when a request fails?

Each SDK raises a typed error you can catch, with separate classes for authentication, validation, rate-limit, connection and server errors. In TypeScript, they all extend APIError, which carries the status, headers and parsed error body. Before that happens, connection errors, timeouts, 429s and 5xx responses are retried twice with exponential backoff, so short outages often never reach your code.

Can the SDKs call an endpoint they don't cover yet?

Yes. Every SDK supports custom requests to endpoints and parameters that the typed client doesn't include yet, and those requests keep the same authentication and retries. That matters when Fans API ships a new endpoint before the next SDK release. You can use it on the day it appears, then switch to the typed method once the package catches up.

Verdict

The SDKs are the fastest way to build on Fans API if your backend runs TypeScript, Python, PHP or Ruby. They save you from writing your own HTTP client, retry logic and response types, and they cost nothing beyond the credits your calls already use. They don't add features the API lacks, and they only run on a server. If your stack is Go or Java, call the REST API yourself.

Best for: Developers who want typed TypeScript, Python, PHP or Ruby clients

Fans API logo

SDKs

Free with Fans API

Visit Site