Pour les développeurs / API des applications

Faucet

Le seul service de première partie qui écrit sur la chaîne. Il détient la clé d'opérateur et soumet le drip pour vous, ce qui explique pourquoi il n'a besoin d'aucun portefeuille - et pourquoi le quota est la seule chose entre un appelant et cette clé.

Ce qu'il fait

Vous postez une adresse ; le service vérifie son propre quota, signe un appel au contrat du faucet avec la clé d'opérateur, le soumet et attend le reçu avant de répondre. Il n'y a pas de portefeuille sur la page et aucune signature de votre part, parce que la transaction n'est pas la vôtre.

Sans authentification, et il dépense une vraie clé

Pas de jeton, pas de captcha, pas de signature. Ce qui tient lieu d'authentification, c'est trois quotas réservés avant toute signature, plus un délai de refroidissement que le contrat lui-même impose, de sorte qu'un appelant qui passe l'un rencontre encore l'autre. Rien ici n'est une preuve de quoi que ce soit sur qui vous êtes.

Deux de ses routes sont aussi réexposées sur l'origine d'accueil du projet - le drip et le statut - pour qu'une page de là puisse s'en servir sans appel multi-origine.

URL de base et CORS

Point d'accès	Value
Public	https://faucet.picklechain.xyzle service sert sa propre page statique depuis la même origine
Réexposé	POST /drip et GET /faucet-statussur l'origine d'accueil du projet, relayés vers le même service
Une pile à vous	http://127.0.0.1:3000
CORS	une liste d'autorisationOPTIONS répond 204 en autorisant POST, GET et OPTIONS ; une Origin absente de la liste est refusée 403

Tout ce qui n'est ni sur les routes d'API ni sur la liste statique explicite donne un 404 - jamais un 403, parce qu'un refus qui distingue les deux confirme qu'un fichier existe.

Routes

/status

GET

Params: address (optional)
Retour: {faucet, pickle, ethAmount, bxAmount, ethAmountEth, bxAmountBx, treasuryEth, treasuryBx, treasuryEthFmt, treasuryBxFmt, cooldown, evmBlock, miniBlock}

The faucet and token addresses, the drip amounts in both base units and display units, what is left in the treasury and the cooldown in seconds. Pass `?address=` and it also answers `canDrip`, `retryIn` and a formatted `retryIn`.

Aussi à. GET /faucet-status

Bon à savoir. The `bx`-prefixed keys are the PKL amounts. The names are historic and the SERVICE still emits them; the formatted string beside them says PKL. 502 when the node is unreachable, 500 for anything else.

/drip

POST

Params: body {"address": "0x..."}
Retour: {hash, address}

Reserves quota, signs `dripTo` with the operator key, submits it and polls for the receipt before answering. No authentication of any kind.

Bon à savoir. It waits for the receipt: about three seconds of polling before it gives up with `no receipt yet`. A quota reservation is ROLLED BACK when the send fails, so a failed attempt does not cost you a daily slot.

/addresses

GET

Params: none
Retour: the deployment manifest, as JSON

Streams the manifest file straight through. This is where an application discovers what is deployed.

Aussi à. GET /op-deployment/l2-addresses.json

Bon à savoir. 404 with a JSON body when the file cannot be read, which is also what you get before a deployment has written it.

any

OPTIONS

Params: none
Retour: 204

Allowed methods are POST, GET and OPTIONS; the allowed header is content-type.

Bon à savoir. 403 when an Origin is present and not on the allowlist.

bash

# What is left, and whether this address may claim right now.
curl -s "$FAUCET/status?address=$ADDR" | jq '{canDrip, retryIn, retryInFmt, treasuryEthFmt}'

# The claim. A body is required: a zero-length one answers 413, not 400.
curl -s -X POST "$FAUCET/drip" \
  -H 'content-type: application/json' \
  -d "{\"address\":\"$ADDR\"}"

# 200 -> {"hash": "0x…", "address": "0x…"}; the receipt has already been seen.

Le quota

Quota is RESERVED before the transaction is signed and committed only once a hash comes back, so two simultaneous requests cannot both pass the check. The journal that backs it is an append-only file outside the served directory, rotated by size and by age, with a checkpoint at the head of each new file so the all-time total survives both rotation and a restart.

Budget	Value
Par adresse cliente	5 par jourindexé sur l'adresse cliente transmise
Par adresse servie	2 par jourindexé sur l'adresse dans le corps
Globalement	1000 par jouret un budget séparé pour toute la durée de vie
Refroidissement on-chain	un jour par adresseimposé par le contrat et lu depuis la chaîne, pas mémorisé dans le service

Deux refus différents veulent dire deux choses différentes

Un 429 est le quota quotidien propre au service et se réinitialise au tournant du jour. Un 409 est le délai de refroidissement du contrat, se compte depuis le dernier drip plutôt que depuis minuit, et porte dans son message l'intervalle à attendre. Seul le second est visible à l'avance : demandez /status?address= et lisez canDrip et retryIn avant de poster.

The per-address budget is keyed on the FUNDED address and the per-client one on the address the request came from, read from the right-hand end of the forwarded chain. Put a cache in front without telling the service how many proxies it now sits behind and every visitor collapses into one bucket.

Erreurs

Statut	Sens
400	invalid json, invalid address, invalid content lengthand a chunked request, which the handler refuses outright
409	cooldownthe message carries the interval to retry in. The cooldown is enforced by the contract, one day per address, and is read from the chain rather than remembered here
413	payload too largethe cap is 4096 bytes - and a ZERO-LENGTH body answers 413 as well, which reads as the opposite of what happened. Send a body
429	quota exceeded5 a day per address seen, 2 a day per funded address, 1000 a day globally; the message says which one you hit
502	upstream RPC unavailablethe node did not answer. Nothing was signed
503	faucet empty, or the drip failedthe message names the remaining balance when it is a funding problem, and is the opaque `drip failed` otherwise

Un 503 après l'envoi n'est pas un réessai sûr

Un 502 signifie que le nœud n'a jamais répondu et que rien n'a été signé - réessayez celui-là librement. Un 503 peut vouloir dire que la transaction est partie puis a échoué, ou qu'elle est partie et qu'aucun reçu n'est arrivé dans la fenêtre de sondage. La réservation de quota est annulée dans les deux cas, donc réessayer est permis ; la transaction peut tout de même atterrir. Sondez la chaîne pour le solde de l'adresse plutôt que de supposer.