Referência da API da FaucetPay.
Envie micropagamentos, verifique usuários e consulte saldos por um único endpoint REST. Requisições form-encoded, respostas JSON, uma api_key por torneira.
Crie faucets, pagamentos e automações no FaucetPay.
Uma API REST pequena e previsível sobre HTTPS. Cada endpoint aceita corpos POST codificados como formulário, retorna JSON com um inteiro status de nível superior e autentica com o api_key do seu faucet. Sem OAuth, sem SDK.
REST sobre HTTPS
Cada endpoint aceita corpos POST form-encoded e retorna JSON.
Uma chave por faucet
Seu api_key de faucet autentica cada solicitação. Mantenha-o no servidor.
Ciente de IP
Envie ip_address com /send para ativar a detecção de abuso entre faucets.
https://faucetpay.io/api/v1Envie seu api_key em cada requisição.
Passe o api_key do seu faucet no campo api_key de cada corpo POST.
Envie seu primeiro pagamento em menos de um minuto.
Substitua YOUR_API_KEY por uma chave de faucet real, escolha um usuário de teste (seu próprio email funciona) e dispare.
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"
Formato de requisição e resposta.
Todos os endpoints são POST, codificados como formulário e retornam JSON. O envelope é idêntico em todos os endpoints, então o código do seu cliente pode compartilhar a 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
}Envelope de resposta
| Parâmetro | Tipo | Descrição |
|---|---|---|
| statusObrigatório | integer | Status |
| messageObrigatório | string | Mensagem |
| …Opcional | varies | Dados |
A superfície da API
Cinco endpoints cobrem todos os cenários do dono do faucet: enviar pagamentos, verificar usuários, consultar saldos, listar histórico e inspecionar a lista de moedas.
/sendSend
Pague criptomoeda do saldo da sua conta para um usuário FaucetPay.
Parâmetros do corpo
| Parâmetro | Tipo | Descrição |
|---|---|---|
| api_keyObrigatório | string | A chave API do seu faucet. |
| amountObrigatório | integer | Valor na menor unidade da moeda (satoshis para BTC). |
| toObrigatório | string | Destino: e-mail, usuário, endereço da carteira ou payout_user_hash. |
| currencyObrigatório | string | Símbolo da moeda em maiúsculas, ex. BTC, DOGE, USDT. |
| ip_addressOpcional | string | IP do claimer — altamente recomendado; habilita limitação anti-abuso. |
| referralOpcional | string | Tag de referência para este pagamento para seus relatórios. |
Requisição de exemplo
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"
Resposta de exemplo
{
"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 se um destino é um usuário registrado do FaucetPay para a moeda escolhida.
Parâmetros do corpo
| Parâmetro | Tipo | Descrição |
|---|---|---|
| api_keyObrigatório | string | A chave API do seu faucet. |
| addressObrigatório | string | E-mail, usuário, endereço da carteira ou payout_user_hash para verificar. |
| currencyObrigatório | string | Símbolo da moeda em maiúsculas para verificar associação. |
Requisição de exemplo
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"
Resposta de exemplo
{
"status": 200,
"message": "This address belongs to a FaucetPay user.",
"payout_user_hash": "3f9c1a2e6b7d0f5e8c4a9b2d1f6e0c8a7b5d2e91"
}/getbalanceCheck balance
Obter o saldo atual do seu faucet para uma moeda específica.
Parâmetros do corpo
| Parâmetro | Tipo | Descrição |
|---|---|---|
| api_keyObrigatório | string | A chave API do seu faucet. |
| currencyObrigatório | string | Símbolo da moeda em maiúsculas. |
Requisição de exemplo
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"
Resposta de exemplo
{
"status": 200,
"message": "OK",
"currency": "BTC",
"balance": 49900,
"balance_bitcoin": 0.00049900
}/payoutsList payouts
Retornar seus pagamentos mais recentes, os mais novos primeiro.
Parâmetros do corpo
| Parâmetro | Tipo | Descrição |
|---|---|---|
| api_keyObrigatório | string | A chave API do seu faucet. |
| countOpcional | integer | Quantos pagamentos retornar (1–100, padrão 10). |
| currencyOpcional | string | Filtrar para uma única moeda. Omita para todas. |
Requisição de exemplo
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"
Resposta de exemplo
{
"status": 200,
"message": "OK",
"rewards": [
{
"to": "[email protected]",
"amount": 100,
"date": "02-05-26 21:12:00 GMT"
}
]
}/currenciesSupported currencies
Retornar todas as moedas atualmente ativas no FaucetPay.
Parâmetros do corpo
| Parâmetro | Tipo | Descrição |
|---|---|---|
| api_keyObrigatório | string | A chave API do seu faucet. |
Requisição de exemplo
curl -X POST https://faucetpay.io/api/v1/currencies \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "api_key=YOUR_API_KEY"
Resposta de exemplo
{
"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 status.
Cada endpoint retorna um destes códigos de status.
| Código | Tom | Significado |
|---|---|---|
| 200 | Sucesso | OK — solicitação bem-sucedida |
| 403 | Erro | Proibido — api_key inválido ou ausente |
| 405 | Erro | Método não permitido — use POST |
| 413 | Aviso | Payload muito grande |
| 414 | Aviso | URI muito longa |
| 415 | Aviso | Tipo de mídia não suportado — use application/x-www-form-urlencoded |
| 416 | Erro | Intervalo solicitado não satisfatório |
| 417 | Erro | Expectativa falhou |
| 418 | Aviso | Eu sou um bule |
| 419 | Erro | Tempo limite de autenticação |
| 420 | Aviso | Limitado por taxa — muitas solicitações |
| 421 | Erro | Solicitação mal direcionada |
| 422 | Aviso | Entidade não processável — erro de validação |
| 456 | Erro | Erro irrecuperável |
Moedas suportadas.
Cada moeda ativa no FaucetPay está disponível para pagamentos.
Limites de taxa.
Os limites são aplicados por api_key de faucet e mantêm tanto sua integração quanto nossa rede saudáveis.
60 / min
Por api_key de faucet. Burst até 120 tolerado.
Janela de burst
Curtos bursts acima do limite são tolerados por até 2 segundos.
Boas práticas de segurança.
Uma checklist curta e direta. Cada item corresponde a uma classe de incidente que já vimos na prática.
- Nunca envie seu api_key ao navegador. Trate-o como senha: apenas backend, gerenciador de segredos, nunca no git.
- Envie sempre ip_address com /send. Ativa a detecção de abuso entre faucets.
- Verifique as unidades de valor em satoshis. Um bug comum é enviar valores fracionários em vez do inteiro de unidade mínima.
- Deduplique reivindicações no servidor. Não dependa do cliente para evitar envios duplicados.
- Rotacione chaves periodicamente. Suportamos rotação a quente: chaves antigas param ao confirmar.
Algo não está claro?
Abra um ticket no central de ajuda e atualizaremos a documentação.
Chaves com escopo e revogáveis com um token Bearer.
A API v2 é a superfície moderna para automação. Em vez de uma única chave de faucet todo-poderosa, você gera chaves restritas (read / send / manage / admin), envia-as como token Bearer e recebe um envelope JSON consistente. A /api/v1 legada acima permanece inalterada.
Autenticação por token Bearer
Envie a chave como Authorization: Bearer '<key>'.
Scopes de menor privilégio
Crie chaves apenas com os escopos que uma ferramenta precisa.
Envelope JSON consistente
Cada resposta v2 usa a mesma estrutura {status, message, data}.
https://faucetpay.io/api/v2Exemplo — requisição autenticada
curl -X POST https://faucetpay.io/api/v2/balances \
-H "Authorization: Bearer YOUR_SCOPED_KEY" \
-H "Content-Type: application/json" \
-d '{}'Autenticação e escopos.
Gere chaves com escopo na página Gerenciar do seu faucet. Cada chave é exibida uma única vez, armazenada com hash e pode ter uma whitelist de IP por chave e (para send) um limite diário em USD.
Ler saldos, pagamentos, estatísticas, moedas, configurações e status antifraude.
Fazer pagamentos — move fundos reais. Manter apenas no servidor.
Alterar configurações do faucet, limites de taxa, lista branca de IP e regras antifraude.
Criar um faucet e solicitar aprovação de listagem. Não pode excluir faucets.
Endpoints.
Cada endpoint v2 usa autenticação Bearer e retorna o envelope padrão.
| Endpoint | Escopo | Corpo | Descrição |
|---|---|---|---|
/balance | read | currency? | Verificar o saldo do seu faucet para uma moeda. |
/balances | read | — | Listar saldos de todas as moedas. |
/currencies | read | — | Listar moedas suportadas. |
/check-address | read | address | Verificar um endereço de destino. |
/payouts | read | currency?, count? | Listar pagamentos recentes. |
/faucet | read | — | Obter detalhes do faucet |
/stats/daily | read | — | Estatísticas diárias |
/stats/users | read | coin, page | Estatísticas de usuários |
/transactions | read | coin, page | Transações |
/ratelimits | read | — | Limites de taxa |
/low-balance-notification | read | — | Alertas de saldo baixo |
| Endpoint | Escopo | Corpo | Descrição |
|---|---|---|---|
/faucet/update | manage | faucet_name, faucet_domain, faucet_url, faucet_description, timer_minutes, currencies_selected?, categories_selected? | Atualizar configurações do faucet |
/ratelimits/set | manage | ratelimits[] | Definir limites de taxa |
/ip-whitelist | manage | — | Lista branca de IP |
/ip-whitelist/set | manage | ip_whitelist | Atualizar lista branca de IP |
/low-balance-notification/toggle | manage | — | Alternar alerta de saldo baixo |
| Endpoint | Escopo | Corpo | Descrição |
|---|---|---|---|
/anti-fraud/rules | manage | — | Regras antifraude |
/anti-fraud/toggle | manage | — | Alternar antifraude |
/anti-fraud/rules/update | manage | trust_rank, negative_rank?, whitelist?, blacklist? | Atualizar regras antifraude |
| Endpoint | Escopo | Corpo | Descrição |
|---|---|---|---|
/send | send | idempotency_key, currency, amount, to, ip_address?, referral? | Enviar pagamento |
| Endpoint | Escopo | Corpo | Descrição |
|---|---|---|---|
/faucet/create | admin | faucet_name, faucet_domain, faucet_url | Criar faucet |
/approval-cost | admin | coin | Custo de aprovação de listagem |
/faucet/request-approval | admin | coin | Solicitar aprovação de listagem |
Enviando pagamentos.
O send v2 é a forma segura de pagar: exige uma chave de idempotência e respeita um limite diário opcional em USD por chave. Ele usa o mesmo caminho de antifraude / saldo / limite de taxa do send legado.
/sendsendEnviar pagamento com idempotência e limite diário opcional.
Parâmetros do corpo
| Parâmetro | Tipo | Descrição |
|---|---|---|
| idempotency_keyObrigatório | string | Único por pagamento lógico. Um retry com a mesma chave nunca paga duas vezes. |
| toObrigatório | string | Destinatário: e-mail, usuário, endereço da carteira ou payout_user_hash. |
| amountObrigatório | integer | Valor na menor unidade da moeda (ex. satoshis para BTC). |
| currencyObrigatório | string | Símbolo da moeda em maiúsculas, ex. BTC, DOGE. |
| ip_addressOpcional | string | IP do destinatário — recomendado para antifraude. |
| referralOpcional | string | Tag de referência para seus relatórios. |
Requisição de exemplo
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"}'Resposta de exemplo
{
"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.
Inscreva-se nos eventos de pagamento e receba POSTs assinados com HMAC. Configure-os na página Gerenciar do seu faucet — o gerenciamento de webhooks é apenas com sessão + 2FA, então uma chave com escopo nunca pode registrar um endpoint de entrega.
Baseado em eventos
Assine os eventos payout.sent e payout.failed.
Assinado com HMAC
Cada entrega inclui um cabeçalho X-FaucetPay-Signature com um HMAC-SHA256 do corpo.
Proteção SSRF
As URLs de webhook devem ser endpoints HTTPS públicos. IPs internos são rejeitados.
Entrega de exemplo
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!"
}
}Verifique a assinatura
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 status HTTP padrão mais uma mensagem descritiva no envelope.
| Código | Tom | Significado |
|---|---|---|
| 200 | Sucesso | 200 OK |
| 400 | Aviso | 400 Solicitação inválida |
| 401 | Erro | 401 Não autorizado |
| 403 | Erro | 403 Proibido |
| 409 | Aviso | 409 Conflito |
| 429 | Aviso | 429 Muitas solicitações |
Gerencie seu faucet a partir de qualquer agente de IA.
O servidor MCP do FaucetPay permite que um assistente de IA (Cursor, Claude Code, Windsurf, …) leia seu faucet e ajuste configurações pelo Model Context Protocol. É um cliente leve sobre a API v2 — apenas read + manage.
Camada fina
O servidor MCP é um wrapper fino sobre a API v2 — sem estado extra.
Sem ferramentas de dinheiro
O servidor não expõe ferramentas de pagamento. Pode ler e gerenciar, mas não enviar fundos.
Nada para instalar
O servidor é executado remotamente. Basta apontar seu assistente de IA para a URL.
Conecte e configure.
Adicione o servidor MCP FaucetPay à configuração do seu assistente de IA. Aponte para seu faucet com uma chave read ou manage com escopo.
// ~/.cursor/mcp.json
{
"mcpServers": {
"faucetpay": {
"url": "https://mcp.faucetpay.io/mcp",
"headers": { "Authorization": "Bearer fpk_your_read_or_manage_key" }
}
}
}Configuração
| Parâmetro | Tipo | Descrição |
|---|---|---|
| urlObrigatório | string | URL do servidor MCP |
| AuthorizationObrigatório | header | Chave API com escopo (escopo read ou manage) |
Tools.
Ferramentas somente leitura e de gerenciamento expostas pelo servidor MCP.
Ferramentas de leitura
get_faucetObter detalhes do faucetget_balancesObter saldos do faucetget_balanceObter o saldo atual do faucet para uma moeda.get_payoutsListar pagamentos recentesget_currenciesListar moedas suportadas e seus limites.check_addressVerificar se um endereço é um usuário registrado do FaucetPay.get_daily_statsObter estatísticas diáriasget_user_statsObter estatísticas de usuáriosget_transactionsListar transaçõesget_ratelimitsObter limites de taxaget_low_balance_notificationObter configurações de saldo baixo
Ferramentas de gerenciamento
get_ip_whitelistObter lista branca de IPset_ip_whitelistAtualizar lista branca de IPget_anti_fraudObter configurações antifraudetoggle_anti_fraudAlternar antifraudeupdate_anti_fraud_rulesAtualizar regras antifraudeupdate_faucet_settingsAtualizar configurações do faucetset_ratelimitsDefinir limites de taxatoggle_low_balance_notificationAlternar alerta de saldo baixo
Segurança e boas práticas.
Melhores práticas para usar o servidor MCP com segurança.
- Use uma chave read ou manage — nunca uma send. Este servidor não expõe ferramentas de pagamento.
- Defina uma curta validade. Dê à chave um tempo de vida para que uma config obsoleta não seja abusada para sempre.
- Revogar instantaneamente se exposto. Um clique na página Manage desativa a chave.
- Atente aos avisos antifraude. Desativar ou enfraquecer o antifraude retorna um aviso.
Ganhe mais
Monetize seu faucet com a rede de anúncios 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 | Descrição |
|---|---|---|
| merchant_usernameObrigatório | string | Your FaucetPay username — the account that receives the payment. |
| item_descriptionObrigatório | string | Description of the item or service the buyer is paying for. |
| amount1Obrigatório | string | Amount you want to receive, denominated in currency1. |
| currency1Obrigatório | 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