# GOVY Protocol

> Tokenized rolling US Treasury bill protocol — 1 GOVY token = 1 T-Bill, continuously rolling at maturity.

## What is GOVY

GOVY is a tokenized treasury protocol that wraps US Treasury bills into ERC-20 tokens. Each GOVY token is backed 1:1 by a short-term T-Bill. When the underlying bill matures, the protocol atomically "rolls forward" into the next bill, maintaining continuous yield exposure without manual intervention.

## Key Concepts

- **T-Rep (Treasury Representation):** Accrual factor starting at 1.0000 that increases over time as treasury yield accrues. The GOVY price = T-Rep x Treasury Price.
- **Treasury Roll:** Automated cycle where the backing T-Bill transitions: upcoming -> current -> previous. Each roll can include a new T-Rep value and initial price.
- **Multi-chain:** GOVY tokens exist on Ethereum mainnet, Sepolia testnet, Hedera (HTS), and Stellar/Soroban.

## API

Base URL: `https://api.govy.finance` (or `http://localhost:3006` for local dev)

### Public Endpoints (no auth)
- `GET /api/health` — Server health check
- `GET /api/openapi.json` — OpenAPI 3.1 specification
- `GET /api/protocol-data` — Full protocol state (treasuries, T-Rep history, prices, contracts)
- `GET /api/price` — Current computed GOVY price (T-Rep x treasury price)
- `GET /api/fetch-treasury-info?isin=...` — Look up US Treasury auction data by ISIN
- `GET /api/networks` — Supported chains with contract addresses and explorers
- `GET /api/supply` — Total GOVY supply across all networks
- `GET /api/holders` — Holder counts across all networks

### Authenticated Endpoints (X-API-Key header)
- `POST /api/auth/verify` — Verify API key validity
- `POST /api/treasuries` — Create a treasury definition
- `PATCH /api/treasuries/:id` — Update a treasury
- `DELETE /api/treasuries/:id` — Delete a treasury
- `POST /api/prices/:treasuryId` — Add a price observation
- `POST /api/trep` — Add a T-Rep accrual entry
- `PATCH /api/contracts` — Update contract addresses
- `POST /api/roll-forward` — Execute treasury roll-forward
- `GET /api/events` — Event history (since/limit params)
- `GET /api/events/stream` — Real-time SSE event stream

### Admin Endpoints (admin scope)
- `GET /api/keys` — List API keys
- `POST /api/keys` — Create scoped API key
- `DELETE /api/keys/:id` — Revoke API key
- `GET /api/audit` — Audit log
- `GET /api/webhooks` — List webhooks
- `POST /api/webhooks` — Register webhook
- `DELETE /api/webhooks/:id` — Delete webhook

## Contract Addresses

- **Ethereum Mainnet:** `0xe1bD7Ca5Df4650DA4724AB118a882eD6bDA001EA`
- **Sepolia Testnet:** `0x2f459Ad5DB7B73B4dcEB5AeEd5d5c27217F5bfa9`
- **Hedera:** Configured per deployment (HTS token ID format `0.0.XXXXX`)
- **Stellar:** Configured per deployment (Soroban contract, 56-char uppercase)

## Links

- Website: https://govy.finance
- API Spec: https://api.govy.finance/api/openapi.json
- Full API Reference: /llms-full.txt