Referencia de la API de FaucetPay.
Envía micropagos, verifica usuarios y consulta saldos con un solo endpoint REST. Solicitudes form-encoded, respuestas JSON, una api_key por faucet.
Crea faucets, pagos y automatizaciones en FaucetPay.
Una API REST pequeña y predecible sobre HTTPS. Cada endpoint acepta cuerpos POST codificados como formulario, devuelve JSON con un entero status de nivel superior y se autentica con el api_key de tu faucet. Sin OAuth ni SDK.
REST sobre HTTPS
Cada endpoint acepta cuerpos POST codificados en formulario y devuelve JSON.
Una clave por faucet
Tu api_key de faucet autentica cada solicitud. Mantenlo en el servidor.
Consciente de IP
Envía ip_address con /send para activar la detección de abuso entre faucets.
https://faucetpay.io/api/v1Envía tu api_key con cada solicitud.
Pasa el api_key de tu faucet en el campo api_key de cada cuerpo POST.
Envía tu primer pago en menos de un minuto.
Reemplaza YOUR_API_KEY con una clave de faucet real, apunta a un usuario de prueba (tu propio email sirve) y lánzalo.
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"
Forma de solicitud y respuesta.
Todos los endpoints son POST, codificados como formulario y devuelven JSON. La envoltura es idéntica en todos los endpoints, por lo que el código de tu cliente puede compartir la lógica 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
}Envoltura de respuesta
| Parámetro | Tipo | Descripción |
|---|---|---|
| statusRequerido | integer | Estado |
| messageRequerido | string | Mensaje |
| …Opcional | varies | Datos |
La superficie de la API
Cinco endpoints cubren todos los escenarios del propietario de faucet: enviar pagos, verificar usuarios, consultar saldos, listar historial e inspeccionar la lista de monedas.
/sendSend
Paga criptomoneda desde el saldo de tu cuenta a un usuario de FaucetPay.
Parámetros del cuerpo
| Parámetro | Tipo | Descripción |
|---|---|---|
| api_keyRequerido | string | La clave API de tu faucet. |
| amountRequerido | integer | Monto en la unidad más pequeña de la moneda (satoshis para BTC). |
| toRequerido | string | Destino: email, usuario, dirección de wallet o payout_user_hash. |
| currencyRequerido | string | Símbolo de moneda en mayúsculas, p.ej. BTC, DOGE, USDT. |
| ip_addressOpcional | string | IP del reclamante — muy recomendado; habilita limitación anti-abuso. |
| referralOpcional | string | Etiqueta de referencia para este pago para tu informe. |
Solicitud de ejemplo
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"
Respuesta de ejemplo
{
"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
Verificar que un destino es un usuario registrado de FaucetPay para la moneda elegida.
Parámetros del cuerpo
| Parámetro | Tipo | Descripción |
|---|---|---|
| api_keyRequerido | string | La clave API de tu faucet. |
| addressRequerido | string | Email, usuario, dirección de wallet o payout_user_hash para verificar. |
| currencyRequerido | string | Símbolo de moneda en mayúsculas para verificar la membresía. |
Solicitud de ejemplo
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"
Respuesta de ejemplo
{
"status": 200,
"message": "This address belongs to a FaucetPay user.",
"payout_user_hash": "3f9c1a2e6b7d0f5e8c4a9b2d1f6e0c8a7b5d2e91"
}/getbalanceCheck balance
Obtener el saldo actual de tu faucet para una moneda dada.
Parámetros del cuerpo
| Parámetro | Tipo | Descripción |
|---|---|---|
| api_keyRequerido | string | La clave API de tu faucet. |
| currencyRequerido | string | Símbolo de moneda en mayúsculas. |
Solicitud de ejemplo
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"
Respuesta de ejemplo
{
"status": 200,
"message": "OK",
"currency": "BTC",
"balance": 49900,
"balance_bitcoin": 0.00049900
}/payoutsList payouts
Devolver tus pagos más recientes, los más nuevos primero.
Parámetros del cuerpo
| Parámetro | Tipo | Descripción |
|---|---|---|
| api_keyRequerido | string | La clave API de tu faucet. |
| countOpcional | integer | Cuántos pagos devolver (1–100, predeterminado 10). |
| currencyOpcional | string | Filtrar a una sola moneda. Omitir para todas. |
Solicitud de ejemplo
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"
Respuesta de ejemplo
{
"status": 200,
"message": "OK",
"rewards": [
{
"to": "[email protected]",
"amount": 100,
"date": "02-05-26 21:12:00 GMT"
}
]
}/currenciesSupported currencies
Devolver todas las monedas actualmente activas en FaucetPay.
Parámetros del cuerpo
| Parámetro | Tipo | Descripción |
|---|---|---|
| api_keyRequerido | string | La clave API de tu faucet. |
Solicitud de ejemplo
curl -X POST https://faucetpay.io/api/v1/currencies \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "api_key=YOUR_API_KEY"
Respuesta de ejemplo
{
"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" }
]
}Códigos de estado.
Cada endpoint devuelve uno de estos códigos de estado.
| Código | Tono | Significado |
|---|---|---|
| 200 | Éxito | OK — solicitud exitosa |
| 403 | Error | Prohibido — api_key inválido o ausente |
| 405 | Error | Método no permitido — usa POST |
| 413 | Advertencia | Carga útil demasiado grande |
| 414 | Advertencia | URI demasiado larga |
| 415 | Advertencia | Tipo de medio no soportado — usa application/x-www-form-urlencoded |
| 416 | Error | Rango solicitado no satisfactorio |
| 417 | Error | Expectativa fallida |
| 418 | Advertencia | Soy una tetera |
| 419 | Error | Tiempo de autenticación agotado |
| 420 | Advertencia | Limitado por tasa — demasiadas solicitudes |
| 421 | Error | Solicitud mal dirigida |
| 422 | Advertencia | Entidad no procesable — error de validación |
| 456 | Error | Error irrecuperable |
Monedas compatibles.
Cada moneda activa en FaucetPay está disponible para pagos.
Límites de tasa.
Los límites se aplican por api_key de faucet y mantienen sanas tanto tu integración como nuestra red.
60 / min
Por api_key de faucet. Burst hasta 120 tolerado.
Ventana de burst
Breves ráfagas sobre el límite son toleradas hasta 2 segundos.
Buenas prácticas de seguridad.
Una lista corta y con criterio. Cada punto corresponde a un tipo de incidente que hemos visto en la práctica.
- Nunca envíes tu api_key al navegador. Trátalo como una contraseña: solo backend, gestor de secretos, nunca en git.
- Envía siempre ip_address con /send. Activa nuestra detección de abuso entre faucets.
- Verifica las unidades de monto en satoshis. Un error común es enviar valores fraccionales en lugar del entero de unidad mínima.
- Deduplica reclamaciones en el servidor. No confíes en el cliente para evitar envíos dobles.
- Rota claves periódicamente. Soportamos rotación en caliente: las claves antiguas dejan de funcionar al confirmar.
¿Algo no está claro?
Abre un ticket en el centro de ayuda y actualizaremos la documentación.
Claves con alcance y revocables con un token Bearer.
La API v2 es la superficie moderna para la automatización. En lugar de una única clave de faucet todopoderosa, generas claves acotadas (read / send / manage / admin), las envías como token Bearer y obtienes una envoltura JSON consistente. La /api/v1 heredada de arriba no cambia.
Autenticación con token Bearer
Envía la clave como Authorization: Bearer '<key>'.
Scopes de mínimos privilegios
Crea claves solo con los scopes que necesita una herramienta.
Envelope JSON consistente
Cada respuesta v2 usa la misma estructura {status, message, data}.
https://faucetpay.io/api/v2Ejemplo — solicitud autenticada
curl -X POST https://faucetpay.io/api/v2/balances \
-H "Authorization: Bearer YOUR_SCOPED_KEY" \
-H "Content-Type: application/json" \
-d '{}'Autenticación y alcances.
Genera claves con alcance desde la página Gestionar de tu faucet. Cada clave se muestra una sola vez, se almacena con hash y puede llevar una lista blanca de IP por clave y (para send) un límite diario en USD.
Leer saldos, pagos, estadísticas, monedas, configuraciones y estado antifraude.
Realizar pagos — mueve fondos reales. Mantener solo en el servidor.
Cambiar configuración del faucet, límites de tasa, lista blanca de IP y reglas antifraude.
Crear un faucet y solicitar aprobación de listado. No puede eliminar faucets.
Endpoints.
Cada endpoint v2 usa autenticación Bearer y devuelve el envelope estándar.
| Endpoint | Scope | Cuerpo | Descripción |
|---|---|---|---|
/balance | read | currency? | Verificar el saldo de tu faucet para una moneda. |
/balances | read | — | Listar saldos de todas las monedas. |
/currencies | read | — | Listar monedas soportadas. |
/check-address | read | address | Verificar una dirección de destino. |
/payouts | read | currency?, count? | Listar pagos recientes. |
/faucet | read | — | Obtener detalles del faucet |
/stats/daily | read | — | Estadísticas diarias |
/stats/users | read | coin, page | Estadísticas de usuarios |
/transactions | read | coin, page | Transacciones |
/ratelimits | read | — | Límites de tasa |
/low-balance-notification | read | — | Alertas de saldo bajo |
| Endpoint | Scope | Cuerpo | Descripción |
|---|---|---|---|
/faucet/update | manage | faucet_name, faucet_domain, faucet_url, faucet_description, timer_minutes, currencies_selected?, categories_selected? | Actualizar configuración del faucet |
/ratelimits/set | manage | ratelimits[] | Establecer límites de tasa |
/ip-whitelist | manage | — | Lista blanca de IP |
/ip-whitelist/set | manage | ip_whitelist | Actualizar lista blanca de IP |
/low-balance-notification/toggle | manage | — | Alternar alerta de saldo bajo |
| Endpoint | Scope | Cuerpo | Descripción |
|---|---|---|---|
/anti-fraud/rules | manage | — | Reglas antifraude |
/anti-fraud/toggle | manage | — | Alternar antifraude |
/anti-fraud/rules/update | manage | trust_rank, negative_rank?, whitelist?, blacklist? | Actualizar reglas antifraude |
| Endpoint | Scope | Cuerpo | Descripción |
|---|---|---|---|
/send | send | idempotency_key, currency, amount, to, ip_address?, referral? | Enviar pago |
| Endpoint | Scope | Cuerpo | Descripción |
|---|---|---|---|
/faucet/create | admin | faucet_name, faucet_domain, faucet_url | Crear faucet |
/approval-cost | admin | coin | Costo de aprobación de listado |
/faucet/request-approval | admin | coin | Solicitar aprobación de listado |
Envío de pagos.
El send de v2 es la forma segura de pagar: requiere una clave de idempotencia y respeta un límite diario opcional en USD por clave. Usa la misma ruta de antifraude / saldo / límite de tasa que el send heredado.
/sendsendEnviar pago con idempotencia y límite diario opcional.
Parámetros del cuerpo
| Parámetro | Tipo | Descripción |
|---|---|---|
| idempotency_keyRequerido | string | Único por pago lógico. Un reintento con la misma clave nunca paga dos veces. |
| toRequerido | string | Destinatario: email, nombre de usuario, dirección de wallet o payout_user_hash. |
| amountRequerido | integer | Monto en la unidad más pequeña de la moneda (p.ej. satoshis para BTC). |
| currencyRequerido | string | Símbolo de moneda en mayúsculas, p.ej. BTC, DOGE. |
| ip_addressOpcional | string | IP del destinatario — recomendado para antifraude. |
| referralOpcional | string | Etiqueta de referencia para tu propio informe. |
Solicitud de ejemplo
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"}'Respuesta de ejemplo
{
"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.
Suscríbete a los eventos de pago y recibe POSTs firmados con HMAC. Configúralos desde la página Gestionar de tu faucet: la gestión de webhooks es solo con sesión + 2FA, por lo que una clave con alcance nunca puede registrar un endpoint de entrega.
Basado en eventos
Suscríbete a eventos payout.sent y payout.failed.
Firmado con HMAC
Cada entrega incluye un encabezado X-FaucetPay-Signature con un HMAC-SHA256 del cuerpo.
Protección SSRF
Las URLs de webhook deben ser endpoints HTTPS públicos. Las IPs internas son rechazadas.
Entrega de ejemplo
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 códigos de estado HTTP estándar más un mensaje descriptivo en el envelope.
| Código | Tono | Significado |
|---|---|---|
| 200 | Éxito | 200 OK |
| 400 | Advertencia | 400 Solicitud incorrecta |
| 401 | Error | 401 No autorizado |
| 403 | Error | 403 Prohibido |
| 409 | Advertencia | 409 Conflicto |
| 429 | Advertencia | 429 Demasiadas solicitudes |
Gestiona tu faucet desde cualquier agente de IA.
El servidor MCP de FaucetPay permite que un asistente de IA (Cursor, Claude Code, Windsurf, …) lea tu faucet y ajuste configuraciones mediante el Model Context Protocol. Es un cliente ligero sobre la API v2: solo read + manage.
Capa fina
El servidor MCP es un wrapper fino sobre la API v2 — sin estado adicional.
Sin herramientas de dinero
El servidor no expone herramientas de pago. Puede leer y gestionar, pero no enviar fondos.
Nada que instalar
El servidor se ejecuta de forma remota. Solo apunta tu asistente de IA a la URL.
Conecta y configura.
Añade el servidor MCP de FaucetPay a la configuración de tu asistente de IA. Apúntalo a tu faucet con una clave de lectura o gestión con ámbito.
// ~/.cursor/mcp.json
{
"mcpServers": {
"faucetpay": {
"url": "https://mcp.faucetpay.io/mcp",
"headers": { "Authorization": "Bearer fpk_your_read_or_manage_key" }
}
}
}Configuración
| Parámetro | Tipo | Descripción |
|---|---|---|
| urlRequerido | string | URL del servidor MCP |
| AuthorizationRequerido | header | Clave API con ámbito (scope de lectura o gestión) |
Tools.
Herramientas de solo lectura y gestión expuestas por el servidor MCP.
Herramientas de lectura
get_faucetObtener detalles del faucetget_balancesObtener saldos del faucetget_balanceObtener el saldo actual del faucet para una moneda.get_payoutsListar pagos recientesget_currenciesListar monedas soportadas y sus límites.check_addressVerificar si una dirección es un usuario registrado de FaucetPay.get_daily_statsObtener estadísticas diariasget_user_statsObtener estadísticas de usuariosget_transactionsListar transaccionesget_ratelimitsObtener límites de tasaget_low_balance_notificationObtener configuración de saldo bajo
Herramientas de gestión
get_ip_whitelistObtener lista blanca de IPset_ip_whitelistActualizar lista blanca de IPget_anti_fraudObtener configuración antifraudetoggle_anti_fraudAlternar antifraudeupdate_anti_fraud_rulesActualizar reglas antifraudeupdate_faucet_settingsActualizar configuración del faucetset_ratelimitsEstablecer límites de tasatoggle_low_balance_notificationAlternar alerta de saldo bajo
Seguridad y buenas prácticas.
Mejores prácticas para usar el servidor MCP de forma segura.
- Usa una clave de lectura o gestión — nunca una de envío. Este servidor no expone herramientas de pago.
- Establece una corta duración. Dale a la clave una vida útil para que una config obsoleta no pueda abusarse para siempre.
- Revocar al instante si se expone. Un clic en la página Manage desactiva la clave.
- Haz caso de los avisos antifraude. Desactivar o debilitar el antifraude devuelve una advertencia.
Gana más
Monetiza tu faucet con la red de anuncios de 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.
| Parámetro | Tipo | Descripción |
|---|---|---|
| merchant_usernameRequerido | string | Your FaucetPay username — the account that receives the payment. |
| item_descriptionRequerido | string | Description of the item or service the buyer is paying for. |
| amount1Requerido | string | Amount you want to receive, denominated in currency1. |
| currency1Requerido | string | The pricing currency of your store (e.g. USDT, BTC, …). |
| currency2Opcional | string | The coin the buyer must pay with. Leave blank to let the buyer choose any supported coin. |
| customOpcional | string | An identifier passed back on the callback — use it for your order ID or user ID. |
| callback_urlOpcional | string | URL that receives the server-to-server POST callback once the payment completes. |
| success_urlOpcional | string | URL the buyer is redirected to after a successful payment. |
| cancel_urlOpcional | 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