开发者

FaucetPay API 参考。

通过单个 REST 端点发送微支付、验证用户并查询余额。表单编码请求、JSON 响应，每个水龙头一个 api_key。

Overview

在 FaucetPay 上构建水龙头、付款与自动化。

一个小而可预测的基于 HTTPS 的 REST API。每个端点接受 form-encoded 的 POST 请求体，返回带有顶层 status 整数的 JSON，并使用你的水龙头 api_key 进行认证。无需 OAuth，无需 SDK。

基于HTTPS的REST

每个端点接受表单编码的POST请求体并返回JSON。

每个水龙头一个密钥

你的水龙头api_key验证每个请求。将其保留在服务器端。

IP感知

使用/send发送ip_address以启用跨水龙头滥用检测。

Base URL

https://faucetpay.io/api/v1

Authentication

每个请求都附带你的 api_key。

在每个POST请求体的api_key字段中传递你的水龙头api_key。

切勿暴露你的api_key

将密钥发送到浏览器或公开仓库是水龙头被掏空的第一大原因。

1打开水龙头所有者面板并选择一个水龙头。

2在Manage → API & Webhooks中，查看或重新生成密钥。

3将密钥存储在后端密钥管理器中，不要放在代码仓库中。

Quick start

在一分钟内发送你的第一笔付款。

将 YOUR_API_KEY 替换为真实的水龙头密钥，指定一个测试用户（用你自己的邮箱即可），然后发送。

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]&currency=BTC"

Format

请求与响应结构。

所有端点均为 POST、form-encoded 并返回 JSON。所有端点的封装结构一致，因此你的客户端代码可以共用解析逻辑。

请求application/x-www-form-urlencoded

Content-Type: application/x-www-form-urlencoded

api_key=YOUR_API_KEY
amount=100
[email protected]
currency=BTC
ip_address=203.0.113.4

响应application/json

{
  "status": 200,
  "message": "Payout completed successfully!",
  // …endpoint-specific fields
}

响应封装

参数	类型	描述
status必填	integer	状态
message必填	string	消息
…可选	varies	数据

Endpoints

API 接口总览

五个端点覆盖水龙头所有者的每个场景：发送付款、验证用户、查询余额、列出历史记录以及查看币种列表。

POST/send

Send

从你的账户余额向FaucetPay用户支付加密货币。

请求体参数

参数	类型	描述
api_key必填	string	你的水龙头API密钥。
amount必填	integer	以货币的最小单位表示的金额（BTC为聪）。
to必填	string	目标：邮箱、用户名、钱包地址或payout_user_hash。
currency必填	string	大写货币符号，例如BTC、DOGE、USDT。
ip_address可选	string	领取者IP——强烈推荐；启用防滥用速率限制。
referral可选	string	附在此付款上的推荐标签，用于你自己的报告。

示例请求

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]&currency=BTC&ip_address=203.0.113.4"

示例响应

{
  "status": 200,
  "message": "OK",
  "rate_limit_remaining": 0.00049900,
  "currency": "BTC",
  "balance": 49900,
  "balance_bitcoin": 0.00049900,
  "payout_id": 12834721,
  "payout_user_hash": "3f9c1a2e6b7d0f5e8c4a9b2d1f6e0c8a7b5d2e91"
}

POST/checkaddress

Check address

验证目标是所选货币的已注册FaucetPay用户。

请求体参数

参数	类型	描述
api_key必填	string	你的水龙头API密钥。
address必填	string	要验证的邮箱、用户名、钱包地址或payout_user_hash。
currency必填	string	用于检查成员资格的大写货币符号。

示例请求

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]&currency=BTC"

示例响应

{
  "status": 200,
  "message": "This address belongs to a FaucetPay user.",
  "payout_user_hash": "3f9c1a2e6b7d0f5e8c4a9b2d1f6e0c8a7b5d2e91"
}

POST/getbalance

Check balance

获取指定货币的当前水龙头余额。

请求体参数

参数	类型	描述
api_key必填	string	你的水龙头API密钥。
currency必填	string	大写货币符号。

示例请求

curl -X POST https://faucetpay.io/api/v1/getbalance \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "api_key=YOUR_API_KEY&currency=BTC"

