WebSockets

Receive real-time OnlyFans events through a persistent WebSocket connection. The gateway proxies your connection directly to the OnlyFans WebSocket server on behalf of a model.

Relay architecture

You connect to the gateway WebSocket endpoint. The gateway authenticates your request, then opens a connection to OnlyFans on behalf of the model and relays all messages in both directions. You do not need to manage OnlyFans session tokens.

Endpoint

TEXT

wss://api.onlyfans-api.ai/api/models/{model_id}/ws

Parameter	Type	Description
`model_id`	path	UUID of the connected model to open the WS for
`api_key`	query	Your API key (alternative to X-API-Key header)
`X-API-Key`	header	Your API key (for Node.js and server-side clients)

Browser auth

Browser WebSocket connections cannot set custom headers. Pass your API key as the api_key query parameter instead of the X-API-Key header.

Connecting

Open the WebSocket connection. The gateway validates your API key, verifies the model is connected, then sends a confirmation message.

const ws = new WebSocket(
  "wss://api.onlyfans-api.ai/api/models/MODEL_UUID/ws?api_key=YOUR_API_KEY"
)

ws.addEventListener("message", (event) => {
  const msg = JSON.parse(event.data)

  if (msg.connected) {
    console.log("Connected to model:", msg.modelId)
    return
  }

  if (msg.error) {
    console.error("Error:", msg.error, msg.code)
    return
  }

  // Real-time OF event
  console.log("Event:", msg)
})

ws.addEventListener("close", (event) => {
  console.log("Disconnected:", event.code, event.reason)
})

Confirmation message

JSON

// Sent by the gateway immediately after a successful connection
{
  "connected": true,
  "modelId": "16f3d13b-9415-4e6b-babe-e8db6b31bd97"
}

Sending Actions

After connecting, send JSON messages directly to OnlyFans. All messages are relayed transparently.

Action	Description	Response
`{"act":"get_onlines","ids":[...]}`	Check which fan user IDs are currently online	`{"online":["id1","id2"]}`

// Check which user IDs are currently online
ws.send(JSON.stringify({
  act: "get_onlines",
  ids: ["12345678", "87654321"],
}))

// Response from server:
// { "online": ["12345678"] }

Connection Errors

If the connection cannot be established, the gateway sends a JSON error message and closes the socket immediately.

Code	Meaning	Fix
`NO_API_KEY`	No API key provided	Add api_key query param or X-API-Key header
`INVALID_API_KEY`	API key is invalid or revoked	Generate a new key from the dashboard
`NO_SUBSCRIPTION`	Organization has no active subscription	Subscribe to a plan in the Billing section
`MODEL_NOT_FOUND`	Model UUID not found or not accessible	Verify the model UUID and org access
`MODEL_NOT_CONNECTED`	Model session is not active	Reconnect the model from the Models page
`NO_WS_CREDENTIALS`	Model has no WS credentials	Reconnect the model to refresh credentials
`WS_CONNECT_ERROR`	Gateway failed to connect to OnlyFans WS	Reconnect the model; check proxy settings

Example error message

JSON

// Sent before the connection is closed
{
  "error": "Model is not connected",
  "code": "MODEL_NOT_CONNECTED"
}

Reconnection

The gateway does not automatically reconnect on your behalf. If the socket closes unexpectedly, implement exponential backoff in your client before reopening the connection.

JAVASCRIPT

function connectWithRetry(modelId, apiKey, attempt = 0) {
  const delay = Math.min(1000 * 2 ** attempt, 30000)
  setTimeout(() => {
    const ws = new WebSocket(
      `wss://api.onlyfans-api.ai/api/models/${modelId}/ws?api_key=${apiKey}`
    )
    ws.addEventListener("close", (e) => {
      if (e.code !== 1000) { // not a clean close
        connectWithRetry(modelId, apiKey, attempt + 1)
      }
    })
  }, delay)
}

PreviousAPI ReferenceAll endpoints and parameters NextRate LimitingLimits, headers, and retry