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. Request parameters are TypedDicts and responses are Pydantic models, giving you autocomplete and docs in your editor. Python 3.9+.

What happens when a request fails?

A subclass of onlyfansapi.APIError is raised — APIConnectionError, RateLimitError, APIStatusError with status_code and response. Connection errors, timeouts, 429s, and 5xx responses are retried twice automatically with exponential backoff.

Yes. Pass bytes, a PathLike instance, or a (filename, contents, media type) tuple. The async client reads files asynchronously.

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 python sdk]

OnlyFans
Python SDK

A typed, production-ready Python client for the OnlyFans API. Authenticate once, call any endpoint, and ship reliable creator tools with less boilerplate.

Browse Docs

Install

# install from PyPI
pip install onlyfans

/Python 3.9+/Sync & Async Clients/Built-in Retries

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

[code examples]

Link stats, chats, messages, media

Fetch the dashboard summary for a tracking link and derive ARPS and lifetime revenue from the typed totals.

from onlyfansapi import OnlyFansAPI

client = OnlyFansAPI()

stats = client.tracking_links.get_stats(
    "tracking_link_id",
    account="acct_XXXXXXXXXXXXX",
)

summary = stats.data.summary
arps = summary.revenue_total / max(summary.subs_total, 1)
print(f"Clicks: {summary.clicks_total} · Subs: {summary.subs_total}")
print(f"ARPS: ${arps:.2f} · Lifetime: ${summary.revenue_total:.2f}")

# Output:
# Clicks: 1240 · Subs: 300
# ARPS: $12.40 · Lifetime: $3720.00

List the fans who paid through a tracking link, filtered by minimum spend and paginated with limit.

from onlyfansapi import OnlyFansAPI

client = OnlyFansAPI()

spenders = client.tracking_links.list_spenders(
    "tracking_link_id",
    account="acct_XXXXXXXXXXXXX",
    min_spend=10,
    limit=50,
)

for fan in spenders.data:
    print(f"@{fan.username} spent ${fan.revenue.total:.2f}")

# Output:
# @sarah_k spent $189.00

Page through an account's chats with a filter such as unread and read the fan and last message inline.

from onlyfansapi import OnlyFansAPI

client = OnlyFansAPI()

chats = client.chats.list(
    "acct_XXXXXXXXXXXXX",
    filter="unread",
    limit="20",
)

for chat in chats.data:
    unread = chat.unread_messages_count
    print(f"@{chat.fan.username} ({unread} unread): {chat.last_message.text}")

# Output:
# @sarah_k (3 unread): Hey, are you around?

Load the newest messages in a chat and keep the next_page cursor from _pagination for the following request.

from onlyfansapi import OnlyFansAPI

client = OnlyFansAPI()

messages = client.chats.messages.list(
    "chat_id",
    account="acct_XXXXXXXXXXXXX",
    limit="25",
    order="desc",
)

for message in messages.data:
    print(f"[{message.created_at}] {message.text}")

next_page = messages.api_pagination.next_page

# Output:
# [2026-09-04T18:22:41+00:00] Just posted something new for you 💜

Send a text message with attached media to a chat, optionally locking the media behind a price.

from onlyfansapi import OnlyFansAPI

client = OnlyFansAPI()

sent = client.chats.messages.send(
    "chat_id",
    account="acct_XXXXXXXXXXXXX",
    text="Hey! Here is something new for you",
    media_files=["ofapi_media_XXXXXXXXXXXXX"],
    price=10,
)

print(f"Message sent #{sent.data.id}")

# Output:
# Message sent #6182934517

Stream a file from the OnlyFans CDN through the API proxy to disk using the streaming response context manager.

from onlyfansapi import OnlyFansAPI

client = OnlyFansAPI()

cdn_url = "https://cdn2.onlyfans.com/files/.../photo.jpg"

with client.media.with_streaming_response.download(
    cdn_url,
    account="acct_XXXXXXXXXXXXX",
) as response:
    with open("photo.jpg", "wb") as file:
        for chunk in response.iter_bytes():
            file.write(chunk)

# Output:
# photo.jpg written (1.8 MB)

[features]

Made for modern
Python applications

From a quick script to a high-concurrency service, the client scales with you.

Sync and async
Use OnlyFans API for synchronous work or Async OnlyFans API with await.
Typed models
TypedDict requests and Pydantic responses bring autocomplete to every call.
Flexible uploads
Upload bytes, PathLike values, or filename and media-type tuples.

[built for real products]

Turn API access into useful creator tools

Use one consistent client across dashboards, internal operations, and automated workflows.

Analytics Dashboards
Bring account and performance data into reporting experiences your team can act on.
Media Workflows
Build upload flows around familiar file, stream, and byte-based objects.
Internal Automation
Build upload flows around familiar file, stream, and byte-based objects.
Multi-account tools
Create focused interfaces for teams working across multiple connected accounts.
Reporting Pipelines
Move structured API responses into warehouses, spreadsheets, and custom reports.
Custom integrations
Extend the typed client with custom requests when your product needs more flexibility.

[keep exploring]

Everything you need
for the next step

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

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