FaucetPay API

https://faucetpay.io/api-docs
Admin
FaucetPay API is a REST interface for sending micro-payouts, verifying users, and checking balances...
Tokens:15,491
Snippets:108
Trust Score:10
Update:23 hours ago
Show doc for...
Tokens:
Raw
### Check balance - example response

Source: https://faucetpay.io/api-docs

Example JSON response from POST /getbalance, showing status, message, currency, balance, and balance_bitcoin.

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

--------------------------------

### Supported currencies - example response

Source: https://faucetpay.io/api-docs

Example JSON response from POST /currencies, showing status, message, currencies array, and currencies_names array with name and acronym.

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

--------------------------------

### GET /faucet

Source: https://faucetpay.io/api-docs

Get faucet details. Requires the 'read' scope.

```APIDOC
## GET /faucet

### Description
Get faucet details.

### Method
GET

### Endpoint
/faucet

### Parameters
None.

### Response
#### Success Response (200)
Standard envelope with faucet details.

```

--------------------------------

### Send payout - example response

Source: https://faucetpay.io/api-docs

Example JSON response from POST /send, showing status, message, rate_limit_remaining, currency, balance, balance_bitcoin, payout_id, and payout_user_hash.

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

--------------------------------

### List payouts - example response

Source: https://faucetpay.io/api-docs

Example JSON response from POST /payouts, showing status, message, and a rewards array with to, amount, and date.

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

--------------------------------

### Check address - example response

Source: https://faucetpay.io/api-docs

Example JSON response from POST /checkaddress, showing status, message, and payout_user_hash.

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

--------------------------------

### GET /ip-whitelist

Source: https://faucetpay.io/api-docs

Get IP whitelist. Requires the 'manage' scope.

```APIDOC
## GET /ip-whitelist

### Description
Get IP whitelist.

### Method
GET

### Endpoint
/ip-whitelist

### Parameters
None.

### Response
#### Success Response (200)
Standard envelope with IP whitelist.

```

--------------------------------

### Example response for POST /send

Source: https://faucetpay.io/api-docs

Shows a successful response from the v2 /send endpoint, including rate limit remaining, balance, and payout identifiers.

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

--------------------------------

### cURL example request for POST /send

Source: https://faucetpay.io/api-docs

Sends a payout using the v2 /send endpoint. Requires an idempotency key and honors an optional daily cap; exceeding the cap returns a 429.

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

--------------------------------

### GET /balance

Source: https://faucetpay.io/api-docs

Check your faucet balance for a coin. Requires the 'read' scope.

```APIDOC
## GET /balance

### Description
Check your faucet balance for a coin.

### Method
GET

### Endpoint
/balance

### Parameters
#### Body
- **currency** (string) - Optional - The currency code to check balance for.

### Response
#### Success Response (200)
Standard envelope with balance information.

```

--------------------------------

### GET /balances

Source: https://faucetpay.io/api-docs

List balances across all coins. Requires the 'read' scope.

```APIDOC
## GET /balances

### Description
List balances across all coins.

### Method
GET

### Endpoint
/balances

### Parameters
None.

### Response
#### Success Response (200)
Standard envelope with balances for all coins.

```

--------------------------------

### GET /ratelimits

Source: https://faucetpay.io/api-docs

Get rate limits. Requires the 'read' scope.

```APIDOC
## GET /ratelimits

### Description
Get rate limits.

### Method
GET

### Endpoint
/ratelimits

### Parameters
None.

### Response
#### Success Response (200)
Standard envelope with rate limits.

```

--------------------------------

### GET /currencies

Source: https://faucetpay.io/api-docs

List supported currencies. Requires the 'read' scope.

```APIDOC
## GET /currencies

### Description
List supported currencies.

### Method
GET

### Endpoint
/currencies

### Parameters
None.

### Response
#### Success Response (200)
Standard envelope with list of supported currencies.

```

--------------------------------

### GET /transactions

Source: https://faucetpay.io/api-docs

Get transactions. Requires the 'read' scope.

