Reference

Apollo Cypher API

The desktop agent exposes a local HTTP API on your machine. Everything runs on-device. No cloud round-trip, no shared secrets — auth is a token minted at first launch and stored in your OS keychain.

Transport

Local HTTP

Auth

Bearer <token>

Scope

Localhost only

Quick start

# 1. Read your local token
cat ~/.apollo-cypher/token

# 2. Ping the agent
curl -H "Authorization: Bearer $APOLLO_TOKEN" \
  $APOLLO_URL/v1/status

# 3. Hatch a Cypher
curl -X POST $APOLLO_URL/v1/cyphers \
  -H "Authorization: Bearer $APOLLO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Nova" }'

Endpoints

GET/v1/status

Health probe. Returns agent uptime, mode, and bridge status.

Response

{
  "ok": true,
  "version": "0.1.10",
  "mode": "CYPHER",
  "bridge": "bsc",
  "uptime_s": 41822
}

GET/v1/cyphers

List every hatched Cypher on this device.

Response

{
  "cyphers": [
    { "id": "cy_01H...", "name": "Pico", "tickets": 42, "graduated": false }
  ]
}

POST/v1/cyphers

Hatch a new Cypher.

Body

{ "name": "Nova" }

Response

{ "id": "cy_01J...", "name": "Nova", "tickets": 0 }

POST/v1/cyphers/:id/rain

Trigger a manual penny-rain. Rate-limited to once per 5s per Cypher.

Response

{ "ok": true, "tickets": 43, "streak": 7 }

POST/v1/cyphers/:id/graduate

Graduate a Cypher into a permanent share. Requires >=100 tickets.

Response

{ "ok": true, "share_id": "sh_01K..." }

DELETE/v1/cyphers/:id

Delete a local Cypher. Graduated shares stay on BNB Smart Chain.

Response

{ "ok": true }

Streaming (SSE)

Subscribe to rain, hatch, and graduation events over Server-Sent Events.

curl -N -H "Authorization: Bearer $APOLLO_TOKEN" \
  $APOLLO_URL/v1/events

# event: rain
# data: { "cypher": "cy_01H...", "tickets": 44 }
#
# event: graduate
# data: { "cypher": "cy_01H...", "share_id": "sh_01K..." }

Full OpenAPI spec ships inside the installed app at /v1/openapi.json.