<!-- Generated by scripts/gen-docs.ts from @bfl/contract. Do not edit. -->

# Platforms

Every account is on OnlyFans, Fansly or Fanvue. `GET /v1/accounts` gives each account's `platform`, and every response for one account names it in `meta.platform`. Routes, objects, actions, MCP tools and webhook events have the same shapes on every platform. Every read of a Fanvue account is live and counts as a live call. Full guides: https://betterfans.link/docs/fansly and https://betterfans.link/docs/fanvue

## Only on some platforms

Calling one of these for an account on another platform answers `400` `not_supported_on_platform`. Skip it for that account and carry on: the same call fails the same way every time.

### Routes

- Search messages (`GET /v1/accounts/{accountId}/messages/search`): OnlyFans and Fansly only.
- Mass messages (`GET /v1/accounts/{accountId}/mass-messages`): OnlyFans and Fanvue only.
- Call OnlyFans (`GET /v1/accounts/{accountId}/onlyfans/{path}`): OnlyFans only.
- Call Fansly (`GET /v1/accounts/{accountId}/fansly/{path}`): Fansly only.
- Call Fanvue (`GET /v1/accounts/{accountId}/fanvue/{path}`): Fanvue only.

### Action types

- `send_mass_message`: OnlyFans and Fanvue only.
- `add_fan_to_list`: OnlyFans and Fanvue only.
- `remove_fan_from_list`: OnlyFans and Fanvue only.

### MCP tools

- `search_messages`: OnlyFans and Fansly only.
- `mass_message_performance`: OnlyFans and Fanvue only.
- `send_mass_message`: OnlyFans and Fanvue only.
- `label_fan`: OnlyFans and Fanvue only.

### Webhook events

- `message.liked`: OnlyFans only.
- `message.unliked`: OnlyFans only.
- `message.purchased`: OnlyFans and Fanvue only.
- `fan.online`: OnlyFans only.
- `fan.typing`: OnlyFans and Fansly only.
- Every `fanvue.*` event, Fanvue's own notifications passed on: Fanvue only.

## Fields that differ

The shapes match, but some fields carry less on one platform. Read a value this table marks as always 0 or always null as "the platform does not say", never as a real zero. Webhook `data` follows the same rules.