```APIDOC
## GET /transactions

### Description
Get transactions.

### Method
GET

### Endpoint
/transactions

### Parameters
#### Body
- **coin** (string) - Required - The coin for which to get transactions.
- **page** (integer) - Required - Page number.

### Response
#### Success Response (200)
Standard envelope with transactions.

```

--------------------------------

### GET /stats/daily

Source: https://faucetpay.io/api-docs

Get daily statistics. Requires the 'read' scope.

```APIDOC
## GET /stats/daily

### Description
Get daily statistics.

### Method
GET

### Endpoint
/stats/daily

### Parameters
None.

### Response
#### Success Response (200)
Standard envelope with daily statistics.

```

--------------------------------

### GET /anti-fraud/rules

Source: https://faucetpay.io/api-docs

Get anti-fraud rules. Requires the 'manage' scope.

```APIDOC
## GET /anti-fraud/rules

### Description
Get anti-fraud rules.

### Method
GET

### Endpoint
/anti-fraud/rules

### Parameters
None.

### Response
#### Success Response (200)
Standard envelope with anti-fraud rules.

```

--------------------------------

### Example callback (IPN) POST request

Source: https://faucetpay.io/api-docs

FaucetPay POSTs a form-encoded callback to your callback_url after a completed payment. The callback includes payment details and a single-use verification token. Respond with HTTP 200 OK to acknowledge receipt.

```http
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
```

--------------------------------

### GET /approval-cost

Source: https://faucetpay.io/api-docs

Get listing approval cost. Requires the 'admin' scope.

```APIDOC
## GET /approval-cost

### Description
Get listing approval cost.

### Method
GET

### Endpoint
/approval-cost

### Parameters
#### Body
- **coin** (string) - Required - The coin for which to get approval cost.

### Response
#### Success Response (200)
Standard envelope with approval cost.

```

--------------------------------

### GET /low-balance-notification

Source: https://faucetpay.io/api-docs

Get low-balance alerts. Requires the 'read' scope.

```APIDOC
## GET /low-balance-notification

### Description
Get low-balance alerts.

### Method
GET

### Endpoint
/low-balance-notification

### Parameters
None.

### Response
#### Success Response (200)
Standard envelope with low-balance alert settings.

```

--------------------------------

### Webhook Delivery

Source: https://faucetpay.io/api-docs

Example of a webhook POST delivery to your endpoint, including the X-FaucetPay-Signature header and the JSON payload.

```APIDOC
## POST https://your-site.example/webhooks/faucetpay

### Description
Example delivery of a payout event to your webhook endpoint.

### Method
POST

### Endpoint
https://your-site.example/webhooks/faucetpay

### Headers
- **X-FaucetPay-Signature** (string) - Required - HMAC-SHA256 signature of the raw body, prefixed with 'sha256='.

### Request Body
- **id** (string) - Required - Unique identifier for the event.
- **event** (string) - Required - Event type, e.g., 'payout.sent'.
- **faucet_id** (integer) - Required - Identifier of the faucet.
- **created_at** (integer) - Required - Unix timestamp of the event.
- **data** (object) - Required - Event-specific data.
  - **to** (string) - Required - Recipient email.
  - **amount** (number) - Required - Payout amount.
  - **currency** (string) - Required - Currency code (e.g., 'BTC').
  - **payout_id** (string) - Required - Payout identifier.
  - **payout_user_hash** (string) - Required - Hash of the payout user.
  - **message** (string) - Required - Human-readable message.

### Request Example
{
  "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!"
  }
}

### Response
#### Success Response (200)
- No content body expected.

```

--------------------------------

### GET /stats/users

Source: https://faucetpay.io/api-docs

Get user statistics. Requires the 'read' scope.

```APIDOC
## GET /stats/users

### Description
Get user statistics.

### Method
GET

### Endpoint
/stats/users

### Parameters
#### Body
- **coin** (string) - Required - The coin for which to get user statistics.
- **page** (integer) - Required - Page number.

### Response
#### Success Response (200)
Standard envelope with user statistics.

```

--------------------------------

