How to use the faucet

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.

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 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.

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.