# Hyperion Agent Guide

Hyperion exposes a session-cookie or bearer-token authenticated JSON API for AI agents. Do not scrape the SPA.

Recommended TUI/CLI authentication flow:
1. Start an HTTP client. Cookie storage is optional; stateless agents can keep only challenge_id and bearer_token.
2. Start a challenge with GET or POST https://www.hyperion.zone/api/v1/agent/auth_challenges. If your client requires a distinct GET URL, GET https://www.hyperion.zone/api/v1/agent/auth_challenges/start.
3. Show the returned hivesigner_login_url to the user and ask them to open it.
4. The user completes HiveSigner privately in their own browser. The agent must not ask for, receive, store, or handle Hive private keys, HiveSigner passwords, or signing credentials.
5. After HiveSigner redirects back to Hyperion, the user sees a one-time code like HYP-ABC123.
6. Ask the user to paste only that HYP-* code back to you.
7. Redeem with challenge_id + code. POST {"code":"HYP-ABC123"} to /api/v1/agent/auth_challenges/{challenge_id}/redeem, or GET /api/v1/agent/auth_challenges/{challenge_id}/redeem?code=HYP-ABC123 if your sandbox cannot issue POST. The redeem request does not require browser cookies.
8. Keep the returned bearer_token and use Authorization: Bearer for subsequent API and MCP requests. Browser-capable agents may use the _hyperion cookie instead.

Suggested user-facing prompt:
"Please open this HiveSigner link in your browser and complete the login there. Do not paste any Hive key, password, or signing credential into this chat. When Hyperion shows a code beginning with HYP-, paste only that code here."

Credential handling rules:
- Never ask the user for Hive private keys, HiveSigner passwords, or any signing credential.
- Do not describe HiveSigner login as something the agent needs to complete.
- The user completes HiveSigner directly; the agent only receives the final HYP-* code.
- If HiveSigner asks for a private key or password, tell the user to handle that only on the HiveSigner page and never paste it into the agent.
- Prefer POST for redeem. Use the GET redeem fallback only when the agent sandbox cannot POST; the HYP-* code is one-time and short-lived.
- Do not tell the user that persistent browser/cookie support is required for agent auth; the challenge_id plus HYP-* code can be redeemed statelessly for a bearer token.

Browser-side agents may use the existing browser session cookie if they are running same-origin with Hyperion.
Keychain-capable agents may use the returned keychain.message/keychain.digest and POST account_name, public_key, digest, and signature to /api/v1/agent/auth_challenges/{challenge_id}/keychain.

Useful endpoints:
- GET or POST https://www.hyperion.zone/api/v1/agent/auth_challenges
- GET https://www.hyperion.zone/api/v1/agent/auth_challenges/start (alternate POST-restricted sandbox fallback for starting auth only)
- GET https://www.hyperion.zone/api/v1/agent/session
- GET https://www.hyperion.zone/api/v1/agent/digest?limit=10
- GET https://www.hyperion.zone/api/v1/agent/digest?query=california
- GET https://www.hyperion.zone/api/v1/agent/posts/:id
- GET https://www.hyperion.zone/api/v1/agent/posts/:id/vote_link?weight=10000
- POST https://www.hyperion.zone/api/v1/agent/read with {"post_id":123}, {"id":123}, {"post_ids":[123,456]}, {"ids":[123,456]}, or {"all_matching":true,"query":{...}}
- POST https://www.hyperion.zone/api/v1/agent/ignored_tags with {"tag":"spam"}, {"tags":["spam","ai"]}, or {"ignored_tags":"spam, ai"}
- DELETE https://www.hyperion.zone/api/v1/agent/ignored_tags with {"tag":"spam"}, {"tags":["spam","ai"]}, or {"ignored_tags":"spam, ai"}
- POST https://www.hyperion.zone/mcp

Example curl flow:
curl https://www.hyperion.zone/api/v1/agent/auth_challenges
# POST also works:
curl -X POST https://www.hyperion.zone/api/v1/agent/auth_challenges
# Alternate GET fallback:
curl https://www.hyperion.zone/api/v1/agent/auth_challenges/start
ask the user to open hivesigner_login_url privately, then:
curl -H 'Content-Type: application/json' -d '{"code":"HYP-ABC123"}' https://www.hyperion.zone/api/v1/agent/auth_challenges/:challenge_id/redeem
# POST-restricted sandbox redeem fallback:
curl "https://www.hyperion.zone/api/v1/agent/auth_challenges/:challenge_id/redeem?code=HYP-ABC123"
curl -H 'Authorization: Bearer hyp_at_...' https://www.hyperion.zone/api/v1/agent/digest?limit=5

Vote broadcasting is done through HiveSigner links. Hyperion does not store posting keys or broadcast votes server-side.