### Verify the token GET request and response

Source: https://faucetpay.io/api-docs

Call the verify endpoint with the received token to confirm the payment. The response contains the authoritative payment record. Each token works exactly once.

```http
GET https://faucetpay.io/merchant/get-payment/{token}
```

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

--------------------------------

### Example HTML form for FaucetPay hosted checkout

Source: https://faucetpay.io/api-docs

A plain HTML form that POSTs to the FaucetPay checkout endpoint. The buyer is redirected to a FaucetPay-hosted page to confirm the payment. Must be submitted with a standard browser POST (not XHR).

```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>
```

--------------------------------

### GET /check-address

Source: https://faucetpay.io/api-docs

Verify a destination address. Requires the 'read' scope.

```APIDOC
## GET /check-address

### Description
Verify a destination address.

### Method
GET

### Endpoint
/check-address

### Parameters
#### Body
- **address** (string) - Required - The address to verify.

### Response
#### Success Response (200)
Standard envelope with verification result.

```

--------------------------------

### GET /merchant/get-payment/{token}

Source: https://faucetpay.io/api-docs

Verifies a payment by providing the single-use token received in the callback. Returns the authoritative payment record. Each token works exactly once.

```APIDOC
## [GET] /merchant/get-payment/{token}

### Description
Verifies a payment by providing the single-use token received in the callback. Returns the authoritative payment record. Each token works exactly once.

### Method
GET

### Endpoint
https://faucetpay.io/merchant/get-payment/{token}

### Parameters
#### Path Parameters
- **token** (string) - Required - The single-use verification token received in the callback.

### Request Example
```
GET https://faucetpay.io/merchant/get-payment/{token}
```

### Response
#### Success Response (200)
- **valid** (boolean) - Indicates whether the token is valid.
- **transaction_id** (string) - Unique transaction identifier.
- **merchant_username** (string) - Merchant's FaucetPay username.
- **payer_username** (string) - Payer's FaucetPay username.
- **amount1** (string) - Amount in the original currency.
- **currency1** (string) - Original currency code.
- **amount2** (string) - Amount in the converted currency.
- **currency2** (string) - Converted currency code.
- **custom** (string) - Custom order identifier.

#### Response Example
```json
{
  "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"
}
```
```

--------------------------------

### Example webhook delivery payload

Source: https://faucetpay.io/api-docs

Shows the HTTP POST request and JSON body sent to a webhook endpoint for a payout.sent event. Includes the X-FaucetPay-Signature header with HMAC-SHA256 signature and fields like id, event, faucet_id, created_at, and data.

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

--------------------------------

### cURL Authenticated Request to /api/v2/balances

Source: https://faucetpay.io/api-docs

Example of an authenticated POST request to the v2 balances endpoint using a Bearer token. Replace YOUR_SCOPED_KEY with a key that has the appropriate scope. The request sends an empty JSON body.

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

--------------------------------

### GET /payouts

Source: https://faucetpay.io/api-docs

List recent payouts. Requires the 'read' scope.

```APIDOC
## GET /payouts

### Description
List recent payouts.

### Method
GET

### Endpoint
/payouts

### Parameters
#### Body
- **currency** (string) - Optional - Filter by currency.
- **count** (integer) - Optional - Number of payouts to return.

### Response
#### Success Response (200)
Standard envelope with list of payouts.

```

--------------------------------

### POST /faucet/create

Source: https://faucetpay.io/api-docs

Create a faucet. Requires the 'admin' scope.

```APIDOC
## POST /faucet/create

### Description
Create a faucet.

### Method
POST

### Endpoint
/faucet/create

### Parameters
#### Body
- **faucet_name** (string) - Required - The name of the faucet.
- **faucet_domain** (string) - Required - The domain of the faucet.
- **faucet_url** (string) - Required - The URL of the faucet.

### Response
#### Success Response (200)
Standard envelope with created faucet details.

```

--------------------------------

### POST /getbalance

Source: https://faucetpay.io/api-docs

Fetch your current faucet balance for a given coin. Requires your API key and the currency symbol.

