API reference

List paid tips (per-fan references)

Paid tips of the key's account, newest first — the polling twin of the [tip.paid webhook](/developers/webhooks/overview).

View as MarkdownUpdated Oct 23, 2026

GET/api/external/tipsNew

Paid tips of the key's account, newest first — the polling twin of the tip.paid webhook.

Filter by externalRef to answer "did this fan tip?" for a tip link you sent, or by since to sweep. Each tip carries the fan's message. Refunded and charged-back tips stay in the list with their status — act on status: "paid" only.

Authentication

Send the creator's API key as a bearer token: Authorization: Bearer dpfn_…. See Authentication & API keys.

Query parameters

Name	Type	Required	Description
`externalRef`	string	Optional	Only tips made through links carrying this reference. Max length: 32 Pattern: `^[A-Za-z0-9_-]{1,32}$`
`since`	string	Optional	Only tips paid at or after this time. Format: date-time
`limit`	integer	Optional	Page size. Default: `50` Min: 1 Max: 100
`cursor`	string	Optional	`nextCursor` from the previous page.

Responses

200A page of tips.

Name Type Description

tips

Tip[]

Newest first.

Show child attributes

tipId string The tip id. Unique per tip — dedupe on it.

accountId string The creator who was tipped (the account behind the key).

externalRef

string | null

Your per-fan reference from the tip link the fan opened (&m= on the web, tm_{cents}_{ref}_{username} in Telegram). Null when the fan came without one. Not proof of identity — the fan can edit the link.

Max length: 32

Pattern: ^[A-Za-z0-9_-]{1,32}$

amountCents integer Gross fan-paid total in **cents** (VAT included).

currency

string

Always USD.

One of: USD

message

string | null

The message the fan wrote with the tip, if any.

Max length: 280

paidAt

string | null

When the payment settled (UTC).

Format: date-time

paidWith

string

Card, or the fan’s prepaid wallet credits.

One of: card, credits

status

string

Current state of the tip.

One of: paid, refunded, charged_back

tipper

object

Who tipped. Every field may be null for a guest checkout.

Show child attributes

`id`	string \| null	The fan’s account id, when signed in.
`email`	string \| null	Billing / account email. Format: email
`telegramUserId`	string \| null	Telegram user id (as a string) when the fan used the Mini App — cross-check it against your externalRef.
`telegramUsername`	string \| null	Telegram @username without the @, when known.

nextCursor string | null Pass as cursor for the next page; null on the last page.

Example response

{
  "tips": [
    {
      "tipId": "clxtp0001tip",
      "accountId": "clx2f8a1b0001qw3k",
      "externalRef": "fan-48213377",
      "amountCents": 1100,
      "currency": "USD",
      "message": "For the new set 💕",
      "paidAt": "2026-10-23T16:20:00.000Z",
      "paidWith": "card",
      "status": "paid",
      "tipper": {
        "id": "clxbu0001buyer",
        "email": "[email protected]",
        "telegramUserId": "48213377",
        "telegramUsername": "fan_one"
      }
    }
  ],
  "nextCursor": null
}

Errors

Status	Body	When
400	`{"error":"externalRef must be 1–32 of A-Z a-z 0-9 _ -"}`	Malformed reference.
400	`{"error":"since must be an ISO date"}`	Unparseable `since`.
401	`{"error":"Unauthorized","code":"unauthorized"}`	Missing or invalid API key.

Rate limiting

Every response carries the X-RateLimit-Tier header and, on limited tiers, the per-minute and per-day trios — read X-RateLimit-Remaining and X-RateLimit-Reset instead of hardcoding limits. Details in Rate limits.

Code samples

curl "https://www.dropfans.io/api/external/tips?externalRef=fan-48213377" \
  -H "Authorization: Bearer $DROPFANS_API_KEY"

const res = await fetch(`https://www.dropfans.io/api/external/tips?externalRef=fan-48213377`, {
  headers: {
    Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
  },
});
console.log(await res.json());

import os
import requests

res = requests.get(
    "https://www.dropfans.io/api/external/tips",
    headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
    params={"externalRef": "fan-48213377"},
)
print(res.json())

← Previous

Earnings stats, chart and recent transactions

Canonical profile, tip, subscribe and buy links

Questions? [email protected]