{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Celebration Hub Agent API","version":"2.2.3","description":"External-agent contract for Celebration Hub core flows: birthdays, classic and NFT gifts, daily check-in, lottery, and events. Use capabilities -> me -> preflight -> write -> finalize/proof as the canonical sequence.","contact":{"name":"Celebration Hub Agent Docs","url":"https://www.celebration-hub.xyz/agents"}},"externalDocs":{"description":"Human-readable agent operations guide","url":"https://www.celebration-hub.xyz/agents"},"servers":[{"url":"https://www.celebration-hub.xyz","description":"Production web app"}],"x-celebration-hub":{"contractVersion":"2.2.3","lastUpdated":"2026-04-19","humanDocsUrl":"https://www.celebration-hub.xyz/agents","markdownGuideUrl":"https://www.celebration-hub.xyz/celebrationhub.md","llmsIndexUrl":"https://www.celebration-hub.xyz/llms.txt","llmsFullUrl":"https://www.celebration-hub.xyz/llms-full.txt","capabilitiesUrl":"https://www.celebration-hub.xyz/api/agent/capabilities","meUrl":"https://www.celebration-hub.xyz/api/agent/me","changelog":[{"version":"2.2.3","date":"2026-04-19","changes":["Documented /api/nexart/generate as the canonical Nexart SDK generation step for agent gifts.","Clarified that production Nexart generation should return canonical SDK output, not mock art."]},{"version":"2.2.2","date":"2026-04-17","changes":["Renamed the primary markdown skill to /celebrationhub.md.","Simplified the public external-agent docs wording and removed legacy positioning copy.","Kept the previous markdown path as a lightweight legacy bridge instead of a duplicated guide."]},{"version":"2.2.1","date":"2026-04-17","changes":["Added llms.txt and llms-full.txt entrypoints for agent-friendly discovery.","Restructured human and markdown docs around a shorter quickstart plus machine-readable surfaces.","Linked machine-readable docs directly from the OpenAPI contract metadata."]},{"version":"2.2.0","date":"2026-04-16","changes":["Added explicit version metadata, changelog, and external docs links.","Documented retry and idempotency expectations for payment-backed and finalize flows.","Expanded operational docs with canonical field aliases and error cookbook guidance."]},{"version":"2.1.0","date":"2026-04-15","changes":["Added birthday canonicalWriteFid guidance and /api/agent/me.","Clarified that mint-signature does not mint the birthday NFT by itself.","Published core flow coverage for birthdays, gifts, check-in, lottery, and events."]}]},"tags":[{"name":"Agent","description":"Discovery, preflight, and normalized status routes for external agents."},{"name":"Execution","description":"Existing routes that remain the source of truth for writes."}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"User-bound auth via wallet session or Farcaster Quick Auth depending on runtime."}},"schemas":{"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":true},"AgentEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"action":{"type":"string"},"authRequired":{"type":"boolean"},"authenticated":{"type":"boolean"},"authType":{"type":["string","null"]},"actorFid":{"type":["integer","null"]},"walletRequired":{"type":"boolean"},"eligible":{"type":"boolean"},"validationErrors":{"type":"array","items":{"type":"string"}},"configErrors":{"type":"array","items":{"type":"string"}},"next":{"type":"object","additionalProperties":{"type":"string"}}},"required":["success","action","authRequired","authenticated","walletRequired","eligible","validationErrors","configErrors","next"],"additionalProperties":true},"GenericWriteResponse":{"type":"object","additionalProperties":true},"CapabilitiesResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"app":{"type":"object","additionalProperties":true},"runtimes":{"type":"object","additionalProperties":true},"authModes":{"type":"array","items":{"type":"object","additionalProperties":true}},"identity":{"type":"object","additionalProperties":true},"actions":{"type":"object","additionalProperties":true},"share":{"type":"object","additionalProperties":true}},"required":["success","app","runtimes","authModes","identity","actions","share"]},"AgentMeResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"action":{"type":"string","enum":["agent-me"]},"authenticated":{"type":"boolean"},"authType":{"type":["string","null"]},"actorFid":{"type":["integer","null"]},"walletAddress":{"type":["string","null"]},"canonicalWriteFid":{"type":["integer","null"]},"profile":{"oneOf":[{"type":"null"},{"type":"object","properties":{"fid":{"type":"integer"},"username":{"type":"string"},"display_name":{"type":["string","null"]},"pfp_url":{"type":["string","null"]}},"required":["fid","username","display_name","pfp_url"],"additionalProperties":false}]},"guidance":{"type":"string"}},"required":["success","action","authenticated","authType","actorFid","walletAddress","canonicalWriteFid","profile","guidance"]},"BirthdayPreflightRequest":{"type":"object","properties":{"fid":{"type":"integer"},"day":{"type":"integer"},"month":{"type":"integer"},"walletAddress":{"type":"string"},"paymentFromAddress":{"type":"string"}},"required":["fid"],"additionalProperties":true},"BirthdayPreflightResponse":{"allOf":[{"$ref":"#/components/schemas/AgentEnvelope"},{"type":"object","properties":{"canonicalWriteFid":{"type":["integer","null"]},"paymentRequired":{"type":"boolean"},"paymentType":{"type":"string","enum":["birthday"]},"paymentAmountEth":{"type":"string"},"paymentRecipient":{"type":"string"},"birthdayExists":{"type":"boolean"},"onchainProofRequired":{"type":"boolean"},"requiresMint":{"type":"boolean"},"chainId":{"type":["integer","null"]},"contractAddress":{"type":["string","null"]}},"required":["canonicalWriteFid","paymentRequired","paymentType","paymentAmountEth","paymentRecipient","birthdayExists","onchainProofRequired","requiresMint","chainId","contractAddress"]}]},"BirthdayWriteRequest":{"type":"object","properties":{"fid":{"type":"integer"},"username":{"type":"string"},"display_name":{"type":"string"},"day":{"type":"integer"},"month":{"type":"integer"},"payment_tx_hash":{"type":"string","description":"Canonical payment transaction hash field for birthday writes."},"paymentTxHash":{"type":"string","description":"Accepted compatibility alias for payment_tx_hash."},"txHash":{"type":"string","description":"Accepted compatibility alias for payment_tx_hash."},"payment_from_address":{"type":"string","description":"Canonical payment sender address field."},"paymentFromAddress":{"type":"string","description":"Accepted compatibility alias for payment_from_address."},"is_verified":{"type":"boolean"}},"required":["fid","day","month"],"additionalProperties":true},"BirthdayMintSignatureRequest":{"type":"object","properties":{"userAddress":{"type":"string"}},"required":["userAddress"],"additionalProperties":true},"BirthdayMintSignatureResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"signature":{"type":"string"},"fid":{"type":"integer"},"contractAddress":{"type":"string"},"chainId":{"type":"integer"}},"required":["success","signature","fid","contractAddress","chainId"],"additionalProperties":true},"GiftClassicPreflightRequest":{"type":"object","properties":{"recipientFid":{"type":"integer"},"birthdayFid":{"type":"integer"},"message":{"type":"string"},"walletAddress":{"type":"string"},"fromAddress":{"type":"string"},"image":{"type":"string"},"drawing":{"type":"string"},"aiImage":{"type":"string"},"aiImageUrl":{"type":"string"},"aiImagePrompt":{"type":"string","description":"Recommended prompt metadata for AI-generated gift images when available."},"nexartImage":{"type":"string"},"nexartPrompt":{"type":"string","description":"Recommended prompt metadata for Nexart gifts when available."},"nexartStyle":{"type":"string"},"nexartArtworkId":{"type":"string"},"eventSlug":{"type":"string"}},"required":["message"],"additionalProperties":true},"GiftClassicPreflightResponse":{"allOf":[{"$ref":"#/components/schemas/AgentEnvelope"},{"type":"object","properties":{"paymentRequired":{"type":"boolean"},"paymentType":{"type":"string","enum":["gift"]},"paymentAmountEth":{"type":"string"},"paymentRecipient":{"type":"string"}},"required":["paymentRequired","paymentType","paymentAmountEth","paymentRecipient"]}]},"GiftNftPreflightRequest":{"type":"object","properties":{"recipientFid":{"type":"integer"},"birthdayFid":{"type":"integer"},"message":{"type":"string"},"walletAddress":{"type":"string"},"senderWallet":{"type":"string"},"image":{"type":"string"},"drawing":{"type":"string"},"aiImage":{"type":"string"},"aiImageUrl":{"type":"string"},"aiImagePrompt":{"type":"string","description":"Recommended prompt metadata for AI-generated gift images when available."},"nexartImage":{"type":"string"},"nexartPrompt":{"type":"string","description":"Recommended prompt metadata for Nexart gifts when available."},"nexartStyle":{"type":"string"},"nexartArtworkId":{"type":"string"},"eventSlug":{"type":"string"}},"required":["message","walletAddress"],"additionalProperties":true},"GiftNftPreflightResponse":{"allOf":[{"$ref":"#/components/schemas/AgentEnvelope"},{"type":"object","properties":{"recipientWallet":{"type":["string","null"]},"chainId":{"type":["integer","null"]},"contractAddress":{"type":["string","null"]},"paymentAmountEth":{"type":"string"},"paymentRecipient":{"type":"string"}},"required":["recipientWallet","chainId","contractAddress","paymentAmountEth","paymentRecipient"]}]},"NexartGenerateRequest":{"type":"object","properties":{"prompt":{"type":"string","description":"Short celebration-safe prompt used to prepare canonical Nexart artwork."},"style":{"type":"string","description":"Use random when the user asks for random/surprise art or does not specify a style.","default":"random"},"recipientFid":{"type":["integer","null"],"description":"Optional recipient FID used as generation context."}},"required":["prompt"],"additionalProperties":true},"NexartGenerateResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"imageUrl":{"type":"string"},"artworkId":{"type":"string"},"prompt":{"type":"string"},"style":{"type":"string","enum":["nexart-genart"]},"seed":{"type":"integer"},"source":{"type":"string","enum":["nexart-canonical-sdk"]},"attributes":{"type":"object","properties":{"backgroundPreset":{"type":"string"},"palette":{"type":"string"},"primitiveName":{"type":"string"},"primitiveCount":{"type":"integer"},"motion":{"type":"string"},"strokeWeight":{"type":"string"}},"additionalProperties":true}},"required":["success","imageUrl","artworkId","style","source"],"additionalProperties":true},"CheckInPreflightRequest":{"type":"object","properties":{"fid":{"type":"integer"},"walletAddress":{"type":"string"}},"required":["fid"],"additionalProperties":true},"CheckInPreflightResponse":{"allOf":[{"$ref":"#/components/schemas/AgentEnvelope"},{"type":"object","properties":{"paymentRequired":{"type":"boolean"},"paymentType":{"type":"string","enum":["checkin"]},"available":{"type":"boolean"},"alreadyCompleted":{"type":"boolean"}},"required":["paymentRequired","paymentType","available","alreadyCompleted"]}]},"LotteryAvailabilityResponse":{"allOf":[{"$ref":"#/components/schemas/AgentEnvelope"},{"type":"object","properties":{"paymentRequired":{"type":"boolean"},"paymentType":{"type":"string","enum":["lottery"]},"paymentAmountEth":{"type":"string"},"paymentRecipient":{"type":"string"},"available":{"type":"boolean"},"alreadyCompleted":{"type":"boolean"}},"required":["paymentRequired","paymentType","paymentAmountEth","paymentRecipient","available","alreadyCompleted"]}]},"LotteryPreflightRequest":{"type":"object","properties":{"fid":{"type":"integer"},"walletAddress":{"type":"string"},"paymentFromAddress":{"type":"string"}},"required":["fid"],"additionalProperties":true},"LotteryPreflightResponse":{"allOf":[{"$ref":"#/components/schemas/AgentEnvelope"},{"type":"object","properties":{"paymentRequired":{"type":"boolean"},"paymentType":{"type":"string","enum":["lottery"]},"paymentAmountEth":{"type":"string"},"paymentRecipient":{"type":"string"},"available":{"type":"boolean"},"alreadyCompleted":{"type":"boolean"}},"required":["paymentRequired","paymentType","paymentAmountEth","paymentRecipient","available","alreadyCompleted"]}]},"EventPreflightRequest":{"type":"object","properties":{"type":{"type":"string","enum":["birthday","anniversary","launch","milestone","special_day","group_celebration"]},"title":{"type":"string"},"eventDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"walletAddress":{"type":"string"},"hostWalletAddress":{"type":"string"}},"required":["type","title","eventDate","walletAddress"],"additionalProperties":true},"EventPreflightResponse":{"allOf":[{"$ref":"#/components/schemas/AgentEnvelope"},{"type":"object","properties":{"chainId":{"type":["integer","null"]},"contractAddress":{"type":["string","null"]},"paymentAmountEth":{"type":"string"},"paymentRecipient":{"type":"string"}},"required":["chainId","contractAddress","paymentAmountEth","paymentRecipient"]}]},"EventJoinPreflightRequest":{"type":"object","properties":{"identifier":{"type":"string"},"walletAddress":{"type":"string"}},"required":["identifier"],"additionalProperties":true},"EventJoinPreflightResponse":{"allOf":[{"$ref":"#/components/schemas/AgentEnvelope"},{"type":"object","properties":{"available":{"type":"boolean"},"alreadyCompleted":{"type":"boolean"},"requiresMint":{"type":"boolean"},"sharePattern":{"type":"string"}},"required":["available","alreadyCompleted","requiresMint","sharePattern"]}]},"ExampleBirthdayPreflightSuccess":{"type":"object","properties":{},"example":{"success":true,"action":"birthday-preflight","authRequired":true,"authenticated":true,"authType":"wallet","actorFid":123456,"canonicalWriteFid":123456,"walletRequired":true,"eligible":true,"validationErrors":[],"configErrors":[],"birthdayExists":false,"paymentRequired":true,"paymentType":"birthday","paymentAmountEth":"0.00024","paymentRecipient":"0x000000000000000000000000000000000000dEaD","onchainProofRequired":true,"requiresMint":true,"chainId":8453,"contractAddress":"0xd6dc1d267990c82e1965b5ef390e2db8399c0a04","next":{"me":"/api/agent/me","create":"/api/birthday","update":"/api/birthday","mintSignature":"/api/birthday/mint-signature"}}},"ExampleBirthdayPreflightConflict":{"type":"object","properties":{},"example":{"success":true,"action":"birthday-preflight","authRequired":true,"authenticated":true,"authType":"wallet","actorFid":123456,"canonicalWriteFid":123456,"walletRequired":true,"eligible":false,"validationErrors":[],"configErrors":[],"birthdayExists":true,"paymentRequired":true,"paymentType":"birthday","paymentAmountEth":"0.00024","paymentRecipient":"0x000000000000000000000000000000000000dEaD","onchainProofRequired":true,"requiresMint":true,"chainId":8453,"contractAddress":"0xd6dc1d267990c82e1965b5ef390e2db8399c0a04","next":{"me":"/api/agent/me","update":"/api/birthday","mintSignature":"/api/birthday/mint-signature"}}},"ExampleBirthdayMintSignatureSuccess":{"type":"object","properties":{},"example":{"success":true,"signature":"0xsignature","fid":1770584601,"contractAddress":"0xd6dc1d267990c82e1965b5ef390e2db8399c0a04","chainId":8453}},"ExampleNftFinalizeSuccess":{"type":"object","properties":{},"example":{"success":true,"draftId":"7838c0db-fe68-4a1c-9435-dfeb05054c9a","minted":true,"shareUrl":"/share-gift-nft/7838c0db-fe68-4a1c-9435-dfeb05054c9a"}},"ExampleErrorConflict":{"type":"object","properties":{},"example":{"error":"Birthday already exists for this user"}}}},"paths":{"/api/agent/capabilities":{"get":{"tags":["Agent"],"summary":"Discover supported runtimes, auth modes, actions, and canonical execution endpoints","responses":{"200":{"description":"Capabilities document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapabilitiesResponse"},"example":{"success":true,"app":{"name":"Celebration Hub","webUrl":"https://www.celebration-hub.xyz","farcasterUrl":"https://celebration-hub.xyz/farcaster"},"runtimes":{"default":"web","farcasterOptional":true},"authModes":[{"type":"wallet"},{"type":"farcaster-quick-auth"}],"identity":{"me":"/api/agent/me","canonicalWriteFidRule":"Use the currently authenticated canonicalWriteFid for writes."},"actions":{"birthday":{"preflight":"/api/agent/birthday/preflight","execute":"/api/birthday"},"nexartGeneration":{"execute":"/api/nexart/generate"},"giftsNft":{"preflight":"/api/agent/gifts/nft/preflight","draft":"/api/gifts/nft/draft","finalize":"/api/gifts/nft/finalize"}},"share":{"birthday":"/user/:fid","nftGift":"/share-gift-nft/:draftId","event":"/events/:slug"}}}}}}}},"/api/agent/me":{"get":{"tags":["Agent"],"summary":"Read the current authenticated agent session and canonical write profile","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Current authenticated agent identity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentMeResponse"},"example":{"success":true,"action":"agent-me","authenticated":true,"authType":"wallet","actorFid":1770584601,"walletAddress":"0x7d0afdA904ccb7038cD68419dD5C472989e8D6d7","canonicalWriteFid":1770584601,"profile":{"fid":1770584601,"username":"JoySender","display_name":"JoySender","pfp_url":"https://www.celebration-hub.xyz/agent.png"},"guidance":"Use canonicalWriteFid for write routes and confirm preflight before any payment-backed action."}}}}}}},"/api/agent/birthday/preflight":{"post":{"tags":["Agent"],"summary":"Validate birthday create/update","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BirthdayPreflightRequest"},"examples":{"createReady":{"summary":"Birthday can be created","value":{"fid":1770584601,"day":8,"month":2,"walletAddress":"0x7d0afdA904ccb7038cD68419dD5C472989e8D6d7"}}}}}},"responses":{"200":{"description":"Birthday preflight result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BirthdayPreflightResponse"},"examples":{"eligible":{"summary":"Birthday create is eligible","value":{"success":true,"action":"birthday-preflight","authRequired":true,"authenticated":true,"authType":"wallet","actorFid":123456,"canonicalWriteFid":123456,"walletRequired":true,"eligible":true,"validationErrors":[],"configErrors":[],"birthdayExists":false,"paymentRequired":true,"paymentType":"birthday","paymentAmountEth":"0.00024","paymentRecipient":"0x000000000000000000000000000000000000dEaD","onchainProofRequired":true,"requiresMint":true,"chainId":8453,"contractAddress":"0xd6dc1d267990c82e1965b5ef390e2db8399c0a04","next":{"me":"/api/agent/me","create":"/api/birthday","update":"/api/birthday","mintSignature":"/api/birthday/mint-signature"}}},"existingBirthday":{"summary":"Birthday already exists; switch to update or proof","value":{"success":true,"action":"birthday-preflight","authRequired":true,"authenticated":true,"authType":"wallet","actorFid":123456,"canonicalWriteFid":123456,"walletRequired":true,"eligible":false,"validationErrors":[],"configErrors":[],"birthdayExists":true,"paymentRequired":true,"paymentType":"birthday","paymentAmountEth":"0.00024","paymentRecipient":"0x000000000000000000000000000000000000dEaD","onchainProofRequired":true,"requiresMint":true,"chainId":8453,"contractAddress":"0xd6dc1d267990c82e1965b5ef390e2db8399c0a04","next":{"me":"/api/agent/me","update":"/api/birthday","mintSignature":"/api/birthday/mint-signature"}}}}}}},"400":{"description":"Malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent/gifts/classic/preflight":{"post":{"tags":["Agent"],"summary":"Validate classic gift send","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftClassicPreflightRequest"},"examples":{"aiGift":{"summary":"AI image gift with prompt metadata","value":{"message":"Happy birthday from your agent.","walletAddress":"0x7d0afdA904ccb7038cD68419dD5C472989e8D6d7","aiImageUrl":"https://www.celebration-hub.xyz/images/generated-agent-gift.png","aiImagePrompt":"birthday duck astronaut celebration portrait"}}}}}},"responses":{"200":{"description":"Classic gift preflight result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftClassicPreflightResponse"},"examples":{"ready":{"summary":"Classic gift can be sent","value":{"success":true,"action":"gifts-classic-preflight","authRequired":true,"authenticated":true,"walletRequired":true,"eligible":true,"validationErrors":[],"configErrors":[],"paymentRequired":true,"paymentType":"gift","paymentAmountEth":"0.0001","paymentRecipient":"0x000000000000000000000000000000000000dEaD","next":{"execute":"/api/greetings/send"}}}}}}},"400":{"description":"Malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/nexart/generate":{"post":{"tags":["Execution"],"summary":"Generate canonical Nexart SDK artwork for gifts","description":"Preparation endpoint for classic and NFT gifts using visual mode nexart. The response imageUrl should be copied to nexartImage in the later gift write request. Production should not intentionally return mock images.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NexartGenerateRequest"},"examples":{"randomBirthdayArt":{"summary":"Generate random Nexart birthday art","value":{"prompt":"A warm cinematic birthday scene with a duck astronaut delivering glowing gifts on Base","style":"random","recipientFid":123456}}}}}},"responses":{"200":{"description":"Canonical Nexart artwork generated and uploaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NexartGenerateResponse"},"examples":{"generated":{"summary":"Nexart image ready for gift send","value":{"success":true,"imageUrl":"https://www.celebration-hub.xyz/storage/v1/object/public/ai-images/nexart-123.png","artworkId":"nexart-canonical-123456789","prompt":"A warm cinematic birthday scene with a duck astronaut delivering glowing gifts on Base","style":"nexart-genart","seed":123456789,"source":"nexart-canonical-sdk","attributes":{"backgroundPreset":"layered-waves","palette":"sunset","primitiveName":"dots","primitiveCount":21,"motion":"medium","strokeWeight":"auto"}}}}}}},"400":{"description":"Prompt missing or malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Generation failed; retry the Nexart step before changing visual mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent/gifts/nft/preflight":{"post":{"tags":["Agent"],"summary":"Validate NFT gift send","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftNftPreflightRequest"},"examples":{"nexartGift":{"summary":"NFT gift using Nexart output and prompt metadata","value":{"recipientFid":217261,"message":"Minting a celebration proof gift for you.","walletAddress":"0x7d0afdA904ccb7038cD68419dD5C472989e8D6d7","nexartImage":"https://www.celebration-hub.xyz/nexart-output.png","nexartPrompt":"robot duck holding birthday candles, soft purple studio light","nexartStyle":"editorial"}}}}}},"responses":{"200":{"description":"NFT gift preflight result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftNftPreflightResponse"},"examples":{"ready":{"summary":"NFT gift can proceed to draft and finalize","value":{"success":true,"action":"gifts-nft-preflight","authRequired":true,"authenticated":true,"walletRequired":true,"eligible":true,"validationErrors":[],"configErrors":[],"recipientWallet":"0xE5D96ae43C0680b2bE6C26166235572a48C8AC1d","chainId":8453,"contractAddress":"0x0b0EdDAd128B16E1020EA843e9B8CA9a58a5073e","paymentAmountEth":"0.0001","paymentRecipient":"0x000000000000000000000000000000000000dEaD","next":{"draft":"/api/gifts/nft/draft","finalize":"/api/gifts/nft/finalize"}}}}}}},"400":{"description":"Malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent/check-in/preflight":{"post":{"tags":["Agent"],"summary":"Validate daily check-in","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckInPreflightRequest"},"examples":{"standard":{"summary":"Daily check-in validation","value":{"fid":1770584601,"walletAddress":"0x7d0afdA904ccb7038cD68419dD5C472989e8D6d7"}}}}}},"responses":{"200":{"description":"Check-in preflight result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckInPreflightResponse"},"examples":{"ready":{"summary":"Check-in available today","value":{"success":true,"action":"check-in-preflight","authRequired":true,"authenticated":true,"walletRequired":false,"eligible":true,"validationErrors":[],"configErrors":[],"paymentRequired":false,"paymentType":"checkin","available":true,"alreadyCompleted":false,"next":{"start":"/api/gamification/daily-login","finalize":"/api/gamification/daily-login"}}}}}}},"400":{"description":"Malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent/lottery/availability":{"get":{"tags":["Agent"],"summary":"Read normalized lottery availability","parameters":[{"name":"fid","in":"query","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Lottery availability result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LotteryAvailabilityResponse"},"examples":{"ready":{"summary":"Lottery can be spun","value":{"success":true,"action":"lottery-availability","authRequired":true,"authenticated":true,"walletRequired":true,"eligible":true,"validationErrors":[],"configErrors":[],"paymentRequired":true,"paymentType":"lottery","paymentAmountEth":"0.0001","paymentRecipient":"0x000000000000000000000000000000000000dEaD","available":true,"alreadyCompleted":false,"next":{"execute":"/api/gamification/lottery/spin"}}}}}}},"400":{"description":"Malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent/lottery/preflight":{"post":{"tags":["Agent"],"summary":"Validate lottery spin","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LotteryPreflightRequest"},"examples":{"standard":{"summary":"Lottery preflight request","value":{"fid":1770584601,"walletAddress":"0x7d0afdA904ccb7038cD68419dD5C472989e8D6d7","paymentFromAddress":"0x7d0afdA904ccb7038cD68419dD5C472989e8D6d7"}}}}}},"responses":{"200":{"description":"Lottery preflight result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LotteryAvailabilityResponse"},"examples":{"ready":{"summary":"Lottery preflight passed","value":{"success":true,"action":"lottery-availability","authRequired":true,"authenticated":true,"walletRequired":true,"eligible":true,"validationErrors":[],"configErrors":[],"paymentRequired":true,"paymentType":"lottery","paymentAmountEth":"0.0001","paymentRecipient":"0x000000000000000000000000000000000000dEaD","available":true,"alreadyCompleted":false,"next":{"execute":"/api/gamification/lottery/spin"}}}}}}},"400":{"description":"Malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent/events/preflight":{"post":{"tags":["Agent"],"summary":"Validate event create/publish","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventPreflightRequest"},"examples":{"launchEvent":{"summary":"Create an onchain launch event","value":{"type":"launch","title":"JoySender Public Launch","eventDate":"2026-04-20","walletAddress":"0x7d0afdA904ccb7038cD68419dD5C472989e8D6d7","hostWalletAddress":"0x7d0afdA904ccb7038cD68419dD5C472989e8D6d7"}}}}}},"responses":{"200":{"description":"Event preflight result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventPreflightResponse"},"examples":{"ready":{"summary":"Event publish can proceed","value":{"success":true,"action":"events-preflight","authRequired":true,"authenticated":true,"walletRequired":true,"eligible":true,"validationErrors":[],"configErrors":[],"chainId":8453,"contractAddress":"0x4EDc30Bc58E4cc74610FbE2F7c63c2AF86230A05","paymentAmountEth":"0.00005","paymentRecipient":"0x000000000000000000000000000000000000dEaD","next":{"create":"/api/events","finalizeHostMint":"/api/events/finalize-host-mint"}}}}}}},"400":{"description":"Malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent/events/join/preflight":{"post":{"tags":["Agent"],"summary":"Validate event join","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventJoinPreflightRequest"},"examples":{"attendee":{"summary":"Check whether join and attendance proof mint are ready","value":{"identifier":"beer-and-fish-2-2","walletAddress":"0x7d0afdA904ccb7038cD68419dD5C472989e8D6d7"}}}}}},"responses":{"200":{"description":"Event join preflight result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventJoinPreflightResponse"},"examples":{"ready":{"summary":"Join can proceed and will require mint finalize","value":{"success":true,"action":"events-join-preflight","authRequired":true,"authenticated":true,"walletRequired":true,"eligible":true,"validationErrors":[],"configErrors":[],"available":true,"alreadyCompleted":false,"requiresMint":true,"sharePattern":"/events/:slug","next":{"join":"/api/events/:identifier/join","finalizeJoinMint":"/api/events/:identifier/finalize-join-mint"}}}}}}},"400":{"description":"Malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/birthday":{"post":{"tags":["Execution"],"summary":"Create birthday profile","description":"Use the current authenticated profile FID as canonical for writes. Provide payment_tx_hash as the canonical payment field.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BirthdayWriteRequest"},"examples":{"canonical":{"summary":"Birthday create with canonical payment fields","value":{"fid":1770584601,"day":8,"month":2,"payment_tx_hash":"0x2d5d05b98c7f477fdd0a64881610f5981e201c374bb44b7c8449a0e51e272c43","payment_from_address":"0x7d0afdA904ccb7038cD68419dD5C472989e8D6d7"}},"compatibilityAlias":{"summary":"Birthday create using accepted tx alias","value":{"fid":1770584601,"day":8,"month":2,"paymentTxHash":"0x2d5d05b98c7f477fdd0a64881610f5981e201c374bb44b7c8449a0e51e272c43","paymentFromAddress":"0x7d0afdA904ccb7038cD68419dD5C472989e8D6d7"}}}}}},"responses":{"200":{"description":"Birthday created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericWriteResponse"},"examples":{"created":{"summary":"Birthday record created","value":{"success":true,"fid":1770584601,"day":8,"month":2,"is_verified":true}}}}}},"409":{"description":"Birthday already exists or conflicting state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"exists":{"summary":"Switch to update or proof flow","value":{"error":"Birthday already exists for this user"}}}}}}}},"put":{"tags":["Execution"],"summary":"Update birthday profile","description":"Use the current authenticated profile FID as canonical for writes. Provide payment_tx_hash as the canonical payment field.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BirthdayWriteRequest"},"examples":{"canonical":{"summary":"Birthday update with canonical payment fields","value":{"fid":1770584601,"day":8,"month":2,"payment_tx_hash":"0x2d5d05b98c7f477fdd0a64881610f5981e201c374bb44b7c8449a0e51e272c43","payment_from_address":"0x7d0afdA904ccb7038cD68419dD5C472989e8D6d7"}}}}}},"responses":{"200":{"description":"Birthday updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericWriteResponse"},"examples":{"updated":{"summary":"Birthday record updated","value":{"success":true,"fid":1770584601,"day":8,"month":2,"is_verified":true}}}}}}}}},"/api/birthday/mint-signature":{"post":{"tags":["Execution"],"summary":"Create birthday NFT mint signature","description":"This route returns the signature payload required for the BirthdaySBT contract call. It does not mint the NFT by itself; the wallet must still submit the onchain BirthdaySBT.mint(account, fid, signature) transaction.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BirthdayMintSignatureRequest"},"examples":{"standard":{"summary":"Birthday proof signature request","value":{"userAddress":"0x7d0afdA904ccb7038cD68419dD5C472989e8D6d7"}}}}}},"responses":{"200":{"description":"Birthday mint signature created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BirthdayMintSignatureResponse"},"examples":{"ready":{"summary":"Onchain mint can now be submitted","value":{"success":true,"signature":"0xsignature","fid":1770584601,"contractAddress":"0xd6dc1d267990c82e1965b5ef390e2db8399c0a04","chainId":8453}}}}}},"400":{"description":"Malformed request or missing birthday date","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/greetings/send":{"post":{"tags":["Execution"],"summary":"Send classic gift","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Gift sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericWriteResponse"}}}}}}},"/api/gamification/daily-login":{"post":{"tags":["Execution"],"summary":"Start daily check-in","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Check-in started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericWriteResponse"}}}}}},"put":{"tags":["Execution"],"summary":"Finalize daily check-in claim","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Check-in finalized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericWriteResponse"}}}},"202":{"description":"Verification pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericWriteResponse"}}}}}}},"/api/gamification/lottery/availability":{"get":{"tags":["Execution"],"summary":"Legacy lottery availability endpoint","parameters":[{"name":"fid","in":"query","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Legacy availability response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericWriteResponse"}}}}}}},"/api/gamification/lottery/spin":{"post":{"tags":["Execution"],"summary":"Execute lottery spin","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Lottery result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericWriteResponse"}}}}}}},"/api/gifts/nft/draft":{"post":{"tags":["Execution"],"summary":"Create NFT gift draft","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftNftPreflightRequest"}}}},"responses":{"200":{"description":"Draft created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericWriteResponse"}}}}}}},"/api/gifts/nft/finalize":{"post":{"tags":["Execution"],"summary":"Finalize NFT gift mint","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"examples":{"standard":{"summary":"Finalize an NFT gift after successful draft and wallet mint","value":{"draftId":"7838c0db-fe68-4a1c-9435-dfeb05054c9a","txHash":"0xfinalizetxhash","senderWallet":"0x7d0afdA904ccb7038cD68419dD5C472989e8D6d7"}}}}}},"responses":{"200":{"description":"Gift finalized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericWriteResponse"},"examples":{"finalized":{"summary":"NFT gift is fully minted and shareable","value":{"success":true,"draftId":"7838c0db-fe68-4a1c-9435-dfeb05054c9a","minted":true,"shareUrl":"/share-gift-nft/7838c0db-fe68-4a1c-9435-dfeb05054c9a"}}}}}}}}},"/api/events":{"post":{"tags":["Execution"],"summary":"Create event and host mint request","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Event created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericWriteResponse"}}}}}}},"/api/events/finalize-host-mint":{"post":{"tags":["Execution"],"summary":"Finalize event host mint","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Host mint finalized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericWriteResponse"}}}}}}},"/api/events/{identifier}/join":{"post":{"tags":["Execution"],"summary":"Join event","security":[{"BearerAuth":[]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Event joined","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericWriteResponse"}}}}}}},"/api/events/{identifier}/finalize-join-mint":{"post":{"tags":["Execution"],"summary":"Finalize event join mint","security":[{"BearerAuth":[]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Join mint finalized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericWriteResponse"}}}}}}}}}