Agent

External Agents

Celebration Hub agent flows, contracts, and skill files.

This page shows how external agents can use birthdays, gifts, check-in, lottery, and event flows safely through the public web/API/onchain contract.

Canonical sequence: capabilities -> me -> preflight -> write -> finalize/proof

Install skill Capabilities OpenAPI JSON llms.txt

Runtime

Default runtime: https://www.celebration-hub.xyz

Optional Farcaster surface: https://celebration-hub.xyz/farcaster

Identity

Use /api/agent/me and keep canonicalWriteFid as the write source of truth.

Docs

Use /llms.txt for the LLM entrypoint or /api/agent/openapi.json for the machine-readable contract.

Creating Celebration Hub flows with an agent

If you use a coding agent like Claude Code or Codex, you can ask it to install the Celebration Hub skill and then operate through the public API/onchain contract.

install the Celebration Hub skill from https://www.celebration-hub.xyz/SKILL.md
make a Celebration Hub birthday identity, send an NFT gift, or create an event safely

The skill will:

1.Read Celebration Hub capabilities, OpenAPI, and live payment hints.
2.Use the safe flow: capabilities -> me -> preflight -> write -> finalize/proof.
3.Create or update birthday identity, send classic or NFT gifts, check in, use lottery, and create or join events.
4.Respect web/Base as the default runtime and keep Farcaster SDK actions optional.

Start Here

Keep the shape of the flow simple. Agents should not improvise around identity, payments, or onchain proof steps.

Step 01

Discover

Read capabilities first to learn supported runtimes, auth modes, canonical routes, and live payment hints.

/api/agent/capabilities

Step 02

Resolve identity

Read the current authenticated profile and always use canonicalWriteFid for writes.

/api/agent/me

Step 03

Preflight

Validate before every payment-backed or onchain action. Do not write if eligible is false.

/api/agent/*

Step 04

Execute and finish

Call the canonical write route, then complete finalize or proof steps when the flow requires them.

write -> finalize/proof

The Model

These three ideas explain most of the system without dragging an agent through every detail up front.

Shared public flows

Agents use the same public celebration flows and write routes instead of a hidden or privileged backdoor.

Web/API default

Treat https://www.celebration-hub.xyz as the default runtime. Farcaster miniapp behavior is optional and should only be used when a flow truly needs SDK-native UX.

Onchain proof layer

Birthday NFTs, NFT gifts, and event proofs are identity-bearing celebration artifacts, not just collectibles.

Supported Actions

The public external-agent surface covers the main celebration flows. Internal feeds, admin surfaces, and private ops routes are intentionally out of scope.

Birthday identity

Birthday setup is an identity flow. For agents it is only truly complete after the proof transaction exists onchain.

Preflight: /api/agent/birthday/preflight
Execute: POST /api/birthday | PUT /api/birthday
Finalize or proof: POST /api/birthday/mint-signature + wallet mint
Canonical share: /user/:fid

Classic gifts

Send a normal celebration gift with exactly one visual mode: image, drawing, ai_image, or nexart.

Preflight: /api/agent/gifts/classic/preflight
Execute: POST /api/greetings/send
Finalize or proof: No onchain finalize
Canonical share: app and share routes

NFT gifts

Draft prepares the gift. Finalize completes the minted celebration proof.

Preflight: /api/agent/gifts/nft/preflight
Execute: POST /api/gifts/nft/draft
Finalize or proof: POST /api/gifts/nft/finalize
Canonical share: /share-gift-nft/:draftId

Daily check-in

Check-in is a repeat participation loop. Preflight first, then execute and finalize when required.

Preflight: /api/agent/check-in/preflight
Execute: POST /api/gamification/daily-login
Finalize or proof: PUT /api/gamification/daily-login
Canonical share: /rewards/claimed

Lottery

Lottery is gated. Agents should read availability or preflight instead of spinning blindly.

Preflight: /api/agent/lottery/availability | /api/agent/lottery/preflight
Execute: POST /api/gamification/lottery/spin
Finalize or proof: No separate proof route
Canonical share: app reward surfaces

Events

Agents can create and join events. Onchain-enabled events add host or attendance proof steps.

Preflight: /api/agent/events/preflight | /api/agent/events/join/preflight
Execute: POST /api/events | POST /api/events/:identifier/join
Finalize or proof: host mint | join mint finalize
Canonical share: /events/:slug

Nexart Gifts

Nexart is the generated-art gift mode. Agents should treat canonical SDK generation as a preparation step before classic send or NFT draft/finalize.

Generate first

POST /api/nexart/generate
{
  "prompt": "A joyful birthday duck carrying glowing gifts through a neon portal",
  "style": "random",
  "recipientFid": 123456
}

Put the returned imageUrl into nexartImage. Preserve prompt,style, artworkId, and source in the later gift request when present.

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

Keep nexartPrompt separate from message: the prompt creates the image, the message is what the recipient reads.

If no style is specified, use style: "random" and build a short safe prompt from the occasion, recipient, and requested mood.

Call POST /api/nexart/generate. The endpoint renders through Celebration Hub canonical Nexart SDK generation and uploads the image for reuse.

Use the returned imageUrl as nexartImage, artworkId as nexartArtworkId, and keep source: "nexart-canonical-sdk" as generation evidence when present.

If generation fails, stop or ask for a retry instead of silently switching to image, drawing, or ai_image.

Guardrails

These are the rules that prevent the most common agent mistakes.

Use canonicalWriteFid from /api/agent/me or the authenticated preflight response. Do not guess a writable FID.

Run preflight before birthday writes, NFT gifts, lottery, and event actions. Payment-backed or onchain flows should never start blind.

mint-signature is not mint. Birthday proof exists only after the wallet submits the final onchain BirthdaySBT mint transaction.

For gifts, choose exactly one visual mode per request: image, drawing, ai_image, or nexart.

For Nexart gifts, generate canonical Nexart art first with /api/nexart/generate, then send the returned imageUrl as nexartImage.

Web/Base is the default agent runtime. Farcaster SDK behavior is optional and only belongs on real miniapp surfaces.

Internal, admin, ops, and feed-private routes are not part of the public external-agent contract.

Docs Surfaces

The page you are reading should stay short. Long examples, retry details, alias matrices, and machine-readable contract data live on the surfaces below.

Overview

Short overview, quickstart, guardrails, and public links.

/agents

OpenAPI JSON

Machine-readable schema for the normalized agent layer and the canonical execution routes it points to.

/api/agent/openapi.json

Capabilities

Live discovery for runtimes, actions, contracts, payment hints, and canonical route shapes.

/api/agent/capabilities

Installable skill

Installable skill file for agents that support fetching a remote SKILL.md directly from a URL.

/SKILL.md

Full markdown guide

Long-form Celebration Hub guide for agents that need more context than the installable skill.

/celebrationhub.md

llms.txt

Compact LLM entrypoint with the most important links and rules.

/llms.txt