```APIDOC
## POST /getbalance

### Description
Fetch your current faucet balance for a given coin.

### Method
POST

### Endpoint
https://faucetpay.io/api/v1/getbalance

### Parameters
#### Body Parameters
- **api_key** (string) - Required - Your faucet's API key.
- **currency** (string) - Required - Upper-case coin symbol.

### Request Example
```
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"
```

### Response
#### Success Response (200)
- **status** (integer) - HTTP status code.
- **message** (string) - Status message.
- **currency** (string) - Coin symbol.
- **balance** (integer) - Balance in smallest unit.
- **balance_bitcoin** (number) - Balance in BTC.

#### Response Example
```
{
  "status": 200,
  "message": "OK",
  "currency": "BTC",
  "balance": 49900,
  "balance_bitcoin": 0.00049900
}
```
```

--------------------------------

### Send first payout with cURL

Source: https://faucetpay.io/api-docs

Use this cURL command to send a micro-payout via the /send endpoint. Replace YOUR_API_KEY with a real faucet key and target a test user (your own email works). The request is form-encoded and includes api_key, amount, email, and currency.

```bash
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"
```

--------------------------------

### POST /faucet/update

Source: https://faucetpay.io/api-docs

Update faucet settings. Requires the 'manage' scope.

```APIDOC
## POST /faucet/update

### Description
Update faucet settings.

### Method
POST

### Endpoint
/faucet/update

### Parameters
#### Body
- **faucet_name** (string) - Required - The name of the faucet.
- **faucet_domain** (string) - Required - The domain of the faucet.
- **faucet_url** (string) - Required - The URL of the faucet.
- **faucet_description** (string) - Required - Description of the faucet.
- **timer_minutes** (integer) - Required - Timer interval in minutes.
- **currencies_selected** (array) - Optional - Selected currencies.
- **categories_selected** (array) - Optional - Selected categories.

### Response
#### Success Response (200)
Standard envelope with updated faucet details.

```

--------------------------------

### Configure FaucetPay MCP server in Cursor

Source: https://faucetpay.io/api-docs

Add the FaucetPay MCP server to your Cursor configuration file (~/.cursor/mcp.json). Use a scoped read or manage API key in the Authorization header.

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

--------------------------------

### Check balance - cURL request

Source: https://faucetpay.io/api-docs

POST /getbalance endpoint to fetch the current faucet balance for a given coin. Requires api_key and currency.

```bash
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"
```

--------------------------------

### POST /send

Source: https://faucetpay.io/api-docs

Send a payout with idempotency and optional daily cap. Requires an idempotency key and honors an optional per-key daily USD cap. Exceeding the cap returns a 429 and the payout is not made.

```APIDOC
## [POST] /send

### Description
Send a payout with idempotency and optional daily cap. Requires an idempotency key and honors an optional per-key daily USD cap. Exceeding the cap returns a 429 and the payout is not made.

### Method
POST

### Endpoint
/send

### Parameters
#### Body Parameters
- **idempotency_key** (string) - Required - Unique per logical payout. A retry with the same key never double-pays.
- **to** (string) - Required - Recipient: email, username, or wallet address.
- **amount** (integer) - Required - Amount in the coin's smallest unit (e.g. satoshis for BTC).
- **currency** (string) - Required - Upper-case coin symbol, e.g. BTC, DOGE.
- **ip_address** (string) - Optional - Recipient IP — recommended for anti-fraud.
- **referral** (string) - Optional - Referral tag for your own reporting.

### Request Example
```
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
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - Response message.
- **data** (object) - Contains payout details.
  - **rate_limit_remaining** (number) - Remaining rate limit.
  - **currency** (string) - Currency symbol.
  - **balance** (integer) - Balance in smallest unit.
  - **balance_bitcoin** (number) - Balance in BTC.
  - **payout_id** (integer) - Unique payout identifier.
  - **payout_user_hash** (string) - Hash of the payout user.

#### Response Example
```
{
  "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"
  }
}
```

