Usage
What it does
1
Boots the facilitator
Runs
docker compose up -d --build, which builds the image defined in
docker/facilitator.Dockerfile (cloning GoPlausible/x402-avm at build time) and starts it,
exposing port 4022. Fails fast with a clear error if Docker isn’t running.2
Waits for the facilitator to become healthy
Polls
GET /supported on FACILITATOR_URL (default http://localhost:4022) up to 30 times,
2 seconds apart, before giving up — the facilitator’s own image build and startup can take a
while the first time.3
Funds the client account (if possible)
If
WARD_FUNDER_PRIVATE_KEY is set, sends 1 ALGO worth of native currency to
WARD_CLIENT_PRIVATE_KEY’s address to cover transaction fees. If it isn’t set, prints a
warning with a link to the dispenser and continues — this lets you fund manually instead.4
Verifies one real payment, end to end
Builds a real signed payment, calls
/verify (must be approved) and then /settle (must
succeed), and prints the resulting transaction id and a link to view it on an Algorand
explorer. This is the step that proves the facilitator is real, funded, and working —
everything ward test reports afterward is only meaningful once this step has passed.Idempotency
ward init is safe to re-run. docker compose up -d --build is a no-op rebuild if nothing
changed, funding only tops up what’s missing, and the manual-payment check simply runs again.
Example output
Common failures
docker compose up failed — is Docker running?
docker compose up failed — is Docker running?
Start Docker Desktop (or your Docker daemon) and re-run
ward init.Facilitator did not become healthy after 30 attempts
Facilitator did not become healthy after 30 attempts
Check
docker compose logs facilitator — usually a missing or malformed AVM_PRIVATE_KEY,
EVM_PRIVATE_KEY, or SVM_PRIVATE_KEY in .env (the upstream facilitator image
process.exit(1)s on startup if any are absent, even though Ward only exercises Algorand).Manual verification payment was rejected at /verify
Manual verification payment was rejected at /verify
Almost always unfunded or non-opted-in accounts. Confirm
WARD_CLIENT_PRIVATE_KEY’s address
has TestNet ALGO and is opted into the TestNet USDC ASA (10458941 by default).Manual verification payment failed at /settle
Manual verification payment failed at /settle
Check the printed
errorReason/errorMessage — commonly an underfunded AVM_PRIVATE_KEY
address (it needs its own TestNet ALGO to co-sign fee-payer transactions).