{ "openapi": "3.0.3", "info": { "title": "Indexify API", "version": "0.1.12-beta", "description": "Financial API for managing users, stacks, tokens, and transactions through the Indexify platform. All endpoints live under a single base URL and use an `action` query parameter to select the operation.\n", "contact": { "name": "Indexify", "url": "https://indexify.finance" } }, "servers": [ { "url": "https://api.indexify.finance", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY", "description": "API key with the `ix_` prefix. You can generate an API Key by navigating to Settings -> API Key in the web app. Pass it in the `X-API-KEY` header on every request." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Invalid action" } } }, "SuccessMessage": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Operation completed successfully" } } }, "UserPublic": { "type": "object", "properties": { "username": { "type": "string", "example": "alice" }, "avatar": { "type": "string", "nullable": true, "example": "https://cdn.indexify.finance/avatars/alice.webp" }, "bio": { "type": "string", "nullable": true, "example": "DeFi enthusiast" }, "stacks_count": { "type": "integer", "example": 5 }, "telegram": { "type": "string", "nullable": true }, "discord": { "type": "string", "nullable": true }, "twitter": { "type": "string", "nullable": true }, "linkedin": { "type": "string", "nullable": true }, "personal": { "type": "string", "nullable": true } } }, "TokenObject": { "type": "object", "description": "Token representation returned by list/paginated_list actions.", "properties": { "id": { "type": "integer" }, "address": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "image_url": { "type": "string", "nullable": true }, "decimals": { "type": "integer" }, "chain": { "type": "string", "example": "solana" }, "pool_address": { "type": "string", "nullable": true }, "cg_id": { "type": "string", "nullable": true }, "price": { "type": "number", "nullable": true }, "market_cap": { "type": "string", "nullable": true }, "volume_24h": { "type": "string", "nullable": true }, "change4H": { "type": "number", "nullable": true }, "change1D": { "type": "number", "nullable": true }, "change1W": { "type": "number", "nullable": true }, "change1M": { "type": "number", "nullable": true }, "changeAll": { "type": "number", "nullable": true }, "is_verified": { "type": "boolean" }, "archived": { "type": "boolean" }, "categories": { "type": "array", "items": { "type": "string" } } } }, "StackObject": { "type": "object", "description": "Canonical stack representation returned by discovery and fetch actions. Exact fields may vary by context (discovery vs portfolio vs trending).\n", "properties": { "id": { "type": "integer" }, "stack_name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string", "nullable": true }, "topic": { "type": "string", "nullable": true, "description": "Stack risk/duration category." }, "creator_fee": { "type": "number" }, "price": { "type": "number", "nullable": true }, "weighted_market_cap": { "type": "number", "nullable": true }, "change4H": { "type": "number", "nullable": true }, "change1D": { "type": "number", "nullable": true }, "change1W": { "type": "number", "nullable": true }, "change1M": { "type": "number", "nullable": true }, "changeAll": { "type": "number", "nullable": true }, "token_count": { "type": "integer" }, "investor_count": { "type": "integer" }, "is_company_stack": { "type": "boolean" }, "archived": { "type": "boolean" }, "show_creator_holdings": { "type": "boolean" }, "created_at": { "type": "integer", "description": "Unix timestamp." }, "time_p": { "type": "integer", "nullable": true, "description": "Unix timestamp of last price update." }, "tvl": { "type": "number", "nullable": true, "description": "Total Value Locked in USD. Only present when tvl=true in request." }, "user": { "type": "object", "description": "Public creator profile.", "properties": { "username": { "type": "string" }, "avatar": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "stacks_count": { "type": "integer" }, "telegram": { "type": "string", "nullable": true }, "discord": { "type": "string", "nullable": true }, "twitter": { "type": "string", "nullable": true }, "linkedin": { "type": "string", "nullable": true }, "personal": { "type": "string", "nullable": true } } }, "tokens": { "type": "array", "description": "Token allocations within the stack.", "items": { "type": "object", "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "name": { "type": "string" }, "image_url": { "type": "string", "nullable": true }, "weight": { "type": "number" }, "is_verified": { "type": "boolean" } } } } } }, "PaginationOffsetLimit": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } }, "PaginationPage": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_next": { "type": "boolean" }, "has_prev": { "type": "boolean" } } }, "ChatMessage": { "type": "object", "properties": { "id": { "type": "integer" }, "stack_id": { "type": "integer" }, "messages": { "type": "string", "description": "Message content." }, "message_type": { "type": "string", "enum": [ "community", "creator_notes" ] }, "pinned": { "type": "boolean" }, "created_at": { "type": "integer", "description": "Unix timestamp." }, "user": { "type": "object", "properties": { "username": { "type": "string" }, "avatar": { "type": "string", "nullable": true } } } } }, "ReferralVolumeData": { "type": "object", "properties": { "username": { "type": "string" }, "total_successful_orders": { "type": "integer" }, "total_orders": { "type": "integer" }, "total_volume_micro_usdc": { "type": "integer" }, "total_volume_usdc": { "type": "number" }, "total_platform_fees_micro_usdc": { "type": "integer" }, "total_platform_fees_usdc": { "type": "number" }, "total_creator_fees_micro_usdc": { "type": "integer" }, "total_creator_fees_usdc": { "type": "number" }, "first_order_timestamp": { "type": "integer", "nullable": true }, "last_order_timestamp": { "type": "integer", "nullable": true }, "buy_volume_micro_usdc": { "type": "integer" }, "buy_volume_usdc": { "type": "number" }, "sell_volume_micro_usdc": { "type": "integer" }, "sell_volume_usdc": { "type": "number" }, "buy_orders_count": { "type": "integer" }, "sell_orders_count": { "type": "integer" }, "success_rate": { "type": "number" } } }, "LimitOrder": { "type": "object", "description": "Full limit order object returned by list and get actions. Includes token metadata and display fields.", "properties": { "order_id": { "type": "string", "description": "16-character unique order identifier", "example": "aBcDeFgHiJkLmNoP" }, "token_address": { "type": "string", "description": "Solana token mint address", "example": "So11111111111111111111111111111111111111112" }, "token_symbol": { "type": "string", "nullable": true, "description": "Token ticker symbol", "example": "SOL" }, "token_name": { "type": "string", "nullable": true, "description": "Token display name", "example": "Wrapped SOL" }, "token_image": { "type": "string", "nullable": true, "description": "Token logo URL" }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Order direction" }, "condition_type": { "type": "string", "enum": [ "lte", "gte" ], "description": "\"lte\" triggers when price <= target, \"gte\" triggers when price >= target" }, "trigger_price": { "type": "number", "description": "Target USD price threshold", "example": 120.0 }, "amount": { "type": "number", "description": "For buys: USDC amount. For sells: percentage of holdings (0-100)", "example": 50.0 }, "amount_display": { "type": "string", "description": "Human-readable amount \u2014 \"$50.00\" for buys, \"50%\" for sells", "example": "$50.00" }, "status": { "type": "string", "enum": [ "ACTIVE", "TRIGGERED", "FILLING", "FILLED", "FAILED", "CANCELLED" ], "description": "Current lifecycle status" }, "stack_id": { "type": "integer", "description": "Company stack ID used for the trade" }, "swap_provider": { "type": "string", "enum": [ "jupiter", "dflow" ], "description": "Swap provider used for execution" }, "created_at": { "type": "integer", "description": "Unix timestamp of order creation" }, "updated_at": { "type": "integer", "nullable": true, "description": "Unix timestamp of last status change" }, "triggered_at": { "type": "integer", "nullable": true, "description": "Unix timestamp when the price condition was met" }, "triggered_price": { "type": "number", "nullable": true, "description": "Actual USD price that triggered the order" }, "filled_at": { "type": "integer", "nullable": true, "description": "Unix timestamp when the fill completed" }, "fill_order_id": { "type": "string", "nullable": true, "description": "Linked stack_orders.order_id for the fill" }, "error_message": { "type": "string", "nullable": true, "description": "Failure reason (only present when status is FAILED)" }, "expires_at": { "type": "integer", "nullable": true, "description": "Unix timestamp for automatic expiration, or null if no expiry" } } }, "LimitOrderPlaceResponse": { "type": "object", "description": "Subset of limit order fields returned by the place action. Does not include token metadata or display fields.", "properties": { "order_id": { "type": "string", "description": "16-character unique order identifier", "example": "aBcDeFgHiJkLmNoP" }, "status": { "type": "string", "enum": [ "ACTIVE" ], "example": "ACTIVE" }, "token_address": { "type": "string", "description": "Solana token mint address", "example": "So11111111111111111111111111111111111111112" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "condition_type": { "type": "string", "enum": [ "lte", "gte" ] }, "trigger_price": { "type": "number", "description": "Target USD price threshold", "example": 120.0 }, "amount": { "type": "number", "description": "For buys: USDC amount. For sells: percentage (0-100)", "example": 50.0 }, "stack_id": { "type": "integer", "description": "Company stack ID used for the trade" }, "swap_provider": { "type": "string", "enum": [ "jupiter", "dflow" ] }, "created_at": { "type": "integer", "description": "Unix timestamp of order creation" }, "expires_at": { "type": "integer", "nullable": true, "description": "Unix timestamp for automatic expiration, or null if no expiry" } } }, "DeanonHoldersResponse": { "type": "object", "description": "Response from the DeAnon holders endpoint. Contains identified token holders matched against a curated wallet-to-Twitter lookup table.", "properties": { "mint": { "type": "string", "description": "The requested token mint address", "example": "So11111111111111111111111111111111111111112" }, "total_holders_fetched": { "type": "integer", "description": "Total number of token accounts fetched from Helius RPC (up to 10,000)", "example": 8432 }, "identified_count": { "type": "integer", "description": "Number of holders matched against the lookup table", "example": 47 }, "identified_holders": { "type": "array", "description": "Paginated list of identified holders, sorted by balance descending", "items": { "type": "object", "properties": { "rank": { "type": "integer", "description": "1-based rank by balance across all identified holders", "example": 1 }, "owner": { "type": "string", "description": "Solana wallet address", "example": "498g1rVnFcnjBjpfw1xyqA1WvgQXUU8RWuELjxkjAayQ" }, "twitter": { "type": "string", "description": "Twitter/X profile URL", "example": "https://x.com/frankdegods" }, "balance": { "type": "number", "description": "Token balance in human-readable units (adjusted for decimals)", "example": 152340.5 }, "pct_supply": { "type": "number", "description": "Percentage of total supply held, rounded to 6 decimal places", "example": 0.012345 } } } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Current offset", "example": 0 }, "limit": { "type": "integer", "description": "Current page size", "example": 20 }, "total_count": { "type": "integer", "description": "Total number of identified holders", "example": 47 }, "has_more": { "type": "boolean", "description": "True if there are more results after this page", "example": true }, "has_previous": { "type": "boolean", "description": "True if offset > 0", "example": false }, "page": { "type": "integer", "description": "Current page number (1-based)", "example": 1 }, "total_pages": { "type": "integer", "description": "Total number of pages", "example": 3 } } } } } } }, "paths": { "/api/user_info.php?action=fetch": { "post": { "operationId": "userInfoFetch", "summary": "Fetch authenticated user profile", "description": "Returns the full profile for the currently authenticated user including roles, wallet address, and masked phone number.\n", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "fetch" ] } } ], "responses": { "200": { "description": "Full user profile.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "slippage": { "type": "string" }, "priority_fee": { "type": "string" }, "phone_verified": { "type": "boolean" }, "phone_number_last_2": { "type": "string", "nullable": true, "description": "Last two digits of the phone number." }, "twitter": { "type": "string", "nullable": true }, "telegram": { "type": "string", "nullable": true }, "discord": { "type": "string", "nullable": true }, "linkedin": { "type": "string", "nullable": true }, "personal": { "type": "string", "nullable": true }, "wallet_address": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "roles": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "User not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/user_info.php?action=update": { "post": { "operationId": "userInfoUpdate", "summary": "Update user profile fields", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "update" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "minLength": 3, "maxLength": 30, "description": "Alphanumeric + underscores only." }, "bio": { "type": "string", "description": "Free-text bio. Send empty string to clear." }, "slippage": { "type": "string", "description": "Slippage tolerance as a decimal string." }, "priority_fee": { "type": "string", "description": "Priority fee in SOL (0 to 0.002)." } } } } } }, "responses": { "200": { "description": "Update succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "example": true }, "updates": { "type": "object", "additionalProperties": true, "description": "Map of updated field names to their new values." } } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/user_info.php?action=check_name": { "post": { "operationId": "userInfoCheckName", "summary": "Check username availability", "tags": [ "Account" ], "security": [], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "check_name" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "alice123" } } } } } }, "responses": { "200": { "description": "Username status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "OK", "TAKEN", "INVALID" ] } } } } } } } } }, "/api/user_info.php?action=search": { "post": { "operationId": "userInfoSearch", "summary": "Search users by username or bio", "tags": [ "Account" ], "security": [], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "search" ] } }, { "name": "query", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search term matched against username and bio." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "include_stats", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" }, "description": "When \"true\", each user object includes a `stats` sub-object." } ], "responses": { "200": { "description": "Matching users with pagination metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "avatar": { "type": "string" }, "display_name": { "type": "string", "nullable": true }, "verified": { "type": "boolean" }, "stats": { "type": "object", "description": "Present only when `include_stats=true`.", "additionalProperties": true } } } }, "pagination": { "type": "object", "properties": { "total_count": { "type": "integer" }, "has_next": { "type": "boolean" }, "offset": { "type": "integer" }, "limit": { "type": "integer" } } } } } } } } } } }, "/api/user_info.php?action=delete_account": { "post": { "operationId": "userInfoDeleteAccount", "summary": "Delete the authenticated user's account", "description": "Permanently deletes the user account after 2FA verification. All stacks are archived, follow relationships removed, and the wallet private key is returned one final time.\n", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "delete_account" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "verification_code" ], "properties": { "verification_code": { "type": "string", "description": "2FA verification code." } } } } } }, "responses": { "200": { "description": "Account deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "private_key": { "type": "string", "description": "Wallet private key returned for final export." }, "retry_count": { "type": "integer" }, "deletion_summary": { "type": "object", "properties": { "user_id": { "type": "integer" }, "archived_stacks": { "type": "integer" }, "follow_relationships_removed": { "type": "integer" } } } } } } } }, "400": { "description": "Validation error (2FA required, code required, invalid code, remaining balance).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/profile.php?action=twitter": { "post": { "operationId": "profileUpdateTwitter", "summary": "Update Twitter handle", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "twitter" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Twitter/X username (1-15 chars, alphanumeric + underscores). Send empty string or null to remove.\n", "example": "alice_web3" } } } } } }, "responses": { "200": { "description": "Handle updated or removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string", "example": "Twitter handle updated successfully" } } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "message": { "type": "string" } } } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/profile.php?action=telegram": { "post": { "operationId": "profileUpdateTelegram", "summary": "Update Telegram handle", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "telegram" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Telegram username (1-100 chars, alphanumeric + underscores). Send empty string or null to remove.\n" } } } } } }, "responses": { "200": { "description": "Handle updated or removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string", "example": "Telegram handle updated successfully" } } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "message": { "type": "string" } } } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/profile.php?action=discord": { "post": { "operationId": "profileUpdateDiscord", "summary": "Update Discord username", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "discord" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Discord username (2-32 chars, lowercase alphanumeric + underscore + period, no consecutive periods) or legacy format (User#1234). Send empty string or null to remove.\n" } } } } } }, "responses": { "200": { "description": "Username updated or removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string", "example": "Discord updated successfully" } } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "message": { "type": "string" } } } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/profile.php?action=linkedin": { "post": { "operationId": "profileUpdateLinkedin", "summary": "Update LinkedIn profile URL", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "linkedin" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Full LinkedIn profile URL starting with `https://www.linkedin.com/in/` or `https://linkedin.com/in/`. Send empty string or null to remove.\n", "example": "https://www.linkedin.com/in/alice" } } } } } }, "responses": { "200": { "description": "Profile URL updated or removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string", "example": "LinkedIn profile updated successfully" } } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "message": { "type": "string" } } } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/profile.php?action=personal": { "post": { "operationId": "profileUpdatePersonal", "summary": "Update personal website URL", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "personal" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Any valid URL. Send empty string or null to remove.\n", "example": "https://alice.dev" } } } } } }, "responses": { "200": { "description": "Website URL updated or removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string", "example": "Personal website updated successfully" } } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "message": { "type": "string" } } } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/notifications.php?action=get_notifications": { "post": { "operationId": "notificationsGet", "summary": "Get paginated notifications", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "get_notifications" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer", "default": 1, "minimum": 1 }, "limit": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "auto_cleanup": { "type": "boolean", "default": false, "description": "When true, old notifications are automatically purged." } } } } } }, "responses": { "200": { "description": "Paginated notifications list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "notifications": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "origin": { "type": "string", "enum": [ "stack_follow", "price_movement", "transaction_deposit", "transaction_withdrawal", "transaction_buy", "transaction_sell", "creator_fee_received", "creator_note", "trending_stack", "stack_closed" ] }, "type": { "type": "string", "enum": [ "transaction", "system", "social", "trading", "achievement", "stack", "general" ] }, "content": { "type": "string" }, "read": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total_count": { "type": "integer" }, "total_pages": { "type": "integer" } } } } } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/notifications.php?action=get_unread_count": { "post": { "operationId": "notificationsUnreadCount", "summary": "Get unread notification count", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "get_unread_count" ] } } ], "responses": { "200": { "description": "Unread count.", "content": { "application/json": { "schema": { "type": "object", "required": [ "unread_count" ], "properties": { "unread_count": { "type": "integer", "example": 7 } } } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/notifications.php?action=mark_read": { "post": { "operationId": "notificationsMarkRead", "summary": "Mark a single notification as read", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "mark_read" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "notification_id" ], "properties": { "notification_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Notification marked as read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessMessage" } } } }, "400": { "description": "Missing or invalid notification_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Notification not found or does not belong to user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/notifications.php?action=dismiss_all": { "post": { "operationId": "notificationsDismissAll", "summary": "Dismiss all notifications", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "dismiss_all" ] } } ], "responses": { "200": { "description": "All notifications dismissed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessMessage" } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/notifications.php?action=delete": { "post": { "operationId": "notificationsDelete", "summary": "Delete a single notification", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "delete" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "notification_id" ], "properties": { "notification_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Notification deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessMessage" } } } }, "400": { "description": "Missing or invalid notification_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Notification not found or does not belong to user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/notifications.php?action=delete_all": { "post": { "operationId": "notificationsDeleteAll", "summary": "Delete all notifications", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "delete_all" ] } } ], "responses": { "200": { "description": "All notifications deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessMessage" } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/notification_preferences.php?action=get": { "post": { "operationId": "notificationPreferencesGet", "summary": "Get notification preferences", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "get" ] } } ], "responses": { "200": { "description": "List of notification type preferences.", "content": { "application/json": { "schema": { "type": "object", "required": [ "preferences" ], "properties": { "preferences": { "type": "array", "items": { "type": "object", "required": [ "notification_type", "enabled" ], "properties": { "notification_type": { "type": "string", "enum": [ "stack_follow", "price_movement", "transaction", "creator_fee", "creator_note", "trending_stack", "stack_closed" ] }, "enabled": { "type": "boolean" } } } } } } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/notification_preferences.php?action=update": { "post": { "operationId": "notificationPreferencesUpdate", "summary": "Update a single notification preference", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "update" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "notification_type", "enabled" ], "properties": { "notification_type": { "type": "string", "enum": [ "stack_follow", "price_movement", "transaction", "creator_fee", "creator_note", "trending_stack", "stack_closed" ] }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Preference updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessMessage" } } } }, "400": { "description": "Missing required fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/notification_preferences.php?action=update_bulk": { "post": { "operationId": "notificationPreferencesUpdateBulk", "summary": "Update multiple notification preferences at once", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "update_bulk" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "preferences" ], "properties": { "preferences": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "notification_type", "enabled" ], "properties": { "notification_type": { "type": "string", "enum": [ "stack_follow", "price_movement", "transaction", "creator_fee", "creator_note", "trending_stack", "stack_closed" ] }, "enabled": { "type": "boolean" } } } } } } } } }, "responses": { "200": { "description": "All preferences updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessMessage" } } } }, "400": { "description": "Missing or empty preferences array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/stack_info.php": { "post": { "tags": [ "Stacks" ], "summary": "Stack information, discovery, management, and holdings", "description": "Unified endpoint for all stack operations. The `action` query parameter selects the sub-operation. Request/response shapes vary by action.\n", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "paginated_list", "trending", "official", "related_stacks", "fetch", "my_stacks", "create", "update", "close", "edit_allocation", "version_history", "check_name", "check_description", "user_stack_holdings", "get_creator_holdings", "investors", "followers" ] }, "description": "The sub-action to invoke." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "paginated_list", "type": "object", "required": [ "limit", "offset" ], "properties": { "limit": { "type": "integer", "description": "Number of stacks to return." }, "offset": { "type": "integer", "description": "Pagination offset." }, "sort": { "type": "string", "enum": [ "change4H", "change1D", "change1W", "change1M", "changeAll", "newest", "oldest", "price", "mcap", "time_p", "stackIds" ], "description": "Sort field." }, "order": { "type": "string", "enum": [ "ASC", "DESC" ], "description": "Sort direction." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Filter by stack risk categories." }, "token_categories": { "type": "array", "items": { "type": "string" }, "description": "Filter by token categories." }, "token_categories_match_all": { "type": "boolean", "description": "When true, stack must contain tokens matching ALL listed token_categories." }, "following": { "type": "string", "enum": [ "all", "following", "not_following" ], "description": "Filter by follow status (requires auth)." }, "userIds": { "type": "array", "items": { "type": "integer" }, "description": "Filter by creator user IDs." }, "usernames": { "type": "array", "items": { "type": "string" }, "description": "Filter by creator usernames." }, "stackIds": { "type": "array", "items": { "type": "integer" }, "description": "Filter by specific stack IDs." }, "slugs": { "type": "array", "items": { "type": "string" }, "description": "Filter by stack slugs." }, "price_min": { "type": "number", "description": "Minimum stack price filter." }, "price_max": { "type": "number", "description": "Maximum stack price filter." }, "mcap_min": { "type": "number", "description": "Minimum weighted market cap filter." }, "mcap_max": { "type": "number", "description": "Maximum weighted market cap filter." }, "token_count_from": { "type": "integer", "description": "Minimum number of tokens in the stack." }, "archived": { "type": "boolean", "description": "Include archived stacks." }, "closed": { "type": "boolean", "description": "Include closed stacks." }, "tvl": { "type": "boolean", "description": "Include TVL (Total Value Locked) in response." }, "context": { "type": "string", "enum": [ "discovery", "portfolio", "trending", "my_stacks", "search", "admin", "auto" ], "description": "Response context hint. Defaults to auto." } } }, { "title": "trending", "type": "object", "properties": { "limit": { "type": "integer", "maximum": 50, "description": "Max results (capped at 50)." }, "offset": { "type": "integer", "description": "Pagination offset." }, "categories": { "type": "array", "items": { "type": "string" } }, "token_categories": { "type": "array", "items": { "type": "string" } }, "usernames": { "type": "array", "items": { "type": "string" } }, "userIds": { "type": "array", "items": { "type": "integer" } }, "following": { "type": "string", "enum": [ "all", "following", "not_following" ] }, "mcap_min": { "type": "number" }, "mcap_max": { "type": "number" }, "price_min": { "type": "number" }, "price_max": { "type": "number" }, "token_count_from": { "type": "integer" } } }, { "title": "official", "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "sort": { "type": "string" }, "order": { "type": "string", "enum": [ "ASC", "DESC" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "token_categories": { "type": "array", "items": { "type": "string" } } } }, { "title": "related_stacks", "type": "object", "required": [ "token_address" ], "properties": { "token_address": { "type": "string", "description": "Solana token address." }, "limit": { "type": "integer", "default": 10 }, "offset": { "type": "integer", "default": 0 } } }, { "title": "fetch", "type": "object", "properties": { "stackIds": { "type": "array", "items": { "type": "integer" } }, "slugs": { "type": "array", "items": { "type": "string" } }, "userIds": { "type": "array", "items": { "type": "integer" } }, "usernames": { "type": "array", "items": { "type": "string" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "sort": { "type": "string" }, "order": { "type": "string", "enum": [ "ASC", "DESC" ] }, "following": { "type": "string", "enum": [ "all", "following", "not_following" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "token_categories": { "type": "array", "items": { "type": "string" } }, "tvl": { "type": "boolean" }, "context": { "type": "string", "enum": [ "discovery", "portfolio", "trending", "my_stacks", "search", "admin", "auto" ] } } }, { "title": "my_stacks", "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "sort": { "type": "string" }, "order": { "type": "string", "enum": [ "ASC", "DESC" ] }, "following": { "type": "string", "enum": [ "all", "following", "not_following" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "token_categories": { "type": "array", "items": { "type": "string" } } } }, { "title": "create", "type": "object", "required": [ "stackName", "stackTokenInfo", "creatorFee", "description", "category", "socialLinks" ], "properties": { "stackName": { "type": "string", "description": "Display name for the stack." }, "stackTokenInfo": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Map of token address to weight (integer percentages that must sum to 100). Example: `{\"So11...\": 60, \"EPjF...\": 40}`.\n" }, "creatorFee": { "type": "number", "description": "Creator fee percentage (server-enforced min/max bounds)." }, "description": { "type": "string", "maxLength": 500, "description": "Stack description (max 500 characters)." }, "category": { "type": "string", "enum": [ "high_risk_short", "high_risk_long", "medium_risk_short", "medium_risk_long", "low_risk_short", "low_risk_long" ], "description": "Risk/duration category." }, "socialLinks": { "type": "object", "description": "Social media links associated with the stack." }, "showCreatorHoldings": { "type": "boolean", "description": "Whether to publicly display the creator's holdings. Defaults to false." } } }, { "title": "update", "type": "object", "required": [ "stack_id" ], "properties": { "stack_id": { "type": "integer", "description": "ID of the stack to update." }, "stackName": { "type": "string" }, "description": { "type": "string", "maxLength": 500 }, "category": { "type": "string", "enum": [ "high_risk_short", "high_risk_long", "medium_risk_short", "medium_risk_long", "low_risk_short", "low_risk_long" ] }, "showCreatorHoldings": { "type": "boolean" } } }, { "title": "close", "type": "object", "required": [ "stack_id" ], "properties": { "stack_id": { "type": "integer", "description": "ID of the stack to permanently close." }, "creator_note": { "type": "string", "description": "Optional note from the creator explaining the closure." } } }, { "title": "edit_allocation", "type": "object", "required": [ "stack_id", "stackTokenInfo" ], "properties": { "stack_id": { "type": "integer", "description": "ID of the stack to edit." }, "stackTokenInfo": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Map of token_address to weight (integer). Weights must sum to 100.", "example": { "So11111111111111111111111111111111111111112": 50, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v": 30, "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263": 20 } }, "creator_note": { "type": "string", "maxLength": 500, "description": "Optional note explaining the allocation change." } } }, { "title": "check_name", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Proposed stack name to validate." } } }, { "title": "check_description", "type": "object", "required": [ "description" ], "properties": { "description": { "type": "string", "description": "Proposed stack description to validate." } } }, { "title": "user_stack_holdings", "type": "object", "required": [ "stack_id" ], "properties": { "stack_id": { "type": "integer", "description": "Stack ID to retrieve authenticated user's holdings for." } } }, { "title": "get_creator_holdings", "type": "object", "required": [ "stack_id" ], "properties": { "stack_id": { "type": "integer", "description": "Stack ID to retrieve creator's holdings for." } } }, { "title": "investors", "type": "object", "required": [ "stack_id" ], "properties": { "stack_id": { "type": "integer" } } }, { "title": "followers", "type": "object", "required": [ "stack_id" ], "properties": { "stack_id": { "type": "integer" } } }, { "title": "version_history", "type": "object", "required": [ "stack_id" ], "properties": { "stack_id": { "type": "integer", "description": "ID of the stack to retrieve allocation version history for." } } } ] } } } }, "responses": { "200": { "description": "Successful response. Shape varies by action.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "PaginatedListResponse", "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StackObject" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } }, { "title": "StackArrayResponse", "type": "array", "items": { "$ref": "#/components/schemas/StackObject" } }, { "title": "RelatedStacksResponse", "type": "object", "properties": { "stacks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "stack_name": { "type": "string" }, "slug": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "avatar": { "type": "string", "nullable": true } } }, "price": { "type": "number" }, "change1D": { "type": "number", "nullable": true }, "weighted_market_cap": { "type": "number", "nullable": true }, "token_allocation_percentage": { "type": "number" }, "creator_fee": { "type": "number" } } } }, "total_count": { "type": "integer" } } }, { "title": "MyStacksResponse", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/StackObject" }, { "type": "object", "properties": { "metrics": { "type": "object", "properties": { "total_trades": { "type": "integer" }, "total_value_following": { "type": "number" }, "trading_volume": { "type": "number" }, "comments": { "type": "integer" }, "pct_returned": { "type": "number" }, "generated_fees": { "type": "number" } } } } } ] } }, { "title": "CreateResponse", "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "stack_id": { "type": "integer" } } }, { "title": "UpdateResponse", "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "stack_name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "topic": { "type": "string", "nullable": true }, "show_creator_holdings": { "type": "boolean" } } } } }, { "title": "CloseResponse", "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "stack_id": { "type": "integer" }, "stack_name": { "type": "string" }, "closed_at": { "type": "integer", "description": "Unix timestamp of closure." }, "close_price": { "type": "number" }, "creator_note": { "type": "string", "nullable": true }, "message": { "type": "string" } } }, { "title": "EditAllocationResponse", "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "stack_id": { "type": "integer" }, "version": { "type": "integer", "description": "The version number of the snapshot that was saved (previous allocation)." }, "nav": { "type": "number", "description": "The stack NAV at time of edit (unchanged before and after)." }, "message": { "type": "string", "example": "Stack allocation updated successfully" } } }, { "title": "NameCheckResponse", "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK", "TAKEN", "BADWORD", "INVALID" ] } } }, { "title": "DescriptionCheckResponse", "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK", "BADWORD", "INVALID" ] } } }, { "title": "HoldingsResponse", "type": "object", "properties": { "total_usdc": { "type": "number" }, "total_invested": { "type": "number" }, "total_cost_basis": { "type": "number" }, "stack_id": { "type": "integer" }, "amounts": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "object", "description": "Token metadata object." }, "total": { "type": "number", "description": "Raw token amount." }, "total_standard": { "type": "number", "description": "Human-readable token amount (adjusted for decimals)." }, "invested_usdc": { "type": "number" }, "usdc_value": { "type": "number" }, "avg_cost": { "type": "number" }, "realized_pnl": { "type": "number" }, "unrealized_pnl": { "type": "number" }, "total_pnl": { "type": "number" }, "unrealized_pnl_percent": { "type": "number", "nullable": true }, "total_pnl_percent": { "type": "number", "nullable": true }, "weight": { "type": "number" }, "is_verified": { "type": "boolean" } } } }, "pnl": { "type": "object", "properties": { "profit_loss": { "type": "number" }, "realized_pnl": { "type": "number" }, "unrealized_pnl": { "type": "number" }, "profit_loss_percent": { "type": "number", "nullable": true }, "unrealized_pnl_percent": { "type": "number", "nullable": true } } } } }, { "title": "InvestorsResponse", "type": "object", "properties": { "investor_count": { "type": "integer" } } }, { "title": "FollowersResponse", "type": "integer", "description": "Plain integer representing follower count." }, { "title": "VersionHistoryResponse", "type": "object", "properties": { "stack_id": { "type": "integer" }, "current_version": { "type": "integer", "description": "The latest (live) version number." }, "versions": { "type": "array", "description": "Version records in reverse-chronological order.", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "is_current": { "type": "boolean", "description": "True only for the live allocation." }, "created_at": { "type": "integer", "nullable": true, "description": "Unix timestamp of the edit. Null for current version." }, "creator_note": { "type": "string", "nullable": true, "description": "Note from the edit. Null for current and V1 on unedited stacks." }, "nav_at_edit": { "type": "number", "nullable": true, "description": "Stack price when this allocation was replaced. Null for current." }, "allocation": { "type": "array", "items": { "type": "object", "properties": { "token_id": { "type": "integer" }, "symbol": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "image_url": { "type": "string" }, "weight": { "type": "integer" }, "token_price": { "type": "number", "description": "Spot price at time of edit. Present on historical versions only." } } } }, "changes": { "type": "object", "nullable": true, "description": "Null for V1. For V2+, describes changes from previous version.", "properties": { "tokens_added": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "weight": { "type": "integer" } } } }, "tokens_removed": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "weight": { "type": "integer" } } } }, "weight_changes": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "previous_weight": { "type": "integer" }, "new_weight": { "type": "integer" } } } } } } } } } } } ] } } } }, "400": { "description": "Bad request (missing or invalid parameters).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (not the stack owner or insufficient permissions).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Stack or token not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/chat.php": { "post": { "tags": [ "Chat" ], "summary": "Stack chat messages and creator notes", "description": "Manage community messages and creator notes on a stack's chat. The `action` query parameter selects the sub-operation.\n", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "addMessage", "getAll", "togglePin" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "addMessage", "type": "object", "required": [ "stack_id", "message" ], "properties": { "stack_id": { "type": "integer", "description": "Stack whose chat to post to." }, "message": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Message body (1-1000 characters). HTML tags are stripped." }, "message_type": { "type": "string", "enum": [ "community", "creator_notes" ], "default": "community", "description": "Message type. `creator_notes` is restricted to the stack creator.\n" }, "pinned": { "type": "boolean", "default": false, "description": "Pin this message (creator_notes only). Unpins any previously pinned note." } } }, { "title": "getAll", "type": "object", "required": [ "stack_id" ], "properties": { "stack_id": { "type": "integer" }, "message_type": { "type": "string", "enum": [ "community", "creator_notes" ], "default": "community" }, "page": { "type": "integer", "minimum": 1, "default": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } }, { "title": "togglePin", "type": "object", "required": [ "message_id" ], "properties": { "message_id": { "type": "integer", "description": "ID of the creator note to pin or unpin." } } } ] } } } }, "responses": { "200": { "description": "Successful response. Shape varies by action.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "AddMessageResponse", "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "properties": { "id": { "type": "integer" }, "stack_id": { "type": "integer" }, "messages": { "type": "string", "description": "The message content." }, "message_type": { "type": "string", "enum": [ "community", "creator_notes" ] }, "pinned": { "type": "boolean" }, "created_at": { "type": "integer", "description": "Unix timestamp." }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "avatar": { "type": "string", "nullable": true } } } } } } }, { "title": "GetAllResponse", "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_next": { "type": "boolean" }, "has_prev": { "type": "boolean" } } }, "message_type_supported": { "type": "boolean" }, "pinned_notes": { "type": "array", "nullable": true, "description": "Only present when message_type is creator_notes. Contains pinned creator notes outside pagination.\n", "items": { "$ref": "#/components/schemas/ChatMessage" } } } }, { "title": "TogglePinResponse", "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message_id": { "type": "integer" }, "pinned": { "type": "boolean" } } } ] } } } }, "400": { "description": "Validation error (missing fields, message too long/short, etc.).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (not the stack creator for creator_notes / togglePin).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Chat or message not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/stack_wars.php": { "post": { "tags": [ "Stack Wars" ], "summary": "Stack wars listings and details", "description": "Public endpoint for viewing stack war competitions and their AI-generated summaries. Admin actions (create, ai-summary) are on a separate endpoint.\n", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "list", "detail" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "list", "description": "No request body required.", "type": "object" }, { "title": "detail", "type": "object", "required": [ "stack_war_id" ], "properties": { "stack_war_id": { "type": "integer", "description": "ID of the stack war to retrieve." } } } ] } } } }, "responses": { "200": { "description": "Successful response. Shape varies by action.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "ListResponse", "type": "object", "properties": { "stack_wars": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "participant_count": { "type": "integer" }, "status": { "type": "string", "enum": [ "upcoming", "active", "completed" ] }, "start_time": { "type": "integer", "description": "Unix timestamp." }, "end_time": { "type": "integer", "description": "Unix timestamp." }, "has_ai_summary": { "type": "boolean" }, "current_leader": { "type": "string", "nullable": true }, "created_at": { "type": "integer", "description": "Unix timestamp." } } } }, "total": { "type": "integer" }, "active_count": { "type": "integer" }, "upcoming_count": { "type": "integer" } } }, { "title": "DetailResponse", "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "participant_stack_ids": { "type": "array", "items": { "type": "integer" } }, "participant_count": { "type": "integer" }, "status": { "type": "string", "enum": [ "upcoming", "active", "completed" ] }, "start_time": { "type": "integer", "description": "Unix timestamp." }, "end_time": { "type": "integer", "description": "Unix timestamp." }, "created_at": { "type": "integer", "description": "Unix timestamp." }, "updated_at": { "type": "integer", "nullable": true, "description": "Unix timestamp." }, "ai_summary": { "type": "string", "nullable": true, "description": "AI-generated markdown summary of the war." }, "analyzed_at": { "type": "integer", "nullable": true, "description": "Unix timestamp of last AI analysis." }, "data_points_analyzed": { "type": "integer", "nullable": true }, "participant_stacks": { "type": "array", "items": { "$ref": "#/components/schemas/StackObject" } } } } ] } } } }, "400": { "description": "Missing or invalid stack_war_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Stack war not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/token_info.php": { "post": { "tags": [ "Tokens" ], "summary": "Token search, details, listings, categories, and following", "description": "Unified endpoint for all token information operations. The `action` query parameter selects the sub-operation.\n", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "search", "new", "detail", "list", "paginated_list", "fetch", "categories", "follow", "followers" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "search", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Search query (token name or symbol)." }, "exclusions": { "type": "array", "items": { "type": "string" }, "description": "Token addresses to exclude from results." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Filter by token categories." } } }, { "title": "new", "type": "object", "required": [ "token_address" ], "properties": { "token_address": { "type": "string", "description": "Solana token mint address to add." } } }, { "title": "detail", "type": "object", "required": [ "token_address" ], "properties": { "token_address": { "type": "string", "description": "Solana token mint address." } } }, { "title": "list", "type": "object", "properties": { "limit": { "type": "integer", "default": 50 }, "offset": { "type": "integer", "default": 0 }, "sort": { "type": "string", "enum": [ "id", "name", "symbol", "price", "market_cap", "volume_24h", "change4H", "change1D", "change1W", "change1M", "changeAll" ], "description": "Sort field." }, "order": { "type": "string", "enum": [ "ASC", "DESC" ] }, "search": { "type": "string", "description": "Free-text name/symbol filter." }, "following": { "type": "string", "enum": [ "all", "following", "not_following" ], "description": "Filter by follow status (requires auth)." }, "categories": { "type": "array", "items": { "type": "string" } }, "include_unverified": { "type": "boolean", "description": "Include tokens without a CoinGecko ID." }, "price_min": { "type": "number" }, "price_max": { "type": "number" }, "mcap_min": { "type": "number" }, "mcap_max": { "type": "number" }, "volume_min": { "type": "number" }, "volume_max": { "type": "number" } } }, { "title": "paginated_list", "description": "Same parameters as list; returns paginated wrapper.", "type": "object", "properties": { "limit": { "type": "integer", "default": 50 }, "offset": { "type": "integer", "default": 0 }, "sort": { "type": "string", "enum": [ "id", "name", "symbol", "price", "market_cap", "volume_24h", "change4H", "change1D", "change1W", "change1M", "changeAll" ] }, "order": { "type": "string", "enum": [ "ASC", "DESC" ] }, "search": { "type": "string" }, "following": { "type": "string", "enum": [ "all", "following", "not_following" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "include_unverified": { "type": "boolean" }, "price_min": { "type": "number" }, "price_max": { "type": "number" }, "mcap_min": { "type": "number" }, "mcap_max": { "type": "number" }, "volume_min": { "type": "number" }, "volume_max": { "type": "number" } } }, { "title": "fetch", "description": "Alias for list.", "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "sort": { "type": "string" }, "order": { "type": "string", "enum": [ "ASC", "DESC" ] }, "search": { "type": "string" }, "following": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "include_unverified": { "type": "boolean" }, "price_min": { "type": "number" }, "price_max": { "type": "number" }, "mcap_min": { "type": "number" }, "mcap_max": { "type": "number" }, "volume_min": { "type": "number" }, "volume_max": { "type": "number" } } }, { "title": "categories", "description": "No request body required.", "type": "object" }, { "title": "follow", "type": "object", "required": [ "token_address" ], "properties": { "token_address": { "type": "string", "description": "Solana token address to follow/unfollow (toggle)." } } }, { "title": "followers", "type": "object", "required": [ "token_address" ], "properties": { "token_address": { "type": "string" } } } ] } } } }, "responses": { "200": { "description": "Successful response. Shape varies by action.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "SearchResponse", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "icon": { "type": "string", "nullable": true }, "symbol": { "type": "string" }, "is_verified": { "type": "boolean" } } } }, { "title": "NewTokenResponse", "type": "object", "properties": { "token_address": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "image_url": { "type": "string", "nullable": true }, "decimals": { "type": "integer" }, "pool_address": { "type": "string", "nullable": true }, "cg_id": { "type": "string", "nullable": true } } }, { "title": "TokenDetailResponse", "type": "object", "properties": { "address": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "image_url": { "type": "string", "nullable": true }, "decimals": { "type": "integer" }, "pool_address": { "type": "string", "nullable": true }, "price": { "type": "number", "nullable": true }, "market_cap": { "type": "string", "nullable": true, "description": "Market cap as a string (may be very large)." }, "volume_24h": { "type": "string", "nullable": true }, "change4H": { "type": "number", "nullable": true }, "change1D": { "type": "number", "nullable": true }, "change1W": { "type": "number", "nullable": true }, "change1M": { "type": "number", "nullable": true }, "changeAll": { "type": "number", "nullable": true }, "chain": { "type": "string", "example": "solana" }, "description": { "type": "string", "nullable": true }, "categories": { "type": "array", "items": { "type": "string" } }, "is_verified": { "type": "boolean" }, "archived": { "type": "boolean" }, "user_has_held": { "type": "boolean", "description": "Whether the authenticated user has ever held this token. False when unauthenticated." }, "user_following": { "type": "boolean", "description": "Whether the authenticated user follows this token. False when unauthenticated." }, "socials": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "url": { "type": "string" } } } } } }, { "title": "TokenListResponse", "type": "array", "items": { "$ref": "#/components/schemas/TokenObject" } }, { "title": "TokenPaginatedListResponse", "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TokenObject" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } }, { "title": "CategoriesResponse", "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "token_count": { "type": "integer" } } } }, { "title": "FollowResponse", "type": "object", "properties": { "following": { "type": "boolean" }, "message": { "type": "string" } } }, { "title": "TokenFollowersResponse", "type": "object", "properties": { "followers": { "type": "integer" }, "is_following": { "type": "boolean", "description": "Whether the authenticated user follows this token. False when unauthenticated." }, "success": { "type": "string", "example": "success" } } } ] } } } }, "400": { "description": "Missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Token not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/token_trading.php": { "post": { "tags": [ "Token Trading" ], "summary": "Token trading info and company stack statistics", "description": "Provides trading readiness information for tokens (ensuring a company stack exists) and aggregate company stack statistics.\n", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "get_trading_info", "get_company_stats" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "get_trading_info", "type": "object", "description": "At least one of token_address or token_id is required.\n", "properties": { "token_address": { "type": "string", "description": "Solana token mint address." }, "token_id": { "type": "integer", "description": "Internal token ID." } } }, { "title": "get_company_stats", "description": "No request body required.", "type": "object" } ] } } } }, "responses": { "200": { "description": "Successful response. Shape varies by action.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "TradingInfoResponse", "type": "object", "properties": { "company_stack_id": { "type": "integer", "description": "ID of the company stack for this token." }, "token": { "type": "object", "properties": { "id": { "type": "integer" }, "chain": { "type": "string" }, "symbol": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "notes": { "type": "string", "nullable": true }, "image_url": { "type": "string", "nullable": true }, "pool_address": { "type": "string", "nullable": true }, "decimals": { "type": "integer" }, "cg_id": { "type": "string", "nullable": true }, "archived": { "type": "boolean" }, "last_updated": { "type": "string", "nullable": true } } }, "trading_enabled": { "type": "boolean", "example": true }, "display_name": { "type": "string" }, "stack_name": { "type": "string" }, "slug": { "type": "string", "nullable": true }, "message": { "type": "string", "example": "Token ready for trading" } } }, { "title": "CompanyStatsResponse", "type": "object", "properties": { "total_company_stacks": { "type": "integer" } } } ] } } } }, "400": { "description": "Missing token_address and token_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Token not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to prepare token for trading.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/txn.php": { "post": { "tags": [ "Trading" ], "summary": "Trading and wallet operations", "operationId": "tradingOperations", "description": "Handles all trading actions (swap, balance inquiries, withdrawals, key export). The specific operation is selected via the `action` query parameter. All actions require authentication.\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "swap", "rebalance", "balance", "usdc_balance", "total_balance", "address", "withdraw_usdc", "export_key" ] }, "description": "The trading action to perform." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "SwapRequest", "type": "object", "required": [ "stack_id", "amount", "cue" ], "properties": { "stack_id": { "type": "integer", "description": "ID of the stack to trade." }, "amount": { "type": "number", "description": "For buys (cue=fromUSDC): USDC amount to spend. For sells (cue=toUSDC): percentage of holdings to sell (1-100).\n" }, "cue": { "type": "string", "enum": [ "fromUSDC", "toUSDC" ], "description": "Direction of the swap." } } }, { "title": "RebalanceRequest", "type": "object", "required": [ "stack_id" ], "properties": { "stack_id": { "type": "integer", "description": "ID of the stack to rebalance holdings for." } } }, { "title": "WithdrawUsdcRequest", "type": "object", "required": [ "address", "amount", "verification_code" ], "properties": { "address": { "type": "string", "description": "Destination wallet address." }, "amount": { "type": "number", "description": "USDC amount to withdraw." }, "verification_code": { "type": "string", "description": "SMS verification code." } } }, { "title": "ExportKeyRequest", "type": "object", "required": [ "verification_code", "has_acknowledged_risk" ], "properties": { "verification_code": { "type": "string", "description": "SMS verification code." }, "has_acknowledged_risk": { "type": "boolean", "enum": [ true ], "description": "Must be true to confirm risk acknowledgment." } } } ] } } } }, "responses": { "200": { "description": "Successful response. Shape depends on action.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "SwapResponse", "type": "object", "properties": { "order_id": { "type": "string", "description": "Unique identifier for the created order." } } }, { "title": "RebalanceResponse", "type": "object", "properties": { "rebalance_id": { "type": "string", "description": "Unique identifier for the rebalance operation." }, "sell_order_id": { "type": "string", "description": "Order ID for the sell phase." }, "buy_order_id": { "type": "string", "description": "Order ID for buy-only rebalance (when no sells needed)." }, "status": { "type": "string", "enum": [ "SELLING", "BUYING" ], "description": "Current rebalance phase." }, "sells_count": { "type": "integer", "description": "Number of sell swaps initiated." }, "buys_count": { "type": "integer", "description": "Number of buy swaps planned." }, "total_portfolio_value_usdc": { "type": "number", "description": "Total portfolio value in USDC at rebalance time." }, "allocation_version": { "type": "integer", "description": "Target allocation version number." } } }, { "title": "BalanceResponse", "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string", "description": "Token mint address." }, "amount": { "type": "number", "description": "Token balance as a number." }, "amountString": { "type": "string", "description": "Token balance as a string." }, "decimals": { "type": "integer", "description": "Token decimal places." } } } }, { "title": "UsdcBalanceResponse", "type": "object", "properties": { "balance": { "type": "number", "description": "USDC balance." } } }, { "title": "TotalBalanceResponse", "type": "object", "properties": { "total_balance": { "type": "string", "description": "Total portfolio balance in USDC." } } }, { "title": "AddressResponse", "type": "object", "properties": { "pubkey": { "type": "string", "description": "Wallet public key." } } }, { "title": "WithdrawUsdcResponse", "type": "object", "description": "Transaction details for the withdrawal." }, { "title": "ExportKeyResponse", "type": "object", "properties": { "byte_array": { "type": "array", "items": { "type": "integer" }, "description": "Private key as byte array." }, "base_58": { "type": "string", "description": "Private key in Base58 encoding." } } } ] } } } }, "400": { "description": "Bad request (missing fields, invalid parameters, insufficient balance, etc.).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Stack not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (rebalance already in progress).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/orders.php": { "post": { "tags": [ "Trading" ], "summary": "Order management", "description": "Provides order details, partial order handling, retry, sell-all, and retry chain lookups. All actions require authentication and an `order_id` in the request body.\n", "operationId": "manageOrder", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "details", "status", "partial_details", "acknowledge", "retry", "sell_all", "retry_chain" ], "default": "details" }, "description": "The order action to perform. Defaults to `details`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "OrderIdRequest", "type": "object", "required": [ "order_id" ], "properties": { "order_id": { "type": "string", "description": "Unique order identifier." } } }, { "title": "RetryRequest", "type": "object", "required": [ "order_id" ], "properties": { "order_id": { "type": "string", "description": "Unique order identifier." }, "slippage": { "type": "integer", "minimum": 1, "maximum": 51, "description": "Custom slippage tolerance for the retry (optional)." } } } ] } } } }, "responses": { "200": { "description": "Successful response. Shape depends on action.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "OrderDetailsResponse", "type": "object", "properties": { "order": { "type": "object", "properties": { "order_id": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "SUCCESS", "FAILED", "PARTIAL" ] }, "type": { "type": "string", "enum": [ "fromUSDC", "toUSDC" ] }, "created_at": { "type": "string" }, "partial_completion_action": { "type": "string", "nullable": true } } }, "transactions": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": "string" }, "success": { "type": "boolean" }, "txn_hash": { "type": "string", "nullable": true } } } }, "transaction_count": { "type": "integer" } } }, { "title": "PartialDetailsResponse", "type": "object", "properties": { "order_id": { "type": "string" }, "order_info": { "type": "object", "description": "Detailed order metadata." }, "stack_info": { "type": "object", "properties": { "id": { "type": "integer" }, "stack_name": { "type": "string" }, "slug": { "type": "string" } } }, "successful_tokens": { "type": "array", "items": { "type": "object" } }, "failed_tokens": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "object", "properties": { "total_tokens_in_stack": { "type": "integer" }, "successful_token_count": { "type": "integer" }, "failed_token_count": { "type": "integer" }, "success_rate": { "type": "number" } } }, "available_actions": { "type": "object", "properties": { "acknowledge": { "type": "boolean" }, "retry": { "type": "boolean" }, "sell_all": { "type": "boolean" } } } } }, { "title": "AcknowledgeResponse", "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "order_id": { "type": "string" } } }, { "title": "RetryResponse", "type": "object", "properties": { "order_id": { "type": "string" }, "stack_id": { "type": "integer" }, "parent_order_id": { "type": "string" }, "retry_attempt": { "type": "integer" }, "failed_tokens_attempted": { "type": "integer" }, "status": { "type": "string" } } }, { "title": "SellAllResponse", "type": "object", "properties": { "order_id": { "type": "string" }, "stack_id": { "type": "integer" } } }, { "title": "RetryChainResponse", "type": "object", "properties": { "order_id": { "type": "string" }, "retry_chain": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": "string" }, "parent_order_id": { "type": "string", "nullable": true }, "retry_attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "PENDING", "SUCCESS", "FAILED", "PARTIAL" ] }, "type": { "type": "string", "enum": [ "fromUSDC", "toUSDC" ] }, "created_at": { "type": "string" }, "partial_completion_action": { "type": "string", "nullable": true } } } }, "total_attempts": { "type": "integer" } } } ] } } } }, "400": { "description": "Bad request (missing order_id, invalid slippage, invalid action, etc.).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Order not found or not owned by the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/user_orders.php": { "post": { "tags": [ "Trading" ], "summary": "List authenticated user's orders", "description": "Returns a paginated list of all orders for the authenticated user.", "operationId": "listUserOrders", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Pagination offset." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 100 }, "description": "Number of orders to return." } ], "responses": { "200": { "description": "Paginated list of user orders.", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": "string" }, "stack_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "fromUSDC", "toUSDC" ] }, "status": { "type": "string", "enum": [ "PENDING", "SUCCESS", "FAILED", "PARTIAL" ] }, "created_at": { "type": "string" }, "parent_order_id": { "type": "string", "nullable": true }, "retry_attempt": { "type": "integer", "nullable": true }, "partial_completion_action": { "type": "string", "nullable": true }, "stack_name": { "type": "string", "nullable": true }, "stack_symbol": { "type": "string", "nullable": true } } } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer" }, "limit": { "type": "integer" }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_pages": { "type": "integer" } } } } } } } }, "400": { "description": "Invalid pagination parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/stack_partial_orders.php": { "post": { "tags": [ "Trading" ], "summary": "List outstanding partial orders for a stack", "description": "Returns a paginated list of the authenticated user's outstanding partial orders (status=PARTIAL, partial_completion_action=pending) for a given stack.\n", "operationId": "listStackPartialOrders", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "stack_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "ID of the stack to query." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Pagination offset." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 100 }, "description": "Number of orders to return." } ], "responses": { "200": { "description": "Paginated list of outstanding partial orders.", "content": { "application/json": { "schema": { "type": "object", "properties": { "stack": { "type": "object", "properties": { "id": { "type": "integer" }, "stack_name": { "type": "string" }, "stack_token_name": { "type": "string" } } }, "outstanding_partial_orders": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": "string" }, "user_id": { "type": "integer" }, "stack_id": { "type": "integer" }, "type": { "type": "string" }, "status": { "type": "string" }, "usdc_amount": { "type": "number" }, "creator_fee": { "type": "number" }, "platform_fee": { "type": "number" }, "expected_amount": { "type": "number", "nullable": true }, "created_at": { "type": "string" }, "parent_order_id": { "type": "string", "nullable": true }, "retry_attempt": { "type": "integer", "nullable": true }, "partial_completion_action": { "type": "string" }, "username": { "type": "string", "nullable": true } } } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer" }, "limit": { "type": "integer" }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_pages": { "type": "integer" } } } } } } } }, "400": { "description": "Missing or invalid stack_id, invalid pagination parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Stack not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/transaction_history.php": { "get": { "tags": [ "Trading" ], "summary": "Transaction history", "description": "Retrieve the authenticated user's transaction history, a single transaction detail, or a transaction summary. The specific operation is selected via the `action` query parameter.\n", "operationId": "getTransactionHistory", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "list", "detail", "summary" ], "default": "list" }, "description": "The history action to perform." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Pagination offset (action=list only)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Number of transactions to return (action=list only)." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "buy", "sell", "deposit", "withdrawal" ] }, "description": "Filter by transaction type (action=list only)." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "PROCESSING", "SUCCESS", "FAILED", "PARTIAL" ] }, "description": "Filter by transaction status (action=list only)." }, { "name": "stack_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filter by stack ID (action=list only). Cannot be combined with token_address." }, { "name": "token_address", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by token address (action=list only). Cannot be combined with stack_id." }, { "name": "order_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Order ID to look up (action=detail only, required for detail)." } ], "responses": { "200": { "description": "Successful response. Shape depends on action.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "TransactionListResponse", "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": "string" }, "stack_id": { "type": "integer", "nullable": true }, "transaction_type": { "type": "string", "enum": [ "buy", "sell", "deposit", "withdrawal" ] }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "SUCCESS", "FAILED", "PARTIAL" ] }, "usdc_amount": { "type": "number" }, "expected_amount": { "type": "number", "nullable": true }, "sell_percentage": { "type": "number", "nullable": true }, "slippage": { "type": "number", "nullable": true }, "creator_fee": { "type": "number", "nullable": true }, "platform_fee": { "type": "number", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string", "nullable": true }, "parent_order_id": { "type": "string", "nullable": true }, "retry_attempt": { "type": "integer", "nullable": true }, "partial_completion_action": { "type": "string", "nullable": true }, "is_company_stack": { "type": "boolean" }, "asset": { "type": "object", "nullable": true, "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string", "nullable": true }, "symbol": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "image_url": { "type": "string", "nullable": true }, "archived": { "type": "boolean" } } }, "tokens": { "type": "array", "items": { "type": "object" } }, "transaction_hash": { "type": "string", "nullable": true }, "from_wallet": { "type": "string", "nullable": true, "description": "Present for deposits/withdrawals only." }, "to_wallet": { "type": "string", "nullable": true, "description": "Present for deposits/withdrawals only." }, "block_slot": { "type": "integer", "nullable": true, "description": "Present for deposits/withdrawals only." } } } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer" }, "limit": { "type": "integer" }, "total_count": { "type": "integer" }, "has_more": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" } } } } }, { "title": "TransactionDetailResponse", "type": "object", "properties": { "transaction": { "type": "object", "description": "Same fields as list items, plus a `token_transactions` array with per-token breakdown.\n", "properties": { "order_id": { "type": "string" }, "token_transactions": { "type": "array", "items": { "type": "object", "properties": { "token_id": { "type": "integer" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "address": { "type": "string" }, "image_url": { "type": "string", "nullable": true }, "amount": { "type": "number" }, "usdc_paid": { "type": "number" }, "decimals": { "type": "integer" }, "archived": { "type": "boolean" } } } } } } } }, { "title": "TransactionSummaryResponse", "type": "object", "properties": { "summary": { "type": "object", "properties": { "total_transactions": { "type": "integer" }, "total_buys": { "type": "integer" }, "total_sells": { "type": "integer" }, "total_deposits": { "type": "integer" }, "total_withdrawals": { "type": "integer" }, "successful_transactions": { "type": "integer" }, "failed_transactions": { "type": "integer" }, "pending_transactions": { "type": "integer" } } } } } ] } } } }, "400": { "description": "Bad request (invalid filters, missing order_id for detail, conflicting filters).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Transaction not found (action=detail).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed (only GET is accepted).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/fee.php": { "post": { "tags": [ "Trading" ], "summary": "Fee calculations and bounds", "description": "Calculate trading fees, retrieve minimum buy amount, or get creator fee bounds. No authentication required.\n", "operationId": "feeOperations", "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "calculate", "min_buy", "creator_fee_bounds" ] }, "description": "The fee action to perform." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "title": "CalculateFeeRequest", "type": "object", "required": [ "amount", "stack_id" ], "properties": { "amount": { "type": "number", "description": "USDC amount to calculate fees for." }, "stack_id": { "type": "integer", "description": "ID of the stack being traded." } } } ] } } } }, "responses": { "200": { "description": "Successful response. Shape depends on action.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "CalculateFeeResponse", "type": "object", "properties": { "fee_display": { "type": "string", "description": "Human-readable fee string (e.g. \"~$1.50 fee\")." }, "estimated_blockchain_fees_saved": { "type": "string", "description": "Estimated blockchain fees saved (e.g. \"$2.40\")." } } }, { "title": "MinBuyResponse", "type": "object", "properties": { "min_buy": { "type": "number", "description": "Minimum buy amount in micro-USDC." } } }, { "title": "CreatorFeeBoundsResponse", "type": "object", "properties": { "min": { "type": "number", "description": "Minimum creator fee percentage." }, "max": { "type": "number", "description": "Maximum creator fee percentage." }, "default": { "type": "number", "description": "Default creator fee percentage." } } } ] } } } }, "400": { "description": "Bad request (missing amount, invalid stack ID, amount below minimum).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/subscription.php": { "post": { "tags": [ "Social" ], "summary": "Stack and user follow/unfollow operations", "description": "Manage stack subscriptions and user follow relationships. Auth requirements vary by action.\n", "operationId": "subscriptionOperations", "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "followers", "follow", "unfollow", "follow_user", "unfollow_user", "user_followers", "user_following", "user_follow_status" ] }, "description": "The subscription action to perform." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "StackFollowRequest", "description": "Used for `followers`, `follow`, and `unfollow` actions.", "type": "object", "required": [ "stack_id" ], "properties": { "stack_id": { "type": "integer", "description": "ID of the stack." } } }, { "title": "UserFollowRequest", "description": "Used for `follow_user`, `unfollow_user`, `user_followers`, `user_following`, and `user_follow_status` actions.\n", "type": "object", "required": [ "username" ], "properties": { "username": { "type": "string", "description": "Username of the target user." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20, "description": "Number of items to return (user_followers / user_following only).\n" }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Pagination offset (user_followers / user_following only).\n" } } } ] } } } }, "responses": { "200": { "description": "Successful response. Shape depends on action.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "FollowersResponse", "description": "Response for `followers` action. Auth required.", "type": "object", "properties": { "followers": { "type": "integer", "description": "Total follower count for the stack." }, "is_following": { "type": "boolean", "description": "Whether the authenticated user follows this stack." }, "success": { "type": "string", "example": "success" } } }, { "title": "FollowResponse", "description": "Response for `follow` action. Auth required.", "type": "object", "properties": { "success": { "type": "string", "example": "followed" } } }, { "title": "UnfollowResponse", "description": "Response for `unfollow` action. Auth required.", "type": "object", "properties": { "success": { "type": "string", "example": "unfollowed" } } }, { "title": "FollowUserResponse", "description": "Response for `follow_user` action. Auth required.", "type": "object", "properties": { "success": { "type": "string", "example": "followed" } } }, { "title": "UnfollowUserResponse", "description": "Response for `unfollow_user` action. Auth required.", "type": "object", "properties": { "success": { "type": "string", "example": "unfollowed" } } }, { "title": "UserFollowersResponse", "description": "Response for `user_followers` action. Auth optional.", "type": "object", "properties": { "follower_count": { "type": "integer" }, "is_following": { "type": "boolean", "description": "Whether the authenticated user follows this user (false if unauthenticated)." }, "followers": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "avatar": { "type": "string", "nullable": true } } } }, "success": { "type": "string", "example": "success" } } }, { "title": "UserFollowingResponse", "description": "Response for `user_following` action. No auth required.", "type": "object", "properties": { "following_count": { "type": "integer" }, "following": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "avatar": { "type": "string", "nullable": true } } } }, "success": { "type": "string", "example": "success" } } }, { "title": "UserFollowStatusResponse", "description": "Response for `user_follow_status` action. Auth required.", "type": "object", "properties": { "is_following": { "type": "boolean" }, "follows_back": { "type": "boolean" }, "success": { "type": "string", "example": "success" } } } ] } } } }, "400": { "description": "Bad request (missing fields, already following, not following, user not found, etc.).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/user_info.php?action=leaderboard": { "get": { "tags": [ "Social" ], "summary": "Creator leaderboard", "description": "Returns a ranked list of creators sorted by the chosen metric. Authentication is optional; when authenticated, `is_following` is populated for each creator.\n", "operationId": "getLeaderboard", "security": [ { "ApiKeyAuth": [] }, {} ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "leaderboard" ] } }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "4h", "7d", "30d", "3m", "all", "ath" ], "default": "7d" }, "description": "Time period for leaderboard metrics." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100 }, "description": "Number of creators to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Pagination offset." }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "points", "pnl", "stacks_created", "last_activity", "stack_trades", "hit_rate", "best_stack_ath" ], "default": "points" }, "description": "Metric to sort creators by." } ], "responses": { "200": { "description": "Leaderboard data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "creators": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "username": { "type": "string" }, "avatar": { "type": "string", "nullable": true }, "stacks_created": { "type": "integer" }, "stack_trades": { "type": "integer" }, "hit_rate": { "type": "number", "nullable": true }, "best_stack_ath": { "type": "number", "nullable": true }, "combined_pnl": { "type": "number", "nullable": true }, "points": { "type": "number" }, "last_activity": { "type": "string", "nullable": true }, "last_accessed": { "type": "string", "nullable": true }, "last_active": { "type": "string", "nullable": true }, "top_stack": { "type": "object", "nullable": true }, "follower_count": { "type": "integer" }, "is_following": { "type": "boolean", "nullable": true } } } }, "pagination": { "type": "object", "properties": { "total_count": { "type": "integer" }, "has_next": { "type": "boolean" }, "offset": { "type": "integer" }, "limit": { "type": "integer" } } }, "metadata": { "type": "object", "properties": { "period": { "type": "string" }, "sort_by": { "type": "string" }, "updated_at": { "type": "string", "nullable": true }, "source": { "type": "string", "description": "Cache source (redis, db, realtime)." } } } } } } } }, "400": { "description": "Invalid sort_by parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/user_info.php?action=top_creators": { "post": { "tags": [ "Social" ], "summary": "Top creators", "description": "Returns up to 5 top creators with their stack and follower counts. Authentication is optional; when authenticated, `is_following` is populated.\n", "operationId": "getTopCreators", "security": [ { "ApiKeyAuth": [] }, {} ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "top_creators" ] } } ], "responses": { "200": { "description": "Array of top creators.", "content": { "application/json": { "schema": { "type": "array", "maxItems": 5, "items": { "type": "object", "properties": { "username": { "type": "string" }, "avatar": { "type": "string", "nullable": true }, "stack_count": { "type": "integer" }, "follower_count": { "type": "integer" }, "is_following": { "type": "boolean", "nullable": true } } } } } } } } } }, "/api/user_info.php?action=public_profile": { "post": { "tags": [ "Social" ], "summary": "Public user profile", "description": "Returns a user's public profile information. No authentication required.\n", "operationId": "getPublicProfile", "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "public_profile" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username" ], "properties": { "username": { "type": "string", "description": "Username to look up." } } } } } }, "responses": { "200": { "description": "Public profile data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string" }, "avatar": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "slippage": { "type": "number", "nullable": true }, "priority_fee": { "type": "number", "nullable": true }, "telegram": { "type": "string", "nullable": true }, "discord": { "type": "string", "nullable": true }, "twitter": { "type": "string", "nullable": true }, "linkedin": { "type": "string", "nullable": true }, "personal": { "type": "string", "nullable": true } } } } } }, "404": { "description": "User not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/user_info.php?action=public_profile_metrics": { "post": { "tags": [ "Social" ], "summary": "Public user profile metrics", "description": "Returns a user's public profile performance metrics. No authentication required.\n", "operationId": "getPublicProfileMetrics", "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "public_profile_metrics" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username" ], "properties": { "username": { "type": "string", "description": "Username to look up." } } } } } }, "responses": { "200": { "description": "Public profile metrics data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "best_stack_ath": { "type": "number", "nullable": true }, "hit_rate": { "type": "number", "nullable": true }, "combined_pnl": { "type": "number", "nullable": true }, "followers": { "type": "integer" }, "stack_count": { "type": "integer" }, "points": { "type": "number", "nullable": true } } } } } }, "404": { "description": "User not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/refer.php": { "post": { "tags": [ "Social" ], "summary": "Generate a referral link", "description": "Creates a new referral link with an auto-generated access code for the authenticated user.\n", "operationId": "generateReferralLink", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "referral_code" ], "properties": { "referral_code": { "type": "string", "description": "The referral code to embed in the link." } } } } } }, "responses": { "200": { "description": "Referral link created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "referral_link": { "type": "string", "description": "Full referral URL." }, "access_code": { "type": "string", "description": "Generated early-access code." }, "access_code_name": { "type": "string", "description": "Descriptive name of the access code." }, "referral_code": { "type": "string", "description": "The referral code that was provided." }, "expires_at": { "type": "string", "description": "Expiration timestamp of the access code." } } } } } }, "400": { "description": "Missing referral_code or invalid body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "User not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed (only POST is accepted).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/referrals.php": { "get": { "tags": [ "Social" ], "summary": "Get referral data", "description": "Returns the authenticated user's multi-level referral tree with volume data for each referred user.\n", "operationId": "getReferrals", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Multi-level referral data with volume statistics.", "content": { "application/json": { "schema": { "type": "object", "properties": { "level1": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "volume_data": { "$ref": "#/components/schemas/ReferralVolumeData" } } } }, "level2": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "volume_data": { "$ref": "#/components/schemas/ReferralVolumeData" } } } }, "level3": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "volume_data": { "$ref": "#/components/schemas/ReferralVolumeData" } } } }, "summary": { "type": "object", "properties": { "total_referrals": { "type": "integer" }, "total_volume_usdc": { "type": "number" }, "total_platform_fees_usdc": { "type": "number" }, "total_successful_orders": { "type": "integer" }, "by_level": { "type": "object", "additionalProperties": { "type": "object", "properties": { "count": { "type": "integer" }, "total_volume_usdc": { "type": "number" }, "total_platform_fees_usdc": { "type": "number" }, "total_successful_orders": { "type": "integer" } } } } } }, "pagination": { "type": "object", "description": "Pagination metadata from the incentive service." } } } } } }, "401": { "description": "User not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "User not found or username not set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed (only GET is accepted).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/bulk_stack_stats.php": { "post": { "tags": [ "Market Data" ], "summary": "Bulk stack price stats", "description": "Returns current prices and percentage change stats for up to 1000 stacks. No authentication required.\n", "operationId": "getBulkStackStats", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "stack_ids" ], "properties": { "stack_ids": { "type": "array", "items": { "type": "integer" }, "maxItems": 1000, "description": "Array of stack IDs (max 1000)." } } } } } }, "responses": { "200": { "description": "Array of stack stats in the same order as the input.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "stack_id": { "type": "integer" }, "found": { "type": "boolean" }, "price": { "type": "number", "nullable": true, "description": "Current stack price. Present only when found=true." }, "stats": { "type": "object", "nullable": true, "description": "Percentage change stats. Present only when found=true.", "properties": { "change4H": { "type": "number", "nullable": true }, "change1D": { "type": "number", "nullable": true }, "change1W": { "type": "number", "nullable": true }, "change1M": { "type": "number", "nullable": true }, "changeAll": { "type": "number", "nullable": true } } } } } } } } }, "400": { "description": "Invalid input (missing or empty stack_ids, exceeds 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/bulk_token_stats.php": { "post": { "tags": [ "Market Data" ], "summary": "Bulk token price stats", "description": "Returns current prices and percentage change stats for up to 1000 tokens by address. No authentication required.\n", "operationId": "getBulkTokenStats", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "addresses" ], "properties": { "addresses": { "type": "array", "items": { "type": "string" }, "maxItems": 1000, "description": "Array of token addresses (max 1000)." } } } } } }, "responses": { "200": { "description": "Array of token stats in the same order as the input.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "found": { "type": "boolean" }, "price": { "type": "number", "nullable": true, "description": "Current token price. Present only when found=true." }, "stats": { "type": "object", "nullable": true, "description": "Percentage change stats. Present only when found=true.", "properties": { "change4H": { "type": "number", "nullable": true }, "change1D": { "type": "number", "nullable": true }, "change1W": { "type": "number", "nullable": true }, "change1M": { "type": "number", "nullable": true }, "changeAll": { "type": "number", "nullable": true } } } } } } } } }, "400": { "description": "Invalid input (missing or empty addresses, exceeds 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/search.php": { "post": { "tags": [ "Search" ], "summary": "Search stacks, creators, and tokens", "description": "Performs a simple stack name search or a faceted search across stacks, creators, and tokens. If any of `filters`, `sort`, or `pagination` keys are present in the body, the faceted search is used; otherwise simple search is used. No authentication required.\n", "operationId": "search", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "SimpleSearchRequest", "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Search query string." } } }, { "title": "FacetedSearchRequest", "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Search query string." }, "filters": { "type": "object", "properties": { "entity_types": { "type": "array", "items": { "type": "string" }, "description": "Entity types to include in results (e.g. stacks, creators, tokens)." } } }, "sort": { "type": "object", "properties": { "field": { "type": "string", "description": "Field to sort results by." }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction." } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number." }, "per_page": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20, "description": "Results per page." } } } } } ] } } } }, "responses": { "200": { "description": "Search results. Shape depends on search mode.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "SimpleSearchResponse", "type": "array", "items": { "type": "object", "properties": { "stack_name": { "type": "string" }, "stack_id": { "type": "integer" }, "slug": { "type": "string" }, "description_truncated": { "type": "string", "nullable": true } } } }, { "title": "FacetedSearchResponse", "type": "object", "properties": { "results": { "type": "object", "properties": { "stacks": { "type": "array", "items": { "type": "object" } }, "creators": { "type": "array", "items": { "type": "object" } }, "tokens": { "type": "array", "items": { "type": "object" } } } }, "facets": { "type": "object", "properties": { "categories": { "type": "object" }, "price_ranges": { "type": "object" }, "market_cap_ranges": { "type": "object" }, "creators": { "type": "object" } } }, "meta": { "type": "object", "properties": { "total_results": { "type": "integer" }, "query": { "type": "string" }, "execution_time": { "type": "number", "description": "Search execution time in seconds." }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } ] } } } }, "400": { "description": "Missing or empty query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed (only POST is accepted).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported media type (Content-Type must be application/json).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/charts.php?action=stack-chart-payload": { "get": { "operationId": "getStackChartPayload", "summary": "Get stack chart payload with version segments", "description": "Returns token amounts for each allocation version segment so the frontend can build accurate historical charts across allocation edits. Includes a `segments` array with time ranges and per-version base amounts, plus a backwards-compatible `tokens` field with the current allocation.\n", "security": [], "parameters": [ { "name": "slug", "in": "query", "schema": { "type": "string" }, "description": "Stack slug (either slug or stack_id required)." }, { "name": "stack_id", "in": "query", "schema": { "type": "integer" }, "description": "Stack ID (either slug or stack_id required)." }, { "name": "bucket", "in": "query", "schema": { "type": "string", "enum": [ "1s", "1m", "5m", "30m", "1h", "24h" ], "default": "5m" }, "description": "Chart candle bucket size." }, { "name": "endTime", "in": "query", "schema": { "type": "integer" }, "description": "End timestamp for pagination." }, { "name": "includeTokenValues", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether to include per-token values in the chart response." } ], "responses": { "200": { "description": "Chart payload with version segments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "stack_id": { "type": "integer" }, "payload": { "type": "object", "properties": { "segments": { "type": "array", "description": "Version segments ordered chronologically. Each segment represents one allocation version with its time range and token base amounts.\n", "items": { "type": "object", "properties": { "version": { "type": "integer", "description": "Version number (matches version_history endpoint)." }, "start": { "type": "integer", "description": "Unix timestamp when this allocation became active." }, "end": { "type": "integer", "nullable": true, "description": "Unix timestamp when this allocation was replaced. null for the current live allocation.\n" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Solana token address." }, "amount": { "type": "number", "description": "Base token amount for this version." } } } } } } }, "tokens": { "type": "array", "description": "Current base token amounts (backwards compatibility).", "items": { "type": "object", "properties": { "address": { "type": "string" }, "amount": { "type": "number" } } } }, "bucket": { "type": "string" }, "limit": { "type": "integer" }, "includeTokenValues": { "type": "boolean" } } } } } } } }, "400": { "description": "Missing parameters or invalid bucket.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Stack not found or no base token amounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/charts.php?action=chart-markers": { "get": { "operationId": "getChartMarkers", "summary": "Get chart markers for a stack", "description": "Returns buy/sell/inception/closed/allocation_change markers for overlay on stack price charts. Requires authentication for buy/sell markers. Allocation change markers are included at each version transition point.\n", "parameters": [ { "name": "slug", "in": "query", "schema": { "type": "string" }, "description": "Stack slug (either slug or stack_id required)." }, { "name": "stack_id", "in": "query", "schema": { "type": "integer" }, "description": "Stack ID (either slug or stack_id required)." }, { "name": "start", "in": "query", "schema": { "type": "integer" }, "description": "Start of time range (unix timestamp). Defaults to 30 days ago." }, { "name": "end", "in": "query", "schema": { "type": "integer" }, "description": "End of time range (unix timestamp). Defaults to now." } ], "responses": { "200": { "description": "Chart markers within the requested time range.", "content": { "application/json": { "schema": { "type": "object", "properties": { "stack_id": { "type": "integer" }, "start": { "type": "integer" }, "end": { "type": "integer" }, "markers": { "type": "array", "items": { "type": "object", "required": [ "type", "time", "time_iso" ], "properties": { "type": { "type": "string", "enum": [ "inception", "closed", "buy", "sell", "allocation_change" ] }, "time": { "type": "integer", "description": "Unix timestamp." }, "time_iso": { "type": "string", "description": "ISO 8601 timestamp." }, "order_id": { "type": "integer", "description": "Present on buy/sell markers only." }, "amount_usdc": { "type": "number", "nullable": true, "description": "USDC amount, present on buy/sell markers only." }, "status": { "type": "string", "description": "Order status, present on buy/sell markers only." }, "version": { "type": "integer", "description": "The version that became active at this point. Present on allocation_change markers only.\n" }, "creator_note": { "type": "string", "nullable": true, "description": "Creator's note about the allocation change. Present on allocation_change markers only.\n" } } } } } } } } }, "400": { "description": "Missing slug/stack_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Stack not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/deanon.php?action=holders": { "get": { "operationId": "deanonHolders", "summary": "Identify known holders of a token", "description": "Fetches all token holders for a given Solana mint address and cross-references wallet addresses against a curated lookup table of over 20,000 known wallet-to-Twitter mappings, and returns identified holders sorted by balance descending with pagination.", "tags": [ "DeAnon" ], "security": [], "parameters": [ { "name": "mint", "in": "query", "required": true, "schema": { "type": "string", "minLength": 32, "maxLength": 44 }, "description": "Solana token mint address (32-44 Base58 characters)", "example": "So11111111111111111111111111111111111111112" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Number of results per page (1-100)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of results to skip for pagination" } ], "responses": { "200": { "description": "Identified holders for the given token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeanonHoldersResponse" } } } }, "400": { "description": "Invalid or missing mint address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/limit_orders.php?action=place": { "post": { "operationId": "limitOrderPlace", "summary": "Place a new limit order", "description": "Place a conditional order that triggers automatically when a token reaches a target price. Supports limit buys (buy + lte), stop losses (sell + lte), take profits (sell + gte), and breakout buys (buy + gte). Balances are checked at fill time only \u2014 no escrow. A company stack is auto-created for the token if one does not exist. DFlow-only tokens are auto-detected and routed accordingly.\n**Limits**: 20 active orders per user, 1 active order per token per user, minimum buy amount 1 USDC.", "tags": [ "Limit Orders" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token_address", "side", "condition_type", "trigger_price", "amount" ], "properties": { "token_address": { "type": "string", "description": "Solana token mint address", "example": "So11111111111111111111111111111111111111112" }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Order direction. \"buy\" purchases the token with USDC, \"sell\" sells existing holdings" }, "condition_type": { "type": "string", "enum": [ "lte", "gte" ], "description": "Price comparison. \"lte\" triggers when price <= target, \"gte\" triggers when price >= target" }, "trigger_price": { "type": "number", "description": "USD price threshold that triggers the order. Must be > 0", "example": 120.0 }, "amount": { "type": "number", "description": "For buys: USDC amount (minimum 1 USDC). For sells: percentage of holdings (0-100)", "example": 50.0 }, "expires_at": { "type": "integer", "nullable": true, "description": "Optional unix timestamp for order expiration. Must be in the future. Omit for no expiry" } } } } } }, "responses": { "200": { "description": "Order placed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitOrderPlaceResponse" } } } }, "400": { "description": "Validation error \u2014 missing/invalid fields, minimum amount not met, invalid percentage, archived token with buy side, or invalid expires_at.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Token not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Per-user limit reached (20 active orders) or per-token limit reached (1 active order per token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/limit_orders.php?action=cancel": { "post": { "operationId": "limitOrderCancel", "summary": "Cancel an active limit order", "description": "Cancel a limit order that has not yet been triggered. Only orders in ACTIVE status can be cancelled. Orders in TRIGGERED, FILLING, FILLED, FAILED, or CANCELLED status cannot be cancelled. The order is removed from both the database and Redis.", "tags": [ "Limit Orders" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "order_id" ], "properties": { "order_id": { "type": "string", "description": "The 16-character limit order ID to cancel", "example": "aBcDeFgHiJkLmNoP" } } } } } }, "responses": { "200": { "description": "Order cancelled successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "string", "example": "aBcDeFgHiJkLmNoP" }, "status": { "type": "string", "example": "CANCELLED" } } } } } }, "400": { "description": "Order is not in ACTIVE status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Order not found or does not belong to the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/limit_orders.php?action=list": { "get": { "operationId": "limitOrderList", "summary": "List user's limit orders", "description": "Returns all limit orders for the authenticated user, ordered by creation time (newest first). Supports optional filtering by status and/or token address. Returns an empty array if no orders match.", "tags": [ "Limit Orders" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "ACTIVE", "TRIGGERED", "FILLING", "FILLED", "FAILED", "CANCELLED" ] }, "description": "Filter by order status" }, { "name": "token_address", "in": "query", "schema": { "type": "string" }, "description": "Filter by Solana token mint address" } ], "responses": { "200": { "description": "List of limit orders. Returns an empty array if no orders match the filters.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LimitOrder" } } } } } } } }, "/api/limit_orders.php?action=get": { "get": { "operationId": "limitOrderGet", "summary": "Get a single limit order", "description": "Returns full details for a specific limit order including token metadata and fill information. The order must belong to the authenticated user.", "tags": [ "Limit Orders" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "order_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The 16-character limit order ID" } ], "responses": { "200": { "description": "Limit order details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitOrder" } } } }, "404": { "description": "Order not found or does not belong to the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }