Tài liệu API FaucetPay.
Gửi thanh toán vi mô, xác minh người dùng và tra cứu số dư qua một endpoint REST duy nhất. Yêu cầu form-encoded, phản hồi JSON, một api_key cho mỗi faucet.
Xây dựng faucet, thanh toán và tự động hóa trên FaucetPay.
Một REST API nhỏ gọn và dễ đoán qua HTTPS. Mỗi endpoint chấp nhận body POST dạng form-encoded, trả về JSON với status integer ở cấp cao nhất và xác thực bằng api_key của faucet của bạn. Không cần OAuth, không cần SDK.
REST qua HTTPS
Mỗi endpoint nhận POST body form-encoded và trả về JSON.
Một khóa mỗi faucet
api_key faucet xác thực mỗi yêu cầu. Giữ phía máy chủ.
Nhận thức IP
Gửi ip_address với /send để bật phát hiện lạm dụng chéo faucet.
https://faucetpay.io/api/v1Gửi api_key của bạn với mỗi request.
Đặt api_key faucet vào trường api_key của mỗi POST body.
Gửi khoản thanh toán đầu tiên của bạn trong chưa đầy một phút.
Thay YOUR_API_KEY bằng key faucet thật, nhắm đến một người dùng thử nghiệm (email của chính bạn cũng được) và gửi.
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"
Cấu trúc request & response.
Tất cả endpoint đều dùng POST, form-encoded và trả về JSON. Envelope giống nhau trên mọi endpoint nên code client của bạn có thể dùng chung logic 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 phản hồi
| Tham số | Loại | Mô tả |
|---|---|---|
| statusBắt buộc | integer | Trạng thái |
| messageBắt buộc | string | Thông điệp |
| …Tùy chọn | varies | Dữ liệu |
Bề mặt API
Năm endpoint bao quát mọi tình huống của chủ faucet: gửi thanh toán, xác minh người dùng, kiểm tra số dư, liệt kê lịch sử và xem danh sách coin.
/sendSend
Thanh toán tiền mã hóa từ số dư cho người dùng FaucetPay.
Tham số body
| Tham số | Loại | Mô tả |
|---|---|---|
| api_keyBắt buộc | string | Khóa API của faucet bạn. |
| amountBắt buộc | integer | Số lượng trong đơn vị nhỏ nhất (satoshi cho BTC). |
| toBắt buộc | string | Đích: email, tên người dùng, địa chỉ ví hoặc payout_user_hash. |
| currencyBắt buộc | string | Ký hiệu tiền tệ viết hoa, vd. BTC, DOGE, USDT. |
| ip_addressTùy chọn | string | IP của người nhận — rất khuyến nghị; bật giới hạn chống lạm dụng. |
| referralTùy chọn | string | Thẻ giới thiệu cho thanh toán này cho báo cáo của bạn. |
Request mẫu
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"
Response mẫu
{
"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
Xác minh đích là người dùng FaucetPay đã đăng ký cho đồng tiền đã chọn.
Tham số body
| Tham số | Loại | Mô tả |
|---|---|---|
| api_keyBắt buộc | string | Khóa API của faucet bạn. |
| addressBắt buộc | string | Email, tên người dùng, địa chỉ ví hoặc payout_user_hash để xác minh. |
| currencyBắt buộc | string | Ký hiệu tiền tệ viết hoa để kiểm tra thành viên. |
Request mẫu
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"
Response mẫu
{
"status": 200,
"message": "This address belongs to a FaucetPay user.",
"payout_user_hash": "3f9c1a2e6b7d0f5e8c4a9b2d1f6e0c8a7b5d2e91"
}/getbalanceCheck balance
Lấy số dư faucet hiện tại cho một đồng tiền.
Tham số body
| Tham số | Loại | Mô tả |
|---|---|---|
| api_keyBắt buộc | string | Khóa API của faucet bạn. |
| currencyBắt buộc | string | Ký hiệu tiền tệ viết hoa. |
Request mẫu
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"
Response mẫu
{
"status": 200,
"message": "OK",
"currency": "BTC",
"balance": 49900,
"balance_bitcoin": 0.00049900
}/payoutsList payouts
Trả về các khoản thanh toán gần đây nhất, mới nhất trước.
Tham số body
| Tham số | Loại | Mô tả |
|---|---|---|
| api_keyBắt buộc | string | Khóa API của faucet bạn. |
| countTùy chọn | integer | Số lượng thanh toán trả về (1–100, mặc định 10). |
| currencyTùy chọn | string | Lọc theo một đồng tiền. Bỏ trống cho tất cả. |
Request mẫu
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"
Response mẫu
{
"status": 200,
"message": "OK",
"rewards": [
{
"to": "[email protected]",
"amount": 100,
"date": "02-05-26 21:12:00 GMT"
}
]
}/currenciesSupported currencies
Trả về tất cả tiền tệ hiện đang hoạt động trên FaucetPay.
Tham số body
| Tham số | Loại | Mô tả |
|---|---|---|
| api_keyBắt buộc | string | Khóa API của faucet bạn. |
Request mẫu
curl -X POST https://faucetpay.io/api/v1/currencies \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "api_key=YOUR_API_KEY"
Response mẫu
{
"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" }
]
}Mã trạng thái.
Mỗi endpoint trả về một trong các mã trạng thái này.
| Mã | Tông | Ý nghĩa |
|---|---|---|
| 200 | Thành công | OK — yêu cầu thành công |
| 403 | Lỗi | Bị cấm — api_key không hợp lệ hoặc thiếu |
| 405 | Lỗi | Phương thức không được phép — dùng POST |
| 413 | Cảnh báo | Payload quá lớn |
| 414 | Cảnh báo | URI quá dài |
| 415 | Cảnh báo | Loại phương tiện không được hỗ trợ — dùng application/x-www-form-urlencoded |
| 416 | Lỗi | Phạm vi yêu cầu không thỏa mãn |
| 417 | Lỗi | Kỳ vọng thất bại |
| 418 | Cảnh báo | Tôi là ấm trà |
| 419 | Lỗi | Hết thời gian xác thực |
| 420 | Cảnh báo | Giới hạn tỷ lệ — quá nhiều yêu cầu |
| 421 | Lỗi | Yêu cầu sai hướng |
| 422 | Cảnh báo | Thực thể không thể xử lý — lỗi xác thực |
| 456 | Lỗi | Lỗi không thể khôi phục |
Các coin được hỗ trợ.
Mỗi đồng tiền hoạt động trên FaucetPay đều có thể thanh toán.
Giới hạn tần suất.
Giới hạn được áp dụng theo từng api_key của faucet, giúp cả tích hợp của bạn lẫn mạng lưới của chúng tôi luôn ổn định.
60 / phút
Mỗi api_key faucet. Burst lên đến 120 được dung túng.
Cửa sổ burst
Burst ngắn vượt giới hạn được dung túng tối đa 2 giây.
Các best practice về bảo mật.
Một checklist ngắn gọn và rõ quan điểm. Mỗi mục tương ứng với một loại sự cố mà chúng tôi đã gặp trong thực tế.
- Không bao giờ gửi api_key đến trình duyệt. Coi nó như mật khẩu: chỉ backend, trình quản lý bí mật, không trong git.
- Luôn gửi ip_address với /send. Bật phát hiện lạm dụng chéo faucet.
- Xác minh đơn vị số tiền bằng satoshi. Lỗi phổ biến là gửi giá trị thập phân thay vì số nguyên đơn vị nhỏ nhất.
- Khử trùng lặp yêu cầu phía máy chủ. Đừng dựa vào client để ngăn gửi trùng.
- Xoay khóa định kỳ. Chúng tôi hỗ trợ xoay nóng: khóa cũ ngừng hoạt động khi xác nhận.
Điều gì đó chưa rõ?
Mở ticket trên help desk và chúng tôi sẽ cập nhật tài liệu.
Key có scope và có thể thu hồi với Bearer token.
API v2 là bề mặt hiện đại cho tự động hóa. Thay vì một key faucet toàn quyền, bạn tạo các key giới hạn (read / send / manage / admin), gửi chúng dưới dạng Bearer token và nhận về envelope JSON nhất quán. /api/v1 cũ ở trên không thay đổi.
Xác thực Bearer token
Gửi khóa dạng Authorization: Bearer '<key>'.
Phạm vi ít quyền nhất
Tạo khóa chỉ với phạm vi công cụ cần.
Phong bì JSON nhất quán
Mỗi phản hồi v2 dùng cùng cấu trúc {status, message, data}.
https://faucetpay.io/api/v2Ví dụ — request đã xác thực
curl -X POST https://faucetpay.io/api/v2/balances \
-H "Authorization: Bearer YOUR_SCOPED_KEY" \
-H "Content-Type: application/json" \
-d '{}'Xác thực & scope.
Tạo các key có scope từ trang Quản lý của faucet. Mỗi key chỉ hiển thị một lần, được lưu dưới dạng hash, và có thể đi kèm IP whitelist riêng cho từng key và (với send) hạn mức USD hằng ngày.
Đọc số dư, thanh toán, thống kê, tiền tệ, cài đặt và trạng thái chống gian lận.
Thực hiện thanh toán — di chuyển tiền thật. Chỉ giữ phía máy chủ.
Thay đổi cài đặt faucet, giới hạn tỷ lệ, danh sách trắng IP và quy tắc chống gian lận.
Tạo faucet và yêu cầu phê duyệt danh sách. Không thể xóa faucet.
Endpoints.
Mỗi endpoint v2 dùng xác thực Bearer và trả về phong bì chuẩn.
| Endpoint | Phạm vi | Thân | Mô tả |
|---|---|---|---|
/balance | read | currency? | Kiểm tra số dư faucet cho một đồng tiền. |
/balances | read | — | Liệt kê số dư tất cả đồng tiền. |
/currencies | read | — | Liệt kê tiền tệ được hỗ trợ. |
/check-address | read | address | Xác minh địa chỉ đích. |
/payouts | read | currency?, count? | Liệt kê thanh toán gần đây. |
/faucet | read | — | Lấy chi tiết faucet |
/stats/daily | read | — | Thống kê hàng ngày |
/stats/users | read | coin, page | Thống kê người dùng |
/transactions | read | coin, page | Giao dịch |
/ratelimits | read | — | Giới hạn tỷ lệ |
/low-balance-notification | read | — | Cảnh báo số dư thấp |
| Endpoint | Phạm vi | Thân | Mô tả |
|---|---|---|---|
/faucet/update | manage | faucet_name, faucet_domain, faucet_url, faucet_description, timer_minutes, currencies_selected?, categories_selected? | Cập nhật cài đặt faucet |
/ratelimits/set | manage | ratelimits[] | Đặt giới hạn tỷ lệ |
/ip-whitelist | manage | — | Danh sách trắng IP |
/ip-whitelist/set | manage | ip_whitelist | Cập nhật danh sách trắng IP |
/low-balance-notification/toggle | manage | — | Bật/tắt cảnh báo số dư thấp |
| Endpoint | Phạm vi | Thân | Mô tả |
|---|---|---|---|
/anti-fraud/rules | manage | — | Quy tắc chống gian lận |
/anti-fraud/toggle | manage | — | Bật/tắt chống gian lận |
/anti-fraud/rules/update | manage | trust_rank, negative_rank?, whitelist?, blacklist? | Cập nhật quy tắc chống gian lận |
| Endpoint | Phạm vi | Thân | Mô tả |
|---|---|---|---|
/send | send | idempotency_key, currency, amount, to, ip_address?, referral? | Gửi thanh toán |
| Endpoint | Phạm vi | Thân | Mô tả |
|---|---|---|---|
/faucet/create | admin | faucet_name, faucet_domain, faucet_url | Tạo faucet |
/approval-cost | admin | coin | Chi phí phê duyệt danh sách |
/faucet/request-approval | admin | coin | Yêu cầu phê duyệt danh sách |
Gửi khoản thanh toán.
v2 send là cách thanh toán an toàn: nó yêu cầu idempotency key và tôn trọng hạn mức USD hằng ngày tùy chọn theo từng key. Nó dùng cùng luồng chống gian lận / số dư / rate-limit như send cũ.
/sendsendGửi thanh toán với idempotency và giới hạn hàng ngày tùy chọn.
Tham số body
| Tham số | Loại | Mô tả |
|---|---|---|
| idempotency_keyBắt buộc | string | Duy nhất cho mỗi thanh toán. Thử lại với cùng khóa không bao giờ trả hai lần. |
| toBắt buộc | string | Người nhận: email, tên người dùng, địa chỉ ví hoặc payout_user_hash. |
| amountBắt buộc | integer | Số lượng trong đơn vị nhỏ nhất (vd. satoshi cho BTC). |
| currencyBắt buộc | string | Ký hiệu tiền tệ viết hoa, vd. BTC, DOGE. |
| ip_addressTùy chọn | string | IP người nhận — khuyến nghị cho chống gian lận. |
| referralTùy chọn | string | Thẻ giới thiệu cho báo cáo của bạn. |
Request mẫu
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"}'Response mẫu
{
"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.
Đăng ký các sự kiện thanh toán và nhận các POST được ký HMAC. Cấu hình chúng từ trang Quản lý của faucet — việc quản lý webhook chỉ qua session + 2FA, nên một key có scope không bao giờ có thể đăng ký delivery endpoint.
Dựa trên sự kiện
Đăng ký sự kiện payout.sent và payout.failed.
Ký HMAC
Mỗi giao hàng gồm header X-FaucetPay-Signature với HMAC-SHA256 của thân.
Bảo vệ SSRF
URL webhook phải là endpoint HTTPS công khai. IP nội bộ bị từ chối.
Delivery mẫu
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!"
}
}Xác minh chữ ký
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 dùng mã trạng thái HTTP chuẩn kèm thông điệp mô tả trong phong bì.
| Mã | Tông | Ý nghĩa |
|---|---|---|
| 200 | Thành công | 200 OK |
| 400 | Cảnh báo | 400 Yêu cầu sai |
| 401 | Lỗi | 401 Không được ủy quyền |
| 403 | Lỗi | 403 Bị cấm |
| 409 | Cảnh báo | 409 Xung đột |
| 429 | Cảnh báo | 429 Quá nhiều yêu cầu |
Quản lý faucet của bạn từ bất kỳ AI agent nào.
Máy chủ MCP của FaucetPay cho phép một trợ lý AI (Cursor, Claude Code, Windsurf, …) đọc faucet của bạn và tinh chỉnh cài đặt qua Model Context Protocol. Đây là thin client trên nền API v2 — chỉ read + manage.
Lớp mỏng
Máy chủ MCP là wrapper mỏng trên API v2 — không trạng thái thêm.
Không có công cụ tiền
Máy chủ không cung cấp công cụ thanh toán. Có thể đọc và quản lý nhưng không gửi tiền.
Không cần cài đặt
Máy chủ chạy từ xa. Chỉ cần trỏ AI assistant của bạn tới URL.
Kết nối & cấu hình.
Thêm máy chủ MCP FaucetPay vào cấu hình AI assistant. Trỏ tới faucet với khóa đọc hoặc quản lý có phạm vi.
// ~/.cursor/mcp.json
{
"mcpServers": {
"faucetpay": {
"url": "https://mcp.faucetpay.io/mcp",
"headers": { "Authorization": "Bearer fpk_your_read_or_manage_key" }
}
}
}Cấu hình
| Tham số | Loại | Mô tả |
|---|---|---|
| urlBắt buộc | string | URL máy chủ MCP |
| AuthorizationBắt buộc | header | Khóa API có phạm vi (phạm vi đọc hoặc quản lý) |
Tools.
Công cụ chỉ đọc và quản lý do máy chủ MCP cung cấp.
Công cụ đọc
get_faucetLấy chi tiết faucetget_balancesLấy số dư faucetget_balanceLấy số dư faucet hiện tại cho một đồng tiền.get_payoutsLiệt kê thanh toán gần đâyget_currenciesLiệt kê tiền tệ được hỗ trợ và giới hạn.check_addressKiểm tra địa chỉ có phải người dùng FaucetPay đã đăng ký.get_daily_statsLấy thống kê hàng ngàyget_user_statsLấy thống kê người dùngget_transactionsLiệt kê giao dịchget_ratelimitsLấy giới hạn tỷ lệget_low_balance_notificationLấy cài đặt số dư thấp
Công cụ quản lý
get_ip_whitelistLấy danh sách trắng IPset_ip_whitelistCập nhật danh sách trắng IPget_anti_fraudLấy cài đặt chống gian lậntoggle_anti_fraudBật/tắt chống gian lậnupdate_anti_fraud_rulesCập nhật quy tắc chống gian lậnupdate_faucet_settingsCập nhật cài đặt faucetset_ratelimitsĐặt giới hạn tỷ lệtoggle_low_balance_notificationBật/tắt cảnh báo số dư thấp
Bảo mật & best practice.
Thực hành tốt nhất khi sử dụng máy chủ MCP an toàn.
- Dùng khóa đọc hoặc quản lý — không bao giờ dùng khóa gửi. Máy chủ này không có công cụ thanh toán.
- Đặt thời hạn ngắn. Cho khóa thời hạn để cấu hình cũ không bị lạm dụng mãi.
- Thu hồi ngay nếu bị lộ. Một click trên trang Manage vô hiệu hóa khóa.
- Tuân theo cảnh báo chống gian lận. Tắt hoặc suy yếu chống gian lận trả về cảnh báo.
Kiếm thêm
Kiếm tiền từ faucet với mạng quảng cáo 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.
| Tham số | Loại | Mô tả |
|---|---|---|
| merchant_usernameBắt buộc | string | Your FaucetPay username — the account that receives the payment. |
| item_descriptionBắt buộc | string | Description of the item or service the buyer is paying for. |
| amount1Bắt buộc | string | Amount you want to receive, denominated in currency1. |
| currency1Bắt buộc | string | The pricing currency of your store (e.g. USDT, BTC, …). |
| currency2Tùy chọn | string | The coin the buyer must pay with. Leave blank to let the buyer choose any supported coin. |
| customTùy chọn | string | An identifier passed back on the callback — use it for your order ID or user ID. |
| callback_urlTùy chọn | string | URL that receives the server-to-server POST callback once the payment completes. |
| success_urlTùy chọn | string | URL the buyer is redirected to after a successful payment. |
| cancel_urlTùy chọn | 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