Common Request Format
Method: POST
URL: /api/faucet/request
Body: {"targetAddress":"NQ..."}
Success: {"txHash":"<nimiq_tx_hash>"}
Response header: X-RateLimit-Remaining
Anonymous Requests
No bearer token required.
Limit: 100 requests per rolling 24 hours per IP address.
Anonymous requests are logged in a separate table.
Anonymous request logs are automatically deleted after 24 hours.
Anonymous access can be temporarily disabled by the operator.
No dashboard or request history is available for anonymous usage.
curl -X POST http://localhost:8000/api/faucet/request \
-H "Content-Type: application/json" \
-d '{"targetAddress":"NQXX ..."}'Authenticated Requests
Send your bearer token in the Authorization header.
Your personal limit depends on your account configuration.
Authenticated users can see their request history in the dashboard.
curl -X POST http://localhost:8000/api/faucet/request \
-H "Authorization: Bearer YOUR_BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"targetAddress":"NQXX ..."}'Example (JavaScript / Browser / Node / Deno)
const response = await fetch("http://localhost:8000/api/faucet/request", {
method: "POST",
headers: {
"Content-Type": "application/json",
// Add Authorization only for authenticated requests:
// "Authorization": "Bearer YOUR_BEARER_TOKEN",
},
body: JSON.stringify({
targetAddress: "NQXX ...",
}),
});
console.log(response.headers.get("X-RateLimit-Remaining"));
console.log(response.status, await response.json());Limits And Concurrency
Only one in-flight request is allowed at a time per authenticated user.
Only one in-flight request is allowed at a time per anonymous IP.
The remaining rolling-24h quota is returned in X-RateLimit-Remaining.
Common Errors
400 invalid JSON or invalid target address
401 invalid bearer token
403 authenticated user is temporarily banned
409 another request is already in progress for this user or IP
429 rolling 24h limit exceeded
503 anonymous requests are temporarily disabled
503 faucet is currently empty, try again later
503 maintenance mode is active, try again later
502 transaction send failed
If you need help, higher limits or features: hi@nim.re