# ArkFaucet Full Agent Reference

ArkFaucet provides valueless Bitcoin Signet sats for development and testing.
It supports Ark, Lightning, and native on-chain payouts. It does not serve
mainnet funds and requires no account, API key, cookie, or CAPTCHA.

## Discovery

- Canonical origin: https://arkfaucet.com/
- Compact agent index: https://arkfaucet.com/llms.txt
- OpenAPI: https://arkfaucet.com/openapi.json
- Agent skill: https://arkfaucet.com/skills/ark-faucet/SKILL.md
- Well-known manifest: https://arkfaucet.com/.well-known/arkfaucet.json
- Tor guide: https://arkfaucet.com/tor/
- I2P guide: https://arkfaucet.com/i2p/

## Safe workflow

1. Read `GET /api/status` immediately before a claim.
2. Confirm `network` is `signet`, choose one returned `supported_rails` value,
   and choose one returned `allowed_amounts` value.
3. Obtain a fresh destination that matches the selected rail.
4. Submit exactly one `POST /api/request` JSON body.
5. Treat Ark or Lightning as complete only after HTTP 200 with `status: sent`.
6. For on-chain HTTP 202, keep `claim_status_url` private and poll it until
   `sent`, `failed`, or `unknown`. Never replace a pending or uncertain claim.

Example:

```json
{"rail":"ark","destination":"tark1YOUR_VALID_ADDRESS","amount_sats":500}
```

## Destinations

- `ark`: fresh checksum-valid `tark1` address from a compatible Bark wallet
  using the `ark_server` returned by status.
- `lightning`: fresh Bitcoin Signet BOLT11 invoice beginning `lntbs`; any fixed
  invoice amount must equal `amount_sats`.
- `onchain`: fresh lowercase Bitcoin Signet SegWit address beginning `tb1`.

Never alter an address or invoice, switch rails after failure without user
approval, or use a mainnet destination.

## Public endpoints

- `GET|HEAD /api/health`: lightweight readiness.
- `GET|HEAD /api/status`: current rails, amounts, limits, balances, required Ark
  server, contribution addresses, service transports, and agent resources.
- `GET /api/activity`: privacy-safe received and distributed aggregates.
- `GET /api/liquidity`: pool allocation, snapshots, runway, and observation-only
  fund-overseer status.
- `POST /api/request`: request a payout.
- `GET /api/claim/{token}`: poll a private queued on-chain claim.
- `POST /api/contribute/lightning-invoice`: create a fixed-amount Signet invoice
  for funding the faucet.

Use the OpenAPI document for authoritative schemas and response codes.

## Contributions

- Ark: fetch status and send compatible, current Signet Ark sats to the current
  `deposit_address` using the returned `ark_server`.
- Lightning: request a supported fixed amount from the contribution invoice
  endpoint and pay the complete `lntbs` invoice before `expires_at`.
- Native on-chain: send only native Signet sats to
  `onchain_deposit_address`; this funds the isolated on-chain payout pool.

Contributions do not create claim credit or an account. Sender success proves
submission, not receiver credit. Public aggregates cannot prove a particular
payment settled.

## Rate and retry safety

- Read current exact limits from status; the shared daily sat cap is dynamic.
- Clearnet applies rolling per-IP and per-destination limits.
- Tor and I2P skip the IP limit but share a rolling anonymous claim cap plus
  destination, rail, and global limits.
- Pending, processing, and uncertain payouts reserve limits.
- Obey HTTP 429 `Retry-After` and never rotate IPs or destinations to evade it.
- Correct HTTP 400/415 payloads instead of retrying unchanged input.
- Use bounded backoff for ordinary HTTP 503 responses.
- Stop on `payout_unknown`; the original payment may have completed.

## Private transports

Use the published clearnet guides to verify the complete Tor or I2P destination
before connecting. Keep a workflow on one origin. Do not send tokens through a
public gateway. I2P tunnel construction can be slower than clearnet; use
`--connect-timeout 20 --max-time 90` and bounded retries.

## Payment reporting

Keep `generated`, `submitted`, `payer-confirmed`, `receiver-confirmed`, and
`unconfirmed` distinct. Never expose claim tokens, invoices, wallet secrets,
transaction identifiers, or private payment evidence in public logs.