Build with the faucet

Fund Esmeralda Ootle wallets from your dapp’s backend. Native L2 test tXTR only. Requests are saved immediately and paid through the faucet’s shared queue.

Get an API key

Create and manage your developer key. Registration is open to everyone after bot verification. Public keys start with 10 claims and 1,000 tXTR per UTC day; contact the operator for higher quotas. Download the API secret and management token when issued; they cannot be retrieved later. Use the management token on the developer page to inspect or revoke your key.

Keep the key on your backend, never in browser JavaScript, mobile bundles, URLs, or source control.

Create a claim

POST https://testnet-faucet.taritracker.com/api/v1/claims

Supply Authorization: Bearer YOUR_API_KEY and Content-Type: application/json. Generate one UUID v4 receipt per intended withdrawal. Reuse that exact receipt, address and amount for retries.

curl https://testnet-faucet.taritracker.com/api/v1/claims \
  -H "Authorization: Bearer $FAUCET_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"receipt":"6cf1df90-7645-44d2-8ed5-a00121aa8001","address":"otl_esm_YOUR_RECEIVE_ADDRESS","amountTokens":100}'

amountTokens is an integer from 1 to 1,000, in whole tXTR. Use an Esmeralda receive address without a payment reference. API requests do not require Turnstile.

{
  "receipt": "6cf1df90-7645-44d2-8ed5-a00121aa8001",
  "status": "queued",
  "transactionId": null,
  "amountMicrotari": "100000000",
  "createdAt": "2026-10-16T12:00:00.000Z"
}

Check the payment

GET /api/v1/claims/{receipt} with the same API key. Poll every 2–5 seconds, with backoff on errors. Receipts belong to the issuing key. A 202 response means accepted, not confirmed.

queued

Saved and waiting for payment preparation.

prepared / pending

A transaction has been saved or submitted; keep polling.

uncertain

Submission response was interrupted. The original transaction is being reconciled. Do not create a replacement request.

confirmed

Chain confirmation recorded. The recipient wallet must scan the private output to display funds.

rejected / failed

Terminal failure. A failed request was not prepared. A rejected transaction may have consumed a fee. No replacement is sent automatically.

Limits and errors

One withdrawal per wallet owner per hour across both API and website, regardless of key or IP. Default keys allow 100 claims and 10,000 tXTR per UTC day; operators can assign different quotas. All keys also share the faucet’s global daily budget and available balance. Accepted queued requests reserve quota. Signed requests count even if rejected. Each key allows 120 API requests per minute, including receipt polling.

• 400: invalid address, amount or receipt.
• 401: missing, invalid or revoked key.
• 404: receipt not found or belongs to another key.
• 409: receipt reused with different request details.
• 429: wallet cooldown, key quota, global budget or rate limit. Honor Retry-After when supplied.
• 503: faucet unavailable or at capacity.

Errors return {"error":"message"}, optionally with safeToChangeRequest. After a timeout, retry the same receipt and payload. Never assume a missing response means no payment.

Backend example

const receipt = crypto.randomUUID(); // persist before sending
const response = await fetch(
  'https://testnet-faucet.taritracker.com/api/v1/claims', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.FAUCET_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ receipt, address, amountTokens: 100 })
  });
const result = await response.json();
// Save result; poll its receipt until a terminal status.

Authenticate and rate-limit users in your own dapp. An API key authorizes faucet requests; it is not evidence that a user owns the recipient wallet. No browser CORS access is provided.

Operator: manage keys on the VPS

Generate keys locally in the faucet container. The secret is printed once; it cannot be recovered from the database. Share it through a private channel. Create a separate key per dapp.

docker exec testnet-faucet-faucet-1 node tools/api-keys.mjs create hauntboard 100 10000
docker exec testnet-faucet-faucet-1 node tools/api-keys.mjs list
docker exec testnet-faucet-faucet-1 node tools/api-keys.mjs revoke KEY_ID

For Hauntboard on the same VPS, store the generated key in its protected server configuration as FAUCET_API_KEY and call the public HTTPS API from its backend. Key issuance does not automatically modify Hauntboard. Rotate by creating a new key, updating the dapp, then revoking the old key. Revocation blocks new requests and receipt access; previously accepted payments continue.