示例响应

{
  "status": 200,
  "message": "OK",
  "currency": "BTC",
  "balance": 49900,
  "balance_bitcoin": 0.00049900
}

POST/payouts

List payouts

返回你最近的付款，最新的优先。

请求体参数

参数	类型	描述
api_key必填	string	你的水龙头API密钥。
count可选	integer	返回多少笔付款（1–100，默认10）。
currency可选	string	筛选单一货币。留空表示全部。

示例请求

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&currency=BTC"

示例响应

{
  "status": 200,
  "message": "OK",
  "rewards": [
    {
      "to":     "[email protected]",
      "amount": 100,
      "date":   "02-05-26 21:12:00 GMT"
    }
  ]
}

POST/currencies

Supported currencies

返回FaucetPay上当前活跃的所有货币。

请求体参数

参数	类型	描述
api_key必填	string	你的水龙头API密钥。

示例请求

curl -X POST https://faucetpay.io/api/v1/currencies \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "api_key=YOUR_API_KEY"

示例响应

{
  "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" }
  ]
}

Reference

状态码。

每个端点返回这些状态码之一。

代码	语气	含义
200	成功	OK — 请求成功
403	错误	禁止 — 无效或缺少api_key
405	错误	方法不允许——使用POST
413	警告	载荷过大
414	警告	URI过长
415	警告	不支持的媒体类型——使用application/x-www-form-urlencoded
416	错误	请求的范围无法满足
417	错误	期望失败
418	警告	我是个茶壶
419	错误	认证超时
420	警告	速率限制——请求过多
421	错误	错误的请求
422	警告	不可处理的实体——验证错误
456	错误	不可恢复的错误

Reference

支持的币种。

FaucetPay上活跃的每种货币都可用于付款。

Bitcoin

BTC

活跃

Ethereum

ETH

活跃

Tether

USDT

活跃

Litecoin

LTC

活跃

Dogecoin

DOGE

活跃

Bitcoin Cash

BCH

活跃

Dash

DASH

活跃

DigiByte

DGB

活跃

Tron

TRX

活跃

Zcash

ZEC

活跃

Solana

SOL

活跃

BNB

活跃

Feyorra

FEY

活跃

USD Coin

USDC

活跃

Reference

速率限制。

限制按每个水龙头的 api_key 应用，既保护你的集成，也保障我们网络的健康。

正式密钥

60/分钟

每个水龙头api_key。允许突发至120。

突发容忍度

突发窗口

超过限制的短时突发最多容忍2秒。

Reference

安全最佳实践。

一份简短而有主张的清单。每一项都对应我们在实际中遇到过的一类事件。

切勿将api_key发送到浏览器。像密码一样对待它：仅后端、密钥管理器、绝不放在git中。
始终使用/send发送ip_address。它启用跨水龙头滥用检测。
以聪为单位验证金额。常见错误是发送小数值而非最小单位整数。
在服务器端去重领取。不要依赖客户端来防止重复提交。
定期轮换密钥。我们支持热轮换：确认后旧密钥立即停止工作。

有什么不清楚？

在帮助台开一个工单，我们会更新文档。

打开帮助台

Scoped-key API (v2)

使用 Bearer 令牌的范围化、可撤销密钥。

v2 API 是面向自动化的现代接口。你不再使用单一的全权水龙头密钥，而是创建范围受限的密钥（read / send / manage / admin），以 Bearer 令牌发送，并获得一致的 JSON 封装。上方的旧版 /api/v1 保持不变。

Bearer令牌认证

将密钥作为Authorization: Bearer '<key>'发送。

最小权限范围

仅使用工具所需的范围创建密钥。

一致的JSON信封

每个v2响应使用相同的{status, message, data}结构。

Base URL

https://faucetpay.io/api/v2

示例 — 已认证请求

curl -X POST https://faucetpay.io/api/v2/balances \
  -H "Authorization: Bearer YOUR_SCOPED_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Scoped-key API (v2)

认证与作用域。

在水龙头的「管理」页面创建范围受限的密钥。每个密钥仅显示一次，以哈希形式存储，并可为每个密钥设置 IP 白名单以及（用于 send）每日 USD 上限。

