# How to use the faucet

Request test SUI for development, whether you are using a browser, an agent, or CI.
Proof of work replaces request rate limits: each request must complete a computation
before the faucet pays. Thank you for using this public good fairly.

## In your browser

1. Open the [faucet](/) and choose Testnet, Devnet, or a trusted Custom faucet.
2. Paste your recipient address. On Testnet and Devnet, connecting a wallet can fill it in for you.
3. Select **Request SUI**. Keep the page open while it proves work and waits for the payout.
4. Check the transaction digest shown in the result.

No wallet signature or private key is needed. The faucet pays the transaction gas.
Funds arrive in the recipient's **address balance**, not as a new coin object.
The amount is set by the faucet and advertised in the challenge as `amountMist`.

## For agents, scripts, and CI

Call the HTTP API directly. You do not need a browser or wallet connection,
but you must compute a valid proof of work. Use the same faucet URL and recipient
throughout the request. The following shell examples use `curl`.

### 1. Fetch the inputs

Choose your backend and replace the placeholder with a complete, lowercase Sui address
(`0x` followed by 64 hex characters). For Devnet, use
`https://faucet.devnet.sui.io`. For your own deployment, use its API base URL.

```sh
export FAUCET=https://faucet.testnet.sui.io
export RECIPIENT=0xYOUR_64_HEX_CHARACTER_ADDRESS

curl --fail-with-body --get "$FAUCET/v3/challenge" \
  --data-urlencode "recipient=$RECIPIENT" \
  --output challenge.json
```

`GET /v3/challenge?recipient=0x...` returns JSON containing the chain ID,
checkpoint sequence and digest, checkpoint randomness, faucet address, recipient,
hashing parameters, threshold, freshness window, and payout amount.
Check that the network and recipient match your request.

### 2. Compute the proof

Follow the [proof-of-work protocol specification](/pow-spec/)
to compute a valid proof for your challenge.

### 3. Submit the solution

Save these four fields as a JSON object in `proof.json`, then submit promptly
after solving. `POST /v3/gas` accepts:

- `recipient`

  The same normalized address used to fetch the challenge.

- `checkpointSeq`

  The challenge's checkpoint sequence, as a decimal string.

- `nonce`

  Your solved unsigned 64-bit nonce, as a decimal string.

- `hashHex`

  The computed Argon2d output: 64 lowercase hex characters, without a `0x` prefix.

```sh
curl --fail-with-body "$FAUCET/v3/gas" \
  --header 'Content-Type: application/json' \
  --data-binary @proof.json
```

A successful response includes `status: "success"`, the transaction
`digest`, the `recipient`, and `amountMist`.
One SUI is 1,000,000,000 MIST. Save the proof and response so you can recover an
uncertain outcome without requesting another payment.

To inspect a working request without writing a client, open browser developer tools,
select **Network**, and request SUI from the homepage. Inspect the
challenge response and the gas request's JSON payload.

## Errors and recovery

- `stale_checkpoint` before any uncertain submission: fetch a fresh challenge and solve again.
- `invalid_proof`: check your preimage, address normalization, Argon2d parameters, and full hash output against the test vectors.
- `funds_unavailable`, `not_ready`, or `overloaded`: back off. The service can be unavailable even without request rate limits.
- A lost response, gateway failure, or `payout_status_unknown` after submission: do not automatically grind another proof. The payout may already have executed.

For an uncertain result, retain the original endpoint and the **exact same
four request fields**. While the checkpoint remains usable, resubmitting them
can return `already_used` with the existing digest. Check that transaction
before requesting another payout. Without a digest, the original request may still
be in progress. Recovery is limited by checkpoint freshness and server restarts;
it is not a permanent idempotency guarantee.

The legacy `/v2/gas` path is an opt-in compatibility mode for isolated
deployments, not the public automation interface. Agents and CI using the public
faucet should implement the v3 proof-of-work flow above.

## Protocol references

These resources are static and readable without JavaScript, including by agents.

- [HTML guide](/how-to-use/)
- [Agent entry point](/llms.txt)
- [Full specification](/pow-spec/)
- [Raw Markdown specification](/pow-spec/pow-spec.md)
- [Conformance vectors (JSON)](/pow-spec/pow-vectors.json)