### Error Handling
- **429** - Daily payout cap exceeded. The payout is not made.
```

--------------------------------

### POST /ip-whitelist/set

Source: https://faucetpay.io/api-docs

Update IP whitelist. Requires the 'manage' scope.

```APIDOC
## POST /ip-whitelist/set

### Description
Update IP whitelist.

### Method
POST

### Endpoint
/ip-whitelist/set

### Parameters
#### Body
- **ip_whitelist** (array) - Required - List of IP addresses to whitelist.

### Response
#### Success Response (200)
Standard envelope with updated IP whitelist.

```

--------------------------------

### POST /faucet/request-approval

Source: https://faucetpay.io/api-docs

Request listing approval. Requires the 'admin' scope.

```APIDOC
## POST /faucet/request-approval

### Description
Request listing approval.

### Method
POST

### Endpoint
/faucet/request-approval

### Parameters
#### Body
- **coin** (string) - Required - The coin for which to request approval.

### Response
#### Success Response (200)
Standard envelope with approval request status.

```

--------------------------------

### POST /send

Source: https://faucetpay.io/api-docs

Sends a micro-payout to a user. Requires an api_key, amount, email, and currency. Optionally accepts ip_address for cross-faucet abuse detection.

```APIDOC
## POST /send

### Description
Sends a micro-payout to a user. Requires an api_key, amount, email, and currency. Optionally accepts ip_address for cross-faucet abuse detection.

### Method
POST

### Endpoint
https://faucetpay.io/api/v1/send

### Parameters
#### Request Body
- **api_key** (string) - Required - Your faucet's API key.
- **amount** (number) - Required - The amount to send.
- **email** (string) - Required - The recipient's email address.
- **currency** (string) - Required - The currency code (e.g., BTC).
- **ip_address** (string) - Optional - The user's IP address for cross-faucet abuse detection.

### Request Example
```
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"
```

### Response
#### Success Response (200)
Returns JSON with a top-level status integer.

#### Response Example
(No explicit response example provided in the source.)
```

--------------------------------

### POST /currencies

Source: https://faucetpay.io/api-docs

Return every currency currently active on FaucetPay. Requires only your API key.

```APIDOC
## POST /currencies

### Description
Return every currency currently active on FaucetPay.

### Method
POST

### Endpoint
https://faucetpay.io/api/v1/currencies

### Parameters
#### Body Parameters
- **api_key** (string) - Required - Your faucet's API key.

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

### Response
#### Success Response (200)
- **status** (integer) - HTTP status code.
- **message** (string) - Status message.
- **currencies** (array of strings) - List of active currency symbols.
- **currencies_names** (array of objects) - List of currency names and acronyms.
  - **name** (string) - Full currency name.
  - **acronym** (string) - Currency symbol.

#### Response Example
```
{
  "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" }
  ]
}
```
```

--------------------------------

### Supported currencies - cURL request

Source: https://faucetpay.io/api-docs

POST /currencies endpoint to return every currency currently active on FaucetPay. Requires api_key.

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

--------------------------------

### POST /low-balance-notification/toggle

Source: https://faucetpay.io/api-docs

Toggle low-balance alert. Requires the 'manage' scope.

```APIDOC
## POST /low-balance-notification/toggle

### Description
Toggle low-balance alert.

### Method
POST

### Endpoint
/low-balance-notification/toggle

### Parameters
None.

### Response
#### Success Response (200)
Standard envelope with updated low-balance alert status.

```

--------------------------------

### POST /ratelimits/set

Source: https://faucetpay.io/api-docs

Set rate limits. Requires the 'manage' scope.

```APIDOC
## POST /ratelimits/set

### Description
Set rate limits.

### Method
POST

### Endpoint
/ratelimits/set

### Parameters
#### Body
- **ratelimits[]** (array) - Required - Array of rate limit settings.

### Response
#### Success Response (200)
Standard envelope with updated rate limits.

```

--------------------------------

### POST /checkaddress

Source: https://faucetpay.io/api-docs

Verify that a destination is a registered FaucetPay user for the chosen currency. Requires your API key, the address to verify, and the currency.

```APIDOC
## POST /checkaddress

