{"openapi":"3.0.0","info":{"version":"0.1.10","title":"Grapevine API","description":"Decentralized data feeds platform API for creating, managing, and monetizing content feeds using IPFS storage and x402 micropayments on Base blockchain. Supports both free and paid content with wallet-based authentication."},"servers":[{"url":"https://api.grapevine.fyi","description":"v1 production grapevine API"}],"tags":[{"name":"Authentication","description":"Wallet signature authentication endpoints for MetaMask, WalletConnect, and other Web3 wallets"},{"name":"Feeds","description":"Data feed management endpoints including creation, updates, entries, and IPFS content uploads"},{"name":"Transactions","description":"x402 payment transaction endpoints for querying blockchain transaction records"},{"name":"Categories","description":"Pre-defined category taxonomy endpoints for feed organization"},{"name":"Wallets","description":"Wallet profile and statistics endpoints"},{"name":"Leaderboards","description":"Gamification and ranking endpoints for trending feeds, top providers, top buyers, and category statistics"}],"components":{"schemas":{},"parameters":{}},"paths":{"/v1/auth/nonce":{"post":{"summary":"Generate authentication nonce","description":"Generate a nonce for wallet signature authentication. The nonce expires after 5 minutes and can only be used once.","tags":["Authentication"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"wallet_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum wallet address (0x prefixed)"}},"required":["wallet_address"]}}}},"responses":{"200":{"description":"Nonce generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"nonce":{"type":"string","description":"Random nonce to be included in signature message"},"message":{"type":"string","description":"Complete message to sign with wallet"},"expiresAt":{"type":"number","description":"Unix timestamp (milliseconds) when nonce expires"}},"required":["nonce","message","expiresAt"]}}}},"400":{"description":"Invalid wallet address format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/v1/wallets/{wallet_id}":{"get":{"tags":["Wallets"],"summary":"Get wallet by ID","description":"Retrieve detailed information about a specific wallet by its unique identifier","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"wallet_id","in":"path"}],"responses":{"200":{"description":"Wallet details","content":{"application/json":{"schema":{"type":"object","properties":{"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"id":{"type":"string","format":"uuid"},"wallet_address":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"wallet_address_network":{"type":"string","enum":["base","base-sepolia","ethereum","ethereum-sepolia","polygon","polygon-amoy"]},"username":{"type":"string","nullable":true,"minLength":3,"maxLength":50},"picture_url":{"type":"string","nullable":true,"maxLength":2048}},"required":["created_at","updated_at","id","wallet_address","wallet_address_network","username","picture_url"]}}}},"404":{"description":"Wallet not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}},"patch":{"tags":["Wallets"],"summary":"Update wallet","description":"Update wallet properties including username and picture_url. Users can only update their own wallet. Requires wallet authentication via x-auth headers.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"wallet_id","in":"path"},{"schema":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$","description":"Ethereum wallet address (0x prefixed)","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"},"required":true,"description":"Ethereum wallet address (0x prefixed)","name":"x-wallet-address","in":"header"},{"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]+$","description":"Cryptographic signature (hex format)","example":"0x..."},"required":true,"description":"Cryptographic signature (hex format)","name":"x-signature","in":"header"},{"schema":{"type":"string","description":"The signed message (base64 encoded if it contains newlines)","example":"R3JhcGV2aW5lIEF1dGhlbnRpY2F0aW9u..."},"required":true,"description":"The signed message (base64 encoded if it contains newlines)","name":"x-message","in":"header"},{"schema":{"type":"string","description":"Unix timestamp in seconds","example":"1735689600"},"required":true,"description":"Unix timestamp in seconds","name":"x-timestamp","in":"header"},{"schema":{"type":"string","description":"Chain ID for network detection (optional). Supported: 8453 (base), 84532 (base-sepolia), 1 (ethereum), 11155111 (ethereum-sepolia), 137 (polygon), 80002 (polygon-amoy)","example":"8453"},"required":false,"description":"Chain ID for network detection (optional). Supported: 8453 (base), 84532 (base-sepolia), 1 (ethereum), 11155111 (ethereum-sepolia), 137 (polygon), 80002 (polygon-amoy)","name":"x-chain-id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","maxLength":50},"picture_url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Wallet updated","content":{"application/json":{"schema":{"type":"object","properties":{"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"id":{"type":"string","format":"uuid"},"wallet_address":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"wallet_address_network":{"type":"string","enum":["base","base-sepolia","ethereum","ethereum-sepolia","polygon","polygon-amoy"]},"username":{"type":"string","nullable":true,"minLength":3,"maxLength":50},"picture_url":{"type":"string","nullable":true,"maxLength":2048}},"required":["created_at","updated_at","id","wallet_address","wallet_address_network","username","picture_url"]}}}},"401":{"description":"Unauthorized - signature verification failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"403":{"description":"Forbidden - you can only update your own wallet","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"404":{"description":"Wallet not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/wallets/address/{address}":{"get":{"tags":["Wallets"],"summary":"Get wallet by address","description":"Retrieve detailed information about a specific wallet by its Ethereum wallet address (0x-prefixed, 42 characters)","parameters":[{"schema":{"type":"string","minLength":42,"maxLength":42},"required":true,"name":"address","in":"path"}],"responses":{"200":{"description":"Wallet details","content":{"application/json":{"schema":{"type":"object","properties":{"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"id":{"type":"string","format":"uuid"},"wallet_address":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"wallet_address_network":{"type":"string","enum":["base","base-sepolia","ethereum","ethereum-sepolia","polygon","polygon-amoy"]},"username":{"type":"string","nullable":true,"minLength":3,"maxLength":50},"picture_url":{"type":"string","nullable":true,"maxLength":2048}},"required":["created_at","updated_at","id","wallet_address","wallet_address_network","username","picture_url"]}}}},"404":{"description":"Wallet not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/wallets/{wallet_id}/stats":{"get":{"tags":["Wallets"],"description":"Retrieve comprehensive statistics for a specific wallet including provider and buyer metrics","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"wallet_id","in":"path"}],"responses":{"200":{"description":"Wallet statistics","content":{"application/json":{"schema":{"type":"object","properties":{"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"wallet_id":{"type":"string","format":"uuid"},"total_feeds_created":{"type":"integer","minimum":0},"total_entries_published":{"type":"integer","minimum":0},"total_revenue_earned":{"type":"string","maxLength":78},"total_items_sold":{"type":"integer","minimum":0},"unique_buyers_count":{"type":"integer","minimum":0},"total_purchases_made":{"type":"integer","minimum":0},"total_amount_spent":{"type":"string","maxLength":78},"unique_feeds_purchased_from":{"type":"integer","minimum":0},"revenue_rank":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"purchases_rank":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"last_calculated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["created_at","updated_at","wallet_id","total_feeds_created","total_entries_published","total_revenue_earned","total_items_sold","unique_buyers_count","total_purchases_made","total_amount_spent","unique_feeds_purchased_from","revenue_rank","purchases_rank","last_calculated_at"]}}}},"404":{"description":"Wallet stats not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/categories":{"get":{"tags":["Categories"],"summary":"List categories","description":"Retrieve a cursor-paginated list of all categories with optional filtering by active status and search term. Results are ordered by name ASC (alphabetically). Categories are pre-defined in the system and cannot be created via API.","parameters":[{"schema":{"type":"string","default":"20"},"required":false,"name":"page_size","in":"query"},{"schema":{"type":"string"},"required":false,"name":"page_token","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"is_active","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"}],"responses":{"200":{"description":"List of categories with cursor pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true,"maxLength":1000},"icon_url":{"type":"string","nullable":true,"maxLength":2048,"format":"uri"},"is_active":{"type":"boolean"}},"required":["created_at","updated_at","id","name","description","icon_url","is_active"]}},"pagination":{"type":"object","properties":{"page_size":{"type":"integer"},"next_page_token":{"type":"string","nullable":true},"has_more":{"type":"boolean"}},"required":["page_size","next_page_token","has_more"]}},"required":["data","pagination"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/categories/{category_id}":{"get":{"tags":["Categories"],"summary":"Get category by ID","description":"Retrieve detailed information about a specific category by its unique identifier","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"category_id","in":"path"}],"responses":{"200":{"description":"Category details","content":{"application/json":{"schema":{"type":"object","properties":{"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true,"maxLength":1000},"icon_url":{"type":"string","nullable":true,"maxLength":2048,"format":"uri"},"is_active":{"type":"boolean"}},"required":["created_at","updated_at","id","name","description","icon_url","is_active"]}}}},"404":{"description":"Category not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/feeds":{"get":{"tags":["Feeds"],"summary":"List feeds","description":"Retrieve a cursor-paginated list of data feeds with optional filtering by owner, category, tags, entry count, age, and active status. Defaults to showing only active feeds. Results are ordered by created_at DESC (newest first).","parameters":[{"schema":{"type":"string","default":"20"},"required":false,"name":"page_size","in":"query"},{"schema":{"type":"string"},"required":false,"name":"page_token","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"owner_id","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"category","in":"query"},{"schema":{"type":"string"},"required":false,"name":"tags","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","default":"1"},"required":false,"name":"min_entries","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"min_age","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"max_age","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"is_active","in":"query"}],"responses":{"200":{"description":"List of feeds with cursor pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"owner_id":{"type":"string","format":"uuid"},"category_id":{"type":"string","nullable":true,"format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true,"maxLength":2000},"image_cid":{"type":"string","nullable":true,"maxLength":255},"is_active":{"type":"boolean"},"total_entries":{"type":"integer","minimum":0},"total_purchases":{"type":"integer","minimum":0},"total_revenue":{"type":"string","maxLength":78},"tags":{"type":"array","nullable":true,"items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20},"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"owner_wallet_address":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"}},"required":["id","owner_id","category_id","name","description","image_cid","is_active","total_entries","total_purchases","total_revenue","tags","created_at","updated_at","owner_wallet_address"]}},"pagination":{"type":"object","properties":{"page_size":{"type":"integer"},"next_page_token":{"type":"string","nullable":true},"has_more":{"type":"boolean"}},"required":["page_size","next_page_token","has_more"]}},"required":["data","pagination"]}}}},"400":{"description":"Bad request - invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}},"post":{"tags":["Feeds"],"summary":"Create feed","description":"Create a new data feed with specified category, name, description, tags, and optional image. Creates a Pinata storage group using the group ID as the feed ID. The authenticated wallet becomes the feed owner and is automatically created on Base network if it does not exist. Existing wallets must be on Base chain. Enforces maximum feed limit per wallet. Requires wallet authentication via x-auth headers.","parameters":[{"schema":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$","description":"Ethereum wallet address (0x prefixed)","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"},"required":true,"description":"Ethereum wallet address (0x prefixed)","name":"x-wallet-address","in":"header"},{"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]+$","description":"Cryptographic signature (hex format)","example":"0x..."},"required":true,"description":"Cryptographic signature (hex format)","name":"x-signature","in":"header"},{"schema":{"type":"string","description":"The signed message (base64 encoded if it contains newlines)","example":"R3JhcGV2aW5lIEF1dGhlbnRpY2F0aW9u..."},"required":true,"description":"The signed message (base64 encoded if it contains newlines)","name":"x-message","in":"header"},{"schema":{"type":"string","description":"Unix timestamp in seconds","example":"1735689600"},"required":true,"description":"Unix timestamp in seconds","name":"x-timestamp","in":"header"},{"schema":{"type":"string","description":"Chain ID for network detection (optional). Supported: 8453 (base), 84532 (base-sepolia), 1 (ethereum), 11155111 (ethereum-sepolia), 137 (polygon), 80002 (polygon-amoy)","example":"8453"},"required":false,"description":"Chain ID for network detection (optional). Supported: 8453 (base), 84532 (base-sepolia), 1 (ethereum), 11155111 (ethereum-sepolia), 137 (polygon), 80002 (polygon-amoy)","name":"x-chain-id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":2000},"image_url":{"type":"string","maxLength":52428800},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20}},"required":["name"]}}}},"responses":{"201":{"description":"Feed created with database-generated UUID","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"owner_id":{"type":"string","format":"uuid"},"category_id":{"type":"string","nullable":true,"format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true,"maxLength":2000},"image_cid":{"type":"string","nullable":true,"maxLength":255},"is_active":{"type":"boolean"},"total_entries":{"type":"integer","minimum":0},"total_purchases":{"type":"integer","minimum":0},"total_revenue":{"type":"string","maxLength":78},"tags":{"type":"array","nullable":true,"items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20},"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"owner_wallet_address":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"}},"required":["id","owner_id","category_id","name","description","image_cid","is_active","total_entries","total_purchases","total_revenue","tags","created_at","updated_at","owner_wallet_address"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"401":{"description":"Unauthorized - signature verification failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"403":{"description":"Forbidden - maximum feed limit reached or invalid wallet network","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"503":{"description":"Service unavailable - failed to create storage group","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/feeds/{feed_id}":{"get":{"tags":["Feeds"],"summary":"Get feed by ID","description":"Retrieve detailed information about a specific data feed by its unique identifier, including statistics, owner wallet address, and metadata","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"feed_id","in":"path"}],"responses":{"200":{"description":"Feed details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"owner_id":{"type":"string","format":"uuid"},"category_id":{"type":"string","nullable":true,"format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true,"maxLength":2000},"image_cid":{"type":"string","nullable":true,"maxLength":255},"is_active":{"type":"boolean"},"total_entries":{"type":"integer","minimum":0},"total_purchases":{"type":"integer","minimum":0},"total_revenue":{"type":"string","maxLength":78},"tags":{"type":"array","nullable":true,"items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20},"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"owner_wallet_address":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"}},"required":["id","owner_id","category_id","name","description","image_cid","is_active","total_entries","total_purchases","total_revenue","tags","created_at","updated_at","owner_wallet_address"]}}}},"404":{"description":"Feed not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}},"patch":{"tags":["Feeds"],"summary":"Update feed","description":"Update the properties of an existing feed including category, name, description, image_cid, active status, and tags. Requires wallet authentication and feed ownership verification via x-auth headers.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"feed_id","in":"path"},{"schema":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$","description":"Ethereum wallet address (0x prefixed)","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"},"required":true,"description":"Ethereum wallet address (0x prefixed)","name":"x-wallet-address","in":"header"},{"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]+$","description":"Cryptographic signature (hex format)","example":"0x..."},"required":true,"description":"Cryptographic signature (hex format)","name":"x-signature","in":"header"},{"schema":{"type":"string","description":"The signed message (base64 encoded if it contains newlines)","example":"R3JhcGV2aW5lIEF1dGhlbnRpY2F0aW9u..."},"required":true,"description":"The signed message (base64 encoded if it contains newlines)","name":"x-message","in":"header"},{"schema":{"type":"string","description":"Unix timestamp in seconds","example":"1735689600"},"required":true,"description":"Unix timestamp in seconds","name":"x-timestamp","in":"header"},{"schema":{"type":"string","description":"Chain ID for network detection (optional). Supported: 8453 (base), 84532 (base-sepolia), 1 (ethereum), 11155111 (ethereum-sepolia), 137 (polygon), 80002 (polygon-amoy)","example":"8453"},"required":false,"description":"Chain ID for network detection (optional). Supported: 8453 (base), 84532 (base-sepolia), 1 (ethereum), 11155111 (ethereum-sepolia), 137 (polygon), 80002 (polygon-amoy)","name":"x-chain-id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":2000},"image_cid":{"type":"string","maxLength":255},"is_active":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20}}}}}},"responses":{"200":{"description":"Feed updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"owner_id":{"type":"string","format":"uuid"},"category_id":{"type":"string","nullable":true,"format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true,"maxLength":2000},"image_cid":{"type":"string","nullable":true,"maxLength":255},"is_active":{"type":"boolean"},"total_entries":{"type":"integer","minimum":0},"total_purchases":{"type":"integer","minimum":0},"total_revenue":{"type":"string","maxLength":78},"tags":{"type":"array","nullable":true,"items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20},"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"owner_wallet_address":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"}},"required":["id","owner_id","category_id","name","description","image_cid","is_active","total_entries","total_purchases","total_revenue","tags","created_at","updated_at","owner_wallet_address"]}}}},"400":{"description":"Bad Request - invalid category_id","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"401":{"description":"Unauthorized - signature verification failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"403":{"description":"Forbidden - wallet does not own this feed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"404":{"description":"Feed not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}},"delete":{"tags":["Feeds"],"summary":"Delete feed","description":"Soft delete a feed and all its associated entries by setting is_active to false. The feed and entry records remain in the system but will no longer appear in active feed listings. Requires wallet authentication and feed ownership verification.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"feed_id","in":"path"},{"schema":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$","description":"Ethereum wallet address (0x prefixed)","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"},"required":true,"description":"Ethereum wallet address (0x prefixed)","name":"x-wallet-address","in":"header"},{"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]+$","description":"Cryptographic signature (hex format)","example":"0x..."},"required":true,"description":"Cryptographic signature (hex format)","name":"x-signature","in":"header"},{"schema":{"type":"string","description":"The signed message (base64 encoded if it contains newlines)","example":"R3JhcGV2aW5lIEF1dGhlbnRpY2F0aW9u..."},"required":true,"description":"The signed message (base64 encoded if it contains newlines)","name":"x-message","in":"header"},{"schema":{"type":"string","description":"Unix timestamp in seconds","example":"1735689600"},"required":true,"description":"Unix timestamp in seconds","name":"x-timestamp","in":"header"},{"schema":{"type":"string","description":"Chain ID for network detection (optional). Supported: 8453 (base), 84532 (base-sepolia), 1 (ethereum), 11155111 (ethereum-sepolia), 137 (polygon), 80002 (polygon-amoy)","example":"8453"},"required":false,"description":"Chain ID for network detection (optional). Supported: 8453 (base), 84532 (base-sepolia), 1 (ethereum), 11155111 (ethereum-sepolia), 137 (polygon), 80002 (polygon-amoy)","name":"x-chain-id","in":"header"}],"responses":{"204":{"description":"Feed deleted"},"401":{"description":"Unauthorized - signature verification failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"403":{"description":"Forbidden - wallet does not own this feed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"404":{"description":"Feed not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/feeds/{feed_id}/entries":{"get":{"tags":["Feeds"],"summary":"List feed entries","description":"Retrieve a cursor-paginated list of all entries (messages) published to a specific feed, with optional filtering by free/paid status. Only returns active entries (is_active=true). Results are ordered by ID DESC (newest first).","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"feed_id","in":"path"},{"schema":{"type":"string","default":"20"},"required":false,"name":"page_size","in":"query"},{"schema":{"type":"string"},"required":false,"name":"page_token","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"is_free","in":"query"}],"responses":{"200":{"description":"List of feed entries with cursor pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"id":{"type":"string","format":"uuid"},"feed_id":{"type":"string","format":"uuid"},"cid":{"type":"string","minLength":1,"maxLength":255},"mime_type":{"type":"string","minLength":3,"maxLength":50},"pinata_upload_id":{"type":"string","nullable":true,"format":"uuid"},"title":{"type":"string","nullable":true,"minLength":1,"maxLength":500},"description":{"type":"string","nullable":true,"maxLength":10000},"metadata":{"type":"string","nullable":true,"maxLength":10000},"tags":{"type":"array","nullable":true,"items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20},"is_free":{"type":"boolean"},"expires_at":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"piid":{"type":"string","nullable":true,"format":"uuid"},"is_active":{"type":"boolean"},"total_purchases":{"type":"integer","minimum":0},"total_revenue":{"type":"string","maxLength":78}},"required":["created_at","updated_at","id","feed_id","cid","mime_type","pinata_upload_id","title","description","metadata","tags","is_free","expires_at","piid","is_active","total_purchases","total_revenue"]}},"pagination":{"type":"object","properties":{"page_size":{"type":"integer"},"next_page_token":{"type":"string","nullable":true},"has_more":{"type":"boolean"}},"required":["page_size","next_page_token","has_more"]}},"required":["data","pagination"]}}}},"404":{"description":"Feed not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}},"post":{"tags":["Feeds"],"summary":"Create feed entry","description":"Publish a new entry (message) to a specific feed. Content is provided as base64 and uploaded to IPFS via Pinata. Automatically creates payment instructions (paid or free) and enforces maximum entry limit per feed. Requires wallet authentication and feed ownership verification.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"feed_id","in":"path"},{"schema":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$","description":"Ethereum wallet address (0x prefixed)","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"},"required":true,"description":"Ethereum wallet address (0x prefixed)","name":"x-wallet-address","in":"header"},{"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]+$","description":"Cryptographic signature (hex format)","example":"0x..."},"required":true,"description":"Cryptographic signature (hex format)","name":"x-signature","in":"header"},{"schema":{"type":"string","description":"The signed message (base64 encoded if it contains newlines)","example":"R3JhcGV2aW5lIEF1dGhlbnRpY2F0aW9u..."},"required":true,"description":"The signed message (base64 encoded if it contains newlines)","name":"x-message","in":"header"},{"schema":{"type":"string","description":"Unix timestamp in seconds","example":"1735689600"},"required":true,"description":"Unix timestamp in seconds","name":"x-timestamp","in":"header"},{"schema":{"type":"string","description":"Chain ID for network detection (optional). Supported: 8453 (base), 84532 (base-sepolia), 1 (ethereum), 11155111 (ethereum-sepolia), 137 (polygon), 80002 (polygon-amoy)","example":"8453"},"required":false,"description":"Chain ID for network detection (optional). Supported: 8453 (base), 84532 (base-sepolia), 1 (ethereum), 11155111 (ethereum-sepolia), 137 (polygon), 80002 (polygon-amoy)","name":"x-chain-id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content_base64":{"type":"string","minLength":1,"maxLength":52428800},"mime_type":{"type":"string","minLength":3,"maxLength":50},"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","maxLength":10000},"metadata":{"type":"string","maxLength":10000},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20},"is_free":{"type":"boolean","default":false},"expires_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"price":{"type":"object","properties":{"amount":{"type":"string","minLength":1,"maxLength":78,"pattern":"^\\d+$"},"currency":{"type":"string","minLength":1,"maxLength":10},"network":{"type":"string","enum":["base","base-sepolia","ethereum","ethereum-sepolia","polygon","polygon-amoy"]}},"required":["amount","currency","network"]}},"required":["content_base64","mime_type"]}}}},"responses":{"201":{"description":"Entry created","content":{"application/json":{"schema":{"type":"object","properties":{"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"id":{"type":"string","format":"uuid"},"feed_id":{"type":"string","format":"uuid"},"cid":{"type":"string","minLength":1,"maxLength":255},"mime_type":{"type":"string","minLength":3,"maxLength":50},"pinata_upload_id":{"type":"string","nullable":true,"format":"uuid"},"title":{"type":"string","nullable":true,"minLength":1,"maxLength":500},"description":{"type":"string","nullable":true,"maxLength":10000},"metadata":{"type":"string","nullable":true,"maxLength":10000},"tags":{"type":"array","nullable":true,"items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20},"is_free":{"type":"boolean"},"expires_at":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"piid":{"type":"string","nullable":true,"format":"uuid"},"is_active":{"type":"boolean"},"total_purchases":{"type":"integer","minimum":0},"total_revenue":{"type":"string","maxLength":78}},"required":["created_at","updated_at","id","feed_id","cid","mime_type","pinata_upload_id","title","description","metadata","tags","is_free","expires_at","piid","is_active","total_purchases","total_revenue"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"401":{"description":"Unauthorized - signature verification failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"403":{"description":"Forbidden - wallet does not own this feed or maximum entry limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"404":{"description":"Feed not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"409":{"description":"Conflict - entry with this CID already exists","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/feeds/{feed_id}/entries/{entry_id}":{"get":{"tags":["Feeds"],"summary":"Get feed entry by ID","description":"Retrieve detailed information about a specific entry within a feed, including its IPFS CID, metadata, pricing, and statistics","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"feed_id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"entry_id","in":"path"}],"responses":{"200":{"description":"Feed entry details","content":{"application/json":{"schema":{"type":"object","properties":{"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"id":{"type":"string","format":"uuid"},"feed_id":{"type":"string","format":"uuid"},"cid":{"type":"string","minLength":1,"maxLength":255},"mime_type":{"type":"string","minLength":3,"maxLength":50},"pinata_upload_id":{"type":"string","nullable":true,"format":"uuid"},"title":{"type":"string","nullable":true,"minLength":1,"maxLength":500},"description":{"type":"string","nullable":true,"maxLength":10000},"metadata":{"type":"string","nullable":true,"maxLength":10000},"tags":{"type":"array","nullable":true,"items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20},"is_free":{"type":"boolean"},"expires_at":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"piid":{"type":"string","nullable":true,"format":"uuid"},"is_active":{"type":"boolean"},"total_purchases":{"type":"integer","minimum":0},"total_revenue":{"type":"string","maxLength":78}},"required":["created_at","updated_at","id","feed_id","cid","mime_type","pinata_upload_id","title","description","metadata","tags","is_free","expires_at","piid","is_active","total_purchases","total_revenue"]}}}},"404":{"description":"Feed or entry not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}},"delete":{"tags":["Feeds"],"summary":"Delete feed entry","description":"Soft delete an entry from a feed by setting is_active to false. The entry record and IPFS content remain in the system but the entry will no longer appear in feed listings. Requires wallet authentication and feed ownership verification.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"feed_id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"entry_id","in":"path"},{"schema":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$","description":"Ethereum wallet address (0x prefixed)","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"},"required":true,"description":"Ethereum wallet address (0x prefixed)","name":"x-wallet-address","in":"header"},{"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]+$","description":"Cryptographic signature (hex format)","example":"0x..."},"required":true,"description":"Cryptographic signature (hex format)","name":"x-signature","in":"header"},{"schema":{"type":"string","description":"The signed message (base64 encoded if it contains newlines)","example":"R3JhcGV2aW5lIEF1dGhlbnRpY2F0aW9u..."},"required":true,"description":"The signed message (base64 encoded if it contains newlines)","name":"x-message","in":"header"},{"schema":{"type":"string","description":"Unix timestamp in seconds","example":"1735689600"},"required":true,"description":"Unix timestamp in seconds","name":"x-timestamp","in":"header"},{"schema":{"type":"string","description":"Chain ID for network detection (optional). Supported: 8453 (base), 84532 (base-sepolia), 1 (ethereum), 11155111 (ethereum-sepolia), 137 (polygon), 80002 (polygon-amoy)","example":"8453"},"required":false,"description":"Chain ID for network detection (optional). Supported: 8453 (base), 84532 (base-sepolia), 1 (ethereum), 11155111 (ethereum-sepolia), 137 (polygon), 80002 (polygon-amoy)","name":"x-chain-id","in":"header"}],"responses":{"204":{"description":"Entry deleted"},"401":{"description":"Unauthorized - signature verification failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"403":{"description":"Forbidden - wallet does not own this feed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"404":{"description":"Feed or entry not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/feeds/{feed_id}/entries/{entry_id}/access-link":{"post":{"tags":["Feeds"],"summary":"Create private access link for entry","description":"Creates a time-limited presigned URL for accessing a private feed entry. Requires wallet signature authentication. Access is granted if the user is the feed owner, if the entry is free, or if the user has purchased the entry.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Feed UUID"},"required":true,"description":"Feed UUID","name":"feed_id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Entry UUID"},"required":true,"description":"Entry UUID","name":"entry_id","in":"path"},{"schema":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$","description":"Ethereum wallet address (0x prefixed)","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"},"required":true,"description":"Ethereum wallet address (0x prefixed)","name":"x-wallet-address","in":"header"},{"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]+$","description":"Cryptographic signature (hex format)","example":"0x..."},"required":true,"description":"Cryptographic signature (hex format)","name":"x-signature","in":"header"},{"schema":{"type":"string","description":"The signed message (base64 encoded if it contains newlines)","example":"R3JhcGV2aW5lIEF1dGhlbnRpY2F0aW9u..."},"required":true,"description":"The signed message (base64 encoded if it contains newlines)","name":"x-message","in":"header"},{"schema":{"type":"string","description":"Unix timestamp in seconds","example":"1735689600"},"required":true,"description":"Unix timestamp in seconds","name":"x-timestamp","in":"header"},{"schema":{"type":"string","description":"Chain ID for network detection (optional). Supported: 8453 (base), 84532 (base-sepolia), 1 (ethereum), 11155111 (ethereum-sepolia), 137 (polygon), 80002 (polygon-amoy)","example":"8453"},"required":false,"description":"Chain ID for network detection (optional). Supported: 8453 (base), 84532 (base-sepolia), 1 (ethereum), 11155111 (ethereum-sepolia), 137 (polygon), 80002 (polygon-amoy)","name":"x-chain-id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Access link created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Presigned URL for private file access"},"expires_at":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Unix timestamp when the link expires"}},"required":["url","expires_at"]}}}},"401":{"description":"Unauthorized - wallet signature verification failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"403":{"description":"Forbidden - user must have purchased the entry","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"404":{"description":"Entry not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/transactions":{"get":{"tags":["Transactions"],"summary":"List transactions","description":"Retrieve a cursor-paginated list of transactions with optional filtering by payer, pay_to, or entry_id. Results are ordered by ID DESC (newest first). Public endpoint - no authentication required.","parameters":[{"schema":{"type":"string","default":"20"},"required":false,"name":"page_size","in":"query"},{"schema":{"type":"string"},"required":false,"name":"page_token","in":"query"},{"schema":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$","description":"Filter by payer wallet address","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"},"required":false,"description":"Filter by payer wallet address","name":"payer","in":"query"},{"schema":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$","description":"Filter by pay_to wallet address","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"},"required":false,"description":"Filter by pay_to wallet address","name":"pay_to","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter by feed entry ID"},"required":false,"description":"Filter by feed entry ID","name":"entry_id","in":"query"}],"responses":{"200":{"description":"List of transactions with cursor pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"piid":{"type":"string","nullable":true,"format":"uuid"},"payer":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"pay_to":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"amount":{"type":"string","maxLength":20},"asset":{"type":"string","minLength":1,"maxLength":255},"entry_id":{"type":"string","nullable":true,"format":"uuid"},"transaction_hash":{"type":"string","minLength":66,"maxLength":66,"pattern":"^0x[0-9a-fA-F]{64}$"},"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["id","piid","payer","pay_to","amount","asset","entry_id","transaction_hash","created_at"]}},"pagination":{"type":"object","properties":{"page_size":{"type":"integer"},"next_page_token":{"type":"string","nullable":true},"has_more":{"type":"boolean"}},"required":["page_size","next_page_token","has_more"]}},"required":["data","pagination"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}},"post":{"tags":["Transactions"],"summary":"Create transactions (bulk insert)","description":"Creates x402 transaction records in bulk. Accepts array of transaction log data from x402 payment events. Automatically resolves entry_id from CID, validates all fields, and filters to only settled transactions. Requires admin authentication via admin-api-key header.","parameters":[{"schema":{"type":"string","description":"Admin API key for server-to-server authentication"},"required":true,"description":"Admin API key for server-to-server authentication","name":"admin-api-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"integer","minimum":0,"exclusiveMinimum":true},"root_cid":{"type":"string","nullable":true,"maxLength":255},"location_data":{"type":"object","nullable":true,"properties":{"colo":{"type":"string","maxLength":10},"country":{"type":"string","maxLength":100},"city":{"type":"string","maxLength":100},"region":{"type":"string","maxLength":100},"timezone":{"type":"string","maxLength":50},"asn":{"type":"integer","minimum":0,"exclusiveMinimum":true},"as_organization":{"type":"string","maxLength":255}}},"x402_data":{"type":"object","nullable":true,"properties":{"verified":{"type":"boolean"},"settled":{"type":"boolean"},"scheme":{"type":"string","maxLength":50},"network":{"type":"string","maxLength":50},"payer":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"asset":{"type":"string","maxLength":255},"transaction":{"type":"string","minLength":66,"maxLength":66,"pattern":"^0x[0-9a-fA-F]{64}$"},"x402_version":{"anyOf":[{"type":"string","maxLength":50},{"type":"number"}]},"payment_instruction_id":{"type":"string","format":"uuid"},"pay_to":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"amount":{"anyOf":[{"type":"number"},{"type":"string"}]},"paymentInstructionId":{"type":"string","format":"uuid"},"payTo":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"}}},"request":{"type":"object","properties":{"method":{"type":"string","maxLength":10},"url":{"type":"string","maxLength":2048},"pathname":{"type":"string","maxLength":2048},"hostname":{"type":"string","maxLength":255},"search":{"type":"string","maxLength":2048},"user_agent":{"type":"string","nullable":true,"maxLength":500},"forwarded_for":{"type":"string","nullable":true,"maxLength":255},"real_ip":{"type":"string","nullable":true,"maxLength":45},"referer":{"type":"string","nullable":true,"maxLength":2048}}},"response":{"type":"object","nullable":true,"properties":{"status":{"type":"integer","minimum":100,"maximum":599},"headers":{"type":"object","additionalProperties":{"nullable":true}},"size":{"type":"integer","nullable":true,"minimum":0},"duration":{"type":"number","nullable":true,"minimum":0},"cached":{"type":"boolean"},"error":{"type":"string","nullable":true,"maxLength":1000}}}},"required":["timestamp"]}}}}},"responses":{"201":{"description":"Transactions created","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer"},"transactions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"piid":{"type":"string","nullable":true,"format":"uuid"},"payer":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"pay_to":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"amount":{"type":"string","maxLength":20},"asset":{"type":"string","minLength":1,"maxLength":255},"entry_id":{"type":"string","nullable":true,"format":"uuid"},"transaction_hash":{"type":"string","minLength":66,"maxLength":66,"pattern":"^0x[0-9a-fA-F]{64}$"},"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["id","piid","payer","pay_to","amount","asset","entry_id","transaction_hash","created_at"]}}},"required":["created","transactions"]}}}},"204":{"description":"No Content - no x402_data present or no valid settled transactions to create"},"400":{"description":"Bad request - validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"401":{"description":"Unauthorized - admin API key verification failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/transactions/{id}":{"get":{"tags":["Transactions"],"summary":"Get transaction by ID","description":"Retrieve a specific transaction by its UUID. Public endpoint - no authentication required.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Transaction UUID"},"required":true,"description":"Transaction UUID","name":"id","in":"path"}],"responses":{"200":{"description":"Transaction details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"piid":{"type":"string","nullable":true,"format":"uuid"},"payer":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"pay_to":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"amount":{"type":"string","maxLength":20},"asset":{"type":"string","minLength":1,"maxLength":255},"entry_id":{"type":"string","nullable":true,"format":"uuid"},"transaction_hash":{"type":"string","minLength":66,"maxLength":66,"pattern":"^0x[0-9a-fA-F]{64}$"},"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["id","piid","payer","pay_to","amount","asset","entry_id","transaction_hash","created_at"]}}}},"404":{"description":"Transaction not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/transactions/hash/{hash}":{"get":{"tags":["Transactions"],"summary":"Get transaction by hash","description":"Retrieve a transaction by its blockchain transaction hash (0x-prefixed, 66 characters). Public endpoint - no authentication required.","parameters":[{"schema":{"type":"string","minLength":66,"maxLength":66,"description":"Blockchain transaction hash (66 characters with 0x prefix)","example":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"},"required":true,"description":"Blockchain transaction hash (66 characters with 0x prefix)","name":"hash","in":"path"}],"responses":{"200":{"description":"Transaction details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"piid":{"type":"string","nullable":true,"format":"uuid"},"payer":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"pay_to":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"amount":{"type":"string","maxLength":20},"asset":{"type":"string","minLength":1,"maxLength":255},"entry_id":{"type":"string","nullable":true,"format":"uuid"},"transaction_hash":{"type":"string","minLength":66,"maxLength":66,"pattern":"^0x[0-9a-fA-F]{64}$"},"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["id","piid","payer","pay_to","amount","asset","entry_id","transaction_hash","created_at"]}}}},"404":{"description":"Transaction not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/leaderboards/recent-entries":{"get":{"tags":["Leaderboards"],"summary":"Get recent entries","description":"Retrieve most recent feed entries across all active feeds with cursor-based pagination. Uses the gv_recent_entries view ordered by entry ID DESC.","parameters":[{"schema":{"type":"string","default":"20"},"required":false,"name":"page_size","in":"query"},{"schema":{"type":"string"},"required":false,"name":"page_token","in":"query"}],"responses":{"200":{"description":"List of recent entries with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"id":{"type":"string","format":"uuid"},"feed_id":{"type":"string","format":"uuid"},"cid":{"type":"string","minLength":1,"maxLength":255},"mime_type":{"type":"string","minLength":3,"maxLength":50},"pinata_upload_id":{"type":"string","nullable":true,"format":"uuid"},"title":{"type":"string","nullable":true,"minLength":1,"maxLength":500},"description":{"type":"string","nullable":true,"maxLength":10000},"metadata":{"type":"string","nullable":true,"maxLength":10000},"tags":{"type":"array","nullable":true,"items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20},"price":{"type":"string","maxLength":78},"asset":{"type":"string","minLength":1,"maxLength":10},"is_free":{"type":"boolean"},"expires_at":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"piid":{"type":"string","nullable":true,"format":"uuid"},"feed_name":{"type":"string","minLength":1,"maxLength":255},"feed_owner_id":{"type":"string","format":"uuid"},"owner_wallet":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"category_name":{"type":"string","minLength":1,"maxLength":255}},"required":["created_at","updated_at","id","feed_id","cid","mime_type","pinata_upload_id","title","description","metadata","tags","price","asset","is_free","expires_at","piid","feed_name","feed_owner_id","owner_wallet","category_name"]}},"pagination":{"type":"object","properties":{"page_size":{"type":"integer"},"next_page_token":{"type":"string","nullable":true},"has_more":{"type":"boolean"}},"required":["page_size","next_page_token","has_more"]}},"required":["data","pagination"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/leaderboards/top-feeds":{"get":{"tags":["Leaderboards"],"summary":"Get top feeds by entry count","description":"Retrieve top feeds ranked by total entry count (up to 100 results). Uses the gv_top_feeds view which includes all active feeds ordered by total_entries DESC.","parameters":[{"schema":{"type":"string","default":"20"},"required":false,"name":"page_size","in":"query"}],"responses":{"200":{"description":"List of top feeds","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"owner_id":{"type":"string","format":"uuid"},"category_id":{"type":"string","nullable":true,"format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true,"maxLength":2000},"image_cid":{"type":"string","nullable":true,"maxLength":255},"is_active":{"type":"boolean"},"total_entries":{"type":"integer","minimum":0},"total_purchases":{"type":"integer","minimum":0},"total_revenue":{"type":"string","maxLength":78},"tags":{"type":"array","nullable":true,"items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20},"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"owner_wallet":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"owner_username":{"type":"string","nullable":true,"minLength":3,"maxLength":50},"category_name":{"type":"string","nullable":true,"minLength":1,"maxLength":255}},"required":["id","owner_id","category_id","name","description","image_cid","is_active","total_entries","total_purchases","total_revenue","tags","created_at","updated_at","owner_wallet","owner_username","category_name"]}}},"required":["data"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/leaderboards/top-revenue":{"get":{"tags":["Leaderboards"],"summary":"Get top revenue feeds","description":"Retrieve leaderboard of feeds ranked by total revenue (up to 100 results) using dynamic query with flexible time period filtering: 1d (last day), 7d (last 7 days), 30d (last 30 days), or all (all time). Includes transaction data joined from gv_transactions.","parameters":[{"schema":{"type":"string","default":"20"},"required":false,"name":"page_size","in":"query"},{"schema":{"type":"string","enum":["1d","7d","30d","all"],"default":"all"},"required":false,"name":"period","in":"query"}],"responses":{"200":{"description":"Top revenue feeds leaderboard","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"string"},"id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"owner_id":{"type":"string","format":"uuid"},"owner_username":{"type":"string","nullable":true,"minLength":3,"maxLength":50},"owner_wallet":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"category_id":{"type":"string","nullable":true,"format":"uuid"},"category_name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true,"maxLength":2000},"image_cid":{"type":"string","nullable":true,"maxLength":255},"is_active":{"type":"boolean"},"tags":{"type":"array","nullable":true,"items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20},"total_entries":{"type":"integer","minimum":0},"total_purchases":{"type":"string"},"total_revenue":{"type":"string","maxLength":78},"unique_buyers":{"type":"string"},"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["rank","id","name","owner_id","owner_username","owner_wallet","category_id","category_name","description","image_cid","is_active","tags","total_entries","total_purchases","total_revenue","unique_buyers","created_at","updated_at"]}},"period":{"type":"string"}},"required":["data","period"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/leaderboards/top-providers":{"get":{"tags":["Leaderboards"],"summary":"Get top providers by revenue","description":"Retrieve leaderboard of providers (feed owners) ranked by total revenue across all their feeds (up to 100 results) using dynamic query with flexible time period filtering: 1d, 7d, 30d, or all. Aggregates data from all feeds owned by each wallet.","parameters":[{"schema":{"type":"string","default":"20"},"required":false,"name":"page_size","in":"query"},{"schema":{"type":"string","enum":["1d","7d","30d","all"],"default":"all"},"required":false,"name":"period","in":"query"}],"responses":{"200":{"description":"Top providers leaderboard","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"string"},"user_id":{"type":"string","format":"uuid"},"username":{"type":"string","nullable":true,"minLength":3,"maxLength":50},"wallet_address":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"total_feeds":{"type":"string"},"total_entries":{"type":"string"},"total_purchases":{"type":"string"},"total_revenue":{"type":"string","maxLength":78},"unique_buyers":{"type":"string"},"joined_at":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["rank","user_id","username","wallet_address","total_feeds","total_entries","total_purchases","total_revenue","unique_buyers","joined_at"]}},"period":{"type":"string"}},"required":["data","period"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/leaderboards/top-buyers":{"get":{"tags":["Leaderboards"],"summary":"Get top buyers by purchase count","description":"Retrieve leaderboard of most active buyers ranked by total purchase count (up to 100 results) using dynamic query with flexible time period filtering: 1d, 7d, 30d, or all. Joins wallet data with transaction records to calculate buyer statistics.","parameters":[{"schema":{"type":"string","default":"20"},"required":false,"name":"page_size","in":"query"},{"schema":{"type":"string","enum":["1d","7d","30d","all"],"default":"all"},"required":false,"name":"period","in":"query"}],"responses":{"200":{"description":"Top buyers leaderboard","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"string"},"user_id":{"type":"string","format":"uuid"},"username":{"type":"string","nullable":true,"minLength":3,"maxLength":50},"wallet_address":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"total_purchases":{"type":"string"},"total_spent":{"type":"string","maxLength":78},"unique_entries_purchased":{"type":"string"},"unique_feeds_purchased_from":{"type":"string"},"joined_at":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["rank","user_id","username","wallet_address","total_purchases","total_spent","unique_entries_purchased","unique_feeds_purchased_from","joined_at"]}},"period":{"type":"string"}},"required":["data","period"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/leaderboards/trending":{"get":{"tags":["Leaderboards"],"summary":"Get trending feeds","description":"Retrieve trending feeds based on revenue velocity in the last 7 days (up to 50 results). Uses the gv_leaderboard_trending_feeds view which calculates trending score from recent transaction activity.","parameters":[{"schema":{"type":"string","default":"20"},"required":false,"name":"page_size","in":"query"}],"responses":{"200":{"description":"Trending feeds leaderboard","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"string"},"id":{"type":"string","format":"uuid"},"owner_id":{"type":"string","format":"uuid"},"category_id":{"type":"string","nullable":true,"format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true,"maxLength":2000},"image_cid":{"type":"string","nullable":true,"maxLength":255},"is_active":{"type":"boolean"},"total_entries":{"type":"integer","minimum":0},"total_purchases":{"type":"integer","minimum":0},"total_revenue":{"type":"string","maxLength":78},"tags":{"type":"array","nullable":true,"items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20},"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"owner_wallet":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"owner_username":{"type":"string","nullable":true,"minLength":3,"maxLength":50},"category_name":{"type":"string","nullable":true,"minLength":1,"maxLength":255},"purchases_last_7d":{"type":"string"},"revenue_last_7d":{"type":"string","maxLength":78},"unique_buyers_last_7d":{"type":"string"}},"required":["rank","id","owner_id","category_id","name","description","image_cid","is_active","total_entries","total_purchases","total_revenue","tags","created_at","updated_at","owner_wallet","owner_username","category_name","purchases_last_7d","revenue_last_7d","unique_buyers_last_7d"]}}},"required":["data"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/leaderboards/most-popular":{"get":{"tags":["Leaderboards"],"summary":"Get most popular feeds","description":"Retrieve most popular feeds ranked by total purchase count (up to 100 results) using dynamic query with flexible time period filtering: 1d, 7d, 30d, or all. Only includes feeds with at least 1 entry and at least 1 purchase. Calculates average revenue per purchase.","parameters":[{"schema":{"type":"string","default":"20"},"required":false,"name":"page_size","in":"query"},{"schema":{"type":"string","enum":["1d","7d","30d","all"],"default":"all"},"required":false,"name":"period","in":"query"}],"responses":{"200":{"description":"Most popular feeds leaderboard","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"string"},"id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"owner_id":{"type":"string","format":"uuid"},"owner_username":{"type":"string","nullable":true,"minLength":3,"maxLength":50},"owner_wallet":{"type":"string","minLength":42,"maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$"},"category_id":{"type":"string","nullable":true,"format":"uuid"},"category_name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true,"maxLength":2000},"image_cid":{"type":"string","nullable":true,"maxLength":255},"is_active":{"type":"boolean"},"tags":{"type":"array","nullable":true,"items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20},"total_entries":{"type":"integer","minimum":0},"total_purchases":{"type":"string"},"total_revenue":{"type":"string","maxLength":78},"unique_buyers":{"type":"string"},"avg_revenue_per_purchase":{"type":"string","nullable":true,"maxLength":78},"created_at":{"type":"integer","minimum":0,"exclusiveMinimum":true},"updated_at":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["rank","id","name","owner_id","owner_username","owner_wallet","category_id","category_name","description","image_cid","is_active","tags","total_entries","total_purchases","total_revenue","unique_buyers","avg_revenue_per_purchase","created_at","updated_at"]}},"period":{"type":"string"}},"required":["data","period"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}},"/v1/leaderboards/category-stats":{"get":{"tags":["Leaderboards"],"summary":"Get category statistics","description":"Retrieve comprehensive statistics for all categories, including total feeds, providers, entries, purchases, revenue, and unique buyers. Uses the gv_category_stats view ordered by total revenue DESC.","responses":{"200":{"description":"List of category statistics ordered by total revenue descending","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid"},"category_name":{"type":"string","minLength":1,"maxLength":255},"category_description":{"type":"string","nullable":true,"maxLength":1000},"category_icon_url":{"type":"string","nullable":true,"maxLength":2048,"format":"uri"},"total_feeds":{"type":"string"},"total_providers":{"type":"string"},"total_entries":{"type":"string"},"total_purchases":{"type":"string"},"total_revenue":{"type":"string","maxLength":78},"unique_buyers":{"type":"string"},"avg_purchase_amount":{"type":"string","maxLength":78}},"required":["category_id","category_name","category_description","category_icon_url","total_feeds","total_providers","total_entries","total_purchases","total_revenue","unique_buyers","avg_purchase_amount"]}}},"required":["data"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":500},"details":{"nullable":true}},"required":["error","message"]}}}}}}}}}