API Keys

An API key lets scripts and AI agents call the faucet without solving a captcha. Requests draw on your GitHub account's daily allowance, so a key changes how you prove who you are, not how much you can request.

• Authenticate with GitHub to create a key

• You may hold 2 keys. They expire after 90 days.• Never commit a key. Keys found in public repositories are revoked without notice.• Back to the faucet

Using your key

Send it as a bearer token and leave out the captcha:

curl -X POST https://faucet.celo.org/api/faucet \
  -H "Authorization: Bearer $CELO_FAUCET_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"beneficiary":"0xYOUR_ADDRESS","network":"celo-sepolia"}'

Limits

• Keyed requests share your GitHub account's allowance of 10 per day.

• Holding 2 keys does not double it.

• Keys expire after 90 days.

• Celo Sepolia only. There is no mainnet access.

Response codes

• 200 — queued. Poll the status endpoint.

• 400 — invalid network or beneficiary address.

• 401 invalid_api_key — missing, unknown or expired key.

• 429 faucet_limit_exceeded — rate limited. Honour Retry-After.

• 503 faucet_unavailable — a dependency is down. Retry after 30s.

• Schema: openapi.json

Check the outcome

A request returns a key. Poll it for the transaction hash:

GET /api/status?key=<key>&network=celo-sepolia

Read the docs →

Response codes, rate limits and the status endpoint

Ask questions →

Chat with the Celo community on Discord