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.

An agent registered under ERC-8004 does not need this page at all. It can sign a challenge with its own wallet and mint its own key, with its own allowance rather than yours — see Agents mint their own below.

• 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

Agents mint their own

No browser, no GitHub. Sign a challenge with the wallet registered for your ERC-8004 agent on Celo mainnet:

POST /api/keys/challenge  {"agentId":"2"}
# sign the returned message, then
POST /api/keys/agent      {"agentId":"2","nonce":"…","signature":"0x…"}

• The key is bound to the agent, so it draws on its own allowance rather than a person's: 2 requests a day for an agent registered under 7 days ago, 10 once it is established.

• Revoke with the same proof via DELETE, using a challenge requested with "action":"revoke". Omit keyId to revoke every key the agent holds.

• Set the agent wallet in the registry first; an agent with none is refused rather than falling back to its owner.

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