1水龙头所有者 → 管理水龙头 → 限定API密钥。

2创建密钥，勾选最小范围，复制一次。

3存储在服务器端；如泄露，从同一页面立即撤销。

read

读取余额、付款、统计、货币、设置和反欺诈状态。

send转移资金/账户

进行付款——转移真实资金。仅在服务器端保存。

manage

更改水龙头设置、速率限制、IP白名单和反欺诈规则。

admin收取上架费用

创建水龙头并请求上架批准。不能删除水龙头。

旧密钥仍然有效

你现有的水龙头api_key在v1端点上继续有效。

Scoped-key API (v2)

Endpoints.

每个v2端点使用Bearer认证并返回标准信封。

读取

端点	范围	请求体	描述
`/balance`	read	`currency?`	检查某个货币的水龙头余额。
`/balances`	read	`—`	列出所有货币的余额。
`/currencies`	read	`—`	列出支持的货币。
`/check-address`	read	`address`	验证目标地址。
`/payouts`	read	`currency?, count?`	列出最近的付款。
`/faucet`	read	`—`	获取水龙头详情
`/stats/daily`	read	`—`	每日统计
`/stats/users`	read	`coin, page`	用户统计
`/transactions`	read	`coin, page`	交易
`/ratelimits`	read	`—`	速率限制
`/low-balance-notification`	read	`—`	低余额警报

管理

端点	范围	请求体	描述
`/faucet/update`	manage	`faucet_name, faucet_domain, faucet_url, faucet_description, timer_minutes, currencies_selected?, categories_selected?`	更新水龙头设置
`/ratelimits/set`	manage	`ratelimits[]`	设置速率限制
`/ip-whitelist`	manage	`—`	IP白名单
`/ip-whitelist/set`	manage	`ip_whitelist`	更新IP白名单
`/low-balance-notification/toggle`	manage	`—`	切换低余额警报
`/faucet/create`	admin	`faucet_name, faucet_domain, faucet_url`	创建水龙头
`/approval-cost`	admin	`coin`	上架批准费用
`/faucet/request-approval`	admin	`coin`	请求上架批准

反欺诈

端点	范围	请求体	描述
`/anti-fraud/rules`	manage	`—`	反欺诈规则
`/anti-fraud/toggle`	manage	`—`	切换反欺诈
`/anti-fraud/rules/update`	manage	`trust_rank, negative_rank?, whitelist?, blacklist?`	更新反欺诈规则

发送

端点	范围	请求体	描述
`/send`	send	`idempotency_key, currency, amount, to, ip_address?, referral?`	发送付款

Scoped-key API (v2)

发送付款。

v2 send 是安全的付款方式：它需要幂等键，并遵循可选的每密钥每日 USD 上限。它与旧版 send 使用相同的反欺诈 / 余额 / 速率限制流程。

幂等性是强制性的

每个/send都需要幂等键。使用相同密钥重试永远不会重复支付。

每日付款上限

创建发送密钥时可以设置每日付款上限。超过上限返回429，付款不会执行。

POST/sendsend

发送带有幂等性和可选每日上限的付款。

请求体参数

参数	类型	描述
idempotency_key必填	string	每个逻辑付款唯一。使用相同密钥重试永远不会重复支付。
to必填	string	接收者：邮箱、用户名、钱包地址或payout_user_hash。
amount必填	integer	以货币的最小单位表示的金额（例如BTC为聪）。
currency必填	string	大写货币符号，例如BTC、DOGE。
ip_address可选	string	接收者IP——推荐用于反欺诈。
referral可选	string	用于你自己报告的推荐标签。

示例请求

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"}'

示例响应

{
  "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"
  }
}

Scoped-key API (v2)

Webhooks.

订阅付款事件并接收带 HMAC 签名的 POST。请在水龙头的「管理」页面配置它们——webhook 管理仅支持会话 + 2FA，因此范围受限的密钥永远无法注册投递端点。

事件驱动

订阅payout.sent和payout.failed事件。

HMAC签名

每次交付包含X-FaucetPay-Signature头，带有body的HMAC-SHA256。

