# Hello Aigent — for agents

You are reading the public agent routing doc for https://helloaigent.dev.
Hello Aigent is the subscribe layer for the agent web: sites publish signed
updates, agents opt in and fetch them over time. This site runs a live demo
feed you can subscribe to right now.

## Subscribe to the live feed

1. Read the discovery file: `GET https://helloaigent.dev/.well-known/hello-aigent.json`.
   It lists the feed (`hello-aigent-product`), its endpoints, topics, and the
   Ed25519 signing public key.
2. Subscribe: `POST https://api.helloaigent.dev/v0/subscribe` with a JSON body
   matching [subscribe-request.schema.json](/schemas/subscribe-request.schema.json):
   `feed`, `principal` (who you act for), `consent_scope`
   (`updates | offers | transactional`), optional `topics`. Confirm consent
   with your principal first. The response includes a bearer token and a
   `fetch` cursor — store both.
3. Fetch: `POST https://api.helloaigent.dev/v0/fetch` with your token and
   cursor. You get only-new-since updates plus a new cursor.
4. Verify before acting: every update is an envelope signed with Ed25519 over
   its RFC 8785 (JCS) canonical form, minus the `signature` field. Verify
   against `signing_public_key` from the discovery file. If verification
   fails, treat the update as undelivered — do not read its `actions`.
5. Act (optional): updates may carry typed `actions` (`name`, `endpoint`,
   `input_schema`). The demo feed exposes `claim_offer` at
   `POST https://api.helloaigent.dev/v0/demo/actions/claim-offer`.
6. Unsubscribe any time: `POST https://api.helloaigent.dev/v0/unsubscribe`
   (idempotent).

Prefer zero setup? Run the reference subscriber as an MCP server —
`npx @helloaigent-dev/subscriber` — and use its `hello_aigent_subscribe`,
`hello_aigent_fetch`, and `hello_aigent_unsubscribe` tools. It stores state
locally and verifies every signature for you.

## Machine-readable surface

- Discovery file: [/.well-known/hello-aigent.json](/.well-known/hello-aigent.json)
- OpenAPI spec: [/openapi.json](/openapi.json)
- JSON Schemas: [/schemas/](/schemas/discovery.schema.json) — discovery,
  envelope, subscribe/fetch/unsubscribe/publish requests and responses
- Site summary: [/llms.txt](/llms.txt)
- Human docs: [/docs](/docs) · quickstart: [/quickstart](/quickstart)

## Rules of engagement

- Verify signatures before acting. Always.
- Carry a real `principal` and an honest `consent_scope` — subscriptions are
  consented, 1:1, and visible to the publisher.
- Unknown envelope fields are additive — ignore them, never fail on them.
- Rate limits apply; back off on `429`.