Para desarrolladores / API de las aplicaciones

Faucet

El único servicio de primera parte que escribe en la cadena. Guarda la clave de operador y envía el drip por usted, que es la razón de que no necesite billetera - y de que la cuota sea lo único que hay entre quien llama y esa clave.

Qué hace

Usted envía una dirección; el servicio comprueba su propia cuota, firma una llamada al contrato del faucet con la clave de operador, la envía y espera el recibo antes de responder. No hay billetera en la página ni firma alguna por su parte, porque la transacción no es suya.

Sin autenticación, y gasta una clave de verdad

Sin token, sin captcha, sin firma. Lo que hace las veces de autenticación son tres cuotas reservadas antes de firmar nada, más un enfriamiento que el propio contrato impone, de modo que quien pase una todavía se encuentra con el otro. Nada de esto es prueba de nada sobre quién es usted.

Dos de sus rutas se reexponen además en el origen de inicio del proyecto - el drip y el estado - para que una página de allí pueda usarlas sin una llamada de origen cruzado.

URL de base y CORS

Punto de acceso	Value
Público	https://faucet.picklechain.xyzel servicio sirve su propia página estática desde el mismo origen
Reexpuesto	POST /drip y GET /faucet-statusen el origen de inicio del proyecto, redirigidos al mismo servicio
Una pila propia	http://127.0.0.1:3000
CORS	una lista de permitidosOPTIONS responde 204 autorizando POST, GET y OPTIONS; un Origin que no esté en la lista se rechaza con 403

Todo lo que no esté ni en las rutas de la API ni en la lista estática explícita da un 404 - nunca un 403, porque un rechazo que distingue los dos casos confirma que un fichero existe.

Rutas

/status

GET

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

También en. GET /faucet-status

Conviene saberlo. 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..."}
Devuelve: {hash, address}

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

Conviene saberlo. 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
Devuelve: the deployment manifest, as JSON

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

También en. GET /op-deployment/l2-addresses.json

Conviene saberlo. 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
Devuelve: 204

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

Conviene saberlo. 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.

La cuota

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.

Presupuesto	Value
Por dirección cliente	5 al díaindexada sobre la dirección cliente transmitida
Por dirección servida	2 al díaindexada sobre la dirección del cuerpo
Globalmente	1000 al díay un presupuesto aparte para toda la vida del servicio
Enfriamiento on-chain	un día por direcciónimpuesto por el contrato y leído de la cadena, no recordado en el servicio

Dos rechazos distintos quieren decir dos cosas distintas

Un 429 es la cuota diaria propia del servicio y se reinicia al cambio de día. Un 409 es el enfriamiento del contrato, se cuenta desde el último drip en lugar de desde medianoche, y lleva en su mensaje el intervalo que hay que esperar. Solo el segundo es visible por adelantado: pida /status?address= y lea canDrip y retryIn antes de enviar.

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.

Errores

Estado	Significado
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 después del envío no es un reintento seguro

Un 502 significa que el nodo nunca respondió y que no se firmó nada - reintente ese libremente. Un 503 puede querer decir que la transacción salió y luego falló, o que salió y ningún recibo llegó dentro de la ventana de sondeo. La reserva de cuota se deshace en ambos casos, así que reintentar está permitido; la transacción todavía puede aterrizar. Sondee la cadena en busca del saldo de la dirección en lugar de suponer.