Für Entwickler / Anwendungs-APIs

Faucet

Der einzige hauseigene Dienst, der auf die Chain schreibt. Er hält den Betreiberschlüssel und reicht den Drip für Sie ein, weshalb er keine Wallet braucht - und weshalb die Quote das Einzige ist, was zwischen einer Aufruferin und diesem Schlüssel steht.

Was er tut

Sie schicken eine Adresse per POST; der Dienst prüft seine eigene Quote, signiert mit dem Betreiberschlüssel einen Aufruf des Faucet-Contracts, reicht ihn ein und wartet auf die Quittung, bevor er antwortet. Es gibt keine Wallet auf der Seite und keine Signatur von Ihnen, denn die Transaktion ist nicht Ihre.

Ohne Authentifizierung, und er gibt einen echten Schlüssel aus

Kein Token, kein Captcha, keine Signatur. Was an die Stelle der Authentifizierung tritt, sind drei Quoten, die vor dem Signieren reserviert werden, plus eine Abkühlzeit, die der Contract selbst durchsetzt, wer also an der einen vorbeikommt, trifft trotzdem auf die andere. Nichts davon beweist irgendetwas darüber, wer Sie sind.

Zwei seiner Routen werden außerdem auf der Heimat-Herkunft des Projekts erneut bereitgestellt - der Drip und der Status -, damit eine Seite dort ihn ohne einen herkunftsübergreifenden Aufruf nutzen kann.

Basis-URL und CORS

Endpunkt	Value
Öffentlich	https://faucet.picklechain.xyzder Dienst liefert seine eigene statische Seite von derselben Herkunft aus
Erneut bereitgestellt	POST /drip und GET /faucet-statusauf der Heimat-Herkunft des Projekts, an denselben Dienst weitergereicht
Ein Stack, den Sie betreiben	http://127.0.0.1:3000
CORS	eine AllowlistOPTIONS antwortet mit 204 und erlaubt POST, GET und OPTIONS; eine Origin, die nicht auf der Liste steht, wird mit 403 abgelehnt

Alles, was nicht auf den API-Routen oder der ausdrücklichen statischen Allowlist steht, ist eine 404 - nie eine 403, denn eine Ablehnung, die zwischen beiden unterscheidet, bestätigt, dass eine Datei existiert.

Routen

/status

GET

Params: address (optional)
Rückgabe: {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`.

Auch unter. GET /faucet-status

Gut zu wissen. 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..."}
Rückgabe: {hash, address}

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

Gut zu wissen. 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
Rückgabe: the deployment manifest, as JSON

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

Auch unter. GET /op-deployment/l2-addresses.json

Gut zu wissen. 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
Rückgabe: 204

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

Gut zu wissen. 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.

Die Quote

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
Pro Client-Adresse	5 am Taggeschlüsselt auf die weitergereichte Client-Adresse
Pro belieferter Adresse	2 am Taggeschlüsselt auf die Adresse im Körper
Global	1000 am Tagund ein eigenes Budget über die ganze Laufzeit
Abkühlzeit on-chain	ein Tag pro Adressevom Contract durchgesetzt und aus der Chain gelesen, nicht im Dienst gemerkt

Zwei verschiedene Ablehnungen bedeuten zwei verschiedene Dinge

Eine 429 ist die eigene Tagesquote des Dienstes und setzt zum Tageswechsel zurück. Eine 409 ist die Abkühlzeit des Contracts, wird ab dem letzten Drip statt ab Mitternacht gezählt und trägt das zu wartende Intervall in ihrer Nachricht. Nur die zweite ist im Voraus sichtbar: Fragen Sie /status?address= und lesen Sie canDrip und retryIn, bevor Sie posten.

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.

Fehler

Status	Bedeutung
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

Eine 503 nach dem Senden ist kein gefahrloser erneuter Versuch

Eine 502 heißt, der Node hat nie geantwortet und es wurde nichts signiert - diese eine können Sie bedenkenlos wiederholen. Eine 503 kann heißen, dass die Transaktion hinausgegangen und dann fehlgeschlagen ist, oder dass sie hinausgegangen ist und innerhalb des Abfragefensters keine Quittung eintraf. Die Reservierung der Quote wird in beiden Fällen zurückgerollt, ein erneuter Versuch ist also erlaubt; die Transaktion kann trotzdem noch landen. Fragen Sie die Chain nach dem Guthaben der Adresse, statt es anzunehmen.