Справочник API FaucetPay.
Отправляйте микровыплаты, проверяйте пользователей и запрашивайте балансы через единый REST-эндпоинт. Запросы form-encoded, ответы JSON, один api_key на кран.
Создавайте краны, выплаты и автоматизации на FaucetPay.
Небольшой предсказуемый REST API поверх HTTPS. Каждый endpoint принимает form-encoded тело POST, возвращает JSON с целочисленным status верхнего уровня и аутентифицируется через api_key вашего крана. Без OAuth и без SDK.
REST через HTTPS
Каждый эндпоинт принимает form-encoded POST-тела и возвращает JSON.
Один ключ на кран
Ваш api_key крана аутентифицирует каждый запрос. Храните его на сервере.
С учётом IP
Отправляйте ip_address с /send для межкрановой антиабуз-детекции.
https://faucetpay.io/api/v1Отправляйте api_key с каждым запросом.
Передавайте api_key вашего крана в поле api_key каждого POST-тела.
Отправьте первую выплату менее чем за минуту.
Замените YOUR_API_KEY на реальный ключ крана, укажите тестового пользователя (подойдёт ваш собственный email) и отправьте.
curl -X POST https://faucetpay.io/api/v1/send \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "api_key=YOUR_API_KEY&amount=100&[email protected]¤cy=BTC"
Структура запроса и ответа.
Все endpoint-ы используют POST, form-encoded и возвращают JSON. Конверт одинаков для всех endpoint-ов, поэтому ваш клиентский код может использовать общую логику разбора.
Content-Type: application/x-www-form-urlencoded api_key=YOUR_API_KEY amount=100 [email protected] currency=BTC ip_address=203.0.113.4
{
"status": 200,
"message": "Payout completed successfully!",
// …endpoint-specific fields
}Конверт ответа
| Параметр | Тип | Описание |
|---|---|---|
| statusОбязательно | integer | Статус |
| messageОбязательно | string | Сообщение |
| …Опционально | varies | Данные |
Поверхность API
Пять endpoint-ов покрывают любой сценарий владельца крана: отправка выплат, проверка пользователей, проверка балансов, просмотр истории и получение списка монет.
/sendSend
Выплатить криптовалюту с баланса пользователю FaucetPay.
Параметры тела
| Параметр | Тип | Описание |
|---|---|---|
| api_keyОбязательно | string | API-ключ вашего крана. |
| amountОбязательно | integer | Сумма в наименьшей единице (сатоши для BTC). |
| toОбязательно | string | Получатель: email, имя пользователя, адрес кошелька или payout_user_hash. |
| currencyОбязательно | string | Символ монеты в верхнем регистре, напр. BTC, DOGE, USDT. |
| ip_addressОпционально | string | IP клеймера — настоятельно рекомендуется; антиабузное ограничение. |
| referralОпционально | string | Реферальный тег для этой выплаты для вашей отчётности. |
Пример запроса
curl -X POST https://faucetpay.io/api/v1/send \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "api_key=YOUR_API_KEY&amount=100&[email protected]¤cy=BTC&ip_address=203.0.113.4"
Пример ответа
{
"status": 200,
"message": "OK",
"rate_limit_remaining": 0.00049900,
"currency": "BTC",
"balance": 49900,
"balance_bitcoin": 0.00049900,
"payout_id": 12834721,
"payout_user_hash": "3f9c1a2e6b7d0f5e8c4a9b2d1f6e0c8a7b5d2e91"
}/checkaddressCheck address
Проверить, что получатель — зарегистрированный пользователь FaucetPay для выбранной валюты.
Параметры тела
| Параметр | Тип | Описание |
|---|---|---|
| api_keyОбязательно | string | API-ключ вашего крана. |
| addressОбязательно | string | Email, имя пользователя, адрес кошелька или payout_user_hash для проверки. |
| currencyОбязательно | string | Символ монеты в верхнем регистре для проверки членства. |
Пример запроса
curl -X POST https://faucetpay.io/api/v1/checkaddress \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "api_key=YOUR_API_KEY&[email protected]¤cy=BTC"
Пример ответа
{
"status": 200,
"message": "This address belongs to a FaucetPay user.",
"payout_user_hash": "3f9c1a2e6b7d0f5e8c4a9b2d1f6e0c8a7b5d2e91"
}/getbalanceCheck balance
Получить текущий баланс крана для конкретной монеты.
Параметры тела
| Параметр | Тип | Описание |
|---|---|---|
| api_keyОбязательно | string | API-ключ вашего крана. |
| currencyОбязательно | string | Символ монеты в верхнем регистре. |
Пример запроса
curl -X POST https://faucetpay.io/api/v1/getbalance \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "api_key=YOUR_API_KEY¤cy=BTC"
Пример ответа
{
"status": 200,
"message": "OK",
"currency": "BTC",
"balance": 49900,
"balance_bitcoin": 0.00049900
}/payoutsList payouts
Вернуть ваши последние выплаты, сначала новые.
Параметры тела
| Параметр | Тип | Описание |
|---|---|---|
| api_keyОбязательно | string | API-ключ вашего крана. |
| countОпционально | integer | Сколько выплат вернуть (1–100, по умолчанию 10). |
| currencyОпционально | string | Фильтровать по одной монете. Пропустить для всех. |
Пример запроса
curl -X POST https://faucetpay.io/api/v1/payouts \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "api_key=YOUR_API_KEY&count=5¤cy=BTC"
Пример ответа
{
"status": 200,
"message": "OK",
"rewards": [
{
"to": "[email protected]",
"amount": 100,
"date": "02-05-26 21:12:00 GMT"
}
]
}/currenciesSupported currencies
Вернуть все валюты, активные на FaucetPay.
Параметры тела
| Параметр | Тип | Описание |
|---|---|---|
| api_keyОбязательно | string | API-ключ вашего крана. |
Пример запроса
curl -X POST https://faucetpay.io/api/v1/currencies \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "api_key=YOUR_API_KEY"
Пример ответа
{
"status": 200,
"message": "OK",
"currencies": ["BTC", "ETH", "USDT", "LTC", "DOGE"],
"currencies_names": [
{ "name": "Bitcoin", "acronym": "BTC" },
{ "name": "Ethereum", "acronym": "ETH" },
{ "name": "Tether", "acronym": "USDT" },
{ "name": "Litecoin", "acronym": "LTC" },
{ "name": "Dogecoin", "acronym": "DOGE" }
]
}Коды статуса.
Каждый эндпоинт возвращает один из этих кодов статуса.
| Код | Тон | Значение |
|---|---|---|
| 200 | Успех | OK — запрос успешен |
| 403 | Ошибка | Запрещено — недействительный или отсутствующий api_key |
| 405 | Ошибка | Метод не разрешён — используйте POST |
| 413 | Предупреждение | Полезная нагрузка слишком велика |
| 414 | Предупреждение | URI слишком длинный |
| 415 | Предупреждение | Неподдерживаемый тип медиа — используйте application/x-www-form-urlencoded |
| 416 | Ошибка | Запрошенный диапазон не удовлетворяется |
| 417 | Ошибка | Ожидание не удалось |
| 418 | Предупреждение | Я чайник |
| 419 | Ошибка | Тайм-аут аутентификации |
| 420 | Предупреждение | Ограничение скорости — слишком много запросов |
| 421 | Ошибка | Неверный запрос |
| 422 | Предупреждение | Необрабатываемая сущность — ошибка валидации |
| 456 | Ошибка | Неустранимая ошибка |
Поддерживаемые монеты.
Каждая активная на FaucetPay монета доступна для выплат.
Лимиты запросов.
Лимиты применяются к каждому api_key крана и поддерживают работоспособность как вашей интеграции, так и нашей сети.
60 / мин
На api_key крана. Взрыв до 120 терпим.
Окно всплеска
Короткие всплески выше лимита терпимы до 2 секунд.
Лучшие практики безопасности.
Короткий, но принципиальный чек-лист. Каждый пункт соответствует классу инцидентов, с которыми мы сталкивались на практике.
- Никогда не отправляйте api_key в браузер. Обращайтесь как с паролем: только бэкенд, менеджер секретов, не в git.
- Всегда отправляйте ip_address с /send. Это включает межкрановую антиабуз-детекцию.
- Проверяйте единицы суммы в сатоши. Частый баг — отправка дробных значений вместо целого числа наименьшей единицы.
- Дедуплицируйте клеймы на сервере. Не полагайтесь на клиент для предотвращения дублей.
- Периодически ротируйте ключи. Мы поддерживаем горячую ротацию: старые ключи перестают работать при подтверждении.
Что-то непонятно?
Откройте тикет в help desk и мы обновим документацию.
Ключи с ограниченной областью и отзывом через Bearer-токен.
API v2 — это современная поверхность для автоматизации. Вместо одного всемогущего ключа крана вы создаёте узкие ключи (read / send / manage / admin), отправляете их как Bearer-токен и получаете единообразный JSON-конверт. Устаревший /api/v1 выше не меняется.
Аутентификация Bearer-токеном
Отправляйте ключ как Authorization: Bearer '<key>'.
Минимальные привилегии
Создавайте ключи только со scope, нужными инструменту.
Единый JSON-конверт
Каждый v2-ответ использует ту же структуру {status, message, data}.
https://faucetpay.io/api/v2Пример — аутентифицированный запрос
curl -X POST https://faucetpay.io/api/v2/balances \
-H "Authorization: Bearer YOUR_SCOPED_KEY" \
-H "Content-Type: application/json" \
-d '{}'Аутентификация и области (scopes).
Создавайте ключи с областью на странице управления вашего крана. Каждый ключ показывается один раз, хранится в виде хэша и может иметь IP-белый список для ключа и (для send) дневной лимит в USD.
Читать балансы, выплаты, статистику, валюты, настройки и статус антифрода.
Выполнять выплаты — перемещает реальные средства. Только на сервере.
Изменять настройки крана, лимиты, IP-белый список и правила антифрода.
Создать кран и запросить одобрение размещения. Не может удалять краны.
Endpoints.
Каждый v2-эндпоинт использует Bearer-аутентификацию и стандартный конверт.
| Эндпоинт | Scope | Тело | Описание |
|---|---|---|---|
/balance | read | currency? | Проверить баланс крана для монеты. |
/balances | read | — | Список балансов по всем монетам. |
/currencies | read | — | Список поддерживаемых валют. |
/check-address | read | address | Проверить адрес получателя. |
/payouts | read | currency?, count? | Список недавних выплат. |
/faucet | read | — | Получить детали крана |
/stats/daily | read | — | Ежедневная статистика |
/stats/users | read | coin, page | Статистика пользователей |
/transactions | read | coin, page | Транзакции |
/ratelimits | read | — | Лимиты |
/low-balance-notification | read | — | Оповещения о низком балансе |
| Эндпоинт | Scope | Тело | Описание |
|---|---|---|---|
/faucet/update | manage | faucet_name, faucet_domain, faucet_url, faucet_description, timer_minutes, currencies_selected?, categories_selected? | Обновить настройки крана |
/ratelimits/set | manage | ratelimits[] | Установить лимиты |
/ip-whitelist | manage | — | IP-белый список |
/ip-whitelist/set | manage | ip_whitelist | Обновить IP-белый список |
/low-balance-notification/toggle | manage | — | Переключить оповещение о низком балансе |
| Эндпоинт | Scope | Тело | Описание |
|---|---|---|---|
/anti-fraud/rules | manage | — | Правила антифрода |
/anti-fraud/toggle | manage | — | Переключить антифрод |
/anti-fraud/rules/update | manage | trust_rank, negative_rank?, whitelist?, blacklist? | Обновить правила антифрода |
| Эндпоинт | Scope | Тело | Описание |
|---|---|---|---|
/send | send | idempotency_key, currency, amount, to, ip_address?, referral? | Отправить выплату |
| Эндпоинт | Scope | Тело | Описание |
|---|---|---|---|
/faucet/create | admin | faucet_name, faucet_domain, faucet_url | Создать кран |
/approval-cost | admin | coin | Стоимость одобрения размещения |
/faucet/request-approval | admin | coin | Запросить одобрение размещения |
Отправка выплат.
v2 send — безопасный способ выплат: он требует ключ идемпотентности и учитывает необязательный дневной лимит в USD на ключ. Он использует тот же путь анти-фрода / баланса / лимитов, что и устаревший send.
/sendsendОтправить выплату с идемпотентностью и опциональным дневным лимитом.
Параметры тела
| Параметр | Тип | Описание |
|---|---|---|
| idempotency_keyОбязательно | string | Уникален для каждого логического платежа. Повтор с тем же ключом никогда не платит дважды. |
| toОбязательно | string | Получатель: email, имя пользователя, адрес кошелька или payout_user_hash. |
| amountОбязательно | integer | Сумма в наименьшей единице монеты (напр. сатоши для BTC). |
| currencyОбязательно | string | Символ монеты в верхнем регистре, напр. BTC, DOGE. |
| ip_addressОпционально | string | IP получателя — рекомендуется для антифрода. |
| referralОпционально | string | Реферальный тег для вашей отчётности. |
Пример запроса
curl -X POST https://faucetpay.io/api/v2/send \
-H "Authorization: Bearer YOUR_SCOPED_KEY" \
-H "Content-Type: application/json" \
-d '{"idempotency_key":"claim-8f3a1c2e","to":"[email protected]","amount":100,"currency":"BTC","ip_address":"203.0.113.4"}'Пример ответа
{
"success": true,
"message": "OK",
"data": {
"rate_limit_remaining": 0.00049900,
"currency": "BTC",
"balance": 49900,
"balance_bitcoin": 0.00049900,
"payout_id": 12834721,
"payout_user_hash": "3f9c1a2e6b7d0f5e8c4a9b2d1f6e0c8a7b5d2e91"
}
}Webhooks.
Подпишитесь на события выплат и получайте POST-запросы с подписью HMAC. Настройте их на странице управления вашего крана — управление вебхуками доступно только с сессией + 2FA, поэтому ключ с областью никогда не сможет зарегистрировать endpoint доставки.
Событийный
Подпишитесь на события payout.sent и payout.failed.
Подписано HMAC
Каждая доставка включает заголовок X-FaucetPay-Signature с HMAC-SHA256 тела.
SSRF-защита
URL-адреса вебхуков должны быть публичными HTTPS-эндпоинтами. Внутренние IP отклоняются.
Пример доставки
POST https://your-site.example/webhooks/faucetpay
X-FaucetPay-Signature: sha256=4b0c…e91
{
"id": "9f2c1a…",
"event": "payout.sent",
"faucet_id": 1234,
"created_at": 1717365120,
"data": {
"to": "[email protected]",
"amount": 100,
"currency": "BTC",
"payout_id": "payout_9nq0xk2l",
"payout_user_hash": "3f9c…",
"message": "Payout completed successfully!"
}
}Проверьте подпись
import crypto from 'node:crypto';
// rawBody = the exact bytes you received (verify BEFORE JSON.parse)
const signature = req.headers['x-faucetpay-signature']; // 'sha256=<hex>'
const expected =
'sha256=' + crypto.createHmac('sha256', WEBHOOK_SECRET).update(rawBody).digest('hex');
const ok =
signature &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
if (!ok) return res.status(401).end();Errors.
v2 использует стандартные HTTP-коды статуса плюс описательное сообщение в конверте.
| Код | Тон | Значение |
|---|---|---|
| 200 | Успех | 200 OK |
| 400 | Предупреждение | 400 Неверный запрос |
| 401 | Ошибка | 401 Не авторизован |
| 403 | Ошибка | 403 Запрещено |
| 409 | Предупреждение | 409 Конфликт |
| 429 | Предупреждение | 429 Слишком много запросов |
Управляйте своим краном из любого ИИ-агента.
MCP-сервер FaucetPay позволяет ИИ-ассистенту (Cursor, Claude Code, Windsurf, …) читать ваш кран и настраивать параметры по Model Context Protocol. Это тонкий клиент поверх API v2 — только read + manage.
Тонкий слой
MCP-сервер — тонкая обёртка над v2 API — без дополнительного состояния.
Нет денежных инструментов
Сервер не предоставляет инструменты выплат. Он может читать и управлять, но не отправлять средства.
Ничего не устанавливать
Сервер работает удалённо. Просто направьте ваш AI-ассистент на URL.
Подключение и настройка.
Добавьте MCP-сервер FaucetPay в конфиг вашего AI-ассистента. Настройте на ваш кран с scoped read или manage ключом.
// ~/.cursor/mcp.json
{
"mcpServers": {
"faucetpay": {
"url": "https://mcp.faucetpay.io/mcp",
"headers": { "Authorization": "Bearer fpk_your_read_or_manage_key" }
}
}
}Конфигурация
| Параметр | Тип | Описание |
|---|---|---|
| urlОбязательно | string | URL MCP-сервера |
| AuthorizationОбязательно | header | Scoped API-ключ (scope read или manage) |
Tools.
Read-only и manage-инструменты MCP-сервера.
Инструменты чтения
get_faucetПолучить детали кранаget_balancesПолучить балансы кранаget_balanceПолучить текущий баланс крана для монеты.get_payoutsСписок недавних выплатget_currenciesСписок поддерживаемых валют и их лимитов.check_addressПроверить, является ли адрес зарегистрированным пользователем FaucetPay.get_daily_statsПолучить ежедневную статистикуget_user_statsПолучить статистику пользователейget_transactionsСписок транзакцийget_ratelimitsПолучить лимитыget_low_balance_notificationПолучить настройки низкого баланса
Инструменты управления
get_ip_whitelistПолучить IP-белый списокset_ip_whitelistОбновить IP-белый списокget_anti_fraudПолучить настройки антифродаtoggle_anti_fraudПереключить антифродupdate_anti_fraud_rulesОбновить правила антифродаupdate_faucet_settingsОбновить настройки кранаset_ratelimitsУстановить лимитыtoggle_low_balance_notificationПереключить оповещение о низком балансе
Безопасность и лучшие практики.
Лучшие практики безопасного использования MCP-сервера.
- Используйте read или manage ключ — никогда send. Этот сервер не предоставляет инструменты выплат.
- Установите короткий срок. Дайте ключу время жизни, чтобы устаревшая конфигурация не могла злоупотребляться вечно.
- Отозвать немедленно при компрометации. Один клик на странице Manage убивает ключ.
- Прислушивайтесь к антифрод-рекомендациям. Отключение или ослабление антифрода возвращает предупреждение.
Зарабатывать больше
Монетизируйте кран через рекламную сеть FaucetPay.
Accept crypto payments in your store.
The Merchant API lets any website accept payments from FaucetPay users through a hosted checkout page. The buyer pays from their FaucetPay balance and the funds settle to your account instantly — no keys or server-side SDK required to get started.
Hosted checkout
You submit a plain HTML form; FaucetPay hosts the whole payment page. Nothing sensitive ever touches your server.
Any supported coin
Price in one currency and let the buyer pay with any coin FaucetPay supports — or pin the payment coin yourself.
Instant settlement
Payments move between FaucetPay balances, so they confirm instantly with no on-chain fees or waiting.
The payment form.
Checkout starts with a simple HTML form POSTed to the FaucetPay checkout endpoint. The buyer is taken to a FaucetPay-hosted page to review and confirm the payment.
Submit the form with a standard browser POST (not XHR) — the buyer must land on the hosted checkout page to confirm the payment.
| Параметр | Тип | Описание |
|---|---|---|
| merchant_usernameОбязательно | string | Your FaucetPay username — the account that receives the payment. |
| item_descriptionОбязательно | string | Description of the item or service the buyer is paying for. |
| amount1Обязательно | string | Amount you want to receive, denominated in currency1. |
| currency1Обязательно | string | The pricing currency of your store (e.g. USDT, BTC, …). |
| currency2Опционально | string | The coin the buyer must pay with. Leave blank to let the buyer choose any supported coin. |
| customОпционально | string | An identifier passed back on the callback — use it for your order ID or user ID. |
| callback_urlОпционально | string | URL that receives the server-to-server POST callback once the payment completes. |
| success_urlОпционально | string | URL the buyer is redirected to after a successful payment. |
| cancel_urlОпционально | string | URL the buyer is redirected to if they cancel. |
Example HTML form
<form action="https://faucetpay.io/merchant/webscr" method="post"> <input type="hidden" name="merchant_username" value="YOUR_USERNAME"> <input type="hidden" name="item_description" value="PlayStation 5"> <input type="hidden" name="amount1" value="100"> <input type="hidden" name="currency1" value="USDT"> <input type="hidden" name="currency2" value=""> <input type="hidden" name="custom" value="order-4564211"> <input type="hidden" name="callback_url" value="https://your-site.com/ipn"> <input type="hidden" name="success_url" value="https://your-site.com/success"> <input type="hidden" name="cancel_url" value="https://your-site.com/cancel"> <input type="submit" name="submit" value="Pay with FaucetPay"> </form>
Callback & verification.
After a completed payment, FaucetPay POSTs a form-encoded callback to your callback_url with the payment details and a single-use verification token. Verify the token server-side before delivering the goods.
Example callback (IPN)
POST https://your-site.com/ipn Content-Type: application/x-www-form-urlencoded token=1a2b3c4d5e6f7a8b9c0d &transaction_id=87654321 &merchant_username=your_username &payer_username=buyer_username &amount1=100 ¤cy1=USDT &amount2=0.00105 ¤cy2=BTC &custom=order-4564211 &exchange_rate=95238.09
Verify the token
GET https://faucetpay.io/merchant/get-payment/{token}
{
"valid": true,
"transaction_id": "87654321",
"merchant_username": "your_username",
"payer_username": "buyer_username",
"amount1": "100",
"currency1": "USDT",
"amount2": "0.00105",
"currency2": "BTC",
"custom": "order-4564211"
}Retry schedule
We expect that you respond to the callback request with an HTTP 200 OK response. If we don't receive a 200 response, our system will assume that the request has failed and will reattempt the callback based on the following schedule.
- 1st Callback:Immediately (After Payment)
- 2nd Callback:5 Minutes Delay
- 3rd Callback:15 Minutes Delay
- 4th Callback:30 Minutes Delay
- 5th Callback:60 Minutes Delay
- 6th Callback:120 Minutes Delay
- 7th Callback:240 Minutes Delay