# Celebration Hub Agent Docs

> Celebration Hub exposes birthdays, gifts, check-in, lottery, and event flows through a public web/API/onchain contract that external agents can use safely.

## Core Entry Points

- [Agents overview](https://www.celebration-hub.xyz/agents): Human-readable quickstart and guardrails.
- [Capabilities](https://www.celebration-hub.xyz/api/agent/capabilities): Live discovery for actions, runtimes, contracts, payment hints, and share patterns.
- [Current session identity](https://www.celebration-hub.xyz/api/agent/me): Returns the authenticated profile and canonical write identity.
- [OpenAPI](https://www.celebration-hub.xyz/api/agent/openapi.json): Machine-readable API schema.
- [Installable SKILL.md](https://www.celebration-hub.xyz/SKILL.md): Remote-install skill file for agents that support SKILL.md URLs.
- [celebrationhub.md](https://www.celebration-hub.xyz/celebrationhub.md): Primary markdown skill for external agents.
- [Full LLM guide](https://www.celebration-hub.xyz/llms-full.txt): Expanded machine-readable documentation.

## Canonical Flow

1. Read capabilities.
2. Read agent/me.
3. Use canonicalWriteFid for writes.
4. Run preflight or availability.
5. Execute the canonical write route.
6. Complete finalize or proof steps for onchain flows.

## Supported Actions

- Birthday identity: create or update birthday, then request proof signature and submit the onchain mint transaction.
- Classic gifts: send a normal gift with exactly one visual mode.
- NFT gifts: preflight, draft, finalize, then share via `/share-gift-nft/:draftId`.
- Nexart gifts: generate canonical Nexart SDK art through `POST /api/nexart/generate`, use returned `imageUrl` as `nexartImage`, keep `nexartPrompt` separate from the recipient-facing `message`, and use `style: "random"` when the user asks for random/surprise art. If generation fails, stop and ask for a retry; do not silently switch visual modes.
- Daily check-in: preflight, execute, finalize when required.
- Lottery: read availability or preflight before spinning.
- Events: create or join, then finalize host or attendance proof when the flow is onchain.

## Rules

- Web/Base is the default agent runtime.
- Farcaster miniapp behavior is optional and only needed for miniapp-native UX.
- Do not guess a writable FID; use `canonicalWriteFid`.
- Do not treat `mint-signature` as the final birthday NFT mint.
- Do not use internal, admin, or private ops routes as the public contract.