Stellar-Pathfinder / stellar-pathfinder

# Stellar Pathfinder
**A corridor-integrity monitor for the Stellar network.**
Stellar Pathfinder prices stablecoin → fiat-token corridors across trade sizes, scores
every route against independent mid-market rates, and states plainly when
none of them are worth taking — including when the honest answer is *don't
send this*.
**Status:** pre-MVP, read-only. Non-custodial: no funds held, no tokens
issued, no KYC, no keys.
---
## Try Stellar Pathfinder
| | |
|:---|:---|
| **Live** | **https://stellar-pathfinder.onrender.com/** |
| **Source** | https://github.com/Stellar-Pathfinder/stellar-pathfinder |
| **Health** | https://stellar-pathfinder.onrender.com/healthz |
That is a real deployed instance of the code in this repository — the same
container image CI builds and verifies. Three things about it are worth knowing
before you read a figure off it:
**It serves recorded measurements, not live ones.** The instance runs with
`-schedule=0 -history-first`, so a request answers from the hash-chained history
embedded in the binary at build time. Every response carries `live: false` and a
`stale` block with the reading's age. Ask for a live measurement explicitly with
`?live=1` — that prices a full ladder against Horizon and takes tens of seconds.
**Freshness depends on the measure workflow, not on the deployment.** New
records are written by `.github/workflows/measure.yml` and committed to `data/`.
The committed history is a bounded window, not the whole chain: each corridor
keeps its newest 366 records and rotates the rest (ADR 007) — the dropped,
older records live on in the repository's git history. The workflow is currently
unable to push (#63),
so the served history is older than its six-hour cadence implies. Read
`stale.age_human` rather than assuming. The mechanism — history embedded at
build time, so freshness advances by redeploy rather than by scheduler — is
documented in full.
**It sleeps.** The free instance sleeps after fifteen minutes without traffic,
so the first request after a quiet period may take several seconds or fail
outright before the instance wakes. Retry once. The checked observation and
the boundary between manual retry and built behavior are recorded in
**docs/cold-start-reliability.md**.
It runs the current system, and only the current system. Nothing in the v2–v6
roadmap below is deployed there.
To reproduce it locally, `go run ./cmd/wayfared` and open
`http://127.0.0.1:8080/` — that measures live against mainnet rather than
serving history. Deployment details: **docs/deployment.md**.
How the deployed instance serves its embedded history:
**docs/embedded-history.md**.
---
## Why a monitor and not a router
The project began as a router — find the cheapest path, rank the results. Live
mainnet measurement killed that thesis, and the measurement is the reason the
tool exists in its current form.
Sending 100 USDC to NGNC returns roughly 62,900 NGNC against a USD/NGN mid
near 1,364. The best available route delivers about 46% of fa