Sanggunian ng FaucetPay API.
Magpadala ng micro-payout, mag-verify ng user, at maghanap ng balanse sa iisang REST endpoint. Mga form-encoded na request, JSON na tugon, isang api_key bawat faucet.
Gumawa ng faucets, payouts at automations sa FaucetPay.
Isang maliit at predictable na REST API sa HTTPS. Bawat endpoint ay tumatanggap ng form-encoded na POST bodies, nagbabalik ng JSON na may top-level na status integer, at nag-a-authenticate gamit ang api_key ng iyong faucet. Walang OAuth, walang SDK na kailangan.
REST sa HTTPS
Bawat endpoint ay tumatanggap ng form-encoded POST body at nagbabalik ng JSON.
Isang key kada faucet
Ang api_key ng faucet ay nag-aauthenticate ng bawat kahilingan. Itago sa server.
IP-aware
Magpadala ng ip_address sa /send para sa cross-faucet abuse detection.
https://faucetpay.io/api/v1Ipadala ang iyong api_key sa bawat request.
Ilagay ang api_key ng faucet sa api_key field ng bawat POST body.
Magpadala ng unang payout mo sa wala pang isang minuto.
Palitan ang YOUR_API_KEY ng totoong faucet key, mag-target ng test user (pwede ang sarili mong email) at i-fire.
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"
Hugis ng request at response.
Lahat ng endpoint ay POST, form-encoded at nagbabalik ng JSON. Pareho ang envelope sa lahat ng endpoint kaya pwedeng pag-isahin ng client code mo ang parsing logic.
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
}Response envelope
| Parameter | Uri | Paglalarawan |
|---|---|---|
| statusKinakailangan | integer | Status |
| messageKinakailangan | string | Mensahe |
| …Opsyonal | varies | Data |
Ang API surface
Limang endpoint ang sumasaklaw sa bawat senaryo ng faucet owner: magpadala ng payouts, mag-verify ng users, mag-check ng balances, mag-list ng history at i-introspect ang coin list.
/sendSend
Magbayad ng kripto mula sa account balance sa FaucetPay user.
Mga body parameter
| Parameter | Uri | Paglalarawan |
|---|---|---|
| api_keyKinakailangan | string | Ang API key ng iyong faucet. |
| amountKinakailangan | integer | Halaga sa pinakamaliit na unit (satoshis para sa BTC). |
| toKinakailangan | string | Destinasyon: email, username, wallet address, o payout_user_hash. |
| currencyKinakailangan | string | Capital na coin symbol, hal. BTC, DOGE, USDT. |
| ip_addressOpsyonal | string | IP ng claimer — matinding inirerekomenda; anti-abuse rate limiting. |
| referralOpsyonal | string | Referral tag para sa payout na ito para sa iyong pag-uulat. |
Halimbawang 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"
Halimbawang 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
I-verify na ang destinasyon ay rehistradong FaucetPay user para sa napiling currency.
Mga body parameter
| Parameter | Uri | Paglalarawan |
|---|---|---|
| api_keyKinakailangan | string | Ang API key ng iyong faucet. |
| addressKinakailangan | string | Email, username, wallet address, o payout_user_hash para i-verify. |
| currencyKinakailangan | string | Capital na coin symbol para i-check ang membership. |
Halimbawang 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"
Halimbawang response
{
"status": 200,
"message": "This address belongs to a FaucetPay user.",
"payout_user_hash": "3f9c1a2e6b7d0f5e8c4a9b2d1f6e0c8a7b5d2e91"
}/getbalanceCheck balance
Kunin ang kasalukuyang faucet balance para sa isang coin.
Mga body parameter
| Parameter | Uri | Paglalarawan |
|---|---|---|
| api_keyKinakailangan | string | Ang API key ng iyong faucet. |
| currencyKinakailangan | string | Capital na coin symbol. |
Halimbawang 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"
Halimbawang response
{
"status": 200,
"message": "OK",
"currency": "BTC",
"balance": 49900,
"balance_bitcoin": 0.00049900
}/payoutsList payouts
Ibalik ang iyong mga pinakabagong payout, pinakabago muna.
Mga body parameter
| Parameter | Uri | Paglalarawan |
|---|---|---|
| api_keyKinakailangan | string | Ang API key ng iyong faucet. |
| countOpsyonal | integer | Ilang payout ang ibabalik (1–100, default 10). |
| currencyOpsyonal | string | I-filter sa isang coin. Alisin para sa lahat. |
Halimbawang 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"
Halimbawang response
{
"status": 200,
"message": "OK",
"rewards": [
{
"to": "[email protected]",
"amount": 100,
"date": "02-05-26 21:12:00 GMT"
}
]
}/currenciesSupported currencies
Ibalik ang bawat currency na aktibo sa FaucetPay.
Mga body parameter
| Parameter | Uri | Paglalarawan |
|---|---|---|
| api_keyKinakailangan | string | Ang API key ng iyong faucet. |
Halimbawang request
curl -X POST https://faucetpay.io/api/v1/currencies \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "api_key=YOUR_API_KEY"
Halimbawang 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" }
]
}Mga status code.
Bawat endpoint ay nagbabalik ng isa sa mga status code na ito.
| Code | Tono | Kahulugan |
|---|---|---|
| 200 | Tagumpay | OK — matagumpay ang kahilingan |
| 403 | Error | Pinagbawalan — hindi wasto o walang api_key |
| 405 | Error | Hindi pinapayagang method — gamitin ang POST |
| 413 | Babala | Masyadong malaki ang payload |
| 414 | Babala | Masyadong mahaba ang URI |
| 415 | Babala | Hindi sinusuportahang media type — gamitin ang application/x-www-form-urlencoded |
| 416 | Error | Hindi matugunan ang hiniling na range |
| 417 | Error | Bigo ang expectasyon |
| 418 | Babala | Ako ay teapot |
| 419 | Error | Timeout ng autentikasyon |
| 420 | Babala | Rate limited — masyadong maraming kahilingan |
| 421 | Error | Maling direksyon ang kahilingan |
| 422 | Babala | Hindi maprosesong entity — error sa validation |
| 456 | Error | Hindi mare-recover na error |
Mga suportadong coin.
Bawat coin na aktibo sa FaucetPay ay available para sa payout.
Mga rate limit.
Ang mga limit ay ini-apply kada faucet api_key at pinapanatiling malusog ang iyong integration at ang aming network.
60 / min
Per api_key ng faucet. Burst hanggang 120 tolerated.
Burst window
Maikling burst sa itaas ng limit ay tolerated hanggang 2 segundo.
Mga best practice sa seguridad.
Isang maikli at opinionated na checklist. Bawat item ay tumutugma sa isang uri ng incident na nakita namin sa totoong buhay.
- Huwag ipadala ang api_key sa browser. Ituring ito bilang password: backend lang, secrets manager, huwag sa git.
- Palaging magpadala ng ip_address sa /send. Binubuhay nito ang cross-faucet abuse detection.
- I-verify ang amount units sa satoshis. Karaniwang bug ang pagpapadala ng fractional value sa halip na smallest-unit integer.
- I-dedup ang mga claim sa server. Huwag umasa sa client para maiwasan ang double-submit.
- Regular na i-rotate ang mga key. Sinusuportahan namin ang hot rotation: mga lumang key huminto pagkatapos kumpirmahin.
May hindi malinaw?
Magbukas ng ticket sa help desk at i-update namin ang docs.
Scoped at revocable na keys gamit ang Bearer token.
Ang v2 API ang modernong surface para sa automation. Sa halip na isang all-powerful na faucet key, gagawa ka ng mga limitadong key (read / send / manage / admin), ipapadala bilang Bearer token, at makakakuha ng consistent na JSON envelope. Hindi nagbabago ang legacy /api/v1 sa itaas.
Auth sa Bearer token
Magpadala ng key bilang Authorization: Bearer '<key>'.
Mga scope ng least-privilege
Gumawa ng key na may scope lang na kailangan ng tool.
Consistent na JSON envelope
Bawat v2 response ay gumagamit ng parehong {status, message, data} shape.
https://faucetpay.io/api/v2Halimbawa — authenticated na request
curl -X POST https://faucetpay.io/api/v2/balances \
-H "Authorization: Bearer YOUR_SCOPED_KEY" \
-H "Content-Type: application/json" \
-d '{}'Authentication at scopes.
Gumawa ng scoped keys mula sa Manage page ng iyong faucet. Bawat key ay ipinapakita nang isang beses, naka-store nang naka-hash, at pwedeng magdala ng per-key IP whitelist at (para sa send) isang daily USD cap.
Basahin ang balanse, payout, estadistika, currency, setting, at anti-fraud status.
Magpayout — nagagalaw ang tunay na pondo. Server-side lang.
Baguhin ang faucet setting, rate limit, IP whitelist, at anti-fraud rule.
Gumawa ng faucet at humingi ng listing approval. Hindi makapag-delete ng faucet.
Endpoints.
Bawat v2 endpoint ay gumagamit ng Bearer auth at nagbabalik ng standard envelope.
| Endpoint | Scope | Body | Paglalarawan |
|---|---|---|---|
/balance | read | currency? | I-check ang faucet balance para sa isang coin. |
/balances | read | — | I-list ang mga balanse sa lahat ng coin. |
/currencies | read | — | I-list ang mga sinusuportahang currency. |
/check-address | read | address | I-verify ang destinasyon address. |
/payouts | read | currency?, count? | I-list ang mga kamakailang payout. |
/faucet | read | — | Kunin ang faucet details |
/stats/daily | read | — | Pang-araw-araw na estadistika |
/stats/users | read | coin, page | Estadistika ng user |
/transactions | read | coin, page | Mga transaksyon |
/ratelimits | read | — | Mga rate limit |
/low-balance-notification | read | — | Mga low-balance alert |
| Endpoint | Scope | Body | Paglalarawan |
|---|---|---|---|
/faucet/update | manage | faucet_name, faucet_domain, faucet_url, faucet_description, timer_minutes, currencies_selected?, categories_selected? | I-update ang faucet setting |
/ratelimits/set | manage | ratelimits[] | Itakda ang rate limit |
/ip-whitelist | manage | — | IP whitelist |
/ip-whitelist/set | manage | ip_whitelist | I-update ang IP whitelist |
/low-balance-notification/toggle | manage | — | I-toggle ang low-balance alert |
| Endpoint | Scope | Body | Paglalarawan |
|---|---|---|---|
/anti-fraud/rules | manage | — | Mga anti-fraud rule |
/anti-fraud/toggle | manage | — | I-toggle ang anti-fraud |
/anti-fraud/rules/update | manage | trust_rank, negative_rank?, whitelist?, blacklist? | I-update ang anti-fraud rules |
| Endpoint | Scope | Body | Paglalarawan |
|---|---|---|---|
/send | send | idempotency_key, currency, amount, to, ip_address?, referral? | Magpadala ng payout |
| Endpoint | Scope | Body | Paglalarawan |
|---|---|---|---|
/faucet/create | admin | faucet_name, faucet_domain, faucet_url | Gumawa ng faucet |
/approval-cost | admin | coin | Halaga ng listing approval |
/faucet/request-approval | admin | coin | Humingi ng listing approval |
Pagpapadala ng payouts.
Ang v2 send ang ligtas na paraan ng pagbabayad: nangangailangan ito ng idempotency key at sinusunod ang opsyonal na per-key daily USD cap. Ginagamit nito ang parehong anti-fraud / balance / rate-limit path tulad ng legacy send.
/sendsendMagpadala ng payout na may idempotency at opsyonal na daily cap.
Mga body parameter
| Parameter | Uri | Paglalarawan |
|---|---|---|
| idempotency_keyKinakailangan | string | Unique kada logical payout. Hindi kailanman nagbabayad nang dalawang beses ang retry. |
| toKinakailangan | string | Recipient: email, username, wallet address, o payout_user_hash. |
| amountKinakailangan | integer | Halaga sa pinakamaliit na unit (hal. satoshis para sa BTC). |
| currencyKinakailangan | string | Capital na coin symbol, hal. BTC, DOGE. |
| ip_addressOpsyonal | string | IP ng recipient — inirerekomenda para sa anti-fraud. |
| referralOpsyonal | string | Referral tag para sa iyong sariling pag-uulat. |
Halimbawang 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"}'Halimbawang 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.
Mag-subscribe sa payout events at tumanggap ng HMAC-signed na POSTs. I-configure ang mga ito mula sa Manage page ng iyong faucet — ang webhook management ay session + 2FA lamang, kaya hinding-hindi makakapag-register ng delivery endpoint ang isang scoped key.
Event-driven
Mag-subscribe sa payout.sent at payout.failed events.
HMAC-signed
Bawat delivery ay may header na X-FaucetPay-Signature na may HMAC-SHA256 ng body.
SSRF protection
Ang webhook URL ay dapat public HTTPS endpoint. Ang internal IP ay tinatanggi.
Halimbawang 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!"
}
}I-verify ang 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.
Gumagamit ang v2 ng standard HTTP status code plus descriptive message sa envelope.
| Code | Tono | Kahulugan |
|---|---|---|
| 200 | Tagumpay | 200 OK |
| 400 | Babala | 400 Bad request |
| 401 | Error | 401 Hindi awtorisado |
| 403 | Error | 403 Pinagbawalan |
| 409 | Babala | 409 Conflict |
| 429 | Babala | 429 Masyadong maraming kahilingan |
Pamahalaan ang iyong faucet mula sa kahit anong AI agent.
Ang FaucetPay MCP server ay nagbibigay-daan sa isang AI assistant (Cursor, Claude Code, Windsurf, …) na basahin ang iyong faucet at i-tune ang mga setting sa pamamagitan ng Model Context Protocol. Ito ay thin client sa ibabaw ng v2 API — read + manage lamang.
Manipis na layer
Ang MCP server ay manipis na wrapper sa v2 API — walang extra state.
Walang money tool
Walang payout tool ang server. Makakabasa at makakapamahala, pero hindi makakapadala ng pondo.
Walang i-install
Remote nagpapatakbo ang server. Ituro lang ang AI assistant sa URL.
Kumonekta at i-configure.
Idagdag ang FaucetPay MCP server sa config ng AI assistant. Ituro sa iyong faucet gamit ang scoped read o manage key.
// ~/.cursor/mcp.json
{
"mcpServers": {
"faucetpay": {
"url": "https://mcp.faucetpay.io/mcp",
"headers": { "Authorization": "Bearer fpk_your_read_or_manage_key" }
}
}
}Configuration
| Parameter | Uri | Paglalarawan |
|---|---|---|
| urlKinakailangan | string | URL ng MCP server |
| AuthorizationKinakailangan | header | Scoped API key (read o manage scope) |
Tools.
Read-only at manage tool na ibinubunyag ng MCP server.
Read tools
get_faucetKunin ang faucet detailsget_balancesKunin ang faucet balancesget_balanceKunin ang kasalukuyang faucet balance para sa isang coin.get_payoutsI-list ang mga kamakailang payoutget_currenciesI-list ang mga sinusuportahang currency at limit.check_addressI-check kung ang address ay rehistradong FaucetPay user.get_daily_statsKunin ang pang-araw-araw na estadistikaget_user_statsKunin ang estadistika ng userget_transactionsI-list ang mga transaksyonget_ratelimitsKunin ang mga rate limitget_low_balance_notificationKunin ang low-balance settings
Manage tools
get_ip_whitelistKunin ang IP whitelistset_ip_whitelistI-update ang IP whitelistget_anti_fraudKunin ang anti-fraud settingstoggle_anti_fraudI-toggle ang anti-fraudupdate_anti_fraud_rulesI-update ang anti-fraud rulesupdate_faucet_settingsI-update ang faucet settingset_ratelimitsItakda ang rate limittoggle_low_balance_notificationI-toggle ang low-balance alert
Seguridad at best practices.
Mga best practice sa ligtas na paggamit ng MCP server.
- Gumamit ng read o manage key — huwag send key. Walang payout tool ang server na ito.
- Itakda ang maikling expiry. Bigyan ng lifetime ang key para hindi forever ma-abuse ang stale config.
- I-revoke agad kung na-expose. Isang click sa Manage page ang pumatay sa key.
- Pansinin ang anti-fraud advisories. Kapag pinatay o pinahina ang anti-fraud, nagbabalik ng warning.
Kumita ng higit pa
Monetize ang faucet gamit ang FaucetPay ad network.
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 | Uri | Paglalarawan |
|---|---|---|
| merchant_usernameKinakailangan | string | Your FaucetPay username — the account that receives the payment. |
| item_descriptionKinakailangan | string | Description of the item or service the buyer is paying for. |
| amount1Kinakailangan | string | Amount you want to receive, denominated in currency1. |
| currency1Kinakailangan | string | The pricing currency of your store (e.g. USDT, BTC, …). |
| currency2Opsyonal | string | The coin the buyer must pay with. Leave blank to let the buyer choose any supported coin. |
| customOpsyonal | string | An identifier passed back on the callback — use it for your order ID or user ID. |
| callback_urlOpsyonal | string | URL that receives the server-to-server POST callback once the payment completes. |
| success_urlOpsyonal | string | URL the buyer is redirected to after a successful payment. |
| cancel_urlOpsyonal | 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