---
name: sozu-faucet
description: >-
  Claim Stellar testnet Circle USDC (SAC) from Sozu Faucet with one shell command.
  Use when the user says get testnet USDC, get testnet USD, get testnet dollars,
  fund a testnet wallet with USDC/USD/dollars, Sozu faucet, or needs testnet USDC
  for a C…/G… address or $sozutag. Omit the address to generate a fresh G… wallet
  (Friendbot + USDC trustline + claim). Existing G… wallets without a trustline
  use Stellar Lab — never ask for secret keys in chat.
license: MIT
metadata:
  author: blessedux
  homepage: https://faucet.sozu.capital
---

# Sozu Faucet

Testnet **Circle USDC (SAC)** only. Not Friendbot (XLM). Not mainnet.

## Do this

1. Resolve the recipient (below).
2. Run the matching claim command.
3. Print the JSON. Never ask the user for a secret key / seed phrase.
4. On success, open Stellar Expert (account/ for G…, contract/ for C…).
5. If the JSON includes `wallet.secret`, tell the user to **save it once** — it is only in that output.

### Claim commands

**No address** (create + fund a new G… wallet in one shot):

```bash
npx @sozu/faucet@latest claim
```

Generates a keypair locally → Friendbot → Circle USDC trustline → PoW claim.
Stdout includes `wallet.address` + `wallet.secret`.

**Existing C…** (smart account — no trustline):

```bash
npx @sozu/faucet@latest claim <C_ADDRESS>
```

**Existing G…** (must already have a Circle USDC trustline):

```bash
npx @sozu/faucet@latest claim <G_ADDRESS>
```

If the CLI returns `trustline_required` (or `account_missing`), open `helpUrl`
([Stellar Lab Fund Account](https://lab.stellar.org/account/fund)): paste the G…
address → Add trustline for USDC (sign in Lab / Freighter) → re-run claim.
Do **not** ask for their secret in chat.

Local faucet: append `--url http://localhost:3010` (or set `SOZU_FAUCET_URL`).

Issuer (locked): `USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5`.

## Address resolution (pick first match)

1. Explicit `C…` / `G…` (56 chars) in the message → uppercase it → claim with address.
2. `$sozutag` / sozutag →  
   `curl -sS "https://faucet.sozu.capital/api/sozutag/resolve?tag=<tag>"`  
   use `.address` from the JSON.
3. Env / project config: `STELLAR_ADDRESS` only (never request `STELLAR_SECRET` in chat).
4. Otherwise run **bare** `npx @sozu/faucet@latest claim` (new wallet). Do not invent an address.

## Aliases

| Utterance | Meaning |
|---|---|
| USD, USDC, dollars, testnet dollars | Circle USDC SAC (testnet) |
| trailing amount (`0`, `20`, …) | **Ignore** — claim size is server-fixed |
| “make me a wallet” / no address | Bare `claim` (generate G… + trustline + fund) |

## Don't

- Don't ask the user for secret keys, seed phrases, or `STELLAR_SECRET` in chat.
- Don't hand-roll PoW, curl claim, JWT, or Turnstile.
- Don't use Friendbot for USDC (XLM only — the CLI uses it for fees on new G… wallets).
- Don't retry on cooldown / daily-limit / `trustline_required` — surface the JSON (and Lab link) and stop.
- Don't load `/agents.md` unless debugging beyond this skill.