| Resource | Field | OnlyFans | Fansly | Fanvue |
| --- | --- | --- | --- | --- |
| [Account](https://betterfans.link/docs/api/accounts#account) | `status` | Any of the seven statuses. | Never `awaiting_selfie` or `restricted`. | `healthy`, `needs_relink` or `disconnected`. Never `syncing`, `awaiting_2fa`, `awaiting_selfie` or `restricted`: Fanvue signs in on its own page and BetterFans keeps no copy to sync. |
| [Account](https://betterfans.link/docs/api/accounts#account) | `lastSyncedAt` | When BetterFans last synced the account. Reads come from that copy unless `fresh=true`. | When the last sync pass finished. Reads come from that copy unless `fresh=true`. | Always `null`: BetterFans keeps no copy. Each read of the account's data asks Fanvue at that moment (`meta.source` live) and counts as a live call; listing accounts does not ask Fanvue. |
| [Account detail](https://betterfans.link/docs/api/accounts#accountdetail) | `subscriptionPrice` | The subscription price. | The cheapest tier's price. Fansly sells subscriptions in tiers. | The subscription price from Fanvue's account settings. `null` when the creator has set none, or when Fanvue could not give it. |
| [Account detail](https://betterfans.link/docs/api/accounts#accountdetail) | `counts.chats`, `counts.vaultItems` | Counted from the synced copy. | Counted from the synced copy. | Always 0: BetterFans does not count them on Fanvue, whose media list gives no total. While the account needs a relink or is disconnected, every count and revenue30d is 0 and Fanvue is not asked. |
| [Fan](https://betterfans.link/docs/api/fans#fan) | `spend.messages`, `spend.posts` | What the fan paid for messages and for posts. | Always 0. Fansly reports message and post purchases together, so they count in `spend.other`. | What the fan paid for messages and for posts, refunds left out, from Fanvue's own totals for the fan. |
| [Fan](https://betterfans.link/docs/api/fans#fan) | `spend.net` | What the creator kept from the fan's payments. | What the creator kept from the fan's payments. | An estimate: 80 percent of `spend.total`, the usual creator share. Fanvue does not say what the creator kept from one fan. |
| [Fan](https://betterfans.link/docs/api/fans#fan) | `counts.messages` | Messages in the chat, from the synced copy. | Messages in the chat, from the synced copy. | Always 0. Fanvue does not count a fan's messages. |
| [Fan](https://betterfans.link/docs/api/fans#fan) | `notes` | The creator's private note about the fan with `fresh=true`, else `null`. | Always `null`. | The creator's private note about the fan, on every read, without `fresh=true`. `null` when there is none, or when Fanvue could not give it. |
| [Fan](https://betterfans.link/docs/api/fans#fan) | `subscription.expiresAt` | Set whenever the fan has subscribed. | Can be `null` for an active or expired fan, when Fansly says only whether the fan subscribes. | When the current period ends. Get fan and `sort=subscribed` always say; other lists say only while the subscription renews, and `null` for an expired fan. `null` for a fan who only follows. |
| [Fan](https://betterfans.link/docs/api/fans#fan) | `subscription.price` | What the fan pays for the subscription. | The price of the fan's tier. | The subscription's list price, from Fanvue's subscriber record: on Get fan when Fanvue has one for the fan, and when fans are listed with `sort=subscribed`. `null` in other lists. |
| [Fan](https://betterfans.link/docs/api/fans#fan) | List fans sort, status and search | Any sort works with any status and with search. | Any sort works with any status and with search. | A search lists fans by their latest message: with no sort it uses `sort=recent`, and `sort=spend` or `sort=subscribed` with a search answers `invalid_parameter`. `sort=subscribed` needs `status=active`; other statuses answer `invalid_parameter`. `sort=spend` ranks lifetime spend, so with a status other than all a page can hold fewer fans than limit. |
| [Fan](https://betterfans.link/docs/api/fans#fan) | `presence` | `online` when OnlyFans showed the fan as `online` in the last 5 minutes. Online fans uses the same rule. | `online` when the fan's status is automatic and Fansly saw them in the last 30 minutes. A fan who chose any status but automatic reads `offline`, whatever their last-seen time. Online fans uses the same rule. | `online` when Fanvue shows the fan as `online` now, `unknown` when the account has no chat with the fan or Fanvue does not say. Online fans uses the same rule. |
| [Fan list](https://betterfans.link/docs/api/fans#fanlist) | `type` | `custom`, or `system` for the platform's built-in lists. | Always `custom`. | `custom` for the creator's own lists, `system` for Fanvue's smart lists. |
| [Fan list](https://betterfans.link/docs/api/fans#fanlist) | `fanCount` | Always set. | `null` when Fansly has not given a count. | `null` when Fanvue has not given a count. |
| [Fan summary](https://betterfans.link/docs/api/fans#fansummary) | `username` | The handle, or u followed by the fan id when OnlyFans gives none. | The handle, or the bare fan id when Fansly gives none. | The handle, or the bare fan id when Fanvue gives none. |
| [Chat](https://betterfans.link/docs/api/chats#chat) | `lastActivityAt` | When the last message was sent, else when the chat last changed. | When the last message was sent, or `null` until that message has synced. | When the last message was sent, or `null` for a chat with no message yet. |
| [Chat](https://betterfans.link/docs/api/chats#chat) | `lastMessage.price`, `lastMessage.media`, `lastMessage.tip` | Filled, as List messages fills them. | Filled, as List messages fills them. | Always `null`, empty and `null`. Fanvue's chat list names only the last message's text, sender and time; List messages has the rest. |
| [Chat](https://betterfans.link/docs/api/chats#chat) | `unreadCount` | The platform's count of unread messages. | The platform's count of unread messages. | Fanvue's count of unread messages. A chat the creator marked unread by hand counts 1. |
| [Message](https://betterfans.link/docs/api/chats#message) | `purchased` | For a paid message, whether the fan bought it. | Always `null`. Fansly does not tell a creator which fans bought a message. | For a paid message, whether the fan bought it, from Fanvue's media list for the chat; `null` for a message with no price, and for the last message in a chat list. |
| [Message](https://betterfans.link/docs/api/chats#message) | `price`, `media` | Filled whenever the message has them. | Filled whenever the message has them. | From the chat's media list, read beside the messages: up to 100 media items for each page of messages. On a page whose messages carry more media than that, its oldest messages show no media and no price. Ask for fewer messages a page to avoid it. |
| [Message](https://betterfans.link/docs/api/chats#message) | `tip` | What the fan tipped with the message. | What the fan tipped with the message. | What the fan tipped, from Fanvue's tip earnings at the tip's time; `null` when they do not name it. On an account that gets many tips, a page holding tips at more than 6 different times can show the oldest of them as `null`. Ask for fewer messages a page to avoid it. |
| [Message](https://betterfans.link/docs/api/chats#message) | `massMessageId` | Set when the copy came from a mass message. | Always `null`. | The mass message's id, which is also the message's own id: Fanvue gives a mass message one id in every chat it reached, so the same message id shows in each of those chats. |
| [Message](https://betterfans.link/docs/api/chats#message) | `liked` | Whether the message was liked. | Whether the other side liked the message. | Always `null`. Fanvue's message list does not say. |
| [Media](https://betterfans.link/docs/api/chats#media) | `thumbnailUrl`, `durationSeconds` | Filled on synced and `fresh=true` reads alike. | Always `null` with `fresh=true`. Synced reads fill them. | Fanvue's own signed addresses, which expire. `null` when Fanvue gives none. Media named in events, and media past the first 40 on a page of posts or mass messages, carry their id alone (type other). |
| [Transaction](https://betterfans.link/docs/api/money#transaction) | `type` | `subscription`, `tip`, `message`, `post`, `stream`, `referral` or `other`. | `subscription`, `tip`, `stream`, `referral` or `other`. Message and post purchases are `other`, as are refunds, reversals and prizes. `type=message` or `type=post` answers `invalid_parameter`. | `subscription` (renewals included), `tip`, `message`, `post`, `referral` (affiliate rewards included) or `other`: media and checkout link sales, giveaways, refunds, chargebacks and held back earnings are `other`. There is no `stream`: `type=stream` answers `invalid_parameter`. |
| [Transaction](https://betterfans.link/docs/api/money#transaction) | `description` | What OnlyFans says the payment was for, when it says. | Always `null`. | Always `null`. |
| [Transaction](https://betterfans.link/docs/api/money#transaction) | `messageId`, `postId` | Always `null`. | Always `null`. | The message or post the payment was for, when Fanvue names it. On a tip, the chat message Fanvue writes for the tip. |
| [Transaction](https://betterfans.link/docs/api/money#transaction) | `fanId` on List transactions | Lists one fan's transactions. | Lists one fan's transactions. | Answers `invalid_parameter`: Fanvue cannot list one fan's transactions. Get fan has the fan's spend. |
| [Transaction](https://betterfans.link/docs/api/money#transaction) | `gross`, `net`, `fee` | Never negative. Refunds and chargebacks are not listed. | Negative on a refund or a reversal. | Negative on a refund or a chargeback. Where Fanvue holds back or releases earnings, gross and fee are 0 and only net moves. |
| [Revenue summary](https://betterfans.link/docs/api/money#revenuesummary) | `byType` | Every type, `message` and `post` included. | `message` and `post` are always 0. Message and post purchases count in `other`. | Every type but `stream`, from Fanvue's own totals. Every count, in byType and in the series, is 0: Fanvue gives totals, not how many payments made them. |
| [Post](https://betterfans.link/docs/api/content#post) | `tips` | Always `null`. OnlyFans does not say which post a tip was for. | Tips on the post, or `null` when it has none. | Tips on the post, or `null` when it has none. |
| [Post](https://betterfans.link/docs/api/content#post) | Sort and order | recent is newest first, likes is most liked first. | recent is newest first, likes is most liked first. | Pinned posts first, then newest first, as Fanvue orders them. `sort=likes` answers `invalid_parameter`: Fanvue cannot sort posts by likes. |
| [Tracking link](https://betterfans.link/docs/api/content#trackinglink) | `url` | The address fans open. | Always `null`. Fansly does not state it. | The address fans open. |
| [Tracking link](https://betterfans.link/docs/api/content#trackinglink) | `kind` | `tracking`, or `trial` when the link gives a free subscription. | Always `tracking`. | `tracking`, or `trial` for a free `trial` link. Fanvue lists only the free `trial` links that are still active. |
| [Tracking link](https://betterfans.link/docs/api/content#trackinglink) | `clicks` | Always set. | `null` when Fansly has not given a count. | Set on a tracking link. `null` on a free trial link: Fanvue counts its redemptions, which are its subscribers, not clicks. |
| [Tracking link](https://betterfans.link/docs/api/content#trackinglink) | `revenue` | What fans who joined through the link have spent since it was created. | Fansly's own total for the link. | Fanvue's own total for a tracking link. 0 on a free trial link: Fanvue reports no revenue for one. |
| [Tracking link](https://betterfans.link/docs/api/content#trackinglink) | Links listed | Every link BetterFans has synced. | Every link BetterFans has synced. | Up to 200 tracking links, and every active free trial link. Fanvue cannot rank links, so BetterFans reads them and ranks them itself. |
| [Vault item](https://betterfans.link/docs/api/content#vaultitem) | `url` | The archived copy, or `null` until it is archived. | The archived copy. Before that, Fansly's own signed address while it works (it expires after several days), else `null`. Download the file instead of storing the address. | Fanvue's own signed address while it works, else `null`. Download the file instead of storing the address. |
| [Vault item](https://betterfans.link/docs/api/content#vaultitem) | `folders` | Every vault list the item is in. | Every album the item is in. | The folder asked for when the vault is read by folder, else empty: Fanvue's media list does not say which folders an item is in. A folder's id is its name. |
| [Vault item](https://betterfans.link/docs/api/content#vaultitem) | `type=gif` | Lists GIFs. | Lists GIFs. | Answers `invalid_parameter`: Fanvue does not tell GIFs apart from photos. |
| [Online fans](https://betterfans.link/docs/api/fans#onlinefans) | `since` | When the fan came online. | Always `null`. Fansly does not say. | Always `null`. Fanvue says who is online now, not since when. |
| [Online fans](https://betterfans.link/docs/api/fans#onlinefans) | `fresh=true` | Checks up to 1,000 fans, most recently active first. | Checks up to 500 fans, most recently seen first. | Every read is live. Lists the fans Fanvue shows online now, most recently active chats first, up to 500 fans. |
| [Money](https://betterfans.link/docs/concepts/money#money) | Every amount | Exact cents. | Fansly counts tenths of a cent. Each amount is rounded to the nearest cent, so a total can differ from the sum of its items by a few cents. | Exact cents. |
| [Money](https://betterfans.link/docs/concepts/money#money) | Every total | Sales only. Refunds and chargebacks are left out. | Every transaction Fansly records. Refunds and reversals count as negative amounts, so a total can go down. | The revenue summary and revenue30d leave refunds and chargebacks out, as on OnlyFans. A fan's spend leaves out what was refunded. List transactions shows each reversal as its own negative row. |
| [Mass message](https://betterfans.link/docs/api/content#massmessage) | `sort=revenue` | Ranks every mass message sent in the window. | Not on Fansly: Mass messages answers `not_supported_on_platform`. | Ranks every mass message sent in the window, up to 200. A window holding more answers `invalid_parameter` (param from), and so does one with more than 1,000 mass messages sent after it (param to): Fanvue cannot rank mass messages or list them by date, so BetterFans reads the window whole. |

## Live reads

Get fan, List messages and Online fans take `fresh=true` on OnlyFans, Fansly and Fanvue accounts alike, to read live from the platform instead of the synced copy. A live read is slower, so use it only for the answer that must be current.
