Para desenvolvedores / APIs das aplicações

Faucet

O único serviço de primeira parte que escreve na cadeia. Ele detém a chave do operador e envia o drip por você, e é por isso que ele não precisa de carteira nenhuma - e por que a cota é a única coisa entre quem chama e essa chave.

O que ele faz

Você posta um endereço; o serviço verifica a própria cota, assina uma chamada ao contrato do faucet com a chave do operador, a envia e espera o recibo antes de responder. Não há carteira na página nem assinatura da sua parte, porque a transação não é sua.

Sem autenticação, e gastando uma chave de verdade

Sem token, sem captcha, sem assinatura. O que faz as vezes de autenticação são três cotas reservadas antes de qualquer assinatura, mais um tempo de espera que o próprio contrato impõe, de modo que quem passa por um ainda encontra o outro. Nada aqui é prova de coisa alguma sobre quem você é.

Duas de suas rotas também são reexpostas na origem da home do projeto - o drip e o status - para que uma página de lá possa usá-las sem uma chamada entre origens.

URL de base e CORS

Ponto de acesso	Value
Público	https://faucet.picklechain.xyzo serviço serve a própria página estática a partir da mesma origem
Reexposto	POST /drip e GET /faucet-statusna origem da home do projeto, encaminhados ao mesmo serviço
Uma pilha sua	http://127.0.0.1:3000
CORS	uma lista de permissõesOPTIONS responde 204 autorizando POST, GET e OPTIONS; uma Origin fora da lista é recusada com 403

Tudo o que não está nas rotas da API nem na lista de permissões estática explícita dá um 404 - nunca um 403, porque uma recusa que distingue os dois confirma que um arquivo existe.

Rotas

/status

GET

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

Também em. GET /faucet-status

Vale saber. 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..."}
Retorno: {hash, address}

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

Vale saber. 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
Retorno: the deployment manifest, as JSON

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

Também em. GET /op-deployment/l2-addresses.json

Vale saber. 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
Retorno: 204

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

Vale saber. 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.

A cota

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.

Orçamento	Value
Por endereço cliente	5 por diaindexado no endereço cliente encaminhado
Por endereço servido	2 por diaindexado no endereço que está no corpo
Globalmente	1000 por diae um orçamento separado para toda a vida útil
Tempo de espera on-chain	um dia por endereçoimposto pelo contrato e lido da cadeia, não memorizado no serviço

Duas recusas diferentes querem dizer duas coisas diferentes

Um 429 é a cota diária do próprio serviço e se reinicia na virada do dia. Um 409 é o tempo de espera do contrato, é contado desde o último drip e não desde a meia-noite, e carrega na sua mensagem o intervalo a esperar. Só o segundo é visível de antemão: peça /status?address= e leia canDrip e retryIn antes de postar.

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.

Erros

Status	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

Um 503 depois do envio não é uma nova tentativa segura

Um 502 significa que o nó nunca respondeu e que nada foi assinado - repita essa livremente. Um 503 pode querer dizer que a transação saiu e depois falhou, ou que saiu e nenhum recibo chegou dentro da janela de sondagem. A reserva de cota é desfeita nos dois casos, portanto repetir é permitido; a transação ainda pode aterrissar. Sonde a cadeia pelo saldo do endereço em vez de supor.