### Description
Verify that a destination is a registered FaucetPay user for the chosen currency.

### Method
POST

### Endpoint
https://faucetpay.io/api/v1/checkaddress

### Parameters
#### Body Parameters
- **api_key** (string) - Required - Your faucet's API key.
- **address** (string) - Required - Email, username, or wallet address to verify.
- **currency** (string) - Required - Upper-case coin symbol to check membership under.

### Request Example
```
curl -X POST https://faucetpay.io/api/v1/checkaddress \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "api_key=YOUR_API_KEY&address=user@example.com&currency=BTC"
```

### Response
#### Success Response (200)
- **status** (integer) - HTTP status code.
- **message** (string) - Status message.
- **payout_user_hash** (string) - User hash.

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

--------------------------------

### POST /anti-fraud/toggle

Source: https://faucetpay.io/api-docs

Toggle anti-fraud. Requires the 'manage' scope.

```APIDOC
## POST /anti-fraud/toggle

### Description
Toggle anti-fraud.

### Method
POST

### Endpoint
/anti-fraud/toggle

### Parameters
None.

### Response
#### Success Response (200)
Standard envelope with updated anti-fraud status.

```

--------------------------------

### POST /send

Source: https://faucetpay.io/api-docs

Pay out cryptocurrency from your account balance to a FaucetPay user. Requires your API key, amount, destination, and currency. Optional parameters include IP address for anti-abuse and a referral tag.

```APIDOC
## POST /send

### Description
Pay out cryptocurrency from your account balance to a FaucetPay user.

### Method
POST

### Endpoint
https://faucetpay.io/api/v1/send

### Parameters
#### Body Parameters
- **api_key** (string) - Required - Your faucet's API key.
- **amount** (integer) - Required - Amount in the coin's smallest unit (satoshis for BTC).
- **to** (string) - Required - Destination: email, username, or wallet address.
- **currency** (string) - Required - Upper-case coin symbol, e.g. BTC, DOGE, USDT.
- **ip_address** (string) - Optional - Claimer IP — strongly recommended; enables anti-abuse rate-limiting.
- **referral** (string) - Optional - Referral tag attached to this payout for your own reporting.

### Request Example
```
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&to=user@example.com&currency=BTC&ip_address=203.0.113.4"
```

### Response
#### Success Response (200)
- **status** (integer) - HTTP status code.
- **message** (string) - Status message.
- **rate_limit_remaining** (number) - Remaining rate limit.
- **currency** (string) - Coin symbol.
- **balance** (integer) - Balance in smallest unit.
- **balance_bitcoin** (number) - Balance in BTC.
- **payout_id** (integer) - Payout identifier.
- **payout_user_hash** (string) - User hash.

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

--------------------------------

### Check address - cURL request

Source: https://faucetpay.io/api-docs

POST /checkaddress endpoint to verify if a destination is a registered FaucetPay user for a given currency. Requires api_key, address, and currency.

```bash
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"
```

--------------------------------

### POST /ipn (Callback)

Source: https://faucetpay.io/api-docs

FaucetPay sends a form-encoded POST request to the merchant's callback_url after a completed payment. The callback includes payment details and a single-use verification token. Merchants must respond with HTTP 200 OK to acknowledge receipt.

```APIDOC
## [POST] /ipn

### Description
FaucetPay sends a form-encoded POST request to the merchant's callback_url after a completed payment. The callback includes payment details and a single-use verification token. Merchants must respond with HTTP 200 OK to acknowledge receipt.

### Method
POST

### Endpoint
https://your-site.com/ipn

### Parameters
#### Request Body (application/x-www-form-urlencoded)
- **token** (string) - Required - Single-use verification token.
- **transaction_id** (string) - Required - Unique transaction identifier.
- **merchant_username** (string) - Required - Merchant's FaucetPay username.
- **payer_username** (string) - Required - Payer's FaucetPay username.
- **amount1** (string) - Required - Amount in the original currency.
- **currency1** (string) - Required - Original currency code (e.g., USDT).
- **amount2** (string) - Required - Amount in the converted currency.
- **currency2** (string) - Required - Converted currency code (e.g., BTC).
- **custom** (string) - Optional - Custom order identifier provided by the merchant.
- **exchange_rate** (string) - Required - Exchange rate used for conversion.

