Riferimento API FaucetPay.
Invia micro-pagamenti, verifica utenti e consulta i saldi tramite un unico endpoint REST. Richieste form-encoded, risposte JSON, una api_key per faucet.
Crea faucet, pagamenti e automazioni su FaucetPay.
Una REST API piccola e prevedibile su HTTPS. Ogni endpoint accetta body POST form-encoded, restituisce JSON con un intero status di primo livello e si autentica con l'api_key del tuo faucet. Niente OAuth, nessun SDK necessario.
REST su HTTPS
Ogni endpoint accetta corpi POST form-encoded e restituisce JSON.
Una chiave per faucet
Il tuo api_key di faucet autentica ogni richiesta. Tienilo lato server.
Consapevole dell'IP
Invia ip_address con /send per attivare il rilevamento di abusi cross-faucet.
https://faucetpay.io/api/v1Invia la tua api_key a ogni richiesta.
Passa l'api_key del tuo faucet nel campo api_key di ogni corpo POST.
Invia il tuo primo pagamento in meno di un minuto.
Sostituisci YOUR_API_KEY con una vera chiave del faucet, scegli un utente di test (va bene la tua email) e invia.
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"
Struttura di richiesta e risposta.
Tutti gli endpoint sono POST, form-encoded e restituiscono JSON. L'envelope è identico su tutti gli endpoint, così il codice del tuo client può condividere la logica di 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
}Envelope di risposta
| Parametro | Tipo | Descrizione |
|---|---|---|
| statusObbligatorio | integer | Stato |
| messageObbligatorio | string | Messaggio |
| …Opzionale | varies | Dati |
La superficie dell'API
Cinque endpoint coprono ogni scenario del proprietario di faucet: inviare pagamenti, verificare utenti, controllare saldi, elencare lo storico e ispezionare la lista delle coin.
/sendSend
Paga criptovaluta dal saldo del tuo account a un utente FaucetPay.
Parametri del body
| Parametro | Tipo | Descrizione |
|---|---|---|
| api_keyObbligatorio | string | La chiave API del tuo faucet. |
| amountObbligatorio | integer | Importo nella più piccola unità (satoshi per BTC). |
| toObbligatorio | string | Destinazione: email, nome utente, indirizzo portafoglio o payout_user_hash. |
| currencyObbligatorio | string | Simbolo valuta maiuscolo, es. BTC, DOGE, USDT. |
| ip_addressOpzionale | string | IP del claimant — fortemente raccomandato; abilita rate limiting anti-abuso. |
| referralOpzionale | string | Tag referral per questo payout per i tuoi report. |
Richiesta di esempio
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"
Risposta di esempio
{
"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
Verificare che una destinazione sia un utente FaucetPay registrato per la valuta scelta.
Parametri del body
| Parametro | Tipo | Descrizione |
|---|---|---|
| api_keyObbligatorio | string | La chiave API del tuo faucet. |
| addressObbligatorio | string | Email, nome utente, indirizzo portafoglio o payout_user_hash da verificare. |
| currencyObbligatorio | string | Simbolo valuta maiuscolo per verificare l'appartenenza. |
Richiesta di esempio
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"
Risposta di esempio
{
"status": 200,
"message": "This address belongs to a FaucetPay user.",
"payout_user_hash": "3f9c1a2e6b7d0f5e8c4a9b2d1f6e0c8a7b5d2e91"
}/getbalanceCheck balance
Ottenere il saldo attuale del faucet per una determinata moneta.
Parametri del body
| Parametro | Tipo | Descrizione |
|---|---|---|
| api_keyObbligatorio | string | La chiave API del tuo faucet. |
| currencyObbligatorio | string | Simbolo valuta maiuscolo. |
Richiesta di esempio
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"
Risposta di esempio
{
"status": 200,
"message": "OK",
"currency": "BTC",
"balance": 49900,
"balance_bitcoin": 0.00049900
}/payoutsList payouts
Restituisci i tuoi payout più recenti, prima i più nuovi.
Parametri del body
| Parametro | Tipo | Descrizione |
|---|---|---|
| api_keyObbligatorio | string | La chiave API del tuo faucet. |
| countOpzionale | integer | Quanti payout restituire (1–100, predefinito 10). |
| currencyOpzionale | string | Filtra su una singola moneta. Ometti per tutte. |
Richiesta di esempio
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"
Risposta di esempio
{
"status": 200,
"message": "OK",
"rewards": [
{
"to": "[email protected]",
"amount": 100,
"date": "02-05-26 21:12:00 GMT"
}
]
}/currenciesSupported currencies
Restituire ogni valuta attualmente attiva su FaucetPay.
Parametri del body
| Parametro | Tipo | Descrizione |
|---|---|---|
| api_keyObbligatorio | string | La chiave API del tuo faucet. |
Richiesta di esempio
curl -X POST https://faucetpay.io/api/v1/currencies \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "api_key=YOUR_API_KEY"
Risposta di esempio
{
"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" }
]
}Codici di stato.
Ogni endpoint restituisce uno di questi codici di stato.
| Codice | Tono | Significato |
|---|---|---|
| 200 | Success | OK — richiesta riuscita |
| 403 | Errore | Proibito — api_key invalido o mancante |
| 405 | Errore | Metodo non consentito — usa POST |
| 413 | Avviso | Payload troppo grande |
| 414 | Avviso | URI troppo lungo |
| 415 | Avviso | Tipo di media non supportato — usa application/x-www-form-urlencoded |
| 416 | Errore | Range richiesto non soddisfacibile |
| 417 | Errore | Expectation échouée |
| 418 | Avviso | Sono una teiera |
| 419 | Errore | Timeout di autenticazione |
| 420 | Avviso | Rate limitato — troppe richieste |
| 421 | Errore | Richiesta mal indirizzata |
| 422 | Avviso | Entità non elaborabile — errore di validazione |
| 456 | Errore | Errore irreversibile |
Coin supportate.
Ogni moneta attiva su FaucetPay è disponibile per i payout.
Limiti di frequenza.
I limiti sono applicati per api_key del faucet e mantengono sani sia la tua integrazione sia la nostra rete.
60 / min
Per api_key di faucet. Burst fino a 120 tollerato.
Finestra di burst
Brevi burst sopra il limite sono tollerati fino a 2 secondi.
Best practice di sicurezza.
Una checklist breve e decisa. Ogni voce corrisponde a una categoria di incidente che abbiamo visto sul campo.
- Non inviare mai il tuo api_key al browser. Trattalo come una password: solo backend, gestore segreti, mai in git.
- Invia sempre ip_address con /send. Attiva il rilevamento di abusi cross-faucet.
- Verifica le unità di importo in satoshi. Un bug comune è inviare valori frazionari invece dell'intero di unità minima.
- Deduplica i claim lato server. Non affidarti al client per prevenire doppioni.
- Ruota le chiavi periodicamente. Supportiamo la rotazione a caldo: le vecchie chiavi smettono di funzionare alla conferma.
Qualcosa non è chiaro?
Apri un ticket sull'help desk e aggiorneremo la documentazione.
Chiavi con scope e revocabili con un token Bearer.
L'API v2 è la superficie moderna per l'automazione. Invece di un'unica chiave del faucet onnipotente, generi chiavi ristrette (read / send / manage / admin), le invii come token Bearer e ottieni un envelope JSON coerente. La /api/v1 legacy qui sopra è invariata.
Autenticazione con token Bearer
Invia la chiave come Authorization: Bearer '<key>'.
Scope a minimo privilegio
Crea chiavi solo con gli scope di cui uno strumento ha bisogno.
Envelope JSON consistente
Ogni risposta v2 usa la stessa struttura {status, message, data}.
https://faucetpay.io/api/v2Esempio — richiesta autenticata
curl -X POST https://faucetpay.io/api/v2/balances \
-H "Authorization: Bearer YOUR_SCOPED_KEY" \
-H "Content-Type: application/json" \
-d '{}'Autenticazione e scope.
Genera chiavi con scope dalla pagina Gestisci del tuo faucet. Ogni chiave viene mostrata una sola volta, memorizzata con hash e può avere una IP whitelist per chiave e (per send) un limite giornaliero in USD.
Leggere saldi, payout, statistiche, valute, impostazioni e stato anti-frode.
Effettuare payout — muove fondi reali. Solo lato server.
Cambiare impostazioni faucet, rate limit, whitelist IP e regole anti-frode.
Creare un faucet e richiedere l'approvazione dell'inserzione. Non può eliminare faucet.
Endpoints.
Ogni endpoint v2 usa auth Bearer e restituisce l'envelope standard.
| Endpoint | Scope | Corpo | Descrizione |
|---|---|---|---|
/balance | read | currency? | Controlla il saldo del faucet per una moneta. |
/balances | read | — | Elenca i saldi di tutte le monete. |
/currencies | read | — | Elenca le valute supportate. |
/check-address | read | address | Verificare un indirizzo di destinazione. |
/payouts | read | currency?, count? | Elenca i payout recenti. |
/faucet | read | — | Ottieni dettagli faucet |
/stats/daily | read | — | Statistiche giornaliere |
/stats/users | read | coin, page | Statistiche degli utenti |
/transactions | read | coin, page | Transazioni |
/ratelimits | read | — | Rate limit |
/low-balance-notification | read | — | Avvisi saldo basso |
| Endpoint | Scope | Corpo | Descrizione |
|---|---|---|---|
/faucet/update | manage | faucet_name, faucet_domain, faucet_url, faucet_description, timer_minutes, currencies_selected?, categories_selected? | Aggiorna impostazioni faucet |
/ratelimits/set | manage | ratelimits[] | Imposta rate limit |
/ip-whitelist | manage | — | Whitelist IP |
/ip-whitelist/set | manage | ip_whitelist | Aggiorna whitelist IP |
/low-balance-notification/toggle | manage | — | Attiva/disattiva avviso saldo basso |
| Endpoint | Scope | Corpo | Descrizione |
|---|---|---|---|
/anti-fraud/rules | manage | — | Regole anti-frode |
/anti-fraud/toggle | manage | — | Attiva/disattiva anti-frode |
/anti-fraud/rules/update | manage | trust_rank, negative_rank?, whitelist?, blacklist? | Aggiorna regole anti-frode |
| Endpoint | Scope | Corpo | Descrizione |
|---|---|---|---|
/send | send | idempotency_key, currency, amount, to, ip_address?, referral? | Invia payout |
| Endpoint | Scope | Corpo | Descrizione |
|---|---|---|---|
/faucet/create | admin | faucet_name, faucet_domain, faucet_url | Crea faucet |
/approval-cost | admin | coin | Costo approvazione inserzione |
/faucet/request-approval | admin | coin | Richiedi approvazione inserzione |
Invio dei pagamenti.
Il send v2 è il modo sicuro per pagare: richiede una chiave di idempotenza e rispetta un limite giornaliero opzionale in USD per chiave. Usa lo stesso percorso anti-frode / saldo / rate-limit del send legacy.
/sendsendInvia payout con idempotenza e limite giornaliero opzionale.
Parametri del body
| Parametro | Tipo | Descrizione |
|---|---|---|
| idempotency_keyObbligatorio | string | Univoco per payout logico. Un retry con la stessa chiave non paga mai due volte. |
| toObbligatorio | string | Destinatario: email, nome utente, indirizzo portafoglio o payout_user_hash. |
| amountObbligatorio | integer | Importo nella più piccola unità della moneta (es. satoshi per BTC). |
| currencyObbligatorio | string | Simbolo valuta maiuscolo, es. BTC, DOGE. |
| ip_addressOpzionale | string | IP del destinatario — raccomandato per anti-frode. |
| referralOpzionale | string | Tag referral per i tuoi report. |
Richiesta di esempio
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"}'Risposta di esempio
{
"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.
Iscriviti agli eventi di pagamento e ricevi POST firmati con HMAC. Configurali dalla pagina Gestisci del tuo faucet — la gestione dei webhook è solo con sessione + 2FA, quindi una chiave con scope non può mai registrare un endpoint di delivery.
Basato su eventi
Iscriviti agli eventi payout.sent e payout.failed.
Firmato HMAC
Ogni consegna include un header X-FaucetPay-Signature con un HMAC-SHA256 del body.
Protezione SSRF
Gli URL webhook devono essere endpoint HTTPS pubblici. Gli IP interni sono rifiutati.
Esempio di 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!"
}
}Verifica la firma
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 usa codici di stato HTTP standard più un messaggio descrittivo nell'envelope.
| Codice | Tono | Significato |
|---|---|---|
| 200 | Success | 200 OK |
| 400 | Avviso | 400 Richiesta errata |
| 401 | Errore | 401 Non autorizzato |
| 403 | Errore | 403 Proibito |
| 409 | Avviso | 409 Conflitto |
| 429 | Avviso | 429 Troppe richieste |
Gestisci il tuo faucet da qualsiasi agente AI.
Il server MCP di FaucetPay consente a un assistente AI (Cursor, Claude Code, Windsurf, …) di leggere il tuo faucet e regolare le impostazioni tramite il Model Context Protocol. È un thin client sopra l'API v2 — solo read + manage.
Strato sottile
Il server MCP è un wrapper sottile sull'API v2 — nessuno stato extra.
Nessuno strumento di denaro
Il server non espone strumenti di payout. Può leggere e gestire, ma non inviare fondi.
Niente da installare
Il server viene eseguito in remoto. Punta il tuo assistente IA all'URL.
Connetti e configura.
Aggiungi il server MCP FaucetPay alla configurazione del tuo assistente IA. Punta al tuo faucet con una chiave read o manage con scope.
// ~/.cursor/mcp.json
{
"mcpServers": {
"faucetpay": {
"url": "https://mcp.faucetpay.io/mcp",
"headers": { "Authorization": "Bearer fpk_your_read_or_manage_key" }
}
}
}Configurazione
| Parametro | Tipo | Descrizione |
|---|---|---|
| urlObbligatorio | string | URL del server MCP |
| AuthorizationObbligatorio | header | Chiave API con scope (scope read o manage) |
Tools.
Strumenti read-only e di gestione esposti dal server MCP.
Strumenti di lettura
get_faucetOttieni dettagli faucetget_balancesOttieni saldi faucetget_balanceOttieni il saldo attuale del faucet per una moneta.get_payoutsElenca i payout recentiget_currenciesElenca le valute supportate e i loro limiti.check_addressVerificare se un indirizzo è un utente FaucetPay registrato.get_daily_statsOttieni statistiche giornaliereget_user_statsOttieni statistiche degli utentiget_transactionsElenca le transazioniget_ratelimitsOttieni rate limitget_low_balance_notificationOttieni impostazioni saldo basso
Strumenti di gestione
get_ip_whitelistOttieni whitelist IPset_ip_whitelistAggiorna whitelist IPget_anti_fraudOttieni impostazioni anti-frodetoggle_anti_fraudAttiva/disattiva anti-frodeupdate_anti_fraud_rulesAggiorna regole anti-frodeupdate_faucet_settingsAggiorna impostazioni faucetset_ratelimitsImposta rate limittoggle_low_balance_notificationAttiva/disattiva avviso saldo basso
Sicurezza e best practice.
Best practice per usare il server MCP in modo sicuro.
- Usa una chiave read o manage — mai una send. Questo server non espone strumenti di payout.
- Imposta una breve scadenza. Dai alla chiave una durata così una config stale non può essere abusata per sempre.
- Revoca immediatamente se esposto. Un clic sulla pagina Manage disattiva la chiave.
- Segui gli avvisi anti-frode. Disabilitare o indebolire l'anti-frode restituisce un avviso.
Guadagna di più
Monetizza il tuo faucet con la rete pubblicitaria 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.
| Parametro | Tipo | Descrizione |
|---|---|---|
| merchant_usernameObbligatorio | string | Your FaucetPay username — the account that receives the payment. |
| item_descriptionObbligatorio | string | Description of the item or service the buyer is paying for. |
| amount1Obbligatorio | string | Amount you want to receive, denominated in currency1. |
| currency1Obbligatorio | string | The pricing currency of your store (e.g. USDT, BTC, …). |
| currency2Opzionale | string | The coin the buyer must pay with. Leave blank to let the buyer choose any supported coin. |
| customOpzionale | string | An identifier passed back on the callback — use it for your order ID or user ID. |
| callback_urlOpzionale | string | URL that receives the server-to-server POST callback once the payment completes. |
| success_urlOpzionale | string | URL the buyer is redirected to after a successful payment. |
| cancel_urlOpzionale | 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