FaucetPay API リファレンス。
単一の REST エンドポイントで、少額の支払いの送付、ユーザーの確認、残高の照会ができます。フォームエンコードのリクエスト、JSON のレスポンス、フォーセットごとに1つの api_key。
FaucetPay でフォーセット、支払い、自動化を構築しましょう。
HTTPS 上の小さく予測可能な REST API です。すべてのエンドポイントはフォームエンコードの POST ボディを受け付け、トップレベルに status の整数を含む JSON を返し、フォーセットの api_key で認証します。OAuth も SDK も不要です。
HTTPS 上の REST
すべてのエンドポイントはフォームエンコードの POST ボディを受け付け、JSON を返します。
フォーセットごとに1つのキー
フォーセットの api_key ですべてのリクエストを認証します。サーバー側で保管してください。
IP を考慮
/send で ip_address を送ると、フォーセット横断の不正利用検出に活用されます。
https://faucetpay.io/api/v1すべてのリクエストで api_key を送信してください。
すべての POST ボディの api_key フィールドにフォーセットの api_key を渡してください。
1分以内に最初の支払いを送付しましょう。
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]¤cy=BTC"
リクエストとレスポンスの形式。
すべてのエンドポイントは POST でフォームエンコードを使用し、JSON を返します。エンベロープはすべてのエンドポイントで共通なので、クライアントのコードで解析ロジックを共有できます。
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
}レスポンスのエンベロープ
| パラメータ | 種類 | 説明 |
|---|---|---|
| status必須 | integer | ステータス |
| message必須 | string | メッセージ |
| …任意 | varies | データ |
API の全体像
5つのエンドポイントで、支払いの送付、ユーザーの確認、残高の確認、履歴の一覧、コイン一覧の取得と、フォーセットオーナーのあらゆるシナリオに対応します。
/sendSend
アカウントの残高から FaucetPay ユーザーに暗号資産を支払います。
ボディのパラメータ
| パラメータ | 種類 | 説明 |
|---|---|---|
| api_key必須 | string | フォーセットの API キー。 |
| amount必須 | integer | コインの最小単位での金額（BTC の場合はサトシ）。 |
| to必須 | string | 送付先: メールアドレス、ユーザー名、またはウォレットアドレス。 |
| 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]¤cy=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"
}/checkaddressCheck address
送付先が、選択した通貨について登録済みの FaucetPay ユーザーかどうかを確認します。
ボディのパラメータ
| パラメータ | 種類 | 説明 |
|---|---|---|
| api_key必須 | string | フォーセットの API キー。 |
| address必須 | string | 確認するメールアドレス、ユーザー名、またはウォレットアドレス。 |
| 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]¤cy=BTC"
レスポンスの例
{
"status": 200,
"message": "This address belongs to a FaucetPay user.",
"payout_user_hash": "3f9c1a2e6b7d0f5e8c4a9b2d1f6e0c8a7b5d2e91"
}/getbalanceCheck 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¤cy=BTC"
レスポンスの例
{
"status": 200,
"message": "OK",
"currency": "BTC",
"balance": 49900,
"balance_bitcoin": 0.00049900
}/payoutsList payouts
最近の支払いを新しい順に返します。
ボディのパラメータ
| パラメータ | 種類 | 説明 |
|---|---|---|
| api_key必須 | string | フォーセットの API キー。 |
| count任意 | integer | 返す支払いの件数（1〜100、既定は10）。 |
| currency任意 | string | 1つのコインに絞り込みます。省略するとすべて。 |
リクエストの例
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"
レスポンスの例
{
"status": 200,
"message": "OK",
"rewards": [
{
"to": "[email protected]",
"amount": 100,
"date": "02-05-26 21:12:00 GMT"
}
]
}/currenciesSupported 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" }
]
}ステータスコード。
すべてのエンドポイントは HTTP 200 を返し、実際の結果はレスポンスボディの status フィールドに含まれます。これで分岐してください。v1 が送るのは以下の値のみです。
| コード | 種類 | 意味 |
|---|---|---|
| 200 | 成功 | OK — リクエストは成功しました |
| 401 | エラー | アクセス拒否 — IP がこのフォーセットのホワイトリストに登録されていないか、フォーセットのオーナーのアカウントが停止されています |
| 402 | エラー | フォーセットの残高がこの支払いに足りません |
| 403 | エラー | Forbidden — api_key が無効または未指定です |
| 404 | エラー | 不明な API メソッド、またはリクエストが POST ではありません |
| 405 | エラー | 無効な金額 — コインの最小単位での正の整数である必要があります |
| 410 | エラー | 無効な通貨 — FaucetPay が対応しているコインではありません |
| 450 | 警告 | ご自身のフォーセットに設定した送金上限に達しました — 後でもう一度お試しください |
| 456 | エラー | 受取人に支払えません — そのアドレスを所有するユーザーがいないか、アカウントが停止中または未確認です |
| 457 | エラー | 受取人がご自身のルールによって拒否されました — ブラックリストに登録されているか、不正対策チェックに失敗しました |
| 459 | 警告 | レート制限 — お使いの IP からの API リクエストが多すぎます |
対応コイン。
FaucetPay で有効なすべてのコインを支払いに利用できます。
レート制限。
制限はフォーセットの api_key ごとに適用され、あなたの連携と当社のネットワークの両方を健全に保ちます。
60 / 分
フォーセットの api_key ごと。最大120までのバーストを許容します。
バーストの期間
上限を超える短いバーストは最大2秒間許容されます。
セキュリティのベストプラクティス。
短く明確なチェックリストです。各項目は、実際に発生したインシデントの種類に対応しています。
- api_key を決してブラウザに含めないでください。パスワードと同様に扱い、バックエンドでのみ使用してシークレットマネージャーに保管し、git には含めないでください。
- /send では必ず ip_address を送信してください。フォーセット横断の不正利用検出に活用されます。
- 金額の単位がサトシであることを確認してください。最小単位の整数ではなく、コインの小数値を送ってしまうのはよくあるバグです。
- 受け取りの重複はサーバー側で排除してください。二重送信の防止をクライアントに頼らないでください。
- キーは定期的にローテーションしてください。ホットローテーションに対応しており、ローテーションを確定した瞬間に古いキーは使えなくなります。
不明な点がありますか？
ヘルプデスクでチケットを作成していただければ、ドキュメントを更新します。
Bearer トークンによる、スコープ付きで取り消し可能なキー。
v2 API は自動化のための最新のインターフェースです。万能なフォーセットキーを1つ使う代わりに、範囲を絞ったキー（read / send / manage / admin）を発行し、Bearer トークンとして送信すると、一貫した JSON エンベロープが返ります。上記の旧 /api/v1 は変更されていません。
Bearer トークン認証
キーは Authorization: Bearer '<key>' として送信します。
最小権限のスコープ
ツールに必要なスコープだけを付けてキーを発行します。
一貫した JSON エンベロープ
v2 のすべてのレスポンスは同じ {status, message, data} の形式を使用します。
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 '{}'認証とスコープ。
スコープ付きキーはフォーセットの管理ページで発行します。各キーは一度だけ表示され、ハッシュ化して保存され、キーごとの IP ホワイトリストと（send の場合は）1日の USD 上限を設定できます。
残高、支払い、統計、通貨、設定、不正対策の状態を読み取ります。
支払いを行います — 実際の資金が移動します。サーバー側でのみ使用してください。
フォーセットの設定、レート制限、IP ホワイトリスト、不正対策のルールを変更します。
フォーセットを作成し、掲載の承認を申請します。フォーセットの削除はできません。
エンドポイント。
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 | — | 残高不足アラートを切り替え |
| エンドポイント | スコープ | ボディ | 説明 |
|---|---|---|---|
/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? | 支払いを送付 |
| エンドポイント | スコープ | ボディ | 説明 |
|---|---|---|---|
/faucet/create | admin | faucet_name, faucet_domain, faucet_url | フォーセットを作成 |
/approval-cost | admin | coin | 掲載承認の費用 |
/faucet/request-approval | admin | coin | 掲載の承認を申請 |
支払いの送付。
v2 の send は安全な支払い方法です。冪等キーが必須で、キーごとの1日の USD 上限（任意）が適用されます。旧 send と同じ不正対策 / 残高 / レート制限の処理を通ります。
/sendsend冪等キーと1日の上限（任意）を使って支払いを送付します。
ボディのパラメータ
| パラメータ | 種類 | 説明 |
|---|---|---|
| idempotency_key必須 | string | 論理的な支払いごとに一意。同じキーで再試行しても二重に支払われることはありません。 |
| to必須 | string | 受取人: メールアドレス、ユーザー名、またはウォレットアドレス。 |
| 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"
}
}Webhook。
支払いイベントを購読すると、HMAC 署名付きの POST を受け取れます。フォーセットの管理ページから設定してください。Webhook の管理はセッションと 2FA でのみ行えるため、スコープ付きキーで配信先のエンドポイントを登録することはできません。
イベント駆動
payout.sent と payout.failed のイベントを購読できます。
HMAC 署名
すべての配信には、ボディの HMAC-SHA256 を含む X-FaucetPay-Signature ヘッダーが付きます。
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();エラー。
v2 は標準の HTTP ステータスコードと、エンベロープ内のわかりやすいメッセージを使用します。
| コード | 種類 | 意味 |
|---|---|---|
| 200 | 成功 | 200 OK |
| 400 | 警告 | 400 Bad request |
| 401 | エラー | 401 Unauthorized |
| 403 | エラー | 403 Forbidden |
| 409 | 警告 | 409 Conflict |
| 429 | 警告 | 429 Too many requests |
あらゆる AI エージェントからフォーセットを管理。
FaucetPay の MCP サーバーを使うと、AI アシスタント（Cursor、Claude Code、Windsurf など）が Model Context Protocol を通じてフォーセットの情報を読み取り、設定を調整できます。v2 API の薄いクライアントで、read と manage のみに対応しています。
薄いレイヤー
MCP サーバーは v2 API の薄いラッパーで、追加の状態はありません。
資金を動かすツールなし
サーバーは支払いのツールを提供しません。読み取りと管理はできますが、資金の送付はできません。
インストール不要
サーバーはリモートで動作します。AI アシスタントに URL を指定するだけです。
接続と設定。
AI アシスタントの設定に FaucetPay の MCP サーバーを追加し、read または manage のスコープ付きキーでフォーセットに接続します。
// ~/.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 キー（read または manage スコープ） |
ツール。
MCP サーバーが提供する読み取り専用ツールと管理ツール。
読み取りツール
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残高不足の設定を取得
管理ツール
get_ip_whitelistIP ホワイトリストを取得set_ip_whitelistIP ホワイトリストを更新get_anti_fraud不正対策の設定を取得toggle_anti_fraud不正対策を切り替えupdate_anti_fraud_rules不正対策のルールを更新update_faucet_settingsフォーセットの設定を更新set_ratelimitsレート制限を設定toggle_low_balance_notification残高不足アラートを切り替え
セキュリティとベストプラクティス。
MCP サーバーを安全に使うためのベストプラクティスです。
- read または manage のキーを使い、send のキーは決して使わないでください。このサーバーは支払いのツールを提供しません。
- 短い有効期限を設定してください。キーに有効期間を設けておけば、古い設定がいつまでも悪用されることはありません。
- 漏えいした場合はすぐに取り消してください。管理ページでワンクリックするとキーが無効になります。
- 不正対策に関する警告に注意してください。不正対策を無効にしたり弱めたりすると警告が返されます。
さらに稼ぐ
FaucetPay の広告ネットワークでフォーセットを収益化しましょう。
ストアで暗号資産による支払いを受け付けましょう。
マーチャント API を使うと、あらゆるウェブサイトがホスティング型のチェックアウトページを通じて FaucetPay ユーザーからの支払いを受け付けられます。購入者は FaucetPay の残高から支払い、資金は即座にあなたのアカウントに入金されます。始めるのにキーやサーバー側の SDK は不要です。
ホスティング型チェックアウト
送信するのはシンプルな HTML フォームだけで、支払いページ全体は FaucetPay がホスティングします。機密情報があなたのサーバーを通ることはありません。
対応する任意のコイン
1つの通貨で価格を設定し、購入者は FaucetPay が対応する任意のコインで支払えます。支払いコインをご自身で固定することもできます。
即時決済
支払いは FaucetPay の残高間で移動するため、オンチェーン手数料も待ち時間もなく即座に確定します。
支払いフォーム。
チェックアウトは、FaucetPay のチェックアウトエンドポイントに POST されるシンプルな HTML フォームから始まります。購入者は FaucetPay がホスティングするページに移動し、支払いを確認して確定します。
フォームは通常のブラウザの POST（XHR ではなく）で送信してください。購入者は支払いを確定するために、ホスティング型のチェックアウトページに移動する必要があります。
| パラメータ | 種類 | 説明 |
|---|---|---|
| merchant_username必須 | string | あなたの FaucetPay ユーザー名（支払いを受け取るアカウント）。 |
| item_description必須 | string | 購入者が支払う商品またはサービスの説明。 |
| amount1必須 | string | 受け取りたい金額（currency1 建て）。 |
| currency1必須 | string | ストアの価格設定通貨（例: USDT、BTC など）。 |
| currency2任意 | string | 購入者が支払いに使うコイン。空欄にすると、購入者が対応する任意のコインを選べます。 |
| custom任意 | string | コールバックで返される識別子。注文 ID やユーザー ID に使用してください。 |
| callback_url任意 | string | 支払い完了時にサーバー間の POST コールバックを受け取る URL。 |
| success_url任意 | string | 支払い成功後に購入者がリダイレクトされる URL。 |
| cancel_url任意 | string | 購入者がキャンセルした場合にリダイレクトされる URL。 |
HTML フォームの例
<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>
コールバックと検証。
支払いが完了すると、FaucetPay は支払いの詳細と1回限りの検証トークンを含むフォームエンコードのコールバックを callback_url に POST します。商品を引き渡す前に、サーバー側でトークンを検証してください。
コールバックの例（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
トークンを検証
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"
}再試行のスケジュール
コールバックのリクエストには HTTP 200 OK で応答してください。200 の応答を受け取れなかった場合、当社のシステムはリクエストが失敗したとみなし、以下のスケジュールでコールバックを再試行します。
- コールバック（1st）:即時（支払い後）
- コールバック（2nd）:5分後
- コールバック（3rd）:15分後
- コールバック（4th）:30分後
- コールバック（5th）:60分後
- コールバック（6th）:120分後
- コールバック（7th）:240分後