### Request Example
```
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
```

### Response
#### Success Response (200 OK)
- Respond with HTTP 200 OK to acknowledge receipt. No specific body is required.

### Error Handling
- If a non-200 response is returned, FaucetPay will retry the callback according to the retry schedule.

### 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
```

--------------------------------

### Verify Webhook Signature (Node.js)

Source: https://faucetpay.io/api-docs

Code snippet demonstrating how to verify the HMAC-SHA256 signature of a webhook delivery in Node.js.

```APIDOC
## Verify Webhook Signature (Node.js)

### Description
Recompute the HMAC over the raw request body with your webhook secret and constant-time compare it to the X-FaucetPay-Signature header.

### Method
N/A (verification logic)

### Code Example
```javascript
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();
```

### Notes
- Always verify the signature before parsing the JSON body.
- Use constant-time comparison to prevent timing attacks.

```

--------------------------------

### POST /send

Source: https://faucetpay.io/api-docs

Send payout. Requires the 'send' scope.

```APIDOC
## POST /send

### Description
Send payout.

### Method
POST

### Endpoint
/send

### Parameters
#### Body
- **idempotency_key** (string) - Required - Unique key to prevent duplicate sends.
- **currency** (string) - Required - Currency code.
- **amount** (number) - Required - Amount to send.
- **to** (string) - Required - Destination address.
- **ip_address** (string) - Optional - IP address of the user.
- **referral** (string) - Optional - Referral identifier.

### Response
#### Success Response (200)
Standard envelope with payout result.

```

--------------------------------

### List payouts - cURL request

Source: https://faucetpay.io/api-docs

POST /payouts endpoint to return recent payouts, newest first. Requires api_key; count (1-100, default 10) and currency are optional.

```bash
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"
```

--------------------------------

### Send payout - cURL request

Source: https://faucetpay.io/api-docs

POST /send endpoint to pay out cryptocurrency to a FaucetPay user. Requires api_key, amount, to, and currency; ip_address is optional and recommended for anti-abuse rate-limiting.

```bash
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"
```

--------------------------------

### POST https://faucetpay.io/merchant/webscr

Source: https://faucetpay.io/api-docs

Submits a payment request via an HTML form POST to the FaucetPay checkout endpoint. The buyer is redirected to a hosted page to confirm payment. Requires a standard browser POST, not XHR.

```APIDOC
## [POST] https://faucetpay.io/merchant/webscr

### Description
Submits a payment request via an HTML form POST to the FaucetPay checkout endpoint. The buyer is redirected to a hosted page to confirm payment. Requires a standard browser POST, not XHR.

### Method
POST

### Endpoint
https://faucetpay.io/merchant/webscr

### Parameters
#### Form Parameters
- **merchant_username** (string) - Required - Your FaucetPay username — the account that receives the payment.
- **item_description** (string) - Required - Description of the item or service the buyer is paying for.
- **amount1** (string) - Required - Amount you want to receive, denominated in currency1.
- **currency1** (string) - Required - The pricing currency of your store (e.g. USDT, BTC, …).
- **currency2** (string) - Optional - The coin the buyer must pay with. Leave blank to let the buyer choose any supported coin.
- **custom** (string) - Optional - An identifier passed back on the callback — use it for your order ID or user ID.
- **callback_url** (string) - Optional - URL that receives the server-to-server POST callback once the payment completes.
- **success_url** (string) - Optional - URL the buyer is redirected to after a successful payment.
- **cancel_url** (string) - Optional - URL the buyer is redirected to if they cancel.

### Request Example
```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>
```

### Response
#### Success Response (200)
No response details are provided in the source. The buyer is redirected to the hosted checkout page.

#### Response Example
No response example is provided in the source.

```
Tokens:
Raw