SSRF防护

Webhook URL必须是公共HTTPS端点。内部IP被拒绝。

示例投递

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!"
  }
}

验证签名

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();

信任前先验证

用你的webhook密钥对原始请求体重新计算HMAC，并与头进行恒定时间比较。

Scoped-key API (v2)

Errors.

v2使用标准HTTP状态码加信封中的描述性消息。

代码	语气	含义
200	成功	200 OK
400	警告	400 错误请求
401	错误	401 未授权
403	错误	403 禁止
409	警告	409 冲突
429	警告	429 请求过多

MCP server

通过任意 AI 智能体管理你的水龙头。

FaucetPay MCP 服务器让 AI 助手（Cursor、Claude Code、Windsurf 等）通过 Model Context Protocol 读取你的水龙头并调整设置。它是 v2 API 之上的轻量客户端——仅支持 read + manage。

薄层

MCP服务器是v2 API上的薄包装——无额外状态。

无资金工具

服务器不提供付款工具。它可以读取和管理，但不能发送资金。

无需安装

服务器远程运行。只需将你的AI助手指向URL。

内置指南

服务器提供代理指令、安全审查提示和变现提示。

MCP server

连接与配置。

将FaucetPay MCP服务器添加到你的AI助手配置中。使用限定读取或管理密钥指向你的水龙头。

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "faucetpay": {
      "url": "https://mcp.faucetpay.io/mcp",
      "headers": { "Authorization": "Bearer fpk_your_read_or_manage_key" }
    }
  }
}

配置

参数	类型	描述
url必填	string	MCP服务器URL
Authorization必填	header	限定API密钥（读取或管理范围）

MCP server

Tools.

MCP服务器公开的只读和管理工具。

read

读取工具

get_faucet获取水龙头详情
get_balances获取水龙头余额
get_balance获取某个货币的当前水龙头余额。
get_payouts列出最近的付款
get_currencies列出支持的货币及其限额。
check_address检查地址是否为已注册FaucetPay用户。
get_daily_stats获取每日统计
get_user_stats获取用户统计
get_transactions列出交易
get_ratelimits获取速率限制
get_low_balance_notification获取低余额设置

manage

管理工具

get_ip_whitelist获取IP白名单
set_ip_whitelist更新IP白名单
get_anti_fraud获取反欺诈设置
toggle_anti_fraud切换反欺诈
update_anti_fraud_rules更新反欺诈规则
update_faucet_settings更新水龙头设置
set_ratelimits设置速率限制
toggle_low_balance_notification切换低余额警报

提示和资源

斜杠式提示faucetpay_security_review和faucetpay_monetization_setup随服务器提供以供按需帮助。

MCP server

安全与最佳实践。

安全使用MCP服务器的最佳实践。

使用读取或管理密钥——切勿使用发送密钥。此服务器不提供付款工具。
设置较短的有效期。给密钥一个生命周期，使过时配置不会被永久滥用。
泄露后立即撤销。在Manage页面上点击一次即可停用密钥。
注意反欺诈建议。禁用或削弱反欺诈会返回警告。

赚取更多

用FaucetPay广告网络变现你的水龙头。

打开广告网络

Merchant API

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.

Enable merchant payments first

Apply for a merchant account from your FaucetPay dashboard before going live. Payments are received under your FaucetPay username.

Merchant API

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.

POSThttps://faucetpay.io/merchant/webscr

Submit the form with a standard browser POST (not XHR) — the buyer must land on the hosted checkout page to confirm the payment.

参数	类型	描述
merchant_username必填	string	Your FaucetPay username — the account that receives the payment.
item_description必填	string	Description of the item or service the buyer is paying for.
amount1必填	string	Amount you want to receive, denominated in currency1.
currency1必填	string	The pricing currency of your store (e.g. USDT, BTC, …).
currency2可选	string	The coin the buyer must pay with. Leave blank to let the buyer choose any supported coin.
custom可选	string	An identifier passed back on the callback — use it for your order ID or user ID.
callback_url可选	string	URL that receives the server-to-server POST callback once the payment completes.
success_url可选	string	URL the buyer is redirected to after a successful payment.
cancel_url可选	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>

Pinning the payment coin

If currency2 is set, the buyer can only pay with that exact coin. When blank, the buyer picks any supported coin and FaucetPay converts at the current exchange rate.

Merchant API

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
&currency1=USDT
&amount2=0.00105
&currency2=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

Never trust the callback alone

Anyone can POST fake data to your callback URL. Always confirm the payment by calling the verify endpoint with the received token — it returns the authoritative payment record and each token works exactly once. Retries back off for up to several hours, so keep your endpoint idempotent using the custom field.

开发者

FaucetPay API 参考。

通过单个 REST 端点发送微支付、验证用户并查询余额。表单编码请求、JSON 响应，每个水龙头一个 api_key。

Get an API key

Overview

在 FaucetPay 上构建水龙头、付款与自动化。

基于HTTPS的REST

每个端点接受表单编码的POST请求体并返回JSON。

每个水龙头一个密钥

你的水龙头api_key验证每个请求。将其保留在服务器端。

IP感知

使用/send发送ip_address以启用跨水龙头滥用检测。

Base URL

https://faucetpay.io/api/v1

Authentication

每个请求都附带你的 api_key。

在每个POST请求体的api_key字段中传递你的水龙头api_key。

切勿暴露你的api_key

将密钥发送到浏览器或公开仓库是水龙头被掏空的第一大原因。

1打开水龙头所有者面板并选择一个水龙头。

2在Manage → API & Webhooks中，查看或重新生成密钥。

3将密钥存储在后端密钥管理器中，不要放在代码仓库中。

Quick start

在一分钟内发送你的第一笔付款。

将 YOUR_API_KEY 替换为真实的水龙头密钥，指定一个测试用户（用你自己的邮箱即可），然后发送。

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]&currency=BTC"

Format

请求与响应结构。

所有端点均为 POST、form-encoded 并返回 JSON。所有端点的封装结构一致，因此你的客户端代码可以共用解析逻辑。

请求application/x-www-form-urlencoded

Content-Type: application/x-www-form-urlencoded

api_key=YOUR_API_KEY
amount=100
[email protected]
currency=BTC
ip_address=203.0.113.4

响应application/json

{
  "status": 200,
  "message": "Payout completed successfully!",
  // …endpoint-specific fields
}

响应封装

参数	类型	描述
status必填	integer	状态
message必填	string	消息
…可选	varies	数据

Endpoints

API 接口总览

五个端点覆盖水龙头所有者的每个场景：发送付款、验证用户、查询余额、列出历史记录以及查看币种列表。

POST/send

Send

从你的账户余额向FaucetPay用户支付加密货币。

请求体参数

参数	类型	描述
api_key必填	string	你的水龙头API密钥。
amount必填	integer	以货币的最小单位表示的金额（BTC为聪）。
to必填	string	目标：邮箱、用户名、钱包地址或payout_user_hash。
currency必填	string	大写货币符号，例如BTC、DOGE、USDT。
ip_address可选	string	领取者IP——强烈推荐；启用防滥用速率限制。
referral可选	string	附在此付款上的推荐标签，用于你自己的报告。

示例请求

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]&currency=BTC&ip_address=203.0.113.4"

示例响应

{
  "status": 200,
  "message": "OK",
  "rate_limit_remaining": 0.00049900,
  "currency": "BTC",
  "balance": 49900,
  "balance_bitcoin": 0.00049900,
  "payout_id": 12834721,
  "payout_user_hash": "3f9c1a2e6b7d0f5e8c4a9b2d1f6e0c8a7b5d2e91"
}

POST/checkaddress

Check address

验证目标是所选货币的已注册FaucetPay用户。

请求体参数

参数	类型	描述
api_key必填	string	你的水龙头API密钥。
address必填	string	要验证的邮箱、用户名、钱包地址或payout_user_hash。
currency必填	string	用于检查成员资格的大写货币符号。

示例请求

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]&currency=BTC"

示例响应

{
  "status": 200,
  "message": "This address belongs to a FaucetPay user.",
  "payout_user_hash": "3f9c1a2e6b7d0f5e8c4a9b2d1f6e0c8a7b5d2e91"
}

