# Social
## Stack and user follow/unfollow operations
> Manage stack subscriptions and user follow relationships. Auth requirements vary by action.
```json
{"openapi":"3.0.3","info":{"title":"Indexify API","version":"0.1.12-beta"},"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"}}}}},"paths":{"/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"}}},{"title":"FollowResponse","description":"Response for `follow` action. Auth required.","type":"object","properties":{"success":{"type":"string"}}},{"title":"UnfollowResponse","description":"Response for `unfollow` action. Auth required.","type":"object","properties":{"success":{"type":"string"}}},{"title":"FollowUserResponse","description":"Response for `follow_user` action. Auth required.","type":"object","properties":{"success":{"type":"string"}}},{"title":"UnfollowUserResponse","description":"Response for `unfollow_user` action. Auth required.","type":"object","properties":{"success":{"type":"string"}}},{"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"}}},{"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"}}},{"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"}}}]}}}},"400":{"description":"Bad request (missing fields, already following, not following, user not found, etc.).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Creator leaderboard
> Returns a ranked list of creators sorted by the chosen metric. Authentication is optional; when authenticated, \`is\_following\` is populated for each creator.
```json
{"openapi":"3.0.3","info":{"title":"Indexify API","version":"0.1.12-beta"},"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"}}}}},"paths":{"/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","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"}}}}}}}}}
```
## Top creators
> Returns up to 5 top creators with their stack and follower counts. Authentication is optional; when authenticated, \`is\_following\` is populated.
```json
{"openapi":"3.0.3","info":{"title":"Indexify API","version":"0.1.12-beta"},"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."}}},"paths":{"/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","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}}}}}}}}}}}}
```
## Public user profile
> Returns a user's public profile information. No authentication required.
```json
{"openapi":"3.0.3","info":{"title":"Indexify API","version":"0.1.12-beta"},"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"}}}}},"paths":{"/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"}}}}}}}}}
```
## Public user profile metrics
> Returns a user's public profile performance metrics. No authentication required.
```json
{"openapi":"3.0.3","info":{"title":"Indexify API","version":"0.1.12-beta"},"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"}}}}},"paths":{"/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"}}}}}}}}}
```
## Generate a referral link
> Creates a new referral link with an auto-generated access code for the authenticated user.
```json
{"openapi":"3.0.3","info":{"title":"Indexify API","version":"0.1.12-beta"},"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"}}}}},"paths":{"/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","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"}}}}}}}}}
```
## Get referral data
> Returns the authenticated user's multi-level referral tree with volume data for each referred user.
```json
{"openapi":"3.0.3","info":{"title":"Indexify API","version":"0.1.12-beta"},"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":{"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"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"paths":{"/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","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"}}}}}}}}}
```