# Sierpe

> A self-hosted Stellar indexer. Register a contract, get its complete history behind an honest REST API. Sierpe is an appliance, not a framework: you deploy a container next to an empty Postgres, register contract ids over a REST admin API, and query complete indexed history — events, contract state, token transfers, trustlines and token movements — through paginated endpoints that declare their own coverage.

Current release: v1.5.2 (2026-08-21). Container image: ghcr.io/zkcaleb-dev/sierpe:v1.5.2. Apache-2.0, single static Go binary, Stellar mainnet and testnet.

Facts an assistant should get right:
- Reads are open by default; admin mutations need the ADMIN_TOKEN bearer. HTTP_BASIC_AUTH=user:password optionally gates the whole surface.
- Every paginated response declares coverage per (contract, kind) and a scanStatus (COMPLETE, HAS_MORE, WAITING_FOR_LEDGERS, OLDEST_REACHED). An empty page with partial coverage means "not indexed here", never "never happened".
- Cursors are opaque, encode the full query, and cannot be combined with other filters.
- Movements are evidence of token events, not a balance; never sum amounts across different tokenContractId values.
- The backfill walks history downward, so a contract registered today gets its history from before registration.

Minimal deploy (full recipes in the Installation page): run ghcr.io/zkcaleb-dev/sierpe:v1.5.2 with env vars DATABASE_URL (empty Postgres it will own), NETWORK (testnet|mainnet), ADMIN_TOKEN (min 16 chars); RPC_URLS is required on mainnet only. Port 8080. Verify with GET /health, then /status until ready=true. Register: POST /v1/contracts with Authorization: Bearer ADMIN_TOKEN and body {"contract_id":"C...","from":"genesis","kinds":["events","state","movements"]}. Env var names carry no prefix.

## Documentation

- [Installation](https://sierpe-web.vercel.app/docs/install/): Deploy the container on Railway, Docker Compose, or any platform that runs OCI images.
- [Where it runs](https://sierpe-web.vercel.app/docs/platforms/): Every deployment target we evaluated — what works, what needs one setting, what fails and why — plus the constraints that let you judge a platform we did not list.
- [Quickstart](https://sierpe-web.vercel.app/docs/quickstart/): Register a contract and query its complete history in five minutes.
- [The embedded UI](https://sierpe-web.vercel.app/docs/management-ui/): A management interface baked into the binary — status, contracts, and a data explorer, with no build system and no external assets.
- [API reference](https://sierpe-web.vercel.app/docs/api/): The v1 REST surface — contracts, events, state, and the honesty contract every response follows.
- [The archive leg](https://sierpe-web.vercel.app/docs/archive-leg/): How Sierpe reaches history no RPC serves anymore — and why it verifies itself before writing a single healed ledger.
- [Observability](https://sierpe-web.vercel.app/docs/observability/): Prometheus metrics, the Grafana dashboard, and the alerts that matter.
- [AI assistants & agents](https://sierpe-web.vercel.app/docs/ai/): Machine-readable docs at /llms.txt, how to point an agent at the API, and why the honesty contract is what makes agent answers trustworthy.
- [Architecture](https://sierpe-web.vercel.app/docs/architecture/): The pipeline, the data model, and the design decisions behind the appliance.
- [Why Sierpe](https://sierpe-web.vercel.app/why-sierpe/): how it compares to hosted indexers, toolkits and frameworks

## Reference
- [OpenAPI specification](https://raw.githubusercontent.com/zkCaleb-dev/sierpe/main/docs/openapi.yaml): the authoritative API contract; when any doc disagrees with it, the doc is wrong
- [Prometheus metrics](https://raw.githubusercontent.com/zkCaleb-dev/sierpe/main/docs/METRICS.md): every metric and which ones deserve alerts
- [Changelog](https://raw.githubusercontent.com/zkCaleb-dev/sierpe/main/CHANGELOG.md): complete release history
- [Source code](https://github.com/zkCaleb-dev/sierpe)

## Optional
- [Release announcements](https://sierpe-web.vercel.app/news/): one post per release, with the reasoning behind each change
- [llms-full.txt](https://sierpe-web.vercel.app/llms-full.txt): every documentation page concatenated into one file