POST/getbalance

Check balance

获取指定货币的当前水龙头余额。

请求体参数

参数	类型	描述
api_key必填	string	你的水龙头API密钥。
currency必填	string	大写货币符号。

示例请求

curl -X POST https://faucetpay.io/api/v1/getbalance \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "api_key=YOUR_API_KEY&currency=BTC"

示例响应

{
  "status": 200,
  "message": "OK",
  "currency": "BTC",
  "balance": 49900,
  "balance_bitcoin": 0.00049900
}

POST/payouts

List payouts

返回你最近的付款，最新的优先。

请求体参数

参数	类型	描述
api_key必填	string	你的水龙头API密钥。
count可选	integer	返回多少笔付款（1–100，默认10）。
currency可选	string	筛选单一货币。留空表示全部。

示例请求

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&currency=BTC"

示例响应

{
  "status": 200,
  "message": "OK",
  "rewards": [
    {
      "to":     "[email protected]",
      "amount": 100,
      "date":   "02-05-26 21:12:00 GMT"
    }
  ]
}

POST/currencies

Supported currencies

返回FaucetPay上当前活跃的所有货币。

请求体参数

参数	类型	描述
api_key必填	string	你的水龙头API密钥。

示例请求

curl -X POST https://faucetpay.io/api/v1/currencies \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "api_key=YOUR_API_KEY"

示例响应

{
  "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" }
  ]
}

Reference

状态码。

每个端点返回这些状态码之一。

代码	语气	含义
200	成功	OK — 请求成功
403	错误	禁止 — 无效或缺少api_key
405	错误	方法不允许——使用POST
413	警告	载荷过大
414	警告	URI过长
415	警告	不支持的媒体类型——使用application/x-www-form-urlencoded
416	错误	请求的范围无法满足
417	错误	期望失败
418	警告	我是个茶壶
419	错误	认证超时
420	警告	速率限制——请求过多
421	错误	错误的请求
422	警告	不可处理的实体——验证错误
456	错误	不可恢复的错误

Reference

支持的币种。

FaucetPay上活跃的每种货币都可用于付款。

Bitcoin

BTC

活跃

Ethereum

ETH

活跃

Tether

USDT

活跃

Litecoin

LTC

活跃

Dogecoin

DOGE

活跃

Bitcoin Cash

BCH

活跃

Dash

DASH

活跃

DigiByte

DGB

活跃

Tron

TRX

活跃

Zcash

ZEC

活跃

Solana

SOL

活跃

BNB

活跃

Feyorra

FEY

活跃

USD Coin

USDC

活跃

Reference

速率限制。

限制按每个水龙头的 api_key 应用，既保护你的集成，也保障我们网络的健康。

正式密钥

60/分钟

每个水龙头api_key。允许突发至120。

突发容忍度

突发窗口

超过限制的短时突发最多容忍2秒。

Reference

安全最佳实践。

一份简短而有主张的清单。每一项都对应我们在实际中遇到过的一类事件。

切勿将api_key发送到浏览器。像密码一样对待它：仅后端、密钥管理器、绝不放在git中。
始终使用/send发送ip_address。它启用跨水龙头滥用检测。
以聪为单位验证金额。常见错误是发送小数值而非最小单位整数。
在服务器端去重领取。不要依赖客户端来防止重复提交。
定期轮换密钥。我们支持热轮换：确认后旧密钥立即停止工作。

有什么不清楚？

在帮助台开一个工单，我们会更新文档。

打开帮助台

Scoped-key API (v2)

使用 Bearer 令牌的范围化、可撤销密钥。

Bearer令牌认证

将密钥作为Authorization: Bearer '<key>'发送。

最小权限范围

仅使用工具所需的范围创建密钥。

一致的JSON信封

每个v2响应使用相同的{status, message, data}结构。

Base URL

https://faucetpay.io/api/v2

示例 — 已认证请求

curl -X POST https://faucetpay.io/api/v2/balances \
  -H "Authorization: Bearer YOUR_SCOPED_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Scoped-key API (v2)

认证与作用域。

