{"openapi":"3.0.0","info":{"title":"x-gifts API","version":"1.0.0","description":"x402-enabled gift recommendation API that analyzes social media profiles (Instagram, X, TikTok) to suggest personalized gifts. Payments are processed using the x402 protocol with USDC on Solana.","contact":{"name":"Purch","url":"https://github.com/orgs/purch-xyz/repositories"},"license":{"name":"MIT"}},"servers":[{"url":"https://x402gifts.purch.xyz","description":"API Server"}],"tags":[{"name":"gifts","description":"Gift recommendation endpoints"},{"name":"health","description":"Health check endpoints"}],"paths":{"/":{"get":{"summary":"API Information","description":"Get API metadata and available endpoints","tags":["health"],"responses":{"200":{"description":"API information","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"protocol":{"type":"string"},"documentation":{"type":"string"},"endpoints":{"type":"array"}}}}}}}}},"/health":{"get":{"summary":"Health Check","description":"Check API health status","tags":["health"],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"service":{"type":"string","example":"x-gifts"}}}}}}}}},"/gifts/suggest":{"post":{"summary":"Get Gift Suggestions","description":"Analyze a social media profile and return 3 personalized gift recommendations. Supports Instagram, X (Twitter), and TikTok profiles. Results are cached for 24 hours. Requires x402 payment of $0.10 USDC.","tags":["gifts"],"x-x402":{"price":"$0.10","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","token":"USDC","required":true},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profileUrl","platform"],"properties":{"profileUrl":{"type":"string","format":"uri","description":"Social media profile URL to analyze","example":"https://instagram.com/username"},"platform":{"type":"string","enum":["instagram","x","tiktok"],"description":"Social media platform","example":"instagram"}}}}}},"responses":{"200":{"description":"Gift recommendations returned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"username":{"type":"string","description":"Extracted username from profile","example":"techie_traveler"},"profilePicUrl":{"type":"string","format":"uri","description":"Profile picture URL (if available)"},"gifts":{"type":"array","description":"3 personalized gift recommendations","items":{"type":"object","properties":{"title":{"type":"string","description":"Product name","example":"Portable Power Bank 20000mAh"},"price":{"type":"number","description":"Price in USD","example":45.99},"image":{"type":"string","format":"uri","description":"Product image URL"},"reason":{"type":"string","description":"Why this gift matches the profile","example":"Perfect for their frequent travels and tech interests"},"asin":{"type":"string","description":"Amazon Standard Identification Number","example":"B0BSHV8MRZ"},"productUrl":{"type":"string","format":"uri","description":"Direct Amazon product URL","example":"https://www.amazon.com/dp/B0BSHV8MRZ"},"x402CheckoutUrl":{"type":"string","format":"uri","description":"x-purch checkout URL for purchasing"}}}},"interests":{"type":"array","items":{"type":"string"},"description":"Extracted interests from profile","example":["travel","photography","tech"]},"themes":{"type":"array","items":{"type":"string"},"description":"Visual/lifestyle themes detected","example":["adventure","minimalist"]},"cached":{"type":"boolean","description":"Whether result was returned from 24-hour cache"}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"402":{"description":"Payment Required (x402)","headers":{"X-PAYMENT":{"schema":{"type":"string"},"description":"x402 payment challenge"}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/gifts/trending":{"get":{"summary":"Get Trending Gifts","description":"Get trending gifts and popular interests aggregated from recent gift searches over the past 7 days. Requires x402 payment of $0.02 USDC.","tags":["gifts"],"x-x402":{"price":"$0.02","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","token":"USDC","required":true},"responses":{"200":{"description":"Trending gifts returned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"trending":{"type":"object","properties":{"gifts":{"type":"array","description":"Top 10 most recommended gifts","items":{"type":"object","properties":{"title":{"type":"string"},"price":{"type":"number"},"image":{"type":"string","format":"uri"},"reason":{"type":"string"},"asin":{"type":"string"},"productUrl":{"type":"string","format":"uri"},"x402CheckoutUrl":{"type":"string","format":"uri"},"trendingScore":{"type":"number","description":"Frequency count"}}}},"interests":{"type":"array","items":{"type":"string"},"description":"Top 10 most common interests"},"period":{"type":"string","example":"7_days","description":"Time window for analysis"},"sampleSize":{"type":"number","description":"Number of searches analyzed"}}}}}}}},"402":{"description":"Payment Required (x402)","headers":{"X-PAYMENT":{"schema":{"type":"string"},"description":"x402 payment challenge"}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}}},"externalDocs":{"description":"x402 Protocol Documentation","url":"https://docs.cdp.coinbase.com/x402"}}