Referensi API FaucetPay.
Kirim pembayaran mikro, verifikasi pengguna, dan cek saldo melalui satu endpoint REST. Permintaan form-encoded, respons JSON, satu api_key per faucet.
Bangun faucet, payout, dan otomatisasi di FaucetPay.
API REST yang kecil dan dapat diprediksi melalui HTTPS. Setiap endpoint menerima body POST berformat form-encoded, mengembalikan JSON dengan status integer tingkat atas, dan mengautentikasi dengan api_key faucet Anda. Tanpa OAuth, tanpa SDK.
REST via HTTPS
Setiap endpoint menerima body POST form-encoded dan mengembalikan JSON.
Satu key per faucet
api_key faucet Anda mengautentikasi setiap permintaan. Simpan di server.
Sadarkan IP
Kirim ip_address dengan /send untuk mengaktifkan deteksi penyalahgunaan antar faucet.
https://faucetpay.io/api/v1Kirim api_key Anda di setiap request.
Masukkan api_key faucet Anda di field api_key setiap body POST.
Kirim payout pertama Anda dalam waktu kurang dari satu menit.
Ganti YOUR_API_KEY dengan key faucet asli, targetkan user uji coba (email Anda sendiri bisa) lalu jalankan.
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"
Bentuk request & response.
Semua endpoint adalah POST, form-encoded, dan mengembalikan JSON. Envelope-nya identik di semua endpoint sehingga kode klien Anda bisa berbagi logika 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 respons
| Parameter | Tipe | Deskripsi |
|---|---|---|
| statusWajib | integer | Status |
| messageWajib | string | Pesan |
| …Opsional | varies | Data |
Permukaan API
Lima endpoint mencakup setiap skenario pemilik faucet: mengirim payout, memverifikasi pengguna, memeriksa saldo, menampilkan riwayat, dan memeriksa daftar coin.
/sendSend
Bayar kripto dari saldo akun ke pengguna FaucetPay.
Parameter body
| Parameter | Tipe | Deskripsi |
|---|---|---|
| api_keyWajib | string | API key faucet Anda. |
| amountWajib | integer | Jumlah dalam unit terkecil coin (satoshi untuk BTC). |
| toWajib | string | Tujuan: email, nama pengguna, alamat dompet, atau payout_user_hash. |
| currencyWajib | string | Simbol coin huruf besar, mis. BTC, DOGE, USDT. |
| ip_addressOpsional | string | IP claimer — sangat disarankan; mengaktifkan rate limiting anti-abuso. |
| referralOpsional | string | Tag referral untuk payout ini untuk pelaporan Anda. |
Contoh request
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"
Contoh 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
Verifikasi bahwa tujuan adalah pengguna FaucetPay terdaftar untuk coin yang dipilih.
Parameter body
| Parameter | Tipe | Deskripsi |
|---|---|---|
| api_keyWajib | string | API key faucet Anda. |
| addressWajib | string | Email, nama pengguna, alamat dompet, atau payout_user_hash untuk diverifikasi. |
| currencyWajib | string | Simbol coin huruf besar untuk memeriksa keanggotaan. |
Contoh request
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"
Contoh response
{
"status": 200,
"message": "This address belongs to a FaucetPay user.",
"payout_user_hash": "3f9c1a2e6b7d0f5e8c4a9b2d1f6e0c8a7b5d2e91"
}/getbalanceCheck balance
Ambil saldo faucet saat ini untuk coin tertentu.
Parameter body
| Parameter | Tipe | Deskripsi |
|---|---|---|
| api_keyWajib | string | API key faucet Anda. |
| currencyWajib | string | Simbol coin huruf besar. |
Contoh request
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"
Contoh response
{
"status": 200,
"message": "OK",
"currency": "BTC",
"balance": 49900,
"balance_bitcoin": 0.00049900
}/payoutsList payouts
Kembalikan payout terbaru Anda, terbaru lebih dulu.
Parameter body
| Parameter | Tipe | Deskripsi |
|---|---|---|
| api_keyWajib | string | API key faucet Anda. |
| countOpsional | integer | Berapa payout yang dikembalikan (1–100, default 10). |
| currencyOpsional | string | Filter ke satu coin. Hilangkan untuk semua. |
Contoh request
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"
Contoh response
{
"status": 200,
"message": "OK",
"rewards": [
{
"to": "[email protected]",
"amount": 100,
"date": "02-05-26 21:12:00 GMT"
}
]
}/currenciesSupported currencies
Kembalikan semua coin yang aktif di FaucetPay.
Parameter body
| Parameter | Tipe | Deskripsi |
|---|---|---|
| api_keyWajib | string | API key faucet Anda. |
Contoh request
curl -X POST https://faucetpay.io/api/v1/currencies \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "api_key=YOUR_API_KEY"
Contoh 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" }
]
}Kode status.
Setiap endpoint mengembalikan salah satu kode status ini.
| Kode | Nada | Arti |
|---|---|---|
| 200 | Berhasil | OK — permintaan berhasil |
| 403 | Error | Dilarang — api_key tidak valid atau hilang |
| 405 | Error | Metode tidak diizinkan — gunakan POST |
| 413 | Peringatan | Payload terlalu besar |
| 414 | Peringatan | URI terlalu panjang |
| 415 | Peringatan | Tipe media tidak didukung — gunakan application/x-www-form-urlencoded |
| 416 | Error | Rentang yang diminta tidak dapat dipenuhi |
| 417 | Error | Ekspektasi gagal |
| 418 | Peringatan | Saya adalah teko |
| 419 | Error | Timeout autentikasi |
| 420 | Peringatan | Rate limited — terlalu banyak permintaan |
| 421 | Error | Permintaan salah arah |
| 422 | Peringatan | Entitas tidak dapat diproses — error validasi |
| 456 | Error | Error tidak dapat dipulihkan |
Coin yang didukung.
Setiap coin yang aktif di FaucetPay tersedia untuk payout.
Batas laju (rate limit).
Batas diterapkan per api_key faucet dan menjaga integrasi Anda serta jaringan kami tetap sehat.
60 / mnt
Per api_key faucet. Burst hingga 120 ditoleransi.
Jendela burst
Burst singkat di atas limit ditoleransi hingga 2 detik.
Praktik keamanan terbaik.
Checklist singkat dan tegas. Setiap item terkait dengan satu jenis insiden yang pernah kami temui di lapangan.
- Jangan kirim api_key ke browser. Perlakukan seperti password: backend saja, secrets manager, tidak di git.
- Selalu kirim ip_address dengan /send. Mengaktifkan deteksi penyalahgunaan antar faucet.
- Verifikasi unit jumlah dalam satoshi. Bug umum adalah mengirim nilai pecahan alih-alih integer unit terkecil.
- Deduplikasi claim di server. Jangan andalkan client untuk mencegah double-submit.
- Rotasi key secara berkala. Kami mendukung hot rotation: key lama berhenti berfungsi saat konfirmasi.
Ada yang tidak jelas?
Buka tiket di help desk dan kami akan memperbarui dokumentasi.
Key dengan scope dan dapat dicabut menggunakan Bearer token.
API v2 adalah permukaan modern untuk otomatisasi. Alih-alih satu key faucet yang serba kuasa, Anda membuat key terbatas (read / send / manage / admin), mengirimnya sebagai Bearer token, dan mendapatkan envelope JSON yang konsisten. /api/v1 lama di atas tidak berubah.
Autentikasi Bearer token
Kirim key sebagai Authorization: Bearer '<key>'.
Scope minimal privilege
Buat key hanya dengan scope yang dibutuhkan tool.
Envelope JSON konsisten
Setiap respons v2 menggunakan bentuk {status, message, data} yang sama.
https://faucetpay.io/api/v2Contoh — request terautentikasi
curl -X POST https://faucetpay.io/api/v2/balances \
-H "Authorization: Bearer YOUR_SCOPED_KEY" \
-H "Content-Type: application/json" \
-d '{}'Autentikasi & scope.
Buat key dengan scope dari halaman Kelola faucet Anda. Setiap key ditampilkan sekali, disimpan dalam bentuk hash, dan dapat membawa IP whitelist per key serta (untuk send) batas USD harian.
Baca saldo, payout, statistik, coin, pengaturan, dan status anti-fraud.
Melakukan payout — memindahkan dana nyata. Simpan di server saja.
Ubah pengaturan faucet, rate limit, whitelist IP, dan aturan anti-fraud.
Membuat faucet dan meminta persetujuan listing. Tidak dapat menghapus faucet.
Endpoints.
Setiap endpoint v2 menggunakan Bearer auth dan mengembalikan envelope standar.
| Endpoint | Scope | Body | Deskripsi |
|---|---|---|---|
/balance | read | currency? | Cek saldo faucet untuk sebuah coin. |
/balances | read | — | Daftar saldo semua coin. |
/currencies | read | — | Daftar coin yang didukung. |
/check-address | read | address | Verifikasi alamat tujuan. |
/payouts | read | currency?, count? | Daftar payout terbaru. |
/faucet | read | — | Dapatkan detail faucet |
/stats/daily | read | — | Statistik harian |
/stats/users | read | coin, page | Statistik pengguna |
/transactions | read | coin, page | Transaksi |
/ratelimits | read | — | Rate limit |
/low-balance-notification | read | — | Peringatan saldo rendah |
| Endpoint | Scope | Body | Deskripsi |
|---|---|---|---|
/faucet/update | manage | faucet_name, faucet_domain, faucet_url, faucet_description, timer_minutes, currencies_selected?, categories_selected? | Perbarui pengaturan faucet |
/ratelimits/set | manage | ratelimits[] | Atur rate limit |
/ip-whitelist | manage | — | Whitelist IP |
/ip-whitelist/set | manage | ip_whitelist | Perbarui whitelist IP |
/low-balance-notification/toggle | manage | — | Aktifkan/nonaktifkan peringatan saldo rendah |
| Endpoint | Scope | Body | Deskripsi |
|---|---|---|---|
/anti-fraud/rules | manage | — | Aturan anti-fraud |
/anti-fraud/toggle | manage | — | Aktifkan/nonaktifkan anti-fraud |
/anti-fraud/rules/update | manage | trust_rank, negative_rank?, whitelist?, blacklist? | Perbarui aturan anti-fraud |
| Endpoint | Scope | Body | Deskripsi |
|---|---|---|---|
/send | send | idempotency_key, currency, amount, to, ip_address?, referral? | Kirim payout |
| Endpoint | Scope | Body | Deskripsi |
|---|---|---|---|
/faucet/create | admin | faucet_name, faucet_domain, faucet_url | Buat faucet |
/approval-cost | admin | coin | Biaya persetujuan listing |
/faucet/request-approval | admin | coin | Minta persetujuan listing |
Mengirim payout.
Send v2 adalah cara aman untuk membayar: memerlukan idempotency key dan menghormati batas USD harian opsional per key. Ia menggunakan jalur anti-fraud / saldo / rate-limit yang sama seperti send lama.
/sendsendKirim payout dengan idempotensi dan batas harian opsional.
Parameter body
| Parameter | Tipe | Deskripsi |
|---|---|---|
| idempotency_keyWajib | string | Unik per payout logika. Retry dengan key yang sama tidak pernah membayar dua kali. |
| toWajib | string | Penerima: email, nama pengguna, alamat dompet, atau payout_user_hash. |
| amountWajib | integer | Jumlah dalam unit terkecil coin (mis. satoshi untuk BTC). |
| currencyWajib | string | Simbol coin huruf besar, mis. BTC, DOGE. |
| ip_addressOpsional | string | IP penerima — direkomendasikan untuk anti-fraud. |
| referralOpsional | string | Tag referral untuk pelaporan Anda sendiri. |
Contoh request
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"}'Contoh 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.
Berlangganan event payout dan terima POST yang ditandatangani HMAC. Konfigurasikan dari halaman Kelola faucet Anda — manajemen webhook hanya melalui session + 2FA, sehingga key dengan scope tidak akan pernah bisa mendaftarkan delivery endpoint.
Berbasis event
Berlangganan ke event payout.sent dan payout.failed.
Ditandatangani HMAC
Setiap pengiriman menyertakan header X-FaucetPay-Signature dengan HMAC-SHA256 dari body.
Proteksi SSRF
URL webhook harus endpoint HTTPS publik. IP internal ditolak.
Contoh 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!"
}
}Verifikasi 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 menggunakan kode status HTTP standar plus pesan deskriptif di envelope.
| Kode | Nada | Arti |
|---|---|---|
| 200 | Berhasil | 200 OK |
| 400 | Peringatan | 400 Bad request |
| 401 | Error | 401 Tidak terotorisasi |
| 403 | Error | 403 Dilarang |
| 409 | Peringatan | 409 Konflik |
| 429 | Peringatan | 429 Terlalu banyak permintaan |
Kelola faucet Anda dari agen AI mana pun.
Server MCP FaucetPay memungkinkan asisten AI (Cursor, Claude Code, Windsurf, …) membaca faucet Anda dan menyetel pengaturan melalui Model Context Protocol. Ini adalah thin client di atas API v2 — hanya read + manage.
Lapisan tipis
Server MCP adalah wrapper tipis di atas API v2 — tanpa state ekstra.
Tanpa tool uang
Server tidak mengekspos tool payout. Bisa baca dan kelola, tapi tidak mengirim dana.
Tidak perlu install
Server berjalan remote. Cukup arahkan AI assistant Anda ke URL.
Hubungkan & konfigurasikan.
Tambahkan server MCP FaucetPay ke config AI assistant Anda. Arahkan ke faucet Anda dengan scoped read atau manage key.
// ~/.cursor/mcp.json
{
"mcpServers": {
"faucetpay": {
"url": "https://mcp.faucetpay.io/mcp",
"headers": { "Authorization": "Bearer fpk_your_read_or_manage_key" }
}
}
}Konfigurasi
| Parameter | Tipe | Deskripsi |
|---|---|---|
| urlWajib | string | URL server MCP |
| AuthorizationWajib | header | API key scoped (scope read atau manage) |
Tools.
Tool read-only dan manage yang diekspos oleh server MCP.
Read tools
get_faucetDapatkan detail faucetget_balancesDapatkan saldo faucetget_balanceDapatkan saldo faucet saat ini untuk sebuah coin.get_payoutsDaftar payout terbaruget_currenciesDaftar coin yang didukung dan limitnya.check_addressCek apakah alamat adalah pengguna FaucetPay terdaftar.get_daily_statsDapatkan statistik harianget_user_statsDapatkan statistik penggunaget_transactionsDaftar transaksiget_ratelimitsDapatkan rate limitget_low_balance_notificationDapatkan pengaturan saldo rendah
Manage tools
get_ip_whitelistDapatkan whitelist IPset_ip_whitelistPerbarui whitelist IPget_anti_fraudDapatkan pengaturan anti-fraudtoggle_anti_fraudAktifkan/nonaktifkan anti-fraudupdate_anti_fraud_rulesPerbarui aturan anti-fraudupdate_faucet_settingsPerbarui pengaturan faucetset_ratelimitsAtur rate limittoggle_low_balance_notificationAktifkan/nonaktifkan peringatan saldo rendah
Keamanan & praktik terbaik.
Praktik terbaik untuk menggunakan server MCP dengan aman.
- Gunakan key read atau manage — jangan send key. Server ini tidak mengekspos tool payout.
- Set expiry pendek. Beri key masa berlaku agar config lama tidak disalahgunakan selamanya.
- Cabut langsung jika terbongkar. Satu klik di halaman Manage mematikan key.
- Perhatikan advis anti-fraud. Menonaktifkan atau melemahkan anti-fraud mengembalikan peringatan.
Hasilkan lebih banyak
Monetisasi faucet Anda dengan jaringan iklan 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.
| Parameter | Tipe | Deskripsi |
|---|---|---|
| merchant_usernameWajib | string | Your FaucetPay username — the account that receives the payment. |
| item_descriptionWajib | string | Description of the item or service the buyer is paying for. |
| amount1Wajib | string | Amount you want to receive, denominated in currency1. |
| currency1Wajib | string | The pricing currency of your store (e.g. USDT, BTC, …). |
| currency2Opsional | string | The coin the buyer must pay with. Leave blank to let the buyer choose any supported coin. |
| customOpsional | string | An identifier passed back on the callback — use it for your order ID or user ID. |
| callback_urlOpsional | string | URL that receives the server-to-server POST callback once the payment completes. |
| success_urlOpsional | string | URL the buyer is redirected to after a successful payment. |
| cancel_urlOpsional | 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