# faucet.prim.sh

Free testnet USDC and ETH on demand. Fund your agent wallet and start building.

Base URL: https://faucet.prim.sh
Auth: None (free, rate-limited by address). Wallet must be on allowlist during beta.
Chain: Base Sepolia (eip155:84532) during beta.

Install:
  curl -fsSL https://faucet.prim.sh/install.sh | sh

Limits:
  USDC: 10 USDC per drip, 2-hour cooldown per address
  ETH: 0.01 ETH per drip, 1-hour cooldown per address
  Network: Base Sepolia (eip155:84532) only

---

## Quick Start

  1. POST /v1/faucet/usdc with {"address": "0x..."} → receive 10 test USDC (free)
  2. POST /v1/faucet/eth with {"address": "0x..."} → receive 0.01 test ETH (free)
  3. GET /v1/faucet/status?address=0x... → check cooldown before dripping
  4. GET /v1/faucet/treasury → check treasury ETH balance
  5. POST /v1/faucet/refill → batch-claim ETH from CDP faucet into treasury

## Tips

  - No x402 payment required — faucet is entirely free.
  - Check GET /v1/faucet/status before dripping to avoid wasted 429 responses.
  - ETH cooldown is 1 hour; USDC cooldown is 2 hours per address.
  - USDC uses Circle Faucet API with treasury wallet ERC-20 transfer as fallback.
  - faucet.sh only operates on Base Sepolia — mainnet addresses return 403.

---

## Error envelope

  {"error": {"code": "<code>", "message": "<msg>"}}

Error codes:
  invalid_request
  wallet_not_allowed
  mainnet_rejected
  rate_limited
  faucet_error
  treasury_low

---

## Endpoints

### GET /

Health check.

Free.

Response (200):
  service  string  "faucet.sh"
  status   string  "ok"

---

### GET /pricing

Machine-readable pricing for all endpoints.

Free.

Response (200):
  service   string  "faucet.prim.sh"
  currency  string  "USDC"
  network   string  "eip155:8453"
  routes    array   Route pricing list
    .method       string  HTTP method
    .path         string  URL path
    .price_usdc   string  Price in USDC (decimal string)
    .description  string  Human-readable description

---

### GET /v1/metrics

Operational metrics. Uptime, request counts, latency percentiles, error rates.

Free.

Response (200):
  service     string  "faucet.prim.sh"
  uptime_s    number  Seconds since last restart
  requests    object  Request counts and latencies by endpoint
  payments    object  Payment counts by endpoint
  errors      object  Error counts by status code

---

### POST /v1/faucet/usdc

Dispense 10 test USDC on Base Sepolia. Rate limit: once per 2 hours per address.

Free. No x402 payment required.

Request:
  address  string  required  EVM wallet address to drip to (0x... 42 chars).

Response (200):
  tx_hash   string  Transaction hash on Base Sepolia. May be "pending" if Circle returns 204.
  amount    string  Amount dispensed as a decimal string (e.g. "10.00" for USDC, "0.01" for ETH).
  currency  string  Currency dispensed: "USDC" or "ETH".
  chain     string  CAIP-2 chain identifier (e.g. "eip155:84532").
  source    string  Backend that dispensed the tokens. "circle" | "treasury". Only present on USDC drips.

Errors:
  400  invalid_request     Missing or invalid address
  403  wallet_not_allowed  Wallet not on allowlist (private beta)
  403  mainnet_rejected    Faucet only operates on testnet
  429  rate_limited        Address already dripped within 2 hours. retryAfter in response.
  502  faucet_error        Both Circle and treasury fallback failed

---

### POST /v1/faucet/eth

Dispense 0.01 test ETH on Base Sepolia. Rate limit: once per 1 hour per address.

Free. No x402 payment required.

Request:
  address  string  required  EVM wallet address to drip to (0x... 42 chars).

Response (200):
  tx_hash   string  Transaction hash on Base Sepolia. May be "pending" if Circle returns 204.
  amount    string  Amount dispensed as a decimal string (e.g. "10.00" for USDC, "0.01" for ETH).
  currency  string  Currency dispensed: "USDC" or "ETH".
  chain     string  CAIP-2 chain identifier (e.g. "eip155:84532").
  source    string  Backend that dispensed the tokens. "circle" | "treasury". Only present on USDC drips.

Errors:
  400  invalid_request     Missing or invalid address
  403  wallet_not_allowed  Wallet not on allowlist (private beta)
  403  mainnet_rejected    Faucet only operates on testnet
  429  rate_limited        Address already dripped within 1 hour. retryAfter in response.
  503  treasury_low        Treasury ETH too low. Call POST /v1/faucet/refill.
  502  faucet_error        Treasury wallet failed to send ETH

---

### GET /v1/faucet/status

Check rate limit status for a wallet address across both faucets.

Free. Call this before dripping to avoid 429s.

Query params:
  address  string  optional  EVM wallet address (required)

Response (200):
  address  string              The queried wallet address (checksummed).
  usdc     FaucetAvailability  USDC faucet availability (2-hour cooldown).
  eth      FaucetAvailability  ETH faucet availability (1-hour cooldown).

Errors:
  400  invalid_request  Missing or invalid address query param

---

### GET /v1/faucet/treasury

Check treasury wallet ETH balance and refill status.

Free. No allowlist required.

Response (200):
  address       string
  eth_balance   string
  needs_refill  boolean

Errors:
  502  faucet_error  FAUCET_TREASURY_KEY not configured

---

### POST /v1/faucet/refill

Batch-claim testnet ETH from Coinbase CDP faucet into treasury. Rate limited to once per 10 minutes.

Free. No allowlist required. Requires CDP_API_KEY_ID and CDP_API_KEY_SECRET.

Response (200):
  claimed        number
  failed         number
  estimated_eth  string
  tx_hashes      string[]

Errors:
  429  rate_limited  Refill called within 10 minutes. retryAfter in response.
  502  faucet_error  CDP API keys not configured

---

## Ownership

Rate-limited by wallet address. No wallet registration required — anyone can drip to any address.