Welcome to Celo Faucet app

This Repo contains the code for the celo testnets faucet. This is contained in 2 apps.

• The firebase app contains functions which do the actual fauceting.

• The web app contains a UI for making requests.

The web app deploys automatically to vercel.

The deploy-chains gh actions deploys functions to staging and production environments from staging and master branches respectively

Note other branches are not deployed automatically but can be by manually triggering the flow

Setup

Web app

To set up the web app to run locally:

1. navigate to the apps/web folder

   $ cd apps/web
   

2. link your local repository to the faucet project on Vercel

   $ yarn dlx vercel@latest link
   

   You'll be asked to authenticate with your Vercel account. Once you've done that, you'll be guided through a series of prompts to link your local project to the faucet Vercel project.

   ? Set up “~/Documents/celo-org/faucet/apps/web”? [Y/n] y
   ? Which scope should contain your project? Celo Ecosystem Project Hosting
   ? Link to existing project? [y/N] y
   ? What’s the name of your existing project? faucet
   ✅  Linked to c-labs/faucet (created .vercel)
   

3. fetch environment variables from Vercel

   $ yarn dlx vercel@latest env pull
   

   If you get an error like Error! No project found, you may need to run vercel link again. If everything worked, you should see a message like this:

   > Downloading `development` Environment Variables for Project faucet
   ✅  Created .env.local file  [249ms]
   

4. run the app locally

   $ yarn dev
   

   You should see a message like this:

   ready - started server on 0.0.0.0:3000, url: http://localhost:3000
   info  - Loaded env from /Users/arthur/Documents/celo-org/faucet/apps/web/.env.local
   

   You can now view the app in your browser at http://localhost:3000.

Firebase app

To set up the firebase app to run locally:

1. navigate to the apps/firebase folder

   $ cd apps/firebase
   

2. login to firebase

   $ yarn dlx firebase-tools@latest login
   

   You'll be asked to authenticate with your Firebase account.
3. build the firebase app

   $ yarn run preserve
   

4. ensure that you are on required node version specified in engines.node in firebase/package.json. Currently this is Node 24 at the time of writing.

   $ nvm use <the-required-node-version>
   

5. run the firebase app locally

   $ yarn run serve
   

Programmatic access (API keys)

The browser flow is gated on reCAPTCHA v3, which scores headless callers badly and cannot be solved without driving a real browser. Scripts and AI agents use an API key instead.

This section used to be the only place the API was documented, which meant an agent had to fetch and parse a README on GitHub to learn how to behave. The same contract is now published on the faucet's own domain, in formats meant to be read by a machine:

File	For
/openapi.json	The schema. Endpoints, request and response shapes, every error code.
/llms-full.txt	The full reference as prose, for assistants that read rather than call.
/llms.txt	The short index.

Keep this section and those files in agreement. apps/web/tests/geo-assets.test.ts asserts the published limits and payout amounts still match the constants the code enforces, but the prose is on you.

Getting a key

Sign in with GitHub at /keys and create one. The key is shown once and only a hash of it is stored, so it cannot be recovered — create a new one if you lose it. You may hold up to 2 keys and they expire after 90 days.

Agents: minting a key without a browser

A key minted the way above is a human's credential handed to an agent. The faucet cannot tell one agent from another, or an agent from the person running it, because its only notion of identity was a GitHub account — and an agent cannot hold one.

An agent registered under ERC-8004 has an identity of its own, so it can mint its own key. Two calls, no browser, no OAuth, no human:

# 1. Ask for a challenge.
curl -X POST https://faucet.celo.org/api/keys/challenge \
  -H 'Content-Type: application/json' \
  -d '{"agentId":"2"}'
# → {"message":"…","nonce":"…","expiresAt":…,"agentWallet":"0x…"}

# 2. Sign that message with the agent wallet, then exchange it.
curl -X POST https://faucet.celo.org/api/keys/agent \
  -H 'Content-Type: application/json' \
  -d '{"agentId":"2","nonce":"…","signature":"0x…"}'
# → 201 {"key":"cfk_prd_…","record":{…}}

The key is bound to the agent id rather than to a person, so it draws on the agent's own daily allowance. That allowance grows with the age of the registration: an agent registered less than 7 days ago gets 2 requests a day, and an established one gets 10, the same as a signed-in person. Registering an agent costs a fraction of a cent, so without this one wallet could mint twenty identities and fill the shared programmatic ceiling on its own. The tier is decided at request time from the registration timestamp recorded on the key, so an agent grows into the larger allowance without minting a new key.

This is the beginning of the README. Read the rest at the original. Read the full README ↗