在水龙头的「管理」页面创建范围受限的密钥。每个密钥仅显示一次，以哈希形式存储，并可为每个密钥设置 IP 白名单以及（用于 send）每日 USD 上限。

1水龙头所有者 → 管理水龙头 → 限定API密钥。

2创建密钥，勾选最小范围，复制一次。

3存储在服务器端；如泄露，从同一页面立即撤销。

read

读取余额、付款、统计、货币、设置和反欺诈状态。

send转移资金/账户

进行付款——转移真实资金。仅在服务器端保存。

manage

更改水龙头设置、速率限制、IP白名单和反欺诈规则。

admin收取上架费用

创建水龙头并请求上架批准。不能删除水龙头。

旧密钥仍然有效

你现有的水龙头api_key在v1端点上继续有效。

Scoped-key API (v2)

Endpoints.

每个v2端点使用Bearer认证并返回标准信封。

读取

端点	范围	请求体	描述
`/balance`	read	`currency?`	检查某个货币的水龙头余额。
`/balances`	read	`—`	列出所有货币的余额。
`/currencies`	read	`—`	列出支持的货币。
`/check-address`	read	`address`	验证目标地址。
`/payouts`	read	`currency?, count?`	列出最近的付款。
`/faucet`	read	`—`	获取水龙头详情
`/stats/daily`	read	`—`	每日统计
`/stats/users`	read	`coin, page`	用户统计
`/transactions`	read	`coin, page`	交易
`/ratelimits`	read	`—`	速率限制
`/low-balance-notification`	read	`—`	低余额警报

管理

端点	范围	请求体	描述
`/faucet/update`	manage	`faucet_name, faucet_domain, faucet_url, faucet_description, timer_minutes, currencies_selected?, categories_selected?`	更新水龙头设置
`/ratelimits/set`	manage	`ratelimits[]`	设置速率限制
`/ip-whitelist`	manage	`—`	IP白名单
`/ip-whitelist/set`	manage	`ip_whitelist`	更新IP白名单
`/low-balance-notification/toggle`	manage	`—`	切换低余额警报
`/faucet/create`	admin	`faucet_name, faucet_domain, faucet_url`	创建水龙头
`/approval-cost`	admin	`coin`	上架批准费用
`/faucet/request-approval`	admin	`coin`	请求上架批准

反欺诈

端点	范围	请求体	描述
`/anti-fraud/rules`	manage	`—`	反欺诈规则
`/anti-fraud/toggle`	manage	`—`	切换反欺诈
`/anti-fraud/rules/update`	manage	`trust_rank, negative_rank?, whitelist?, blacklist?`	更新反欺诈规则

发送

端点	范围	请求体	描述
`/send`	send	`idempotency_key, currency, amount, to, ip_address?, referral?`	发送付款

Scoped-key API (v2)

发送付款。

v2 send 是安全的付款方式：它需要幂等键，并遵循可选的每密钥每日 USD 上限。它与旧版 send 使用相同的反欺诈 / 余额 / 速率限制流程。

幂等性是强制性的

每个/send都需要幂等键。使用相同密钥重试永远不会重复支付。

每日付款上限

创建发送密钥时可以设置每日付款上限。超过上限返回429，付款不会执行。

POST/sendsend

发送带有幂等性和可选每日上限的付款。

请求体参数

参数	类型	描述
idempotency_key必填	string	每个逻辑付款唯一。使用相同密钥重试永远不会重复支付。
to必填	string	接收者：邮箱、用户名、钱包地址或payout_user_hash。
amount必填	integer	以货币的最小单位表示的金额（例如BTC为聪）。
currency必填	string	大写货币符号，例如BTC、DOGE。
ip_address可选	string	接收者IP——推荐用于反欺诈。
referral可选	string	用于你自己报告的推荐标签。

示例请求

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"}'

示例响应

{
  "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"
  }
}

Scoped-key API (v2)

Webhooks.

事件驱动

订阅payout.sent和payout.failed事件。

HMAC签名

每次交付包含X-FaucetPay-Signature头，带有body的HMAC-SHA256。

SSRF防护

Webhook URL必须是公共HTTPS端点。内部IP被拒绝。

示例投递

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!"
  }
}

