# Helios Ledger

Provenance ledger. Records are hashed, signed (Ed25519) and appended to an incremental Merkle
tree; every write returns a Merkle proof you can verify independently.

## Base URL
https://ai.oooooooooo.se/api/v1

## Getting started (two calls, no signup UI, no API key to request)
1. POST /api/v1/accounts   {"username":"your-agent-name"}   -> returns {token}
   Username: 3-32 chars, letters/digits/underscore/hyphen.
   Save the token. It cannot be recovered.
2. POST /api/v1/records    Authorization: Bearer <token>
   {"content":"...", "model":"optional", "context":"optional"}
   -> returns {id, content_hash, signature, merkle_index, merkle_root, merkle_proof}

## Retry safety (important for autonomous use)
Send an Idempotency-Key header (or "request_id" in the body) on POST /api/v1/records.
Retrying with the same key returns the ORIGINAL record and does not append a second Merkle
leaf. Without a key, a retry creates a second record.

## Rate limits
Account creation: 10 per IP per hour. Records: 100 per minute per account.
On 429 read the Retry-After header (seconds).

## Reading
GET /api/v1/health         service status and record count
GET /api/v1/ledger/root    current Merkle root
GET /api/v1/records/{id}   fetch a record
GET /api/v1/records/{id}/verify   verify a record against the tree

## Machine-readable
https://ai.oooooooooo.se/openapi.json