{"openapi":"3.0.0","paths":{"/api/v1/health":{"get":{"operationId":"HealthController_check","parameters":[],"responses":{"200":{"description":""}},"summary":"Liveness check","tags":["Health"]}},"/api/v1/health/ready":{"get":{"operationId":"HealthController_ready","parameters":[],"responses":{"200":{"description":""}},"summary":"Readiness check — verifies all dependencies","tags":["Health"]}},"/api/v1/health/deep":{"get":{"operationId":"HealthController_deep","parameters":[],"responses":{"200":{"description":""}},"summary":"Deep health check — cron status, service details (internal only)","tags":["Health"]}},"/api/v1/health/database":{"get":{"operationId":"HealthController_checkDatabase","parameters":[],"responses":{"200":{"description":""}},"summary":"Database connection pool health check","tags":["Health"]}},"/api/v1/metrics/dashboard":{"get":{"description":"Returns platform-wide metrics including sales, blockchain health, and customer data. Platform admin access only.","operationId":"MetricsController_getDashboard","parameters":[{"name":"X-Clerk-User-Id","in":"header","description":"Clerk User ID for authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dashboard metrics retrieved successfully"},"401":{"description":"Authentication required"},"403":{"description":"Platform admin access required"}},"security":[{"bearer":[]}],"summary":"Get aggregated dashboard metrics","tags":["Metrics"]}},"/api/v1/metrics/services":{"get":{"description":"Returns current health status and basic info for all running services. Platform admin access only.","operationId":"MetricsController_getServicesHealth","parameters":[{"name":"X-Clerk-User-Id","in":"header","description":"Clerk User ID for authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Service health statuses retrieved"},"401":{"description":"Authentication required"},"403":{"description":"Platform admin access required"}},"security":[{"bearer":[]}],"summary":"Get health status of all microservices","tags":["Metrics"]}},"/api/v1/metrics/service/{name}":{"get":{"description":"Returns Prometheus metrics for the specified service. Platform admin access only.","operationId":"MetricsController_getServiceMetrics","parameters":[{"name":"X-Clerk-User-Id","in":"header","description":"Clerk User ID for authentication","required":true,"schema":{"type":"string"}},{"name":"name","required":true,"in":"path","description":"Service name","schema":{"enum":["payments","blockchain","liquidity","smart-wallets","marketplace","bridge","assets"],"type":"string"}}],"responses":{"200":{"description":"Service metrics retrieved"},"401":{"description":"Authentication required"},"403":{"description":"Platform admin access required"},"404":{"description":"Service not found"}},"security":[{"bearer":[]}],"summary":"Get detailed metrics for a specific service","tags":["Metrics"]}},"/api/v1/companies":{"post":{"operationId":"CompaniesController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCompanyDto"}}}},"responses":{"201":{"description":"Company created successfully"},"400":{"description":"Invalid input"},"403":{"description":"Forbidden - Platform Admin role required"}},"summary":"Create a new company (Platform Admin only)","tags":["Companies"]},"get":{"description":"Platform admins see all companies. Company users see only their own company.","operationId":"CompaniesController_findAll","parameters":[{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Companies retrieved successfully","headers":{"Cache-Control":{"description":"No caching - user-specific data","schema":{"type":"string","example":"no-store, no-cache, must-revalidate"}}}}},"summary":"Get all companies","tags":["Companies"]}},"/api/v1/companies/stats":{"get":{"description":"Returns aggregated stats about companies (total, by status, etc.)","operationId":"CompaniesController_getStats","parameters":[],"responses":{"200":{"description":"Statistics retrieved successfully"}},"summary":"Get company statistics","tags":["Companies"]}},"/api/v1/companies/internal/currencies":{"get":{"description":"Internal endpoint for service-to-service communication. Returns all companies with their defaultCurrency.","operationId":"CompaniesController_getCompanyCurrencies","parameters":[{"name":"X-Internal-Api-Key","in":"header","description":"Internal API key for service-to-service auth","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Company currencies retrieved successfully"}},"summary":"Get all company currencies (Internal)","tags":["Companies"]}},"/api/v1/companies/internal/purchase-notification":{"post":{"operationId":"CompaniesController_sendPurchaseNotification","parameters":[],"responses":{"200":{"description":""}},"tags":["Companies"]}},"/api/v1/companies/{id}/metrics":{"get":{"description":"Returns storage usage metrics for a specific company including used bytes, quota, and usage percentage","operationId":"CompaniesController_getMetrics","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID (UUID)","schema":{"type":"string"}}],"responses":{"200":{"description":"Company metrics retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"companyId":{"type":"string","format":"uuid"},"storage":{"type":"object","properties":{"usedBytes":{"type":"string","example":"1073741824"},"quotaBytes":{"type":"string","example":"10737418240"},"remainingBytes":{"type":"string","example":"9663676416"},"usagePercentage":{"type":"number","example":10}}},"status":{"type":"string","example":"ACTIVE"},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"404":{"description":"Company not found"}},"summary":"Get company storage metrics","tags":["Companies"]}},"/api/v1/companies/{id}":{"get":{"operationId":"CompaniesController_findOne","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Company found"},"404":{"description":"Company not found"}},"summary":"Get company by ID","tags":["Companies"]},"patch":{"operationId":"CompaniesController_update","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCompanyDto"}}}},"responses":{"200":{"description":"Company updated successfully"},"403":{"description":"Forbidden - User does not own this company"},"404":{"description":"Company not found"}},"summary":"Update company details","tags":["Companies"]},"delete":{"operationId":"CompaniesController_delete","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID","schema":{"type":"string"}}],"responses":{"204":{"description":"Company deleted"},"403":{"description":"Forbidden - Platform Admin role required"},"404":{"description":"Company not found"}},"summary":"Delete a company (Platform Admin only)","tags":["Companies"]}},"/api/v1/companies/{id}/status":{"patch":{"description":"Enable, disable, or suspend a company","operationId":"CompaniesController_updateStatus","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyStatusDto"}}}},"responses":{"200":{"description":"Company status updated"},"403":{"description":"Forbidden - User does not own this company"},"404":{"description":"Company not found"}},"summary":"Update company status","tags":["Companies"]}},"/api/v1/companies/{id}/enable":{"post":{"operationId":"CompaniesController_enable","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Company enabled"},"403":{"description":"Forbidden - User does not own this company"}},"summary":"Enable a company","tags":["Companies"]}},"/api/v1/companies/{id}/disable":{"post":{"operationId":"CompaniesController_disable","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Company disabled"},"403":{"description":"Forbidden - User does not own this company"}},"summary":"Disable a company","tags":["Companies"]}},"/api/v1/companies/{id}/stripe/connect":{"post":{"description":"Creates a Stripe Connect Express account and returns onboarding URL","operationId":"CompaniesController_createStripeConnect","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID","schema":{"type":"string"}}],"responses":{"201":{"description":"Stripe Connect account created","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"onboardingUrl":{"type":"string"}}}}}},"403":{"description":"Forbidden - User does not own this company"},"404":{"description":"Company not found"}},"summary":"Create Stripe Connect account for company","tags":["Companies"]}},"/api/v1/companies/{id}/stripe/connect-custom":{"post":{"description":"Creates a Stripe Custom account with transfers-only capability. No hosted onboarding UI — bank details are submitted directly.","operationId":"CompaniesController_createStripeConnectCustom","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeCustomOnboardDto"}}}},"responses":{"201":{"description":"Stripe Custom account created","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"status":{"type":"string"},"payoutsEnabled":{"type":"boolean"}}}}}},"400":{"description":"Company already has active Stripe account"},"403":{"description":"Forbidden - User does not own this company"}},"summary":"Create Stripe Custom Connect account with bank details","tags":["Companies"]}},"/api/v1/companies/{id}/stripe/status":{"get":{"description":"Returns whether Stripe onboarding is complete","operationId":"CompaniesController_getStripeStatus","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Stripe status retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string","nullable":true},"onboardingComplete":{"type":"boolean"},"chargesEnabled":{"type":"boolean"},"payoutsEnabled":{"type":"boolean"}}}}}},"403":{"description":"Forbidden - User does not own this company"},"404":{"description":"Company not found"}},"summary":"Get Stripe Connect onboarding status","tags":["Companies"]}},"/api/v1/companies/{id}/stripe/disconnect":{"delete":{"description":"Removes the Stripe Connect account association. Use this to reconnect with a different country.","operationId":"CompaniesController_disconnectStripe","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Stripe Connect disconnected","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"403":{"description":"Forbidden - User does not own this company"},"404":{"description":"Company not found"}},"summary":"Disconnect Stripe Connect account","tags":["Companies"]}},"/api/v1/companies/{id}/wallet-preference":{"post":{"description":"Configure treasury wallet type: MANAGED (HD-derived), CONNECTED (user wallet), or BOTH","operationId":"CompaniesController_setWalletPreference","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetWalletPreferenceDto"}}}},"responses":{"201":{"description":"Wallet preference set successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletPreferenceResponseDto"}}}},"400":{"description":"Invalid input or wallet service not configured"},"403":{"description":"Forbidden - User does not own this company"},"404":{"description":"Company not found"}},"summary":"Set wallet preference for company","tags":["Companies"]}},"/api/v1/companies/{id}/wallet-info":{"get":{"description":"Returns current wallet configuration including managed and connected wallet addresses","operationId":"CompaniesController_getWalletInfo","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Wallet info retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletInfoResponseDto"}}}},"403":{"description":"Forbidden - User does not own this company"},"404":{"description":"Company not found"}},"summary":"Get wallet info for company","tags":["Companies"]}},"/api/v1/companies/{id}/onboarding":{"get":{"description":"Returns terms acceptance and tour completion state","operationId":"CompaniesController_getOnboardingStatus","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Onboarding status retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"termsAccepted":{"type":"boolean"},"termsVersion":{"type":"string","nullable":true},"termsAcceptedAt":{"type":"string","format":"date-time","nullable":true},"tourCompleted":{"type":"boolean"},"tourCompletedAt":{"type":"string","format":"date-time","nullable":true}}}}}},"403":{"description":"Forbidden - User does not own this company"},"404":{"description":"Company not found"}},"summary":"Get onboarding status for company","tags":["Companies"]}},"/api/v1/companies/{id}/onboarding/accept-terms":{"post":{"description":"Records that the company has accepted terms and conditions","operationId":"CompaniesController_acceptTerms","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","example":"1.0","description":"Version of terms accepted"}},"required":["version"]}}}},"responses":{"201":{"description":"Terms accepted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"termsVersion":{"type":"string"},"acceptedAt":{"type":"string","format":"date-time"}}}}}},"403":{"description":"Forbidden - User does not own this company"},"404":{"description":"Company not found"}},"summary":"Accept terms and conditions","tags":["Companies"]}},"/api/v1/companies/{id}/deactivate":{"post":{"description":"Soft deletes the company. Requires company name confirmation and password. Data retained for 30 days.","operationId":"CompaniesController_deactivateAccount","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"companyName":{"type":"string","description":"Must match exact company name"},"password":{"type":"string","description":"User password for verification"}},"required":["companyName","password"]}}}},"responses":{"200":{"description":"Account deactivated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Company name does not match"},"403":{"description":"Incorrect password or not company owner"},"404":{"description":"Company not found"}},"summary":"Deactivate company account (soft delete)","tags":["Companies"]}},"/api/v1/companies/{id}/onboarding/complete-tour":{"post":{"description":"Records that the company has completed the onboarding tour","operationId":"CompaniesController_completeTour","parameters":[{"name":"id","required":true,"in":"path","description":"Company ID","schema":{"type":"string"}}],"responses":{"201":{"description":"Tour completed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"completedAt":{"type":"string","format":"date-time"}}}}}},"403":{"description":"Forbidden - User does not own this company"},"404":{"description":"Company not found"}},"summary":"Complete onboarding tour","tags":["Companies"]}},"/api/v1/assets":{"get":{"description":"Platform admins see all assets. Company users see only assets from their company.","operationId":"AssetsController_listAssets","parameters":[{"name":"creatorId","required":false,"in":"query","description":"Filter by creator ID","schema":{"type":"string"}},{"name":"assetType","required":false,"in":"query","description":"Filter by asset type","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by status","schema":{"type":"string"}},{"name":"searchTerm","required":false,"in":"query","description":"Search in asset name and description","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page (default: 10)","schema":{"type":"number"}},{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Assets retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"asset_id":{"type":"string","format":"uuid"},"company_id":{"type":"string","format":"uuid"},"asset_name":{"type":"string"},"asset_type":{"type":"string"},"estimated_value_usd":{"type":"string","nullable":true},"creator_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"description":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"is_legacy":{"type":"boolean"}}}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number"}}}}}}}}},"summary":"List assets with filtering and pagination","tags":["Assets"]},"post":{"description":"Creates a new asset. Users can only create assets for their company. Platform admins can create for any company.","operationId":"AssetsController_createAsset","parameters":[{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAssetDto"}}}},"responses":{"201":{"description":"Asset created successfully"},"400":{"description":"Bad Request - Invalid input data"},"403":{"description":"Forbidden - User cannot create assets for this company"}},"summary":"Create a new asset","tags":["Assets"]}},"/api/v1/assets/{id}":{"get":{"description":"Returns asset details. Users can only access assets from their company unless they are platform admins.","operationId":"AssetsController_getAsset","parameters":[{"name":"id","required":true,"in":"path","description":"Asset ID (UUID)","schema":{"type":"string"}},{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Asset retrieved successfully"},"403":{"description":"Forbidden - User does not have access to this asset"},"404":{"description":"Asset not found"}},"summary":"Get asset by ID","tags":["Assets"]},"patch":{"description":"Updates an existing asset. Users can only update assets belonging to their company. Platform admins can update any asset.","operationId":"AssetsController_updateAsset","parameters":[{"name":"id","required":true,"in":"path","description":"Asset ID (UUID)","schema":{"type":"string"}},{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAssetDto"}}}},"responses":{"200":{"description":"Asset updated successfully"},"403":{"description":"Forbidden - User does not have access to this asset"},"404":{"description":"Asset not found"}},"summary":"Update an asset","tags":["Assets"]},"delete":{"description":"Deletes an asset. Users can only delete assets belonging to their company. Platform admins can delete any asset.","operationId":"AssetsController_deleteAsset","parameters":[{"name":"id","required":true,"in":"path","description":"Asset ID (UUID)","schema":{"type":"string"}},{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Asset deleted successfully"},"403":{"description":"Forbidden - User does not have access to this asset"},"404":{"description":"Asset not found"}},"summary":"Delete an asset","tags":["Assets"]}},"/api/v1/customers":{"get":{"description":"Platform admins see all customers. Company users see only customers from their company.","operationId":"CustomersController_listCustomers","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page (default: 10)","schema":{"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by email, name, or customer ID","schema":{"type":"string"}},{"name":"sortField","required":true,"in":"query","schema":{"type":"string"}},{"name":"sortDirection","required":true,"in":"query","schema":{"type":"string"}},{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Customers retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"customer_id":{"type":"string","format":"uuid"},"company_id":{"type":"string","format":"uuid"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone_number":{"type":"string","nullable":true},"custody_type":{"type":"string","enum":["CUSTODIAL","SELF_CUSTODIAL"]},"wallet_address":{"type":"string","nullable":true},"kyc_status":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number"}}}}}}}},"401":{"description":"Unauthorized - Authentication required"}},"summary":"List customers with filtering and pagination","tags":["Customers"]},"post":{"description":"Creates a new customer. Users can only create customers for their company. Platform admins can create for any company.","operationId":"CustomersController_createCustomer","parameters":[{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomerDto"}}}},"responses":{"201":{"description":"Customer created successfully"},"403":{"description":"Forbidden - User cannot create customers for this company"}},"summary":"Create a new customer","tags":["Customers"]}},"/api/v1/customers/stats":{"get":{"description":"Returns customer statistics for the accessible company","operationId":"CustomersController_getStats","parameters":[{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Statistics retrieved successfully"},"401":{"description":"Unauthorized - Authentication required"}},"summary":"Get customer statistics","tags":["Customers"]}},"/api/v1/customers/top-holders":{"get":{"description":"Returns top N customers sorted by total token holdings","operationId":"CustomersController_getTopHolders","parameters":[{"name":"limit","required":false,"in":"query","description":"Number of top holders to return (default: 5)","schema":{"type":"number"}},{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Top holders retrieved successfully"}},"summary":"Get top customers by token holdings","tags":["Customers"]}},"/api/v1/customers/recent-sales":{"get":{"description":"Returns recent token sales for the company","operationId":"CustomersController_getRecentSales","parameters":[{"name":"limit","required":false,"in":"query","description":"Number of sales to return (default: 10)","schema":{"type":"number"}},{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Recent sales retrieved successfully"}},"summary":"Get recent token sales","tags":["Customers"]}},"/api/v1/customers/{id}":{"get":{"description":"Returns customer details. Users can only access customers from their company unless they are platform admins.","operationId":"CustomersController_getCustomer","parameters":[{"name":"id","required":true,"in":"path","description":"Customer ID (UUID)","schema":{"type":"string"}},{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Customer retrieved successfully"},"401":{"description":"Unauthorized - Authentication required"},"403":{"description":"Forbidden - User does not have access to this customer"},"404":{"description":"Customer not found"}},"summary":"Get customer by ID","tags":["Customers"]},"patch":{"description":"Updates an existing customer. Users can only update customers belonging to their company. Platform admins can update any customer.","operationId":"CustomersController_updateCustomer","parameters":[{"name":"id","required":true,"in":"path","description":"Customer ID (UUID)","schema":{"type":"string"}},{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomerDto"}}}},"responses":{"200":{"description":"Customer updated successfully"},"403":{"description":"Forbidden - User does not have access to this customer"},"404":{"description":"Customer not found"}},"summary":"Update a customer","tags":["Customers"]}},"/api/v1/customers/{id}/holdings":{"get":{"description":"Returns all holdings for a customer","operationId":"CustomersController_getCustomerHoldings","parameters":[{"name":"id","required":true,"in":"path","description":"Customer ID (UUID)","schema":{"type":"string"}},{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Holdings retrieved successfully"},"401":{"description":"Unauthorized - Authentication required"},"403":{"description":"Forbidden - User does not have access to this customer"}},"summary":"Get customer holdings (tokens/NFTs)","tags":["Customers"]}},"/api/v1/customers/{id}/credits":{"get":{"description":"Returns credits balance for a customer","operationId":"CustomersController_getCustomerCredits","parameters":[{"name":"id","required":true,"in":"path","description":"Customer ID (UUID)","schema":{"type":"string"}},{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Credits balance retrieved successfully"}},"summary":"Get customer credits balance","tags":["Customers"]}},"/api/v1/customers/{id}/pledges":{"get":{"description":"Returns active pledge subscriptions for a customer","operationId":"CustomersController_getCustomerPledges","parameters":[{"name":"id","required":true,"in":"path","description":"Customer ID (UUID)","schema":{"type":"string"}},{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Pledges retrieved successfully"}},"summary":"Get customer pledge subscriptions","tags":["Customers"]}},"/api/v1/customers/{id}/transactions":{"get":{"description":"Returns all transactions for a customer (purchases, transfers, resales)","operationId":"CustomersController_getCustomerTransactions","parameters":[{"name":"id","required":true,"in":"path","description":"Customer ID (UUID)","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of transactions to return (default: 20)","schema":{"type":"number"}},{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Transactions retrieved successfully"}},"summary":"Get customer transaction history","tags":["Customers"]}},"/api/v1/customers/utilization/timeseries":{"get":{"description":"Returns token utilization over time for assets","operationId":"CustomersController_getUtilizationTimeseries","parameters":[{"name":"period","required":false,"in":"query","description":"Time period (default: 30d)","schema":{"enum":["7d","30d","90d","1y"],"type":"string"}},{"name":"interval","required":false,"in":"query","description":"Data interval (default: daily)","schema":{"enum":["daily","weekly","monthly"],"type":"string"}},{"name":"X-Clerk-User-Id","in":"header","description":"Clerk user ID for authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Utilization time series retrieved successfully"}},"summary":"Get asset utilization time series","tags":["Customers"]}},"/api/v1/admin/legacy-assets/incomplete":{"get":{"description":"Returns all legacy assets from the old production system that are missing required information (documents, rights, distribution config, etc.). Shows completion percentage and specific missing items for each asset. Used to display \"NEEDS ATTENTION!!\" alerts in the admin dashboard for Gearbox tokens.","operationId":"LegacyAssetsController_getIncompleteAssets","parameters":[],"responses":{"200":{"description":"Legacy assets retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncompleteLegacyAssetsResponseDto"}}}},"500":{"description":"Internal server error"}},"summary":"Get incomplete legacy assets that need attention","tags":["Legacy Assets"]}},"/api/v1/admin/legacy-assets/all":{"get":{"description":"Returns all legacy assets from the old production system, including both complete and incomplete ones. Useful for displaying a complete list of migrated assets in the admin dashboard.","operationId":"LegacyAssetsController_getAllLegacyAssets","parameters":[],"responses":{"200":{"description":"All legacy assets retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IncompleteLegacyAssetDto"}}}}},"500":{"description":"Internal server error"}},"summary":"Get all legacy assets (complete and incomplete)","tags":["Legacy Assets"]}},"/api/v1/analytics/revenue":{"get":{"description":"Returns comprehensive revenue metrics including current/previous period comparison, percentage changes, weekly/daily revenue, and trend direction. Used for the main revenue card on the sales dashboard. Company ID is automatically extracted from the authenticated user JWT token.","operationId":"AnalyticsController_getRevenueAnalytics","parameters":[{"name":"companyId","required":false,"in":"query","description":"Company ID (optional - defaults to authenticated user company)","schema":{"type":"string"}},{"name":"period","required":false,"in":"query","description":"Analytics period","schema":{"default":"30d","type":"string","enum":["7d","30d","60d","90d","120d","1y"]}}],"responses":{"200":{"description":"Revenue analytics retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevenueAnalyticsResponseDto"}}}},"400":{"description":"Invalid period parameter"},"401":{"description":"Unauthorized - invalid or missing JWT token"},"403":{"description":"Forbidden - user does not have a company associated"},"500":{"description":"Internal server error"}},"security":[{"bearer":[]}],"summary":"Get revenue analytics with trends","tags":["Analytics"]}},"/api/v1/analytics/revenue/timeseries":{"get":{"description":"Returns daily, weekly, or monthly revenue data points for charting. Used to render the revenue trend chart on the sales dashboard. Includes transaction counts for each period. Company ID is automatically extracted from the authenticated user JWT token.","operationId":"AnalyticsController_getRevenueTimeseries","parameters":[{"name":"companyId","required":false,"in":"query","description":"Company ID (optional - defaults to authenticated user company)","schema":{"type":"string"}},{"name":"period","required":false,"in":"query","description":"Analytics period","schema":{"default":"30d","type":"string","enum":["7d","30d","60d","90d","120d","1y"]}},{"name":"interval","required":false,"in":"query","description":"Time series interval","schema":{"default":"daily","type":"string","enum":["daily","weekly","monthly"]}}],"responses":{"200":{"description":"Revenue time series retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevenueTimeseriesResponseDto"}}}},"400":{"description":"Invalid parameters"},"401":{"description":"Unauthorized - invalid or missing JWT token"},"403":{"description":"Forbidden - user does not have a company associated"}},"security":[{"bearer":[]}],"summary":"Get revenue time series data","tags":["Analytics"]}},"/api/v1/analytics/volume":{"get":{"description":"Returns token and NFT trading volume metrics including total volume, breakdown by type (fungible/non-fungible), percentage changes, and transaction counts. Used for the volume card on the sales dashboard. Company ID is automatically extracted from the authenticated user JWT token.","operationId":"AnalyticsController_getVolumeAnalytics","parameters":[{"name":"companyId","required":false,"in":"query","description":"Company ID (optional - defaults to authenticated user company)","schema":{"type":"string"}},{"name":"period","required":false,"in":"query","description":"Analytics period","schema":{"default":"30d","type":"string","enum":["7d","30d","60d","90d","120d","1y"]}}],"responses":{"200":{"description":"Volume analytics retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolumeAnalyticsResponseDto"}}}},"400":{"description":"Invalid parameters"},"401":{"description":"Unauthorized - invalid or missing JWT token"},"403":{"description":"Forbidden - user does not have a company associated"}},"security":[{"bearer":[]}],"summary":"Get volume analytics","tags":["Analytics"]}},"/api/v1/analytics/assets/top":{"get":{"description":"Returns the top performing assets ranked by revenue, volume, or holder count. Includes detailed performance metrics for each asset including revenue, volume, holders, and calculated KPIs. Used for the \"Top Assets\" section on the sales dashboard. Company ID is automatically extracted from the authenticated user JWT token.","operationId":"AnalyticsController_getTopAssets","parameters":[{"name":"companyId","required":false,"in":"query","description":"Company ID (optional - defaults to authenticated user company)","schema":{"type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sort criterion","schema":{"default":"revenue","type":"string","enum":["revenue","volume","holders"]}},{"name":"limit","required":false,"in":"query","description":"Maximum number of results","schema":{"minimum":1,"maximum":100,"default":5,"type":"number"}}],"responses":{"200":{"description":"Top assets retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AssetPerformanceDto"}}}}},"400":{"description":"Invalid parameters"},"401":{"description":"Unauthorized - invalid or missing JWT token"},"403":{"description":"Forbidden - user does not have a company associated"}},"security":[{"bearer":[]}],"summary":"Get top performing assets","tags":["Analytics"]}},"/api/v1/analytics/customers":{"get":{"description":"Returns customer growth and engagement metrics including total customers, new customers (7d/30d), active customers, average tokens per customer, portfolio values, and lifetime value. Used for the customers card and quick stats on the sales dashboard. Company ID is automatically extracted from the authenticated user JWT token.","operationId":"AnalyticsController_getCustomerAnalytics","parameters":[{"name":"companyId","required":false,"in":"query","description":"Company ID (optional - defaults to authenticated user company)","schema":{"type":"string"}}],"responses":{"200":{"description":"Customer analytics retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerAnalyticsResponseDto"}}}},"400":{"description":"Invalid company ID"},"401":{"description":"Unauthorized - invalid or missing JWT token"},"403":{"description":"Forbidden - user does not have a company associated"}},"security":[{"bearer":[]}],"summary":"Get customer analytics","tags":["Analytics"]}},"/api/v1/analytics/utilization/timeseries":{"get":{"description":"Returns time series data showing the percentage of total token supply that is held by customers for each asset over time. Used for the utilization chart on the console dashboard. Company ID is automatically extracted from the authenticated user JWT token.","operationId":"AnalyticsController_getUtilizationTimeseries","parameters":[{"name":"companyId","required":false,"in":"query","description":"Company ID (optional - defaults to authenticated user company)","schema":{"type":"string"}},{"name":"period","required":false,"in":"query","description":"Analytics period","schema":{"default":"30d","type":"string","enum":["7d","30d","60d","90d","120d","1y"]}},{"name":"interval","required":false,"in":"query","description":"Time series interval","schema":{"default":"daily","type":"string","enum":["daily","weekly","monthly"]}}],"responses":{"200":{"description":"Utilization time series retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UtilizationTimeseriesResponseDto"}}}},"401":{"description":"Unauthorized - invalid or missing JWT token"},"403":{"description":"Forbidden - user does not have a company associated"}},"security":[{"bearer":[]}],"summary":"Get asset utilization time series","tags":["Analytics"]}},"/api/v1/analytics/platform/fees":{"get":{"description":"Returns platform-wide fee revenue metrics including breakdown by order type (PRIMARY_SALE, RESALE, TRANSFER). This endpoint is restricted to platform administrators.","operationId":"AnalyticsController_getPlatformFeeRevenue","parameters":[{"name":"period","required":false,"in":"query","description":"Analytics period","schema":{"default":"30d","type":"string","enum":["7d","30d","60d","90d","120d","1y"]}}],"responses":{"200":{"description":"Platform fee revenue retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformFeeRevenueResponseDto"}}}},"401":{"description":"Unauthorized - invalid or missing JWT token"},"403":{"description":"Forbidden - user is not a platform administrator"}},"security":[{"bearer":[]}],"summary":"Get platform fee revenue (Platform Admin only)","tags":["Analytics"]}},"/api/v1/analytics/platform/overview":{"get":{"description":"Returns a bird's eye view of all athletes on the platform with their onboarding status, Stripe health, revenue, and supporter activity. Aggregates data across all 4 databases.","operationId":"AnalyticsController_getPlatformOverview","parameters":[],"responses":{"200":{"description":"Platform overview retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformOverviewResponseDto"}}}},"403":{"description":"Forbidden - user is not a platform administrator"}},"security":[{"bearer":[]}],"summary":"Get platform overview with all athletes (Platform Admin only)","tags":["Analytics"]}},"/api/v1/analytics/platform/payout-health":{"get":{"description":"Proxies the payments service payout preview endpoint. Returns Stripe balance, amounts owed to athletes, per-athlete breakdowns, and payout readiness status.","operationId":"AnalyticsController_getPayoutHealth","parameters":[],"responses":{"200":{"description":"Payout health data retrieved successfully"},"403":{"description":"Forbidden - user is not a platform administrator"}},"security":[{"bearer":[]}],"summary":"Get payout health overview (Platform Admin only)","tags":["Analytics"]}},"/api/v1/analytics/platform/activity":{"get":{"description":"Returns recent platform events including signups, token purchases, and pledge subscriptions. Events are sorted by timestamp in descending order.","operationId":"AnalyticsController_getPlatformActivity","parameters":[{"name":"limit","required":false,"in":"query","description":"Maximum number of activity events to return","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}}],"responses":{"200":{"description":"Platform activity retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PlatformActivityEventDto"}}}}},"403":{"description":"Forbidden - user is not a platform administrator"}},"security":[{"bearer":[]}],"summary":"Get platform activity feed (Platform Admin only)","tags":["Analytics"]}},"/api/v1/webhooks/clerk":{"post":{"operationId":"WebhookController_handleWebhook","parameters":[{"name":"svix-id","required":true,"in":"header","schema":{"type":"string"}},{"name":"svix-timestamp","required":true,"in":"header","schema":{"type":"string"}},{"name":"svix-signature","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook processed successfully"},"400":{"description":"Invalid webhook signature"}},"summary":"Handle Clerk webhook events for user sync","tags":["Webhooks"]}},"/api/v1/campaigns":{"get":{"description":"Get all campaigns including drafts for admin management. Filtered by your company (platform admins see all).","operationId":"CampaignsController_listCampaigns","parameters":[{"name":"X-Clerk-User-Id","in":"header","description":"Clerk User ID for authentication","required":true,"schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string"}},{"name":"companyId","required":false,"in":"query","description":"Override company filter (platform admins only)","schema":{"type":"string"}}],"responses":{"200":{"description":"List of campaigns"},"401":{"description":"Authentication required"}},"security":[{"bearer":[]}],"summary":"List all campaigns","tags":["Admin - Campaigns"]},"post":{"operationId":"CampaignsController_createCampaign","parameters":[{"name":"X-Clerk-User-Id","in":"header","description":"Clerk User ID for authentication","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCampaignDto"}}}},"responses":{"201":{"description":"Campaign created"},"400":{"description":"Invalid input"},"401":{"description":"Authentication required"},"403":{"description":"Access denied"}},"security":[{"bearer":[]}],"summary":"Create a new campaign","tags":["Admin - Campaigns"]}},"/api/v1/campaigns/{id}":{"get":{"operationId":"CampaignsController_getCampaign","parameters":[{"name":"X-Clerk-User-Id","in":"header","description":"Clerk User ID for authentication","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Campaign details"},"401":{"description":"Authentication required"},"403":{"description":"Access denied"},"404":{"description":"Campaign not found"}},"security":[{"bearer":[]}],"summary":"Get campaign details","tags":["Admin - Campaigns"]},"put":{"operationId":"CampaignsController_updateCampaign","parameters":[{"name":"X-Clerk-User-Id","in":"header","description":"Clerk User ID for authentication","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCampaignDto"}}}},"responses":{"200":{"description":"Campaign updated"},"401":{"description":"Authentication required"},"403":{"description":"Access denied"},"404":{"description":"Campaign not found"}},"security":[{"bearer":[]}],"summary":"Update a campaign","tags":["Admin - Campaigns"]},"delete":{"operationId":"CampaignsController_deleteCampaign","parameters":[{"name":"X-Clerk-User-Id","in":"header","description":"Clerk User ID for authentication","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Campaign deleted"},"401":{"description":"Authentication required"},"403":{"description":"Access denied"},"404":{"description":"Campaign not found"}},"security":[{"bearer":[]}],"summary":"Delete a campaign","tags":["Admin - Campaigns"]}},"/api/v1/campaigns/{id}/status":{"post":{"operationId":"CampaignsController_changeStatus","parameters":[{"name":"X-Clerk-User-Id","in":"header","description":"Clerk User ID for authentication","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Status updated"},"401":{"description":"Authentication required"},"403":{"description":"Access denied"}},"security":[{"bearer":[]}],"summary":"Change campaign status","tags":["Admin - Campaigns"]}},"/api/v1/campaigns/{id}/deploy":{"post":{"operationId":"CampaignsController_deployCampaignContract","parameters":[{"name":"X-Clerk-User-Id","in":"header","description":"Clerk User ID for authentication","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Contract deployed"},"401":{"description":"Authentication required"},"403":{"description":"Access denied"}},"security":[{"bearer":[]}],"summary":"Deploy campaign smart contract","tags":["Admin - Campaigns"]}},"/api/v1/companies/{companyId}/pxl8l/purchase":{"post":{"description":"Creates a new PXL8L purchase transaction record with PENDING status","operationId":"PXL8LController_createPurchase","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePXL8LPurchaseDto"}}}},"responses":{"201":{"description":"PXL8L purchase transaction created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PXL8LTransactionDto"}}}},"400":{"description":"Invalid input or unsupported chain"},"403":{"description":"Forbidden - User does not own this company"},"404":{"description":"Company not found"}},"summary":"Initiate PXL8L purchase","tags":["PXL8L"]}},"/api/v1/companies/{companyId}/pxl8l/balance":{"get":{"description":"Fetches real-time PXL8L balance for the company from the blockchain","operationId":"PXL8LController_getBalance","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"chainId","required":false,"in":"query","description":"Chain ID to check balance on (8453=Base, 137=Polygon, 1=Ethereum, 42161=Arbitrum)","schema":{"example":8453,"type":"number"}}],"responses":{"200":{"description":"PXL8L balance retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PXL8LBalanceDto"}}}},"400":{"description":"Invalid chain ID"},"403":{"description":"Forbidden - User does not own this company"},"404":{"description":"Company not found or PXL8L not deployed on chain"}},"summary":"Get PXL8L balance","tags":["PXL8L"]}},"/api/v1/companies/{companyId}/pxl8l/transactions":{"get":{"description":"Returns paginated transaction history for the company with optional filtering","operationId":"PXL8LController_getTransactions","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of transactions to return (1-100)","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of transactions to skip","schema":{"minimum":0,"default":0,"example":0,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter by transaction status","schema":{"enum":["PENDING","COMPLETED","FAILED"],"type":"string"}},{"name":"chainId","required":false,"in":"query","description":"Filter by chain ID","schema":{"example":8453,"type":"number","enum":[8453,137,1,42161]}}],"responses":{"200":{"description":"Transaction history retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PXL8LTransactionsResponseDto"}}}},"403":{"description":"Forbidden - User does not own this company"},"404":{"description":"Company not found"}},"summary":"Get PXL8L transaction history","tags":["PXL8L"]}},"/api/v1/companies/{companyId}/pxl8l/deduct-fee":{"post":{"description":"Deducts PXL8L from company balance as protocol fee for asset/campaign creation","operationId":"PXL8LController_deductProtocolFee","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeductProtocolFeeDto"}}}},"responses":{"200":{"description":"Protocol fee deducted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeductProtocolFeeResponseDto"}}}},"400":{"description":"Invalid input or insufficient balance"},"403":{"description":"Forbidden - User does not own this company"},"404":{"description":"Company not found"}},"summary":"Deduct protocol fee","tags":["PXL8L"]}},"/api/v1/companies/{companyId}/pxl8l/withdraw":{"post":{"description":"Withdraws PXL8L from company treasury to an external wallet address","operationId":"PXL8LController_withdrawPXL8L","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawPXL8LDto"}}}},"responses":{"200":{"description":"Withdrawal request created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawPXL8LResponseDto"}}}},"400":{"description":"Invalid input, insufficient balance, or invalid address"},"403":{"description":"Forbidden - User does not own this company"},"404":{"description":"Company not found"}},"summary":"Withdraw PXL8L","tags":["PXL8L"]}},"/api/v1/companies/{companyId}/pxl8l/custodial-balance":{"get":{"description":"Fetches database-tracked PXL8L balance for companies using managed wallets","operationId":"PXL8LController_getCustodialBalance","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"type":"string"}}],"responses":{"200":{"description":"Custodial balance retrieved successfully"}},"summary":"Get custodial PXL8L balance","tags":["PXL8L"]}},"/api/v1/companies/{companyId}/pxl8l/deduct-custodial-fee":{"post":{"description":"Deducts PXL8L from database-tracked balance (no blockchain transaction)","operationId":"PXL8LController_deductCustodialFee","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeductProtocolFeeDto"}}}},"responses":{"200":{"description":"Custodial fee deducted successfully"}},"summary":"Deduct custodial protocol fee","tags":["PXL8L"]}},"/api/v1/webhooks/stripe/onramp":{"post":{"operationId":"StripeWebhookController_handleOnrampWebhook","parameters":[{"name":"stripe-signature","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook processed successfully"},"400":{"description":"Invalid webhook signature or payload"}},"summary":"Handle Stripe Crypto Onramp webhook events","tags":["webhooks"]}},"/api/v1/companies/{companyId}/dao/enable":{"post":{"description":"Enable DAO functionality for the company with specified tier","operationId":"DAOController_enableDAO","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnableDAODto"}}}},"responses":{"201":{"description":"DAO enabled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DAOConfigResponseDto"}}}}},"summary":"Enable DAO","tags":["DAO"]}},"/api/v1/companies/{companyId}/dao/config":{"get":{"description":"Get current DAO configuration for the company","operationId":"DAOController_getConfig","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"responses":{"200":{"description":"DAO configuration retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DAOConfigResponseDto"}}}}},"summary":"Get DAO configuration","tags":["DAO"]}},"/api/v1/companies/{companyId}/dao/proposals":{"post":{"description":"Create a new governance proposal","operationId":"DAOController_createProposal","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProposalDto"}}}},"responses":{"201":{"description":"Proposal created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalResponseDto"}}}}},"summary":"Create proposal","tags":["DAO"]},"get":{"description":"List governance proposals with optional filtering","operationId":"DAOController_listProposals","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by status","schema":{"type":"string","enum":["DRAFT","PENDING","ACTIVE","SUCCEEDED","DEFEATED","QUEUED","EXECUTED","CANCELLED","EXPIRED"]}},{"name":"limit","required":false,"in":"query","description":"Number of proposals to return","schema":{"example":10,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of proposals to skip","schema":{"example":0,"type":"number"}}],"responses":{"200":{"description":"Proposals retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalsListResponseDto"}}}}},"summary":"List proposals","tags":["DAO"]}},"/api/v1/companies/{companyId}/dao/proposals/{proposalId}":{"get":{"description":"Get a specific governance proposal","operationId":"DAOController_getProposal","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"proposalId","required":true,"in":"path","description":"Proposal ID (UUID)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"responses":{"200":{"description":"Proposal retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalResponseDto"}}}}},"summary":"Get proposal","tags":["DAO"]}},"/api/v1/companies/{companyId}/dao/proposals/{proposalId}/vote":{"post":{"description":"Cast a vote on a governance proposal","operationId":"DAOController_castVote","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"proposalId","required":true,"in":"path","description":"Proposal ID (UUID)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CastVoteDto"}}}},"responses":{"200":{"description":"Vote cast successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoteResponseDto"}}}}},"summary":"Cast vote","tags":["DAO"]}},"/api/v1/companies/{companyId}/dao/proposals/{proposalId}/votes":{"get":{"description":"Get all votes cast on a specific proposal","operationId":"DAOController_getProposalVotes","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"proposalId","required":true,"in":"path","description":"Proposal ID (UUID)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"responses":{"200":{"description":"Votes retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/VoteResponseDto"}}}}}},"summary":"Get proposal votes","tags":["DAO"]}},"/api/v1/broadcasts/stats":{"get":{"description":"Returns the number of connected clients (Platform Admin only)","operationId":"BroadcastController_getConnectionStats","parameters":[],"responses":{"200":{"description":"Connection statistics retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionStatsDto"}}}},"403":{"description":"Forbidden - Platform Admin role required"}},"security":[{"bearer":[]}],"summary":"Get WebSocket connection statistics","tags":["Broadcasts"]}},"/api/v1/broadcasts/maintenance":{"post":{"description":"Broadcasts a scheduled maintenance notification to all connected clients (Platform Admin only)","operationId":"BroadcastController_sendMaintenance","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMaintenanceDto"}}}},"responses":{"200":{"description":"Maintenance notification broadcast successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastResponseDto"}}}},"400":{"description":"Invalid input"},"403":{"description":"Forbidden - Platform Admin role required"}},"security":[{"bearer":[]}],"summary":"Send maintenance notification to all users","tags":["Broadcasts"]}},"/api/v1/broadcasts/announcement":{"post":{"description":"Broadcasts a general announcement to all connected clients (Platform Admin only)","operationId":"BroadcastController_sendAnnouncement","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendAnnouncementDto"}}}},"responses":{"200":{"description":"Announcement broadcast successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastResponseDto"}}}},"400":{"description":"Invalid input"},"403":{"description":"Forbidden - Platform Admin role required"}},"security":[{"bearer":[]}],"summary":"Send announcement to all users","tags":["Broadcasts"]}},"/api/v1/broadcasts/company":{"post":{"description":"Broadcasts an announcement to all customers holding tokens from the specified company","operationId":"BroadcastController_sendCompanyAnnouncement","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendCompanyAnnouncementDto"}}}},"responses":{"200":{"description":"Company announcement broadcast successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyBroadcastResponseDto"}}}},"400":{"description":"Invalid input"},"403":{"description":"Forbidden - Must be admin of the specified company"}},"security":[{"bearer":[]}],"summary":"Send announcement to company customers","tags":["Broadcasts"]}},"/api/v1/broadcasts/athletes":{"post":{"description":"Broadcasts an announcement to all active athletes (company owners). Platform Admin only.","operationId":"BroadcastController_sendAthleteBroadcast","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendAthleteBroadcastDto"}}}},"responses":{"200":{"description":"Athlete broadcast sent successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AthleteBroadcastResponseDto"}}}},"403":{"description":"Forbidden - Platform Admin role required"}},"security":[{"bearer":[]}],"summary":"Send announcement to all athletes","tags":["Broadcasts"]}},"/api/v1/athletes/signup":{"post":{"description":"\n      Creates a new athlete account with Stripe Connect for receiving payments.\n      This is a PUBLIC endpoint - no authentication required.\n\n      Flow:\n      1. Fighter submits basic info (name, email, country, discipline)\n      2. System creates company record\n      3. System initiates Stripe Connect onboarding\n      4. Returns URL to complete Stripe onboarding\n      5. After Stripe complete, fighter can create their PASS\n    ","operationId":"AthleteController_signup","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AthleteSignupDto"}}}},"responses":{"201":{"description":"Athlete account created, Stripe onboarding URL returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AthleteSignupResponseDto"}}}},"400":{"description":"Invalid input data"},"409":{"description":"Email already registered"}},"summary":"Sign up as an athlete/fighter","tags":["Athletes"]}},"/api/v1/athletes/me/onboarding-status":{"get":{"description":"Returns the current athlete onboarding status (Stripe, PASS creation)","operationId":"AthleteController_getMyOnboardingStatus","parameters":[],"responses":{"200":{"description":"Onboarding status retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AthleteOnboardingStatusDto"}}}},"401":{"description":"Not authenticated"}},"security":[{"bearer":[]}],"summary":"Get my onboarding status","tags":["Athletes"]}},"/api/v1/athletes/{companyId}/onboarding-status":{"get":{"description":"Returns onboarding status for a specific company (must be owner)","operationId":"AthleteController_getOnboardingStatus","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"type":"string"}}],"responses":{"200":{"description":"Onboarding status retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AthleteOnboardingStatusDto"}}}},"403":{"description":"Not authorized to view this company"}},"security":[{"bearer":[]}],"summary":"Get athlete onboarding status by company ID","tags":["Athletes"]}},"/api/v1/athletes/{companyId}/refresh-stripe-link":{"post":{"description":"Get a new Stripe onboarding URL if the previous one expired","operationId":"AthleteController_refreshStripeLink","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"type":"string"}}],"responses":{"200":{"description":"New onboarding URL generated","content":{"application/json":{"schema":{"type":"object","properties":{"onboardingUrl":{"type":"string"}}}}}}},"security":[{"bearer":[]}],"summary":"Refresh Stripe Connect onboarding link","tags":["Athletes"]}},"/api/v1/creators/signup":{"post":{"description":"\n      Creates a new creator account. This is a PUBLIC endpoint - no authentication required.\n\n      **Creator Types:**\n      - **ATHLETE**: Individual fighters/athletes who want to create their own PASS\n      - **PROMOTER**: Fight promoters/agents who manage multiple athletes\n      - **CREATIVE**: Music, art, or content creators (like Gearbox Records)\n\n      **Flow:**\n      1. Creator submits basic info (name, email, country, businessType)\n      2. System creates company record with appropriate role\n      3. Returns success with next steps\n      4. Creator completes Stripe setup from dashboard\n      5. Creator can then create PASS/campaigns\n\n      **Conditional Fields:**\n      - `discipline` is REQUIRED for athletes, optional for others\n    ","operationId":"CreatorController_signup","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorSignupDto"}}}},"responses":{"201":{"description":"Creator account created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorSignupResponseDto"}}}},"400":{"description":"Invalid input data (e.g., missing discipline for athlete)"},"409":{"description":"Email already registered"}},"summary":"Sign up as a creator (athlete, promoter, or creative)","tags":["Creators"]}},"/api/v1/creators/me/onboarding-status":{"get":{"description":"Returns the current creator onboarding status (Stripe setup, PASS creation)","operationId":"CreatorController_getMyOnboardingStatus","parameters":[],"responses":{"200":{"description":"Onboarding status retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorOnboardingStatusDto"}}}},"401":{"description":"Not authenticated"}},"security":[{"bearer":[]}],"summary":"Get my onboarding status","tags":["Creators"]}},"/api/v1/creators/{companyId}/onboarding-status":{"get":{"description":"Returns onboarding status for a specific company (must be owner)","operationId":"CreatorController_getOnboardingStatus","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"type":"string"}}],"responses":{"200":{"description":"Onboarding status retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorOnboardingStatusDto"}}}},"403":{"description":"Not authorized to view this company"}},"security":[{"bearer":[]}],"summary":"Get creator onboarding status by company ID","tags":["Creators"]}},"/api/v1/creators/{companyId}/refresh-stripe-link":{"post":{"description":"Get a new Stripe onboarding URL if the previous one expired","operationId":"CreatorController_refreshStripeLink","parameters":[{"name":"companyId","required":true,"in":"path","description":"Company ID (UUID)","schema":{"type":"string"}}],"responses":{"200":{"description":"New onboarding URL generated","content":{"application/json":{"schema":{"type":"object","properties":{"onboardingUrl":{"type":"string"}}}}}}},"security":[{"bearer":[]}],"summary":"Refresh Stripe Connect onboarding link","tags":["Creators"]}},"/api/v1/unsubscribe":{"get":{"operationId":"UnsubscribeController_unsubscribe","parameters":[{"name":"email","required":true,"in":"query","schema":{"type":"string"}},{"name":"token","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Unsubscribe"]}}},"info":{"title":"PXL8 Admin Gateway","description":"Admin dashboard API - Sales analytics, platform metrics, company management, and system monitoring","version":"1.0","contact":{}},"tags":[{"name":"Analytics","description":"Sales dashboard analytics (revenue, volume, customers, assets)"},{"name":"Metrics","description":"Platform-wide metrics and system health"},{"name":"Companies","description":"Company management operations"},{"name":"Legacy Assets","description":"Legacy asset reconciliation and alerts"},{"name":"Health","description":"Service health monitoring"}],"servers":[],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"CreateCompanyDto":{"type":"object","properties":{"name":{"type":"string","example":"Acme Corporation","description":"Company name"},"email":{"type":"string","example":"contact@acme.com","description":"Company email"},"website":{"type":"string","example":"https://acme.com","description":"Company website"},"contactName":{"type":"string","example":"John Doe","description":"Primary contact name"},"phone":{"type":"string","example":"+1234567890","description":"Contact phone"}},"required":["name","email"]},"UpdateCompanyDto":{"type":"object","properties":{"name":{"type":"string","example":"Acme Corporation","description":"Company name"},"email":{"type":"string","example":"contact@acme.com","description":"Company email"},"website":{"type":"string","example":"https://acme.com","description":"Company website"},"contactName":{"type":"string","example":"John Doe","description":"Primary contact name"},"phone":{"type":"string","example":"+1234567890","description":"Contact phone"},"status":{"type":"string","enum":["ACTIVE","DISABLED","SUSPENDED","PENDING"],"description":"Company status"},"defaultCurrency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","JPY"],"example":"USD","description":"Default currency for payments"},"acceptCrypto":{"type":"boolean","example":false,"description":"Whether company accepts cryptocurrency payments"},"country":{"type":"string","example":"US","description":"Business country (ISO 3166-1 alpha-2 code) - used for Stripe Connect onboarding"},"walletSettings":{"type":"object","description":"Wallet configuration for custodial token storage","example":{"polygon":"0x...","base":"0x..."}}}},"CompanyStatusDto":{"type":"object","properties":{"status":{"type":"string","enum":["ACTIVE","DISABLED","SUSPENDED","PENDING"],"description":"New status for the company"},"reason":{"type":"string","description":"Reason for status change"}},"required":["status"]},"StripeCustomOnboardDto":{"type":"object","properties":{"firstName":{"type":"string","example":"John"},"lastName":{"type":"string","example":"Doe"},"dobDay":{"type":"number","example":15,"description":"Day of birth (1-31)"},"dobMonth":{"type":"number","example":6,"description":"Month of birth (1-12)"},"dobYear":{"type":"number","example":1990,"description":"Year of birth"},"addressLine1":{"type":"string","example":"123 Main St"},"city":{"type":"string","example":"New York"},"state":{"type":"string","example":"NY","description":"State/province code (required for US)"},"postalCode":{"type":"string","example":"10001"},"phone":{"type":"string","example":"+15551234567"},"routingNumber":{"type":"string","example":"110000000","description":"Routing number (US) or sort code (GB)"},"accountNumber":{"type":"string","example":"000123456789","description":"Bank account number (US/GB)"},"iban":{"type":"string","example":"DE89370400440532013000","description":"IBAN (EU countries)"},"ssnLast4":{"type":"string","example":"1234","description":"Last 4 of SSN (US only)"}},"required":["firstName","lastName","dobDay","dobMonth","dobYear","addressLine1","city","postalCode","phone"]},"SetWalletPreferenceDto":{"type":"object","properties":{"walletType":{"type":"string","description":"Treasury wallet management type","enum":["MANAGED","CONNECTED","BOTH"],"example":"MANAGED"},"connectedWalletAddress":{"type":"string","description":"Connected wallet address (required if walletType is CONNECTED or BOTH)","example":"0x1234567890abcdef1234567890abcdef12345678"}},"required":["walletType"]},"WalletPreferenceResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the setup was successful","example":true},"walletType":{"type":"string","description":"Selected wallet type","enum":["MANAGED","CONNECTED","BOTH"],"example":"MANAGED"},"managedWalletAddress":{"type":"string","description":"Managed wallet address (if walletType is MANAGED or BOTH)","example":"0xabcdef1234567890abcdef1234567890abcdef12","nullable":true},"connectedWalletAddress":{"type":"string","description":"Connected wallet address (if walletType is CONNECTED or BOTH)","example":"0x1234567890abcdef1234567890abcdef12345678","nullable":true},"treasuryWalletAddress":{"type":"string","description":"Active treasury wallet address used for protocol operations","example":"0xabcdef1234567890abcdef1234567890abcdef12"},"supportedChains":{"description":"List of supported chain IDs","example":[8453,137,1,42161],"type":"array","items":{"type":"number"}}},"required":["success","walletType","treasuryWalletAddress","supportedChains"]},"WalletInfoResponseDto":{"type":"object","properties":{"companyId":{"type":"string","description":"Company ID","example":"123e4567-e89b-12d3-a456-426614174000"},"walletType":{"type":"string","description":"Current wallet type preference","enum":["MANAGED","CONNECTED","BOTH"],"example":"MANAGED","nullable":true},"managedWalletAddress":{"type":"string","description":"Managed wallet address","example":"0xabcdef1234567890abcdef1234567890abcdef12","nullable":true},"connectedWalletAddress":{"type":"string","description":"Connected wallet address","example":"0x1234567890abcdef1234567890abcdef12345678","nullable":true},"treasuryWalletAddress":{"type":"string","description":"Active treasury wallet address","example":"0xabcdef1234567890abcdef1234567890abcdef12","nullable":true},"isConfigured":{"type":"boolean","description":"Whether wallet preference has been configured","example":true},"hdWalletServiceAvailable":{"type":"boolean","description":"Whether HD wallet service is available","example":true}},"required":["companyId","walletType","isConfigured","hdWalletServiceAvailable"]},"BenefitDto":{"type":"object","properties":{"type":{"type":"string","enum":["ACCESS","REVENUE","MERCHANDISE","GOVERNANCE","REWARDS","EXPERIENCE","CUSTOM"]},"description":{"type":"string"},"eligibility":{"type":"string"},"value":{"type":"object"},"metadata":{"type":"object"}},"required":["type","description"]},"CreateAssetDto":{"type":"object","properties":{"companyId":{"type":"string","description":"Company ID that owns this asset","example":"123e4567-e89b-12d3-a456-426614174000"},"assetName":{"type":"string","description":"Asset name","example":"My Music Album"},"assetType":{"type":"string","description":"Type of asset","enum":["MUSIC","FILM_TV","ATHLETE_CONTRACT","IMAGE_RIGHTS","SPORTS_MEMORABILIA","EVENT_RIGHTS","MERCHANDISE_RIGHTS","CONTENT_RIGHTS","BRAND_PARTNERSHIP","INTELLECTUAL_PROPERTY","PRIZE_PURSE","ROYALTY_STREAM","REVENUE_SHARE","OTHER"],"example":"MUSIC"},"tokenClassification":{"type":"string","description":"Token classification (SECURITY, UTILITY, or HYBRID)","enum":["SECURITY","UTILITY","HYBRID"],"example":"HYBRID"},"distributionModel":{"type":"string","description":"Distribution model for benefits/revenue","enum":["REVENUE_SHARE","FIXED_DIVIDEND","PRIZE_PURSE","MILESTONE_BASED","UTILITY_REWARDS","EQUITY","ROYALTY","CUSTOM"],"example":"REVENUE_SHARE"},"estimatedValueUsd":{"type":"number","description":"Estimated value in USD","example":10000},"creatorId":{"type":"string","description":"Creator user ID","example":"123e4567-e89b-12d3-a456-426614174001"},"description":{"type":"string","description":"Asset description","example":"A collection of original music tracks"},"benefits":{"description":"Token holder benefits (access, revenue, perks)","type":"array","items":{"$ref":"#/components/schemas/BenefitDto"}},"metadata":{"type":"object","description":"Additional metadata","example":{"genre":"Electronic","year":2024}}},"required":["companyId","assetName","assetType","creatorId"]},"UpdateAssetDto":{"type":"object","properties":{"assetName":{"type":"string","description":"Asset name","example":"Updated Album Name"},"estimatedValueUsd":{"type":"number","description":"Estimated value in USD","example":15000},"description":{"type":"string","description":"Asset description","example":"Updated description"},"status":{"type":"string","description":"Asset status","enum":["DRAFT","PENDING_REVIEW","APPROVED","DEPLOYED","ACTIVE","SUSPENDED","ARCHIVED"],"example":"ACTIVE"},"tokenClassification":{"type":"string","description":"Token classification","enum":["SECURITY","UTILITY","HYBRID"]},"distributionModel":{"type":"string","description":"Distribution model","enum":["REVENUE_SHARE","FIXED_DIVIDEND","PRIZE_PURSE","MILESTONE_BASED","UTILITY_REWARDS","EQUITY","ROYALTY","CUSTOM"]},"benefits":{"description":"Token holder benefits","type":"array","items":{"$ref":"#/components/schemas/BenefitDto"}},"metadata":{"type":"object","description":"Additional metadata","example":{"genre":"Electronic","year":2024,"updated":true}}}},"CreateCustomerDto":{"type":"object","properties":{"companyId":{"type":"string","description":"Company ID that owns this customer","example":"123e4567-e89b-12d3-a456-426614174000"},"email":{"type":"string","description":"Customer email address","example":"customer@example.com"},"custodyType":{"type":"string","description":"Custody type","enum":["CUSTODIAL","SELF_CUSTODIAL"],"example":"CUSTODIAL"},"firstName":{"type":"string","description":"First name","example":"John"},"lastName":{"type":"string","description":"Last name","example":"Doe"},"phoneNumber":{"type":"string","description":"Phone number","example":"+1234567890"},"walletAddress":{"type":"string","description":"Wallet address for self-custodial customers","example":"0x1234...5678"},"metadata":{"type":"object","description":"Additional metadata","example":{"source":"admin-panel","notes":"VIP customer"}}},"required":["companyId","email","custodyType"]},"UpdateCustomerDto":{"type":"object","properties":{"firstName":{"type":"string","description":"First name","example":"John"},"lastName":{"type":"string","description":"Last name","example":"Doe"},"phoneNumber":{"type":"string","description":"Phone number","example":"+1234567890"},"status":{"type":"string","description":"Customer status","enum":["ACTIVE","INACTIVE","SUSPENDED","CLOSED"],"example":"ACTIVE"},"kycStatus":{"type":"string","description":"KYC status","enum":["NOT_STARTED","IN_PROGRESS","PENDING_REVIEW","APPROVED","REJECTED","EXPIRED"],"example":"APPROVED"},"metadata":{"type":"object","description":"Additional metadata","example":{"notes":"Updated information"}}}},"IncompleteLegacyAssetDto":{"type":"object","properties":{"assetId":{"type":"string","description":"Asset unique identifier","example":"550e8400-e29b-41d4-a716-446655440000"},"assetName":{"type":"string","description":"Asset name","example":"Gearbox Music Rights"},"assetType":{"type":"string","description":"Type of asset","example":"MUSIC"},"status":{"type":"string","description":"Current asset status","example":"DRAFT"},"estimatedValueUsd":{"type":"number","description":"Estimated value in USD","example":50000},"companyId":{"type":"string","description":"Company ID that owns this asset","example":"550e8400-e29b-41d4-a716-446655440001"},"documentCount":{"type":"number","description":"Number of documents uploaded","example":0},"rightsCount":{"type":"number","description":"Number of rights holders","example":0},"verifiedRightsCount":{"type":"number","description":"Number of verified rights holders","example":0},"hasDistributionConfig":{"type":"boolean","description":"Whether distribution configuration exists","example":false},"hasDeployment":{"type":"boolean","description":"Whether asset has been deployed to blockchain","example":true},"completionPercentage":{"type":"number","description":"Completion percentage (0-100)","example":20},"missingItems":{"description":"List of missing items that need attention","example":["documents","verified_rights","distribution_config"],"type":"array","items":{"type":"string"}},"createdAt":{"format":"date-time","type":"string","description":"When the asset was created","example":"2024-01-15T10:30:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"When the asset was last updated","example":"2024-10-24T22:00:00.000Z"}},"required":["assetId","assetName","assetType","status","companyId","documentCount","rightsCount","verifiedRightsCount","hasDistributionConfig","hasDeployment","completionPercentage","missingItems","createdAt","updatedAt"]},"IncompleteLegacyAssetsResponseDto":{"type":"object","properties":{"totalLegacyAssets":{"type":"number","description":"Total number of legacy assets","example":6},"needsAttention":{"type":"number","description":"Number of legacy assets that need attention (< 100% complete)","example":3},"completeAssets":{"type":"number","description":"Number of legacy assets that are complete","example":3},"assets":{"description":"List of incomplete legacy assets","type":"array","items":{"$ref":"#/components/schemas/IncompleteLegacyAssetDto"}}},"required":["totalLegacyAssets","needsAttention","completeAssets","assets"]},"RevenueAnalyticsResponseDto":{"type":"object","properties":{"currentPeriodRevenue":{"type":"number","description":"Current period revenue in USD","example":127450},"previousPeriodRevenue":{"type":"number","description":"Previous period revenue in USD","example":107890},"weeklyRevenue":{"type":"number","description":"Revenue in last 7 days","example":4248},"dailyRevenue":{"type":"number","description":"Revenue in last 24 hours","example":607},"totalRevenue":{"type":"number","description":"Total all-time revenue","example":542300},"percentageChange":{"type":"number","description":"Percentage change vs previous period","example":18.1},"absoluteChange":{"type":"number","description":"Absolute change in USD","example":19560},"trend":{"type":"string","description":"Revenue trend","enum":["up","down","stable"],"example":"up"},"projectedMonthlyRevenue":{"type":"number","description":"Projected monthly revenue based on daily average","example":18210},"currency":{"type":"string","description":"Currency code","example":"USD"}},"required":["currentPeriodRevenue","previousPeriodRevenue","weeklyRevenue","dailyRevenue","totalRevenue","percentageChange","absoluteChange","trend","projectedMonthlyRevenue","currency"]},"RevenueTimeSeriesPointDto":{"type":"object","properties":{"date":{"format":"date-time","type":"string","description":"Date of data point","example":"2025-10-24T00:00:00.000Z"},"revenue":{"type":"number","description":"Revenue on this date","example":4248},"transactionCount":{"type":"number","description":"Number of transactions on this date","example":42}},"required":["date","revenue","transactionCount"]},"RevenueTimeseriesResponseDto":{"type":"object","properties":{"data":{"description":"Time series data points","type":"array","items":{"$ref":"#/components/schemas/RevenueTimeSeriesPointDto"}},"summary":{"type":"object","description":"Summary statistics"}},"required":["data","summary"]},"VolumeAnalyticsResponseDto":{"type":"object","properties":{"currentPeriodVolume":{"type":"string","description":"Total volume in current period","example":"4892"},"previousPeriodVolume":{"type":"string","description":"Total volume in previous period","example":"4010"},"tokenVolume":{"type":"string","description":"Token volume (fungible)","example":"4234"},"nftVolume":{"type":"string","description":"NFT volume (non-fungible)","example":"658"},"transactionCount":{"type":"number","description":"Number of transactions","example":842},"percentageChange":{"type":"number","description":"Percentage change vs previous period","example":22.4},"tokenVolumePercentage":{"type":"number","description":"Token volume as percentage of total","example":86.6},"nftVolumePercentage":{"type":"number","description":"NFT volume as percentage of total","example":13.4},"averageVolumePerTransaction":{"type":"number","description":"Average volume per transaction","example":5.81},"trend":{"type":"string","description":"Volume trend","enum":["up","down","stable"],"example":"up"}},"required":["currentPeriodVolume","previousPeriodVolume","tokenVolume","nftVolume","transactionCount","percentageChange","tokenVolumePercentage","nftVolumePercentage","averageVolumePerTransaction","trend"]},"AssetPerformanceDto":{"type":"object","properties":{"assetId":{"type":"string","description":"Asset ID","example":"19e59cb4-baf1-423f-b839-af317adae7ca"},"assetName":{"type":"string","description":"Asset name","example":"Knats B&W"},"assetType":{"type":"string","description":"Asset type","example":"MUSIC"},"revenue":{"type":"number","description":"Revenue generated","example":42300},"volume":{"type":"string","description":"Volume sold","example":"1560"},"holderCount":{"type":"number","description":"Number of token holders","example":156},"averageHoldingSize":{"type":"number","description":"Average holding size per holder","example":10},"revenuePerHolder":{"type":"number","description":"Revenue per holder","example":271.15},"revenuePerUnit":{"type":"number","description":"Revenue per unit sold","example":27.12},"popularityTier":{"type":"string","description":"Popularity tier","enum":["high","medium","low"],"example":"high"},"concentrationScore":{"type":"number","description":"Ownership concentration score (0-100)","example":0.64},"currency":{"type":"string","description":"Currency code","example":"USD"}},"required":["assetId","assetName","assetType","revenue","volume","holderCount","averageHoldingSize","revenuePerHolder","revenuePerUnit","popularityTier","concentrationScore","currency"]},"CustomerAnalyticsResponseDto":{"type":"object","properties":{"totalCustomers":{"type":"number","description":"Total number of customers","example":342},"newLast7d":{"type":"number","description":"New customers in last 7 days","example":12},"newLast30d":{"type":"number","description":"New customers in last 30 days","example":47},"activeCustomers":{"type":"number","description":"Customers with token holdings","example":289},"averageTokensPerCustomer":{"type":"number","description":"Average number of different tokens per customer","example":3.2},"averagePortfolioValue":{"type":"number","description":"Average portfolio value in USD","example":372.51},"customerLifetimeValue":{"type":"number","description":"Customer lifetime value in USD","example":434.21}},"required":["totalCustomers","newLast7d","newLast30d","activeCustomers","averageTokensPerCustomer","averagePortfolioValue","customerLifetimeValue"]},"UtilizationTimeseriesResponseDto":{"type":"object","properties":{"data":{"description":"Time series data points with utilization per asset","example":[{"date":"2025-11-01","Asset A":45.2,"Asset B":32.1},{"date":"2025-11-02","Asset A":47.8,"Asset B":33.5}],"type":"array","items":{"type":"string"}},"assetNames":{"description":"Asset names in the response","example":["Asset A","Asset B"],"type":"array","items":{"type":"string"}}},"required":["data","assetNames"]},"PlatformFeeRevenueResponseDto":{"type":"object","properties":{"totalFeeCents":{"type":"number","description":"Total platform fees collected (all time) in cents","example":1250000},"currentPeriodFeeCents":{"type":"number","description":"Platform fees in current period in cents","example":125000},"previousPeriodFeeCents":{"type":"number","description":"Platform fees in previous period in cents","example":98000},"percentageChange":{"type":"number","description":"Percentage change vs previous period","example":27.55},"byOrderType":{"type":"object","description":"Fees broken down by order type","example":{"PRIMARY_SALE":{"feeCents":80000,"transactionCount":25},"RESALE":{"feeCents":35000,"transactionCount":12},"TRANSFER":{"feeCents":10000,"transactionCount":5}}},"currency":{"type":"string","description":"Currency code","example":"USD"}},"required":["totalFeeCents","currentPeriodFeeCents","previousPeriodFeeCents","percentageChange","byOrderType","currency"]},"PlatformAthleteOverviewDto":{"type":"object","properties":{"companyId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"country":{"type":"string"},"currency":{"type":"string"},"signupDate":{"type":"string"},"status":{"type":"string"},"role":{"type":"string"},"campaignName":{"type":"string","nullable":true},"campaignStatus":{"type":"string","nullable":true},"discipline":{"type":"string","nullable":true},"weightClass":{"type":"string","nullable":true},"isAmateur":{"type":"boolean"},"totalSupply":{"type":"number"},"tokensSold":{"type":"number"},"tokenRevenue":{"type":"number"},"supporterCount":{"type":"number"},"stripeConnected":{"type":"boolean"},"stripeAccountType":{"type":"string","nullable":true},"payoutsEnabled":{"type":"boolean"},"chargesEnabled":{"type":"boolean"},"pledgeSubscriberCount":{"type":"number"},"monthlyPledgeIncome":{"type":"number"},"totalRevenueCents":{"type":"number"},"platformFeeCents":{"type":"number"}},"required":["companyId","name","email","country","currency","signupDate","status","role","campaignName","campaignStatus","discipline","weightClass","isAmateur","totalSupply","tokensSold","tokenRevenue","supporterCount","stripeConnected","stripeAccountType","payoutsEnabled","chargesEnabled","pledgeSubscriberCount","monthlyPledgeIncome","totalRevenueCents","platformFeeCents"]},"PlatformOverviewSummaryDto":{"type":"object","properties":{"totalAthletes":{"type":"number"},"athletesWithPass":{"type":"number"},"athletesWithStripe":{"type":"number"},"totalPlatformRevenueCents":{"type":"number"},"totalSupporters":{"type":"number"},"totalPledgeSubscribers":{"type":"number"}},"required":["totalAthletes","athletesWithPass","athletesWithStripe","totalPlatformRevenueCents","totalSupporters","totalPledgeSubscribers"]},"PlatformOverviewResponseDto":{"type":"object","properties":{"athletes":{"type":"array","items":{"$ref":"#/components/schemas/PlatformAthleteOverviewDto"}},"summary":{"$ref":"#/components/schemas/PlatformOverviewSummaryDto"}},"required":["athletes","summary"]},"PlatformActivityEventDto":{"type":"object","properties":{"type":{"type":"string","enum":["SIGNUP","TOKEN_PURCHASE","PLEDGE_SUBSCRIPTION"]},"companyId":{"type":"string"},"companyName":{"type":"string"},"details":{"type":"string"},"timestamp":{"type":"string"}},"required":["type","companyId","companyName","details","timestamp"]},"CreateCampaignDto":{"type":"object","properties":{}},"UpdateCampaignDto":{"type":"object","properties":{}},"CreatePXL8LPurchaseDto":{"type":"object","properties":{"chainId":{"type":"number","description":"Chain ID (8453=Base, 137=Polygon, 1=Ethereum, 42161=Arbitrum)","example":8453,"enum":[8453,137,1,42161]},"fromToken":{"type":"string","description":"Token address used for payment (e.g., USDC address)","example":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"},"fromAmount":{"type":"string","description":"Amount of payment token to spend (in token decimals)","example":"100.5"},"toAmount":{"type":"string","description":"Expected amount of PXL8L to receive (in token decimals)","example":"1000.25"},"pricePerToken":{"type":"string","description":"USD price per PXL8L token at time of purchase","example":"0.10"},"stripeSessionId":{"type":"string","description":"Optional Stripe Crypto Onramp session ID","example":"cos_1ABC123"},"metadata":{"type":"object","description":"Additional metadata for the transaction","example":{"swapProvider":"arbitrum","slippage":"0.5"}}},"required":["chainId","fromToken","fromAmount","toAmount","pricePerToken"]},"PXL8LTransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Transaction ID","example":"123e4567-e89b-12d3-a456-426614174000"},"companyId":{"type":"string","description":"Company ID","example":"123e4567-e89b-12d3-a456-426614174000"},"transactionHash":{"type":"string","description":"Blockchain transaction hash","example":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"},"chainId":{"type":"number","description":"Chain ID","example":8453},"chainName":{"type":"string","description":"Chain name","example":"Base"},"fromToken":{"type":"string","description":"Payment token address","example":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"},"fromTokenSymbol":{"type":"string","description":"Payment token symbol","example":"USDC"},"fromAmount":{"type":"string","description":"Amount paid (formatted)","example":"100.50"},"toAmount":{"type":"string","description":"PXL8L received (formatted)","example":"1000.25"},"pricePerToken":{"type":"string","description":"Price per PXL8L token","example":"0.10"},"status":{"type":"string","description":"Transaction status","enum":["PENDING","COMPLETED","FAILED"],"example":"COMPLETED"},"stripeSessionId":{"type":"string","description":"Stripe session ID if used","example":"cos_1ABC123","nullable":true},"metadata":{"type":"object","description":"Additional metadata","example":{"swapProvider":"arbitrum"},"nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Transaction creation timestamp","example":"2025-11-17T12:00:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"Transaction update timestamp","example":"2025-11-17T12:05:00.000Z"}},"required":["id","companyId","transactionHash","chainId","chainName","fromToken","fromTokenSymbol","fromAmount","toAmount","pricePerToken","status","createdAt","updatedAt"]},"PXL8LBalanceDto":{"type":"object","properties":{"companyId":{"type":"string","description":"Company ID","example":"123e4567-e89b-12d3-a456-426614174000"},"chainId":{"type":"number","description":"Chain ID where balance is checked","example":8453},"balance":{"type":"string","description":"Raw balance in smallest unit (wei)","example":"1000000000000000000000"},"formattedBalance":{"type":"string","description":"Human-readable formatted balance","example":"1000.00"},"usdValue":{"type":"string","description":"USD value of the balance","example":"100.00","nullable":true},"pricePerToken":{"type":"string","description":"Price per token used for USD calculation","example":"0.10","nullable":true},"tier":{"type":"string","description":"Holder tier based on balance","example":"BRONZE","enum":["NONE","BRONZE","SILVER","GOLD","PLATINUM"]},"feeDiscount":{"type":"number","description":"Fee discount percentage based on tier","example":10}},"required":["companyId","chainId","balance","formattedBalance","usdValue","pricePerToken","tier","feeDiscount"]},"PXL8LTransactionsResponseDto":{"type":"object","properties":{"transactions":{"description":"List of transactions","type":"array","items":{"$ref":"#/components/schemas/PXL8LTransactionDto"}},"total":{"type":"number","description":"Total number of transactions","example":42},"limit":{"type":"number","description":"Number of transactions returned","example":10},"offset":{"type":"number","description":"Number of transactions skipped","example":0},"hasMore":{"type":"boolean","description":"Whether there are more transactions","example":true}},"required":["transactions","total","limit","offset","hasMore"]},"DeductProtocolFeeDto":{"type":"object","properties":{"amount":{"type":"string","description":"Amount of PXL8L to deduct (in tokens, not wei)","example":"150000"},"reason":{"type":"string","description":"Reason for the fee deduction","enum":["ASSET_CREATION","CAMPAIGN_CREATION","TOKEN_DEPLOYMENT"],"example":"ASSET_CREATION"},"assetId":{"type":"string","description":"Associated asset ID (for asset creation)","example":"123e4567-e89b-12d3-a456-426614174000"},"chainId":{"type":"number","description":"Chain ID to deduct from (defaults to highest balance)","example":8453,"enum":[8453,137,1,42161]},"metadata":{"type":"object","description":"Additional metadata for the fee deduction","example":{"assetValue":"1000000","feePercentage":"0.015"}}},"required":["amount","reason"]},"DeductProtocolFeeResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the deduction was successful","example":true},"transactionId":{"type":"string","description":"Internal transaction reference ID","example":"550e8400-e29b-41d4-a716-446655440000"},"transactionHash":{"type":"string","description":"Blockchain transaction hash","example":"0x1234567890abcdef..."},"amountDeducted":{"type":"string","description":"Amount deducted (in PXL8L tokens)","example":"150000"},"chainId":{"type":"number","description":"Chain ID where deduction occurred","example":8453},"reason":{"type":"string","description":"Reason for the deduction","enum":["ASSET_CREATION","CAMPAIGN_CREATION","TOKEN_DEPLOYMENT"],"example":"ASSET_CREATION"},"remainingBalance":{"type":"string","description":"Remaining PXL8L balance after deduction","example":"850000"},"timestamp":{"format":"date-time","type":"string","description":"Timestamp of the deduction","example":"2025-11-21T12:00:00.000Z"}},"required":["success","transactionId","amountDeducted","chainId","reason","remainingBalance","timestamp"]},"WithdrawPXL8LDto":{"type":"object","properties":{"amount":{"type":"string","description":"Amount of PXL8L to withdraw (in tokens)","example":"1000"},"destinationAddress":{"type":"string","description":"Destination wallet address","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f8bE87"},"chainId":{"type":"number","description":"Chain ID to withdraw from (defaults to Base 8453)","example":8453,"enum":[8453,137,1,42161]},"metadata":{"type":"object","description":"Additional metadata for the withdrawal","example":{"reason":"User requested withdrawal"}}},"required":["amount","destinationAddress"]},"WithdrawPXL8LResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the withdrawal was initiated successfully","example":true},"transactionId":{"type":"string","description":"Internal transaction ID","example":"123e4567-e89b-12d3-a456-426614174000"},"transactionHash":{"type":"string","description":"Blockchain transaction hash (null if pending)","example":"0x1234567890abcdef...","nullable":true},"amount":{"type":"string","description":"Amount withdrawn","example":"1000"},"destinationAddress":{"type":"string","description":"Destination wallet address","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f8bE87"},"chainId":{"type":"number","description":"Chain ID","example":8453},"status":{"type":"string","description":"Status of the withdrawal","enum":["PENDING","PROCESSING","COMPLETED","FAILED"],"example":"PENDING"},"remainingBalance":{"type":"string","description":"Remaining balance after withdrawal","example":"9000"},"timestamp":{"format":"date-time","type":"string","description":"Timestamp of the withdrawal request","example":"2025-11-21T12:00:00.000Z"}},"required":["success","transactionId","transactionHash","amount","destinationAddress","chainId","status","remainingBalance","timestamp"]},"EnableDAODto":{"type":"object","properties":{"tier":{"type":"string","description":"DAO tier to enable","enum":["BASIC","ONCHAIN","ADVANCED","ENTERPRISE"],"example":"BASIC"},"tokenAddress":{"type":"string","description":"Token address for governance","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f8bE87"},"chainId":{"type":"number","description":"Chain ID for DAO deployment (defaults to Base 8453)","example":8453},"votingDelay":{"type":"number","description":"Voting delay in blocks","example":1},"votingPeriod":{"type":"number","description":"Voting period in blocks","example":50400},"quorumPercentage":{"type":"number","description":"Quorum percentage (1-100)","example":4},"proposalThreshold":{"type":"string","description":"Proposal threshold (minimum tokens to create proposal)","example":"1000"},"multisigOwners":{"description":"Multi-sig owner addresses for treasury","example":["0xabc...","0xdef..."],"type":"array","items":{"type":"string"}}},"required":["tier","tokenAddress"]},"DAOConfigResponseDto":{"type":"object","properties":{"companyId":{"type":"string","description":"Company ID","example":"123e4567-e89b-12d3-a456-426614174000"},"isEnabled":{"type":"boolean","description":"Whether DAO is enabled","example":true},"tier":{"type":"string","description":"DAO tier","enum":["BASIC","ONCHAIN","ADVANCED","ENTERPRISE"],"example":"BASIC"},"tokenAddress":{"type":"string","description":"Governance token address","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f8bE87"},"governorAddress":{"type":"string","description":"Governor contract address (for on-chain tiers)","example":"0x123..."},"timelockAddress":{"type":"string","description":"Timelock contract address","example":"0x456..."},"snapshotSpaceId":{"type":"string","description":"Snapshot space ID (for off-chain voting)","example":"hexagon-token.eth"},"chainId":{"type":"number","description":"Chain ID","example":8453},"enabledAt":{"format":"date-time","type":"string","description":"When DAO was enabled","example":"2025-11-21T12:00:00.000Z"}},"required":["companyId","isEnabled","tier","tokenAddress","chainId","enabledAt"]},"CreateProposalDto":{"type":"object","properties":{"title":{"type":"string","description":"Proposal title","example":"Increase marketing budget"},"description":{"type":"string","description":"Proposal description (supports markdown)","example":"This proposal aims to increase the marketing budget by $10,000..."},"choices":{"description":"Choices for voting (for Snapshot)","example":["For","Against","Abstain"],"type":"array","items":{"type":"string"}},"targets":{"description":"Target contract addresses (for on-chain proposals)","example":["0x123..."],"type":"array","items":{"type":"string"}},"values":{"description":"Call values (ETH amounts)","example":["0"],"type":"array","items":{"type":"string"}},"calldatas":{"description":"Encoded function call data","example":["0x..."],"type":"array","items":{"type":"string"}},"startTime":{"type":"number","description":"Voting start timestamp (Unix)","example":1700000000},"endTime":{"type":"number","description":"Voting end timestamp (Unix)","example":1700604800}},"required":["title","description"]},"ProposalResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Proposal ID","example":"123e4567-e89b-12d3-a456-426614174000"},"companyId":{"type":"string","description":"Company ID","example":"123e4567-e89b-12d3-a456-426614174000"},"title":{"type":"string","description":"Proposal title","example":"Increase marketing budget"},"description":{"type":"string","description":"Proposal description","example":"This proposal aims to..."},"status":{"type":"string","description":"Proposal status","enum":["DRAFT","PENDING","ACTIVE","SUCCEEDED","DEFEATED","QUEUED","EXECUTED","CANCELLED","EXPIRED"],"example":"ACTIVE"},"proposer":{"type":"string","description":"Proposer address","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f8bE87"},"votesFor":{"type":"string","description":"Votes for","example":"1000000"},"votesAgainst":{"type":"string","description":"Votes against","example":"500000"},"votesAbstain":{"type":"string","description":"Votes abstain","example":"100000"},"startTime":{"format":"date-time","type":"string","description":"Voting start time","example":"2025-11-21T12:00:00.000Z"},"endTime":{"format":"date-time","type":"string","description":"Voting end time","example":"2025-11-28T12:00:00.000Z"},"onChainProposalId":{"type":"string","description":"On-chain proposal ID","example":"12345678901234567890"},"snapshotProposalId":{"type":"string","description":"Snapshot proposal ID","example":"Qm..."},"createdAt":{"format":"date-time","type":"string","description":"When proposal was created","example":"2025-11-21T12:00:00.000Z"}},"required":["id","companyId","title","description","status","proposer","votesFor","votesAgainst","votesAbstain","startTime","endTime","createdAt"]},"ProposalsListResponseDto":{"type":"object","properties":{"proposals":{"description":"List of proposals","type":"array","items":{"$ref":"#/components/schemas/ProposalResponseDto"}},"total":{"type":"number","description":"Total number of proposals","example":42},"hasMore":{"type":"boolean","description":"Whether there are more proposals","example":true}},"required":["proposals","total","hasMore"]},"CastVoteDto":{"type":"object","properties":{"proposalId":{"type":"string","description":"Proposal ID","example":"123e4567-e89b-12d3-a456-426614174000"},"vote":{"type":"number","description":"Vote option (0=Against, 1=For, 2=Abstain)","enum":[0,1,2],"example":1},"reason":{"type":"string","description":"Optional reason for the vote","example":"I support this initiative because..."}},"required":["proposalId","vote"]},"VoteResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Vote ID","example":"123e4567-e89b-12d3-a456-426614174000"},"proposalId":{"type":"string","description":"Proposal ID","example":"123e4567-e89b-12d3-a456-426614174000"},"voter":{"type":"string","description":"Voter address","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f8bE87"},"vote":{"type":"number","description":"Vote option","enum":[0,1,2],"example":1},"votingPower":{"type":"string","description":"Voting power","example":"1000000"},"reason":{"type":"string","description":"Reason for vote","example":"I support this..."},"castAt":{"format":"date-time","type":"string","description":"When vote was cast","example":"2025-11-21T12:00:00.000Z"}},"required":["id","proposalId","voter","vote","votingPower","castAt"]},"ConnectionStatsDto":{"type":"object","properties":{"totalConnections":{"type":"number","description":"Total number of WebSocket connections","example":150},"userConnections":{"type":"number","description":"Number of user (customer) connections","example":120},"adminConnections":{"type":"number","description":"Number of admin dashboard connections","example":30}},"required":["totalConnections","userConnections","adminConnections"]},"SendMaintenanceDto":{"type":"object","properties":{"message":{"type":"string","description":"Maintenance message to display to users","example":"Scheduled maintenance for system upgrades"},"scheduledAt":{"type":"string","description":"Scheduled start time (ISO 8601)","example":"2026-01-10T10:00:00Z"},"expectedDuration":{"type":"number","description":"Expected duration in minutes","example":60,"minimum":1,"maximum":1440},"severity":{"type":"string","description":"Severity level of the maintenance","enum":["info","warning","critical"],"default":"warning"},"affectedServices":{"description":"Services affected by the maintenance","example":["marketplace","payments"],"type":"array","items":{"type":"array"}}},"required":["message","scheduledAt","expectedDuration"]},"BroadcastResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the broadcast was sent successfully","example":true},"eventId":{"type":"string","description":"Event ID for tracking","example":"evt_abc123"},"eventType":{"type":"string","description":"Event type that was broadcast","example":"system:maintenance"},"connectedClients":{"type":"number","description":"Number of connected clients at time of broadcast","example":42},"timestamp":{"type":"string","description":"Timestamp of the broadcast","example":"2026-01-09T10:30:00.000Z"}},"required":["success","eventId","eventType","connectedClients","timestamp"]},"SendAnnouncementDto":{"type":"object","properties":{"title":{"type":"string","description":"Announcement title","example":"New Feature: Token Transfers"},"message":{"type":"string","description":"Announcement message body","example":"You can now transfer tokens to other users directly from your portfolio!"},"link":{"type":"string","description":"Link for more information","example":"https://pxl8.io/blog/token-transfers"},"linkText":{"type":"string","description":"Link button text","example":"Learn More"},"severity":{"type":"string","description":"Severity/importance level","enum":["info","warning","critical"],"default":"info"},"category":{"type":"string","description":"Category for the announcement","example":"feature"}},"required":["title","message"]},"SendCompanyAnnouncementDto":{"type":"object","properties":{"companyId":{"type":"string","description":"Company ID to broadcast to","example":"550e8400-e29b-41d4-a716-446655440000"},"title":{"type":"string","description":"Announcement title","example":"New Benefits Available"},"message":{"type":"string","description":"Announcement message body","example":"Check out the new exclusive benefits for token holders!"},"link":{"type":"string","description":"Link for more information","example":"https://pxl8.io/benefits"},"linkText":{"type":"string","description":"Link button text","example":"View Benefits"}},"required":["companyId","title","message"]},"CompanyBroadcastResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the broadcast was sent successfully","example":true},"eventId":{"type":"string","description":"Event ID for tracking","example":"evt_abc123"},"customersNotified":{"type":"number","description":"Number of customers notified","example":42},"timestamp":{"type":"string","description":"Timestamp of the broadcast","example":"2026-01-09T10:30:00.000Z"}},"required":["success","eventId","customersNotified","timestamp"]},"SendAthleteBroadcastDto":{"type":"object","properties":{"title":{"type":"string","description":"Announcement title","example":"New Feature: Fight Predictions"},"message":{"type":"string","description":"Announcement message body","example":"Predictions now auto-generate for your upcoming fights. Fans earn PXL8 coin for correct picks!"},"link":{"type":"string","description":"Link for more information"},"linkText":{"type":"string","description":"Link button text","example":"Learn More"}},"required":["title","message"]},"AthleteBroadcastResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"eventId":{"type":"string","example":"evt_abc123"},"athletesNotified":{"type":"number","description":"Number of athletes notified","example":6},"timestamp":{"type":"string","example":"2026-03-23T16:00:00.000Z"}},"required":["success","eventId","athletesNotified","timestamp"]},"AthleteSignupDto":{"type":"object","properties":{"name":{"type":"string","example":"John \"The Beast\" Smith","description":"Fighter name (as you want it displayed)"},"email":{"type":"string","example":"john@fighter.com","description":"Email for account and payments"},"country":{"type":"string","example":"US","description":"Country code (ISO 3166-1 alpha-2) - required for Stripe payouts"},"discipline":{"type":"string","enum":["MMA","Boxing","Muay Thai","Wrestling","BJJ","Kickboxing"],"example":"MMA","description":"Primary fighting discipline"},"businessType":{"type":"string","enum":["individual","company"],"example":"individual","description":"Are you registering as an individual (sole trader) or a registered company (Ltd, LLC, etc.)?"},"instagram":{"type":"string","example":"johnnyfighter","description":"Instagram handle (without @)"},"clerkUserId":{"type":"string","example":"user_abc123xyz","description":"Clerk user ID if already authenticated"}},"required":["name","email","country","discipline","businessType"]},"AthleteSignupResponseDto":{"type":"object","properties":{"companyId":{"type":"string","description":"Newly created company ID"},"name":{"type":"string","description":"Fighter/athlete name"},"stripeOnboardingUrl":{"type":"string","description":"Stripe Connect onboarding URL (null - setup deferred to dashboard)","nullable":true},"nextStep":{"type":"string","description":"Next step instructions"}},"required":["companyId","name","stripeOnboardingUrl","nextStep"]},"AthleteOnboardingStatusDto":{"type":"object","properties":{"companyId":{"type":"string","description":"Company ID"},"isComplete":{"type":"boolean","description":"Overall onboarding complete"},"stripeComplete":{"type":"boolean","description":"Stripe Connect setup complete"},"hasActivePASS":{"type":"boolean","description":"Has at least one active PASS/campaign"},"stripeOnboardingUrl":{"type":"string","description":"URL to continue Stripe onboarding (if incomplete)"}},"required":["companyId","isComplete","stripeComplete","hasActivePASS","stripeOnboardingUrl"]},"CreatorSignupDto":{"type":"object","properties":{"creatorType":{"type":"string","enum":["athlete","promoter","creative"],"example":"athlete","description":"Type of creator account"},"name":{"type":"string","example":"John \"The Beast\" Smith","description":"Display name (fighter name, company name, or artist name)"},"email":{"type":"string","example":"john@fighter.com","description":"Email for account and payments"},"country":{"type":"string","example":"US","description":"Country code (ISO 3166-1 alpha-2) - required for Stripe payouts"},"businessType":{"type":"string","enum":["individual","company"],"example":"individual","description":"Are you registering as an individual (sole trader) or a registered company (Ltd, LLC, etc.)?"},"discipline":{"type":"string","enum":["MMA","Boxing","Muay Thai","Wrestling","BJJ","Kickboxing","Other"],"example":"MMA","description":"Primary fighting discipline (required for athletes only)"},"instagram":{"type":"string","example":"johnnyfighter","description":"Instagram handle (without @)"},"clerkUserId":{"type":"string","example":"user_abc123xyz","description":"Clerk user ID if already authenticated"},"description":{"type":"string","example":"Professional MMA fighter competing in the UFC","description":"Brief description (for profile page)"}},"required":["creatorType","name","email","country","businessType"]},"CreatorSignupResponseDto":{"type":"object","properties":{"companyId":{"type":"string","description":"Newly created company ID"},"name":{"type":"string","description":"Display name"},"creatorType":{"type":"string","enum":["athlete","promoter","creative"],"description":"Creator type assigned"},"stripeOnboardingUrl":{"type":"string","description":"Stripe Connect onboarding URL (null - setup deferred to dashboard)","nullable":true},"nextStep":{"type":"string","description":"Next step instructions"}},"required":["companyId","name","creatorType","stripeOnboardingUrl","nextStep"]},"CreatorOnboardingStatusDto":{"type":"object","properties":{"companyId":{"type":"string","description":"Company ID"},"creatorType":{"type":"string","enum":["athlete","promoter","creative"],"description":"Creator type"},"isComplete":{"type":"boolean","description":"Overall onboarding complete"},"stripeComplete":{"type":"boolean","description":"Stripe Connect setup complete"},"hasActivePASS":{"type":"boolean","description":"Has at least one active PASS/campaign"},"stripeOnboardingUrl":{"type":"string","description":"URL to continue Stripe onboarding (if incomplete)"}},"required":["companyId","creatorType","isComplete","stripeComplete","hasActivePASS","stripeOnboardingUrl"]}}}}