---
name: celebration-hub
description: Use Celebration Hub through its public agent contract for birthdays, gifts, check-in, lottery, and events. Start with capabilities, resolve canonicalWriteFid via /api/agent/me, run preflight before payment-backed or onchain flows, then execute and finalize/proof when required.
---

# Celebration Hub Skill

Use this skill when an agent needs to operate Celebration Hub through the public web/API/onchain contract.

## Start Here

- Docs: `https://www.celebration-hub.xyz/agents`
- Capabilities: `https://www.celebration-hub.xyz/api/agent/capabilities`
- Current session identity: `https://www.celebration-hub.xyz/api/agent/me`
- OpenAPI: `https://www.celebration-hub.xyz/api/agent/openapi.json`
- Full guide: `https://www.celebration-hub.xyz/celebrationhub.md`
- Full LLM guide: `https://www.celebration-hub.xyz/llms-full.txt`

## Canonical Flow

1. Read `GET /api/agent/capabilities`.
2. Read `GET /api/agent/me`.
3. Use `canonicalWriteFid` as the write identity.
4. Run the relevant `preflight` or `availability` route.
5. Execute the canonical write route.
6. Complete any finalize or proof step before treating the flow as complete.

## Core Rules

- Default agent runtime is web/Base.
- Farcaster miniapp behavior is optional and should only be used when a flow truly needs SDK-native UX.
- Do not guess a writable FID. Always use `canonicalWriteFid`.
- Do not write when `eligible` is false or when validation/config errors are present.
- Birthday proof is not complete until the final onchain mint transaction is submitted.
- NFT gift draft is not the final minted state.
- Internal, admin, notification-internal, referral-internal, and feed-private routes are not part of the external-agent contract.

## Supported Flows

- Birthday identity:
  - preflight: `POST /api/agent/birthday/preflight`
  - write: `POST /api/birthday`, `PUT /api/birthday`
  - proof: `POST /api/birthday/mint-signature`, then wallet mint
- Classic gifts:
  - preflight: `POST /api/agent/gifts/classic/preflight`
  - write: `POST /api/greetings/send`
- NFT gifts:
  - preflight: `POST /api/agent/gifts/nft/preflight`
  - draft: `POST /api/gifts/nft/draft`
  - finalize: `POST /api/gifts/nft/finalize`
  - canonical share: `/share-gift-nft/:draftId`
- Daily check-in:
  - preflight: `POST /api/agent/check-in/preflight`
  - write/finalize: `POST /api/gamification/daily-login`, `PUT /api/gamification/daily-login`
- Lottery:
  - availability: `GET /api/agent/lottery/availability`
  - preflight: `POST /api/agent/lottery/preflight`
  - write: `POST /api/gamification/lottery/spin`
- Events:
  - create preflight: `POST /api/agent/events/preflight`
  - join preflight: `POST /api/agent/events/join/preflight`
  - write: `POST /api/events`, `POST /api/events/:identifier/join`
  - finalize: `POST /api/events/finalize-host-mint`, `POST /api/events/:identifier/finalize-join-mint`
  - canonical share: `/events/:slug`

## Gift Rules

Choose exactly one visual mode per gift:

- `image`
- `drawing`
- `ai_image`
- `nexart`

Use:

- `image` when you already have a stored image path.
- `drawing` when the visual is canvas/drawing data.
- `ai_image` when the visual came from AI generation. Include `aiImagePrompt` when available.
- `nexart` when the visual came from Nexart. Include `nexartPrompt`, `nexartStyle`, or `nexartArtworkId` when available.

## Nexart Gift Mode

Use Nexart when the user asks for Nexart, generated art, random/surprise art, or the same generated-art behavior as the main gift interface.

Nexart has two separate texts:

- `nexartPrompt`: image-generation prompt.
- `message`: recipient-facing gift message.

Recommended sequence:

1. Run the relevant classic or NFT gift preflight.
2. Build a short, celebration-safe `nexartPrompt` from the occasion, recipient, and user request.
3. If the user says "random" or does not choose a style, use `style: "random"`.
4. Call `POST /api/nexart/generate`.
5. Use the returned `imageUrl` as `nexartImage`.
6. Use returned `artworkId` as `nexartArtworkId` and keep `source: "nexart-canonical-sdk"` as generation evidence when present.
7. Continue with classic send or NFT draft/finalize.

Generate request:

```json
{
  "prompt": "A joyful surreal birthday duck carrying glowing gifts through a neon celebration portal",
  "style": "random",
  "recipientFid": 123456
}
```

Generate response:

```json
{
  "success": true,
  "imageUrl": "https://...",
  "artworkId": "nexart-canonical-123456789",
  "style": "nexart-genart",
  "source": "nexart-canonical-sdk"
}
```

Then include these Nexart fields in the gift write request:

- `nexartImage`: returned `imageUrl`
- `nexartPrompt`: prompt used for generation
- `nexartStyle`: requested style, often `random`
- `nexartArtworkId`: returned `artworkId` when present

If Nexart generation fails, do not silently switch to `image`, `drawing`, or `ai_image`; stop and ask for a retry.

Classic gift common fields:

- `birthdayFid`
- `message`
- `txHash`
- `fromAddress`
- optional `showInPublicFeed`
- optional `eventSlug`

NFT gift common fields:

- `birthdayFid` or `recipientFid`
- `message`
- `walletAddress` or `senderWallet`
- optional `showInPublicFeed`
- optional `eventSlug`

NFT gift finalize fields:

- `draftId`
- `txHash`
- `walletAddress` or `senderWallet`

If NFT preflight says the recipient wallet is missing or unconfirmed, stop before draft/finalize.

## Errors And Retries

- `401`: refresh auth and re-read `/api/agent/me`
- `409`: re-read state or preflight; do not blind-retry
- `400` or `422`: fix the request payload first
- `404` on finalize or proof: the prior app-level step probably did not complete yet
- Reuse the same `Idempotency-Key` for retries of the same intended write when supported

## Prompt Template

Use Celebration Hub through its public celebration flows and public web/API/onchain contract. Start with `https://www.celebration-hub.xyz/api/agent/capabilities`, then read `https://www.celebration-hub.xyz/api/agent/me` and use `canonicalWriteFid` as the write identity. Before birthdays, gifts, lottery, or events, call the relevant preflight or availability route. Only then call the canonical execution route. If the flow has a finalize or proof step, complete it before treating the action as finished.