> For the complete documentation index, see [llms.txt](https://howto.indexify.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://howto.indexify.finance/indexify-api-documentation/social.md).
# 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"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://howto.indexify.finance/indexify-api-documentation/social.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.