FaucetPay API-Referenz.
Sende Micro-Auszahlungen, verifiziere Nutzer und frage Guthaben über einen einzigen REST-Endpunkt ab. Form-codierte Anfragen, JSON-Antworten, ein api_key pro Faucet.
Baue Faucets, Auszahlungen und Automatisierungen auf FaucetPay.
Eine kleine, vorhersehbare REST-API über HTTPS. Jeder Endpoint akzeptiert form-encoded POST-Bodies, gibt JSON mit einem Top-Level Status-Integer zurück und authentifiziert mit dem api_key deines Faucets. Kein OAuth, kein SDK nötig.
REST über HTTPS
Jeder Endpunkt akzeptiert form-codierte POST-Bodies und gibt JSON zurück.
Ein Schlüssel pro Faucet
Dein Faucet api_key authentifiziert jede Anfrage. Behalte ihn serverseitig.
IP-bewusst
Sende ip_address mit /send um faucet-übergreifende Betrugserkennung zu aktivieren.
https://faucetpay.io/api/v1Sende deinen api_key mit jeder Anfrage.
Übergib den api_key deines Faucets im api_key-Feld jedes POST-Bodies.
Sende deine erste Auszahlung in unter einer Minute.
Ersetze YOUR_API_KEY mit einem echten Faucet-Key, zielle auf einen Test-User (deine eigene E-Mail funktioniert) und feuere.
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"
Request- & Response-Shape.
Alle Endpoints sind POST, form-encoded und geben JSON zurück. Der Envelope ist identisch über alle Endpoints sodass dein Client-Code Parsing-Logik teilen kann.
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
}Response-Envelope
| Parameter | Typ | Beschreibung |
|---|---|---|
| statusErforderlich | integer | Status |
| messageErforderlich | string | Nachricht |
| …Optional | varies | Daten |
Die API-Oberfläche
Fünf Endpoints decken jedes Faucet-Owner-Szenario ab: Auszahlungen senden, User verifizieren, Salden prüfen, Verlauf auflisten und Coin-Liste introspectieren.
/sendSend
Krypto aus deinem Kontostand an einen FaucetPay-Nutzer auszahlen.
Body-Parameter
| Parameter | Typ | Beschreibung |
|---|---|---|
| api_keyErforderlich | string | API-Schlüssel deines Faucets. |
| amountErforderlich | integer | Betrag in der kleinsten Einheit der Münze (Satoshis bei BTC). |
| toErforderlich | string | Ziel: E-Mail, Benutzername, Wallet-Adresse oder payout_user_hash. |
| currencyErforderlich | string | Großgeschriebenes Münzsymbol, z.B. BTC, DOGE, USDT. |
| ip_addressOptional | string | IP des Claimers — dringend empfohlen; ermöglicht Anti-Missbrauch-Ratenbegrenzung. |
| referralOptional | string | Referral-Tag für diese Auszahlung für deine Berichterstattung. |
Beispiel-Anfrage
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"
Beispiel-Response
{
"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
Überprüfen, ob ein Ziel ein registrierter FaucetPay-Nutzer für die gewählte Währung ist.
Body-Parameter
| Parameter | Typ | Beschreibung |
|---|---|---|
| api_keyErforderlich | string | API-Schlüssel deines Faucets. |
| addressErforderlich | string | E-Mail, Benutzername, Wallet-Adresse oder payout_user_hash zur Verifizierung. |
| currencyErforderlich | string | Großgeschriebenes Münzsymbol, unter dem die Mitgliedschaft geprüft wird. |
Beispiel-Anfrage
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"
Beispiel-Response
{
"status": 200,
"message": "This address belongs to a FaucetPay user.",
"payout_user_hash": "3f9c1a2e6b7d0f5e8c4a9b2d1f6e0c8a7b5d2e91"
}/getbalanceCheck balance
Aktuellen Faucet-Bestand für eine bestimmte Münze abrufen.
Body-Parameter
| Parameter | Typ | Beschreibung |
|---|---|---|
| api_keyErforderlich | string | API-Schlüssel deines Faucets. |
| currencyErforderlich | string | Großgeschriebenes Münzsymbol. |
Beispiel-Anfrage
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"
Beispiel-Response
{
"status": 200,
"message": "OK",
"currency": "BTC",
"balance": 49900,
"balance_bitcoin": 0.00049900
}/payoutsList payouts
Deine letzten Auszahlungen zurückgeben, neueste zuerst.
Body-Parameter
| Parameter | Typ | Beschreibung |
|---|---|---|
| api_keyErforderlich | string | API-Schlüssel deines Faucets. |
| countOptional | integer | Anzahl der zurückzugebenden Auszahlungen (1–100, Standard 10). |
| currencyOptional | string | Auf eine einzelne Münze filtern. Weglassen für alle. |
Beispiel-Anfrage
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"
Beispiel-Response
{
"status": 200,
"message": "OK",
"rewards": [
{
"to": "[email protected]",
"amount": 100,
"date": "02-05-26 21:12:00 GMT"
}
]
}/currenciesSupported currencies
Jede aktuell auf FaucetPay aktive Währung zurückgeben.
Body-Parameter
| Parameter | Typ | Beschreibung |
|---|---|---|
| api_keyErforderlich | string | API-Schlüssel deines Faucets. |
Beispiel-Anfrage
curl -X POST https://faucetpay.io/api/v1/currencies \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "api_key=YOUR_API_KEY"
Beispiel-Response
{
"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" }
]
}Status-Codes.
Jeder Endpunkt gibt einen dieser Statuscodes zurück.
| Code | Ton | Bedeutung |
|---|---|---|
| 200 | Erfolg | OK — Anfrage erfolgreich |
| 403 | Fehler | Verboten — ungültiger oder fehlender api_key |
| 405 | Fehler | Methode nicht erlaubt — POST verwenden |
| 413 | Warnung | Nutzlast zu groß |
| 414 | Warnung | URI zu lang |
| 415 | Warnung | Nicht unterstützter Medientyp — application/x-www-form-urlencoded verwenden |
| 416 | Fehler | Angeforderter Bereich nicht erfüllbar |
| 417 | Fehler | Erwartung fehlgeschlagen |
| 418 | Warnung | Ich bin eine Teekanne |
| 419 | Fehler | Authentifizierungs-Timeout |
| 420 | Warnung | Ratenbegrenzt — zu viele Anfragen |
| 421 | Fehler | Fehlgeleitete Anfrage |
| 422 | Warnung | Nicht verarbeitbare Entität — Validierungsfehler |
| 456 | Fehler | Nicht behebbarer Fehler |
Unterstützte Coins.
Jede auf FaucetPay aktive Münze ist für Auszahlungen verfügbar.
Rate-Limits.
Limits werden pro Faucet api_key angewendet und halten sowohl deine Integration als auch unser Netzwerk gesund.
60 / Min
Pro Faucet api_key. Burst bis 120 toleriert.
Burst-Fenster
Kurze Bursts über dem Limit werden bis zu 2 Sekunden toleriert.
Security Best Practices.
Eine kurze, meinungsstarke Checkliste. Jeder Punkt mappt zu einer Incident-Klasse die wir in der Wildnis gesehen haben.
- Sende deinen api_key niemals zum Browser. Behandle ihn wie ein Passwort: nur Backend, Secrets-Manager, niemals in Git.
- Sende immer ip_address mit /send. Es aktiviert unsere faucet-übergreifende Betrugserkennung.
- Betragseinheiten in Satoshis verifizieren. Ein häufiger Bug ist das Senden von Bruchteilen statt der kleinsten Einheit.
- Claims serverseitig deduplizieren. Verlasse dich nicht auf den Client, um Doppel-Submits zu verhindern.
- Schlüssel regelmäßig rotieren. Wir unterstützen Hot-Rotation: alte Schlüssel stoppen sofort bei Bestätigung.
Etwas unklar?
Öffne ein Ticket im Help Desk und wir aktualisieren die Dokumentation.
Scoped, widerrufbare Keys mit Bearer-Token.
Die v2 API ist die moderne Oberfläche für Automatisierung. Statt eines allmächtigen Faucet-Keys mintest du narrow Keys (read / send / manage / admin), sendest sie als Bearer-Token und bekommst einen konsistenten JSON-Envelope. Die Legacy /api/v1 oben ist unverändert.
Bearer-Token-Auth
Sende den Schlüssel als Authorization: Bearer '<key>'.
Minimal-Rechte-Scopes
Erstelle Schlüssel nur mit den Scopes, die ein Tool braucht.
Konsistentes JSON-Envelope
Jede v2-Antwort nutzt die gleiche {status, message, data}-Struktur.
https://faucetpay.io/api/v2Beispiel — authentifizierte Anfrage
curl -X POST https://faucetpay.io/api/v2/balances \
-H "Authorization: Bearer YOUR_SCOPED_KEY" \
-H "Content-Type: application/json" \
-d '{}'Authentication & Scopes.
Minte Scoped-Keys von der Manage-Seite deines Faucets. Jeder Key wird einmal gezeigt, gehasht gespeichert und kann eine Per-Key IP-Whitelist und (für send) ein tägliches USD-Cap tragen.
Salden, Auszahlungen, Statistiken, Währungen, Einstellungen und Anti-Fraud-Status lesen.
Auszahlungen vornehmen — bewegt echte Gelder. Nur serverseitig aufbewahren.
Faucet-Einstellungen, Ratenlimits, IP-Whitelist und Anti-Fraud-Regeln ändern.
Faucet erstellen und Listungs-Genehmigung anfordern. Kann Faucets nicht löschen.
Endpoints.
Jeder v2-Endpunkt verwendet Bearer-Auth und gibt das Standard-Envelope zurück.
| Endpoint | Scope | Body | Beschreibung |
|---|---|---|---|
/balance | read | currency? | Faucet-Bestand für eine Münze prüfen. |
/balances | read | — | Salden über alle Münzen auflisten. |
/currencies | read | — | Unterstützte Währungen auflisten. |
/check-address | read | address | Eine Zieladresse verifizieren. |
/payouts | read | currency?, count? | Letzte Auszahlungen auflisten. |
/faucet | read | — | Faucet-Details abrufen |
/stats/daily | read | — | Tagesstatistiken |
/stats/users | read | coin, page | Nutzerstatistiken |
/transactions | read | coin, page | Transaktionen |
/ratelimits | read | — | Ratenlimits |
/low-balance-notification | read | — | Niedrige-Saldo-Warnungen |
| Endpoint | Scope | Body | Beschreibung |
|---|---|---|---|
/faucet/update | manage | faucet_name, faucet_domain, faucet_url, faucet_description, timer_minutes, currencies_selected?, categories_selected? | Faucet-Einstellungen aktualisieren |
/ratelimits/set | manage | ratelimits[] | Ratenlimits festlegen |
/ip-whitelist | manage | — | IP-Whitelist |
/ip-whitelist/set | manage | ip_whitelist | IP-Whitelist aktualisieren |
/low-balance-notification/toggle | manage | — | Niedrige-Saldo-Warnung umschalten |
| Endpoint | Scope | Body | Beschreibung |
|---|---|---|---|
/anti-fraud/rules | manage | — | Anti-Fraud-Regeln |
/anti-fraud/toggle | manage | — | Anti-Fraud umschalten |
/anti-fraud/rules/update | manage | trust_rank, negative_rank?, whitelist?, blacklist? | Anti-Fraud-Regeln aktualisieren |
| Endpoint | Scope | Body | Beschreibung |
|---|---|---|---|
/send | send | idempotency_key, currency, amount, to, ip_address?, referral? | Auszahlung senden |
| Endpoint | Scope | Body | Beschreibung |
|---|---|---|---|
/faucet/create | admin | faucet_name, faucet_domain, faucet_url | Faucet erstellen |
/approval-cost | admin | coin | Listungs-Genehmigungskosten |
/faucet/request-approval | admin | coin | Listungs-Genehmigung anfordern |
Auszahlungen senden.
Der v2 Send ist der sichere Weg auszuzahlen: er erfordert einen Idempotency-Key und ehrt ein optionales Per-Key tägliches USD-Cap. Er nutzt denselben Anti-Fraud / Balance / Rate-Limit-Pfad wie der Legacy-Send.
/sendsendAuszahlung mit Idempotenz und optionalem täglichem Limit senden.
Body-Parameter
| Parameter | Typ | Beschreibung |
|---|---|---|
| idempotency_keyErforderlich | string | Eindeutig pro logischer Auszahlung. Ein Retry mit dem gleichen Schlüssel zahlt nie doppelt. |
| toErforderlich | string | Empfänger: E-Mail, Benutzername, Wallet-Adresse oder payout_user_hash. |
| amountErforderlich | integer | Betrag in der kleinsten Einheit der Münze (z.B. Satoshis bei BTC). |
| currencyErforderlich | string | Großgeschriebenes Münzsymbol, z.B. BTC, DOGE. |
| ip_addressOptional | string | Empfänger-IP — empfohlen für Anti-Fraud. |
| referralOptional | string | Referral-Tag für deine eigene Berichterstattung. |
Beispiel-Anfrage
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"}'Beispiel-Response
{
"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.
Abonniere Payout-Events und empfange HMAC-signierte POSTs. Konfiguriere sie von der Manage-Seite deines Faucets — Webhook-Management ist Session + 2FA only, sodass ein Scoped-Key nie einen Delivery-Endpoint registrieren kann.
Ereignisgesteuert
Abonniere payout.sent- und payout.failed-Ereignisse.
HMAC-signiert
Jede Zustellung enthält einen X-FaucetPay-Signature-Header mit einem HMAC-SHA256 des Bodys.
SSRF-Schutz
Webhook-URLs müssen öffentliche HTTPS-Endpunkte sein. Interne IPs werden abgelehnt.
Beispiel-Delivery
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!"
}
}Signatur verifizieren
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 verwendet Standard-HTTP-Statuscodes plus eine beschreibende Meldung im Envelope.
| Code | Ton | Bedeutung |
|---|---|---|
| 200 | Erfolg | 200 OK |
| 400 | Warnung | 400 Bad request |
| 401 | Fehler | 401 Unauthorized |
| 403 | Fehler | 403 Forbidden |
| 409 | Warnung | 409 Conflict |
| 429 | Warnung | 429 Too many requests |
Verwalte deinen Faucet von jedem AI-Agent.
Der FaucetPay MCP-Server lässt einen AI-Assistant (Cursor, Claude Code, Windsurf, …) deinen Faucet lesen und Einstellungen tunen über das Model Context Protocol. Es ist ein Thin Client über der v2 API — read + manage only.
Dünne Schicht
Der MCP-Server ist ein dünner Wrapper über der v2-API — kein zusätzlicher State.
Keine Geld-Tools
Der Server bietet keine Auszahlungs-Tools. Er kann lesen und verwalten, aber keine Gelder senden.
Nichts zu installieren
Der Server läuft remote. Richte deinen AI-Assistenten einfach auf die URL.
Verbinden & konfigurieren.
Füge den FaucetPay MCP-Server zur Konfiguration deines AI-Assistenten hinzu. Richte ihn mit einem Scoped-Read- oder Manage-Key auf deinen Faucet.
// ~/.cursor/mcp.json
{
"mcpServers": {
"faucetpay": {
"url": "https://mcp.faucetpay.io/mcp",
"headers": { "Authorization": "Bearer fpk_your_read_or_manage_key" }
}
}
}Konfiguration
| Parameter | Typ | Beschreibung |
|---|---|---|
| urlErforderlich | string | MCP-Server-URL |
| AuthorizationErforderlich | header | Scoped API-Schlüssel (Read- oder Manage-Scope) |
Tools.
Read-Only- und Manage-Tools des MCP-Servers.
Read-Tools
get_faucetFaucet-Details abrufenget_balancesFaucet-Salden abrufenget_balanceAktuellen Faucet-Bestand für eine Münze abrufen.get_payoutsLetzte Auszahlungen auflistenget_currenciesUnterstützte Währungen und Limits auflisten.check_addressPrüfen, ob eine Adresse ein registrierter FaucetPay-Nutzer ist.get_daily_statsTagesstatistiken abrufenget_user_statsNutzerstatistiken abrufenget_transactionsTransaktionen auflistenget_ratelimitsRatenlimits abrufenget_low_balance_notificationNiedrige-Saldo-Einstellungen abrufen
Manage-Tools
get_ip_whitelistIP-Whitelist abrufenset_ip_whitelistIP-Whitelist aktualisierenget_anti_fraudAnti-Fraud-Einstellungen abrufentoggle_anti_fraudAnti-Fraud umschaltenupdate_anti_fraud_rulesAnti-Fraud-Regeln aktualisierenupdate_faucet_settingsFaucet-Einstellungen aktualisierenset_ratelimitsRatenlimits festlegentoggle_low_balance_notificationNiedrige-Saldo-Warnung umschalten
Security & Best Practices.
Best Practices für die sichere Nutzung des MCP-Servers.
- Verwende einen Read- oder Manage-Key — niemals einen Send-Key. Dieser Server bietet keine Auszahlungs-Tools.
- Kurze Gültigkeitsdauer setzen. Gib dem Schlüssel eine Lebensdauer, damit eine alte Config nicht ewig missbraucht werden kann.
- Bei Kompromittierung sofort widerrufen. Ein Klick auf der Manage-Seite deaktiviert den Schlüssel.
- Anti-Fraud-Hinweise beachten. Deaktivieren oder Schwächen von Anti-Fraud gibt eine Warnung zurück.
Mehr verdienen
Monetarisiere deinen Faucet mit dem FaucetPay Werbenetzwerk.
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.
| Parameter | Typ | Beschreibung |
|---|---|---|
| merchant_usernameErforderlich | string | Your FaucetPay username — the account that receives the payment. |
| item_descriptionErforderlich | string | Description of the item or service the buyer is paying for. |
| amount1Erforderlich | string | Amount you want to receive, denominated in currency1. |
| currency1Erforderlich | string | The pricing currency of your store (e.g. USDT, BTC, …). |
| currency2Optional | string | The coin the buyer must pay with. Leave blank to let the buyer choose any supported coin. |
| customOptional | string | An identifier passed back on the callback — use it for your order ID or user ID. |
| callback_urlOptional | string | URL that receives the server-to-server POST callback once the payment completes. |
| success_urlOptional | string | URL the buyer is redirected to after a successful payment. |
| cancel_urlOptional | 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