# Donatty API documentation

Get your channel's donations, goals and top donors in a bot or on your website.

### Bot or server

New donations in chat, an overlay or your own program. You need to be able to run a script in a terminal.

- [Quick start: request from a terminal](https://developers.donatty.com/en/quickstart/bot.md)
- [Which donations to show on stream](https://developers.donatty.com/en/quickstart/bot.md#what-to-show-on-stream)
- Complete bot: [Node.js](https://developers.donatty.com/en/examples/bot-node.md) · [Python](https://developers.donatty.com/en/examples/bot-python.md)

### Website

A goal, top donors or a total on your page. You need HTML and a little JavaScript.

- [Quick start: request from a browser](https://developers.donatty.com/en/quickstart/website.md)
- [Ready-made goal page](https://developers.donatty.com/en/examples/goal-html.md)
- [Add your website address to the key](https://developers.donatty.com/en/quickstart/website.md#add-the-addresses-your-page-opens-from)

## Example requests



**Donations:**


```sh
curl -s "https://api.donatty.com/v1/donations?limit=5&moderation=PASSED,NONE" \
  -H "Authorization: Bearer $DONATTY_TOKEN"
```

```json
{
  "items": [
    {
      "id": "don_5d2e8f31-6a47-4c19-9b0e-7f3a2d1c8e46",
      "createdAt": "2026-11-09T10:21:47Z",
      "source": "DONATTY",
      "donorName": "Алексей",
      "message": "Спасибо за стрим!",
      "amount": {
        "value": "500.00",
        "currency": "RUB"
      },
      "feeCompensation": {
        "value": "27.00",
        "currency": "RUB"
      },
      "paymentMethod": "CARD",
      "goal": null,
      "moderation": {
        "status": "PASSED",
        "deadline": null
      },
      "media": null
    },
    {
      "id": "don_9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "createdAt": "2026-11-09T09:58:00Z",
      "source": "DONATION_ALERTS",
      "donorName": "Maria",
      "message": "Hi from Donation Alerts",
      "amount": {
        "value": "5.00",
        "currency": "USD"
      },
      "feeCompensation": null,
      "paymentMethod": null,
      "goal": null,
      "moderation": {
        "status": "NONE",
        "deadline": null
      },
      "media": null
    }
  ],
  "nextCursor": null
}
```

Send this request with your own key: [the Donations method page](https://developers.donatty.com/en/reference/donations.md).

**Goals:**


```sh
curl -s "https://api.donatty.com/v1/goals?status=ACTIVE&limit=1" \
  -H "Authorization: Bearer $DONATTY_TOKEN"
```

```json
{
  "items": [
    {
      "id": "goal_7e3a9c10-4b2d-4f8e-a1c6-0d9b8e7f6a52",
      "title": "New microphone",
      "target": {
        "value": "15000.00",
        "currency": "RUB"
      },
      "raised": {
        "value": "6420.50",
        "currency": "RUB"
      },
      "status": "ACTIVE",
      "endsAt": "2026-12-31T21:00:00Z",
      "createdAt": "2026-10-01T12:00:00Z"
    }
  ],
  "nextCursor": "MTc5MDg1NjAwMDAwMDAwMC43ZTNhOWMxMC00YjJkLTRmOGUtYTFjNi0wZDliOGU3ZjZhNTI"
}
```

Send this request with your own key: [the Fundraising goals method page](https://developers.donatty.com/en/reference/goals.md).

**Top:**


```sh
curl -s "https://api.donatty.com/v1/stats/top?period=WEEK&limit=3" \
  -H "Authorization: Bearer $DONATTY_TOKEN"
```

```json
{
  "period": "WEEK",
  "from": "2026-11-08T21:00:00Z",
  "to": "2026-11-15T21:00:00Z",
  "items": [
    {
      "rank": 1,
      "name": "Alex",
      "total": {
        "value": "12500.00",
        "currency": "RUB"
      }
    },
    {
      "rank": 2,
      "name": "Maria",
      "total": {
        "value": "4300.75",
        "currency": "RUB"
      }
    },
    {
      "rank": 3,
      "name": "Ivan",
      "total": {
        "value": "1000.00",
        "currency": "RUB"
      }
    }
  ]
}
```

Send this request with your own key: [the Top donors method page](https://developers.donatty.com/en/reference/stats-top.md).

**Total:**


```sh
curl -s "https://api.donatty.com/v1/stats/total?period=DAY&timeZone=Asia/Novosibirsk" \
  -H "Authorization: Bearer $DONATTY_TOKEN"
```

```json
{
  "period": "DAY",
  "from": "2026-11-09T17:00:00Z",
  "to": "2026-11-10T17:00:00Z",
  "total": {
    "value": "18250.25",
    "currency": "RUB"
  }
}
```

Send this request with your own key: [the Total donated method page](https://developers.donatty.com/en/reference/stats-total.md).

**Profile:**


```sh
curl -s "https://api.donatty.com/v1/streamer" \
  -H "Authorization: Bearer $DONATTY_TOKEN"
```

```json
{
  "id": "str_5b0c2f4e-8d61-4f43-9a7e-2f1d3c6b9a10",
  "slug": "teststreamer",
  "displayName": "Test Streamer",
  "avatarUrl": "https://storage.donatty.com/avatars/teststreamer.png",
  "donatePageUrl": "https://donatty.com/teststreamer"
}
```

Send this request with your own key: [the Streamer profile method page](https://developers.donatty.com/en/reference/streamer.md).



## API reference

- [Streamer profile](https://developers.donatty.com/en/reference/streamer.md): Nickname, avatar and the donation page link.
- [Donations](https://developers.donatty.com/en/reference/donations.md): Every donation from newest to oldest, with its moderation status.
- [Fundraising goals](https://developers.donatty.com/en/reference/goals.md): Title, target and the amount raised.
- [Top donors](https://developers.donatty.com/en/reference/stats-top.md): The best donors for a day, week, month, year or all time.
- [Total donated](https://developers.donatty.com/en/reference/stats-total.md): How much came in over a period.
- [All methods](https://developers.donatty.com/en/reference.md): The API address, keys and OpenAPI.

## Essentials

- [Keys](https://developers.donatty.com/en/tokens.md): Secret for a bot, public for a website.
- [Working with data](https://developers.donatty.com/en/data.md): Pages, money, time, an empty response.
- [Rate limits](https://developers.donatty.com/en/rate-limits.md): How many requests a minute and what to do after 429.
- [Errors](https://developers.donatty.com/en/errors.md): What a code from a response means and how to fix it.

## If something went wrong

- [FAQ](https://developers.donatty.com/en/faq.md): OBS, test donations, empty list, CORS
- [Service status](https://status.donatty.com/)

## More

- [API changes](https://developers.donatty.com/en/changelog.md)
- [The «Разработчикам» (Developers) section of your dashboard](https://streamer.donatty.com/developers): issue a key
- For programs and AI assistants: [llms.txt](https://developers.donatty.com/en/llms.txt) · [openapi.json](https://developers.donatty.com/openapi.json)
