Référence de l’API FaucetPay.
Envoyez des micro-paiements, vérifiez les utilisateurs et consultez les soldes via un seul endpoint REST. Requêtes form-encoded, réponses JSON, une api_key par robinet.
Créez des faucets, des paiements et des automatisations sur FaucetPay.
Une API REST petite et prévisible sur HTTPS. Chaque endpoint accepte des corps POST encodés en formulaire, renvoie du JSON avec un entier status de premier niveau et s'authentifie avec l'api_key de votre faucet. Pas d'OAuth, pas de SDK requis.
REST sur HTTPS
Chaque endpoint accepte des corps POST encodés en formulaire et renvoie du JSON.
Une clé par faucet
Votre api_key de faucet authentifie chaque requête. Gardez-le côté serveur.
Conscient de l'IP
Envoyez ip_address avec /send pour activer la détection d'abus inter-faucets.
https://faucetpay.io/api/v1Envoyez votre api_key à chaque requête.
Passez l'api_key de votre faucet dans le champ api_key de chaque corps POST.
Envoyez votre premier paiement en moins d'une minute.
Remplacez YOUR_API_KEY par une vraie clé de faucet, ciblez un utilisateur de test (votre propre e-mail fonctionne) et lancez.
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"
Forme des requêtes et réponses.
Tous les endpoints sont en POST, encodés en formulaire et renvoient du JSON. L'enveloppe est identique sur tous les endpoints, donc votre code client peut partager la logique de parsing.
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
}Enveloppe de réponse
| Paramètre | Type | Description |
|---|---|---|
| statusRequis | integer | Statut |
| messageRequis | string | Message |
| …Optionnel | varies | Données |
La surface de l'API
Cinq endpoints couvrent tous les scénarios de propriétaire de faucet : envoyer des paiements, vérifier des utilisateurs, consulter des soldes, lister l'historique et inspecter la liste des coins.
/sendSend
Payez de la cryptomonnaie depuis votre solde à un utilisateur FaucetPay.
Paramètres du corps
| Paramètre | Type | Description |
|---|---|---|
| api_keyRequis | string | La clé API de votre faucet. |
| amountRequis | integer | Montant dans la plus petite unité (satoshis pour BTC). |
| toRequis | string | Destination : e-mail, nom d'utilisateur, adresse de portefeuille ou payout_user_hash. |
| currencyRequis | string | Symbole de monnaie en majuscules, ex. BTC, DOGE, USDT. |
| ip_addressOptionnel | string | IP du réclamant — fortement recommandé; permet limitation anti-abus. |
| referralOptionnel | string | Étiquette de parrainage pour ce paiement pour vos rapports. |
Exemple de requête
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"
Exemple de réponse
{
"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
Vérifier qu'une destination est un utilisateur FaucetPay enregistré pour la devise choisie.
Paramètres du corps
| Paramètre | Type | Description |
|---|---|---|
| api_keyRequis | string | La clé API de votre faucet. |
| addressRequis | string | E-mail, nom d'utilisateur, adresse de portefeuille ou payout_user_hash à vérifier. |
| currencyRequis | string | Symbole de monnaie en majuscules pour vérifier l'appartenance. |
Exemple de requête
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"
Exemple de réponse
{
"status": 200,
"message": "This address belongs to a FaucetPay user.",
"payout_user_hash": "3f9c1a2e6b7d0f5e8c4a9b2d1f6e0c8a7b5d2e91"
}/getbalanceCheck balance
Récupérer le solde actuel de votre faucet pour une monnaie donnée.
Paramètres du corps
| Paramètre | Type | Description |
|---|---|---|
| api_keyRequis | string | La clé API de votre faucet. |
| currencyRequis | string | Symbole de monnaie en majuscules. |
Exemple de requête
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"
Exemple de réponse
{
"status": 200,
"message": "OK",
"currency": "BTC",
"balance": 49900,
"balance_bitcoin": 0.00049900
}/payoutsList payouts
Retourner vos paiements les plus récents, les plus récents d'abord.
Paramètres du corps
| Paramètre | Type | Description |
|---|---|---|
| api_keyRequis | string | La clé API de votre faucet. |
| countOptionnel | integer | Combien de paiements retourner (1–100, 10 par défaut). |
| currencyOptionnel | string | Filtrer sur une seule monnaie. Omettre pour toutes. |
Exemple de requête
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"
Exemple de réponse
{
"status": 200,
"message": "OK",
"rewards": [
{
"to": "[email protected]",
"amount": 100,
"date": "02-05-26 21:12:00 GMT"
}
]
}/currenciesSupported currencies
Retourner toutes les monnaies actuellement actives sur FaucetPay.
Paramètres du corps
| Paramètre | Type | Description |
|---|---|---|
| api_keyRequis | string | La clé API de votre faucet. |
Exemple de requête
curl -X POST https://faucetpay.io/api/v1/currencies \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "api_key=YOUR_API_KEY"
Exemple de réponse
{
"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" }
]
}Codes de statut.
Chaque endpoint renvoie l'un de ces codes de statut.
| Code | Tonalité | Signification |
|---|---|---|
| 200 | Succès | OK — requête réussie |
| 403 | Erreur | Interdit — api_key invalide ou manquant |
| 405 | Erreur | Méthode non autorisée — utilisez POST |
| 413 | Avertissement | Charge utile trop grande |
| 414 | Avertissement | URI trop long |
| 415 | Avertissement | Type de média non supporté — utilisez application/x-www-form-urlencoded |
| 416 | Erreur | Plage demandée non satisfaisante |
| 417 | Erreur | Attente échouée |
| 418 | Avertissement | Je suis une théière |
| 419 | Erreur | Délai d'authentification dépassé |
| 420 | Avertissement | Limité par débit — trop de requêtes |
| 421 | Erreur | Requête mal dirigée |
| 422 | Avertissement | Entité non traitable — erreur de validation |
| 456 | Erreur | Erreur irrécupérable |
Coins pris en charge.
Chaque monnaie active sur FaucetPay est disponible pour les paiements.
Limites de débit.
Les limites s'appliquent par api_key de faucet et préservent la santé de votre intégration comme de notre réseau.
60 / min
Par api_key de faucet. Burst jusqu'à 120 toléré.
Fenêtre de burst
De courts bursts au-dessus de la limite sont tolérés jusqu'à 2 secondes.
Bonnes pratiques de sécurité.
Une checklist courte et tranchée. Chaque point correspond à une catégorie d'incident que nous avons observée en conditions réelles.
- N'envoyez jamais votre api_key au navigateur. Traitez-le comme un mot de passe : backend uniquement, gestionnaire de secrets, jamais dans git.
- Envoyez toujours ip_address avec /send. Cela active notre détection d'abus inter-faucets.
- Vérifiez les unités de montant en satoshis. Un bug courant est d'envoyer des valeurs fractionnelles au lieu de l'entier d'unité minimale.
- Dédupliquez les réclamations côté serveur. Ne comptez pas sur le client pour empêcher les doubles soumissions.
- Faites tourner les clés périodiquement. Nous supportons la rotation à chaud : les anciennes clés cessent de fonctionner dès confirmation.
Quelque chose n'est pas clair ?
Ouvrez un ticket sur le centre d'aide et nous mettrons à jour la documentation.
Clés à portée limitée et révocables avec un token Bearer.
L'API v2 est la surface moderne pour l'automatisation. Au lieu d'une unique clé de faucet toute-puissante, vous générez des clés restreintes (read / send / manage / admin), les envoyez comme token Bearer et obtenez une enveloppe JSON cohérente. L'ancienne /api/v1 ci-dessus reste inchangée.
Authentification par jeton Bearer
Envoyez la clé comme Authorization: Bearer '<key>'.
Scopes à privilèges minimaux
Créez des clés avec uniquement les scopes dont un outil a besoin.
Enveloppe JSON cohérente
Chaque réponse v2 utilise la même structure {status, message, data}.
https://faucetpay.io/api/v2Exemple — requête authentifiée
curl -X POST https://faucetpay.io/api/v2/balances \
-H "Authorization: Bearer YOUR_SCOPED_KEY" \
-H "Content-Type: application/json" \
-d '{}'Authentification et portées.
Générez des clés à portée limitée depuis la page Gérer de votre faucet. Chaque clé n'est affichée qu'une fois, stockée hachée, et peut porter une liste blanche d'IP par clé et (pour send) un plafond quotidien en USD.
Lire les soldes, paiements, statistiques, monnaies, paramètres et statut anti-fraude.
Effectuer des paiements — déplace des fonds réels. À garder côté serveur uniquement.
Modifier les paramètres du faucet, limites de débit, liste blanche IP et règles anti-fraude.
Créer un faucet et demander l'approbation d'inscription. Ne peut pas supprimer les faucets.
Endpoints.
Chaque endpoint v2 utilise l'auth Bearer et renvoie l'enveloppe standard.
| Endpoint | Scope | Corps | Description |
|---|---|---|---|
/balance | read | currency? | Vérifier le solde de votre faucet pour une monnaie. |
/balances | read | — | Lister les soldes de toutes les monnaies. |
/currencies | read | — | Lister les monnaies prises en charge. |
/check-address | read | address | Vérifier une adresse de destination. |
/payouts | read | currency?, count? | Lister les paiements récents. |
/faucet | read | — | Obtenir les détails du faucet |
/stats/daily | read | — | Statistiques quotidiennes |
/stats/users | read | coin, page | Statistiques des utilisateurs |
/transactions | read | coin, page | Transactions |
/ratelimits | read | — | Limites de débit |
/low-balance-notification | read | — | Alertes de solde basse |
| Endpoint | Scope | Corps | Description |
|---|---|---|---|
/faucet/update | manage | faucet_name, faucet_domain, faucet_url, faucet_description, timer_minutes, currencies_selected?, categories_selected? | Mettre à jour les paramètres du faucet |
/ratelimits/set | manage | ratelimits[] | Définir les limites de débit |
/ip-whitelist | manage | — | Liste blanche IP |
/ip-whitelist/set | manage | ip_whitelist | Mettre à jour la liste blanche IP |
/low-balance-notification/toggle | manage | — | Activer/désactiver l'alerte de solde basse |
| Endpoint | Scope | Corps | Description |
|---|---|---|---|
/anti-fraud/rules | manage | — | Règles anti-fraude |
/anti-fraud/toggle | manage | — | Activer/désactiver l'anti-fraude |
/anti-fraud/rules/update | manage | trust_rank, negative_rank?, whitelist?, blacklist? | Mettre à jour les règles anti-fraude |
| Endpoint | Scope | Corps | Description |
|---|---|---|---|
/send | send | idempotency_key, currency, amount, to, ip_address?, referral? | Envoyer un paiement |
| Endpoint | Scope | Corps | Description |
|---|---|---|---|
/faucet/create | admin | faucet_name, faucet_domain, faucet_url | Créer un faucet |
/approval-cost | admin | coin | Coût d'approbation d'inscription |
/faucet/request-approval | admin | coin | Demander l'approbation d'inscription |
Envoi de paiements.
Le send v2 est la façon sûre de payer : il requiert une clé d'idempotence et respecte un plafond quotidien optionnel en USD par clé. Il utilise le même chemin anti-fraude / solde / limite de débit que le send hérité.
/sendsendEnvoyer un paiement avec idempotence et plafond quotidien optionnel.
Paramètres du corps
| Paramètre | Type | Description |
|---|---|---|
| idempotency_keyRequis | string | Unique par paiement logique. Une relance avec la même clé ne paie jamais deux fois. |
| toRequis | string | Destinataire : e-mail, nom d'utilisateur, adresse de portefeuille ou payout_user_hash. |
| amountRequis | integer | Montant dans la plus petite unité de la monnaie (ex. satoshis pour BTC). |
| currencyRequis | string | Symbole de monnaie en majuscules, ex. BTC, DOGE. |
| ip_addressOptionnel | string | IP du destinataire — recommandé pour l'anti-fraude. |
| referralOptionnel | string | Étiquette de parrainage pour vos propres rapports. |
Exemple de requête
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"}'Exemple de réponse
{
"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.
Abonnez-vous aux événements de paiement et recevez des POST signés HMAC. Configurez-les depuis la page Gérer de votre faucet — la gestion des webhooks se fait uniquement avec session + 2FA, donc une clé à portée limitée ne peut jamais enregistrer un endpoint de livraison.
Piloté par événements
Abonnez-vous aux événements payout.sent et payout.failed.
Signé HMAC
Chaque livraison inclut un en-tête X-FaucetPay-Signature avec un HMAC-SHA256 du corps.
Protection SSRF
Les URLs de webhook doivent être des endpoints HTTPS publics. Les IPs internes sont rejetées.
Exemple de livraison
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!"
}
}Vérifier la signature
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 utilise les codes de statut HTTP standard plus un message descriptif dans l'enveloppe.
| Code | Tonalité | Signification |
|---|---|---|
| 200 | Succès | 200 OK |
| 400 | Avertissement | 400 Mauvaise requête |
| 401 | Erreur | 401 Non autorisé |
| 403 | Erreur | 403 Interdit |
| 409 | Avertissement | 409 Conflit |
| 429 | Avertissement | 429 Trop de requêtes |
Gérez votre faucet depuis n'importe quel agent IA.
Le serveur MCP de FaucetPay permet à un assistant IA (Cursor, Claude Code, Windsurf, …) de lire votre faucet et d'ajuster les paramètres via le Model Context Protocol. C'est un client léger au-dessus de l'API v2 — read + manage uniquement.
Couche fine
Le serveur MCP est une fine couche sur l'API v2 — pas d'état supplémentaire.
Pas d'outils monétaires
Le serveur n'expose pas d'outils de paiement. Il peut lire et gérer, mais pas envoyer de fonds.
Rien à installer
Le serveur s'exécute à distance. Pointez simplement votre assistant IA sur l'URL.
Connecter et configurer.
Ajoutez le serveur MCP FaucetPay à la config de votre assistant IA. Pointez-le vers votre faucet avec une clé read ou manage restreinte.
// ~/.cursor/mcp.json
{
"mcpServers": {
"faucetpay": {
"url": "https://mcp.faucetpay.io/mcp",
"headers": { "Authorization": "Bearer fpk_your_read_or_manage_key" }
}
}
}Configuration
| Paramètre | Type | Description |
|---|---|---|
| urlRequis | string | URL du serveur MCP |
| AuthorizationRequis | header | Clé API restreinte (scope read ou manage) |
Tools.
Outils en lecture seule et de gestion exposés par le serveur MCP.
Outils de lecture
get_faucetObtenir les détails du faucetget_balancesObtenir les soldes du faucetget_balanceObtenir le solde actuel du faucet pour une monnaie.get_payoutsLister les paiements récentsget_currenciesLister les monnaies prises en charge et leurs limites.check_addressVérifier si une adresse est un utilisateur FaucetPay enregistré.get_daily_statsObtenir les statistiques quotidiennesget_user_statsObtenir les statistiques des utilisateursget_transactionsLister les transactionsget_ratelimitsObtenir les limites de débitget_low_balance_notificationObtenir les paramètres de solde bas
Outils de gestion
get_ip_whitelistObtenir la liste blanche IPset_ip_whitelistMettre à jour la liste blanche IPget_anti_fraudObtenir les paramètres anti-fraudetoggle_anti_fraudActiver/désactiver l'anti-fraudeupdate_anti_fraud_rulesMettre à jour les règles anti-fraudeupdate_faucet_settingsMettre à jour les paramètres du faucetset_ratelimitsDéfinir les limites de débittoggle_low_balance_notificationActiver/désactiver l'alerte de solde basse
Sécurité et bonnes pratiques.
Bonnes pratiques pour utiliser le serveur MCP en toute sécurité.
- Utilisez une clé read ou manage — jamais une clé send. Ce serveur n'expose pas d'outils de paiement.
- Définissez une courte durée. Donnez à la clé une durée de vie pour qu'une config obsolète ne puisse pas être abusée indéfiniment.
- Révoquer instantanément si exposé. Un clic sur la page Manage désactive la clé.
- Tenez compte des avis anti-fraude. Désactiver ou affaiblir l'anti-fraude renvoie un avertissement.
Gagnez plus
Monétisez votre faucet avec le réseau publicitaire 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.
| Paramètre | Type | Description |
|---|---|---|
| merchant_usernameRequis | string | Your FaucetPay username — the account that receives the payment. |
| item_descriptionRequis | string | Description of the item or service the buyer is paying for. |
| amount1Requis | string | Amount you want to receive, denominated in currency1. |
| currency1Requis | string | The pricing currency of your store (e.g. USDT, BTC, …). |
| currency2Optionnel | string | The coin the buyer must pay with. Leave blank to let the buyer choose any supported coin. |
| customOptionnel | string | An identifier passed back on the callback — use it for your order ID or user ID. |
| callback_urlOptionnel | string | URL that receives the server-to-server POST callback once the payment completes. |
| success_urlOptionnel | string | URL the buyer is redirected to after a successful payment. |
| cancel_urlOptionnel | 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