验证签名

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();

信任前先验证

用你的webhook密钥对原始请求体重新计算HMAC，并与头进行恒定时间比较。

Scoped-key API (v2)

Errors.

v2使用标准HTTP状态码加信封中的描述性消息。

代码	语气	含义
200	成功	200 OK
400	警告	400 错误请求
401	错误	401 未授权
403	错误	403 禁止
409	警告	409 冲突
429	警告	429 请求过多

MCP server

通过任意 AI 智能体管理你的水龙头。

薄层

MCP服务器是v2 API上的薄包装——无额外状态。

无资金工具

服务器不提供付款工具。它可以读取和管理，但不能发送资金。

无需安装

服务器远程运行。只需将你的AI助手指向URL。

内置指南

服务器提供代理指令、安全审查提示和变现提示。

MCP server

连接与配置。

将FaucetPay MCP服务器添加到你的AI助手配置中。使用限定读取或管理密钥指向你的水龙头。

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "faucetpay": {
      "url": "https://mcp.faucetpay.io/mcp",
      "headers": { "Authorization": "Bearer fpk_your_read_or_manage_key" }
    }
  }
}

配置

参数	类型	描述
url必填	string	MCP服务器URL
Authorization必填	header	限定API密钥（读取或管理范围）

MCP server

Tools.

MCP服务器公开的只读和管理工具。

read

读取工具

get_faucet获取水龙头详情
get_balances获取水龙头余额
get_balance获取某个货币的当前水龙头余额。
get_payouts列出最近的付款
get_currencies列出支持的货币及其限额。
check_address检查地址是否为已注册FaucetPay用户。
get_daily_stats获取每日统计
get_user_stats获取用户统计
get_transactions列出交易
get_ratelimits获取速率限制
get_low_balance_notification获取低余额设置

manage

管理工具

get_ip_whitelist获取IP白名单
set_ip_whitelist更新IP白名单
get_anti_fraud获取反欺诈设置
toggle_anti_fraud切换反欺诈
update_anti_fraud_rules更新反欺诈规则
update_faucet_settings更新水龙头设置
set_ratelimits设置速率限制
toggle_low_balance_notification切换低余额警报

提示和资源

斜杠式提示faucetpay_security_review和faucetpay_monetization_setup随服务器提供以供按需帮助。

MCP server

安全与最佳实践。

安全使用MCP服务器的最佳实践。

使用读取或管理密钥——切勿使用发送密钥。此服务器不提供付款工具。
设置较短的有效期。给密钥一个生命周期，使过时配置不会被永久滥用。
泄露后立即撤销。在Manage页面上点击一次即可停用密钥。
注意反欺诈建议。禁用或削弱反欺诈会返回警告。

赚取更多

用FaucetPay广告网络变现你的水龙头。

打开广告网络

Merchant API

Accept crypto payments in your store.

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.

Enable merchant payments first

Apply for a merchant account from your FaucetPay dashboard before going live. Payments are received under your FaucetPay username.

Merchant API

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.

POSThttps://faucetpay.io/merchant/webscr

Submit the form with a standard browser POST (not XHR) — the buyer must land on the hosted checkout page to confirm the payment.

参数	类型	描述
merchant_username必填	string	Your FaucetPay username — the account that receives the payment.
item_description必填	string	Description of the item or service the buyer is paying for.
amount1必填	string	Amount you want to receive, denominated in currency1.
currency1必填	string	The pricing currency of your store (e.g. USDT, BTC, …).
currency2可选	string	The coin the buyer must pay with. Leave blank to let the buyer choose any supported coin.
custom可选	string	An identifier passed back on the callback — use it for your order ID or user ID.
callback_url可选	string	URL that receives the server-to-server POST callback once the payment completes.
success_url可选	string	URL the buyer is redirected to after a successful payment.
cancel_url可选	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>

Pinning the payment coin

If currency2 is set, the buyer can only pay with that exact coin. When blank, the buyer picks any supported coin and FaucetPay converts at the current exchange rate.

Merchant API

Callback & verification.

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
&currency1=USDT
&amount2=0.00105
&currency2=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

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

Never trust the callback alone