{ "openapi": "3.0.0", "info": { "title": "pump.fun Developer API", "version": "0.281.0", "description": "Read-only social data from pump.fun for approved organisations. Every request needs an API key sent as `Authorization: Bearer pf_live_...` (the header `x-api-key: pf_live_...` is accepted as an alias), never in a query string. Keys are server-only. CORS preflight (OPTIONS) requests and requests from a browser origin not on the CORS allowlist are answered before any API-key processing, so they carry no `X-Request-Id` and are not metered; the API is intended for server-side callers.", "contact": { "name": "pump.fun developer support", "url": "https://docs.pump.fun/status-and-support/" } }, "externalDocs": { "description": "Developer documentation", "url": "https://docs.pump.fun" }, "servers": [ { "url": "https://api.pump.fun/v1", "description": "Production" }, { "url": "https://api-devnet.pump.fun/v1", "description": "Devnet" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "profiles.read", "description": "User profiles, lookups and search." }, { "name": "graph.read", "description": "Follow graph, likers, reposters and group membership." }, { "name": "content.read", "description": "Callouts, replies, posts and public feeds." }, { "name": "leaderboards.read", "description": "PnL leaderboards, competitions and creator payouts." }, { "name": "positions.read", "description": "Positions, trades and portfolios of public wallets." }, { "name": "moderation.read", "description": "The public ban oracle. Outside every default grant; request it explicitly." } ], "paths": { "/achievements/overlays": { "post": { "operationId": "post_achievements_overlays", "tags": [ "profiles.read" ], "summary": "Top badge ids for a batch of avatars", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "profiles.read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "Wallet addresses (Solana base58 or EVM 0x) or user ids (UUID), disambiguated by format." } }, "required": [ "ids" ] } } } }, "responses": { "201": { "description": "Top badge ids for a batch of avatars", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Map of the requested id (wallet or user id) to its badge ids; ids with no unlocks are an empty array." } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/callout/coin/{coin}": { "get": { "operationId": "get_callout_coin_by_coin", "tags": [ "content.read" ], "summary": "List top callouts on a coin", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "content.read", "parameters": [ { "name": "coin", "in": "path", "required": true, "schema": { "type": "string", "description": "A base58 or EVM mint, or with an hlcore chain the HyperCore coin name verbatim (BTC, kPEPE, xyz:TSLA; case-sensitive), or with ton:-239 the friendly EQ... jetton master, or with near:mainnet the token account id, or with starknet:SN_MAIN the 0x felt token address" } }, { "name": "chain", "in": "query", "required": false, "schema": { "description": "CAIP-2 chain; hlcore keeps only that chain perp rows, ton:-239 only TON rows, near:mainnet only NEAR rows, starknet:SN_MAIN only Starknet rows, absent or solana/eip155 keeps only token rows", "type": "string", "maxLength": 64, "pattern": "^((solana|eip155):[A-Za-z0-9]{1,48}|hlcore:(mainnet|testnet)|ton:-239|near:mainnet|starknet:SN_MAIN)$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Default 50", "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "List top callouts on a coin (legacy shape); chain=hlcore:* reads perp callouts by HyperCore coin name", "content": { "application/json": { "schema": { "type": "object", "properties": { "callouts": { "type": "array", "items": { "type": "object", "properties": { "calloutId": { "type": "string" }, "userId": { "type": "string" }, "coinMint": { "type": "string" }, "marketCap": { "type": "number" }, "calloutPrice": { "type": "number", "description": "SOL-denominated; 0 both for a genuine zero and when the SOL price lookup failed open" }, "calloutPriceUsd": { "type": "number" }, "multiple": { "type": "number" }, "createdAt": { "type": "number", "description": "Epoch milliseconds; 0 when unparseable" }, "maxPriceSol": { "type": "number", "description": "SOL-denominated; 0 both for a genuine zero and when the SOL price lookup failed open" }, "maxPriceUsd": { "type": "number" }, "thesis": { "type": "string" }, "user_uuid": { "type": "string", "description": "Unread by every known caller; kept for wire compatibility, and always empty on the list read" }, "likes": { "type": "number" }, "hasLiked": { "nullable": true, "type": "boolean" }, "hasReposted": { "nullable": true, "type": "boolean" }, "repostCount": { "type": "number" }, "quoteCount": { "type": "number" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "createdAt": { "nullable": true, "type": "string" }, "likeCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "parentMessageId": { "nullable": true, "type": "string" }, "repostCount": { "type": "number" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" } }, "required": [ "id", "content", "createdAt", "likeCount", "mediaUrl", "parentMessageId", "repostCount" ], "additionalProperties": false }, "description": "Author updates (the author's own replies), newest first; empty when the route does not include them" }, "updateCount": { "type": "number" }, "commentCount": { "type": "number" }, "replyCount": { "type": "number" }, "maxMultiplier": { "nullable": true, "type": "number" }, "maxMultiplierAt": { "nullable": true, "type": "string" }, "viewCount": { "description": "The only counter here that is not zero-filled: absent means unknown (no counter row yet), never a real 0", "type": "number" }, "mediaUrl": { "nullable": true, "description": "Server-minted CDN URL; null when the callout carries no media", "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "quotedCalloutId": { "nullable": true, "description": "Set with quotedCallout null means the quote target is hidden or unavailable, never \"no quote\"", "type": "string" }, "quotedCallout": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Shared_85bd3a13acc3" } ] }, "chain": { "description": "CAIP-2 chain of the called-out ref; null when the row carries none", "nullable": true, "type": "string" }, "perp": { "description": "Set only on a perp callout; maxPriceSol is 0 when set", "nullable": true, "type": "object", "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "leverageBps": { "type": "number" }, "entryPx": { "nullable": true, "type": "number" }, "closePx": { "nullable": true, "type": "number" }, "closedAt": { "nullable": true, "type": "string" } }, "required": [ "side", "leverageBps", "entryPx", "closePx", "closedAt" ], "additionalProperties": false }, "assetClass": { "description": "ASSET_CLASS_NFT_LIKE on a card callout (collectible set); absent on every token and perp row", "type": "string", "enum": [ "ASSET_CLASS_TOKEN", "ASSET_CLASS_PERPETUAL", "ASSET_CLASS_NFT_LIKE" ] }, "collectible": { "description": "NFT_LIKE card callouts only: the card (identity, grade, mark, insured value, buyback, listing); multiple is then the card mark over calloutPriceUsd. Absent on every token callout", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false } }, "required": [ "calloutId", "userId", "coinMint", "marketCap", "calloutPrice", "calloutPriceUsd", "multiple", "createdAt", "maxPriceSol", "maxPriceUsd", "user_uuid", "likes", "hasLiked", "hasReposted", "repostCount", "quoteCount", "updates", "updateCount", "commentCount", "replyCount", "maxMultiplier", "maxMultiplierAt", "mediaUrl", "quotedCalloutId", "quotedCallout" ], "additionalProperties": false }, "description": "Can be shorter than limit after the chain filter" } }, "required": [ "callouts" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "description": "Error payload on the envelope. Also the shared envelope at this status: a platform refusal, or a validation refusal whose `message` is a string array and whose `error` is the HTTP reason phrase.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "timestamp": { "type": "string" }, "path": { "type": "string" }, "error": { "type": "string", "enum": [ "API_CREDENTIAL_NOT_ALLOWED" ] }, "message": { "type": "string" } }, "required": [ "statusCode", "timestamp", "path", "error", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "timestamp": { "type": "string" }, "path": { "type": "string" }, "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "statusCode", "timestamp", "path", "error", "message" ], "description": "Not a base58 or EVM mint without an hlcore chain, a malformed chain or limit, or an hlcore chain when perp callouts are not available" }, { "$ref": "#/components/schemas/Error" } ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "List top callouts on a coin (legacy shape); chain=hlcore:* reads perp callouts by HyperCore coin name" } }, "/callout/leaderboard-stats/{userId}": { "get": { "operationId": "get_callout_leaderboard_stats_by_userId", "tags": [ "content.read" ], "summary": "Get leaderboard stats for a user", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "content.read", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get leaderboard stats for a user", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "weekly": { "type": "object", "properties": { "top10": { "type": "object", "properties": { "appearances": { "type": "number" }, "currentStreak": { "type": "number" }, "longestStreak": { "type": "number" }, "firstPlaceFinishes": { "type": "number" }, "topThreeFinishes": { "type": "number" }, "averageRank": { "description": "Mean rank across appearances; absent when appearances is 0", "type": "number" } }, "required": [ "appearances", "currentStreak", "longestStreak", "firstPlaceFinishes", "topThreeFinishes" ], "additionalProperties": false }, "top25": { "type": "object", "properties": { "appearances": { "type": "number" }, "currentStreak": { "type": "number" }, "longestStreak": { "type": "number" }, "firstPlaceFinishes": { "type": "number" }, "topThreeFinishes": { "type": "number" }, "averageRank": { "description": "Mean rank across appearances; absent when appearances is 0", "type": "number" } }, "required": [ "appearances", "currentStreak", "longestStreak", "firstPlaceFinishes", "topThreeFinishes" ], "additionalProperties": false }, "top50": { "type": "object", "properties": { "appearances": { "type": "number" }, "currentStreak": { "type": "number" }, "longestStreak": { "type": "number" }, "firstPlaceFinishes": { "type": "number" }, "topThreeFinishes": { "type": "number" }, "averageRank": { "description": "Mean rank across appearances; absent when appearances is 0", "type": "number" } }, "required": [ "appearances", "currentStreak", "longestStreak", "firstPlaceFinishes", "topThreeFinishes" ], "additionalProperties": false } }, "additionalProperties": false }, "monthly": { "type": "object", "properties": { "top10": { "type": "object", "properties": { "appearances": { "type": "number" }, "currentStreak": { "type": "number" }, "longestStreak": { "type": "number" }, "firstPlaceFinishes": { "type": "number" }, "topThreeFinishes": { "type": "number" }, "averageRank": { "description": "Mean rank across appearances; absent when appearances is 0", "type": "number" } }, "required": [ "appearances", "currentStreak", "longestStreak", "firstPlaceFinishes", "topThreeFinishes" ], "additionalProperties": false }, "top25": { "type": "object", "properties": { "appearances": { "type": "number" }, "currentStreak": { "type": "number" }, "longestStreak": { "type": "number" }, "firstPlaceFinishes": { "type": "number" }, "topThreeFinishes": { "type": "number" }, "averageRank": { "description": "Mean rank across appearances; absent when appearances is 0", "type": "number" } }, "required": [ "appearances", "currentStreak", "longestStreak", "firstPlaceFinishes", "topThreeFinishes" ], "additionalProperties": false }, "top50": { "type": "object", "properties": { "appearances": { "type": "number" }, "currentStreak": { "type": "number" }, "longestStreak": { "type": "number" }, "firstPlaceFinishes": { "type": "number" }, "topThreeFinishes": { "type": "number" }, "averageRank": { "description": "Mean rank across appearances; absent when appearances is 0", "type": "number" } }, "required": [ "appearances", "currentStreak", "longestStreak", "firstPlaceFinishes", "topThreeFinishes" ], "additionalProperties": false } }, "additionalProperties": false }, "bestRank": { "description": "Best across all tiers and periodicities; absent if never ranked", "type": "object", "properties": { "rank": { "type": "number" }, "periodType": { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ -1 ] } ], "description": "Board period as a number: UNSPECIFIED=0, WEEKLY=1, MONTHLY=2, DAILY=3; UNRECOGNIZED=-1 for a value this document does not list" }, "periodLabel": { "type": "string" } }, "required": [ "rank", "periodType", "periodLabel" ], "additionalProperties": false }, "bestCallout": { "type": "object", "properties": { "chain": { "description": "CAIP-2 chain (hlcore:mainnet, ton:-239, near:mainnet or starknet:SN_MAIN); present only on a perp, TON, NEAR or Starknet callout, absent on every other token row", "type": "string" }, "assetClass": { "description": "Present only on a perp callout, beside chain", "type": "string", "enum": [ "ASSET_CLASS_PERPETUAL" ] }, "perp": { "description": "The perp fill of a perp callout.", "nullable": true, "type": "object", "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "leverageBps": { "type": "number" }, "entryPx": { "nullable": true, "type": "number" }, "closePx": { "nullable": true, "type": "number" }, "closedAt": { "nullable": true, "type": "string" } }, "required": [ "side", "leverageBps", "entryPx", "closePx", "closedAt" ], "additionalProperties": false }, "coinMint": { "type": "string" }, "multiple": { "type": "number" }, "calloutTimestamp": { "type": "number", "description": "Epoch milliseconds" } }, "required": [ "coinMint", "multiple", "calloutTimestamp" ], "additionalProperties": false }, "firstAppearance": { "type": "object", "properties": { "periodType": { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ -1 ] } ], "description": "Board period as a number: UNSPECIFIED=0, WEEKLY=1, MONTHLY=2, DAILY=3; UNRECOGNIZED=-1 for a value this document does not list" }, "periodLabel": { "type": "string" } }, "required": [ "periodType", "periodLabel" ], "additionalProperties": false }, "snapshotAt": { "type": "number", "description": "Epoch milliseconds; 0 means \"no record\" to clients" }, "user_uuid": { "type": "string" } }, "required": [ "userId", "snapshotAt", "user_uuid" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/callout/list/{userId}": { "get": { "operationId": "get_callout_list_by_userId", "tags": [ "content.read" ], "summary": "List callouts for a user", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "content.read", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "TIMESTAMP", "MULTIPLE" ] } }, { "name": "sortOrder", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "window", "in": "query", "required": false, "schema": { "description": "Case-insensitive and trimmed (daily, WEEKLY, \" monthly \" all accepted): daily|weekly|monthly re-scope to the stats-strip windows; last_round = callouts created between the two newest executed payout round cuts; alltime, empty and omitted all mean full history", "type": "string" } } ], "responses": { "200": { "description": "List callouts for a user (legacy shape). Optional window=daily|weekly|monthly|last_round re-scopes to the stats-strip windows; re-send it with every pageToken request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "callouts": { "type": "array", "items": { "type": "object", "properties": { "calloutId": { "type": "string" }, "userId": { "type": "string" }, "coinMint": { "type": "string" }, "marketCap": { "type": "number" }, "calloutPrice": { "type": "number", "description": "SOL-denominated; 0 both for a genuine zero and when the SOL price lookup failed open" }, "calloutPriceUsd": { "type": "number" }, "multiple": { "type": "number" }, "createdAt": { "type": "number", "description": "Epoch milliseconds; 0 when unparseable" }, "maxPriceSol": { "type": "number", "description": "SOL-denominated; 0 both for a genuine zero and when the SOL price lookup failed open" }, "maxPriceUsd": { "type": "number" }, "thesis": { "type": "string" }, "user_uuid": { "type": "string", "description": "Unread by every known caller; kept for wire compatibility, and always empty on the list read" }, "likes": { "type": "number" }, "hasLiked": { "nullable": true, "type": "boolean" }, "hasReposted": { "nullable": true, "type": "boolean" }, "repostCount": { "type": "number" }, "quoteCount": { "type": "number" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "createdAt": { "nullable": true, "type": "string" }, "likeCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "parentMessageId": { "nullable": true, "type": "string" }, "repostCount": { "type": "number" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" } }, "required": [ "id", "content", "createdAt", "likeCount", "mediaUrl", "parentMessageId", "repostCount" ], "additionalProperties": false }, "description": "Author updates (the author's own replies), newest first; empty when the route does not include them" }, "updateCount": { "type": "number" }, "commentCount": { "type": "number" }, "replyCount": { "type": "number" }, "maxMultiplier": { "nullable": true, "type": "number" }, "maxMultiplierAt": { "nullable": true, "type": "string" }, "viewCount": { "description": "The only counter here that is not zero-filled: absent means unknown (no counter row yet), never a real 0", "type": "number" }, "mediaUrl": { "nullable": true, "description": "Server-minted CDN URL; null when the callout carries no media", "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "quotedCalloutId": { "nullable": true, "description": "Set with quotedCallout null means the quote target is hidden or unavailable, never \"no quote\"", "type": "string" }, "quotedCallout": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Shared_85bd3a13acc3" } ] }, "chain": { "description": "CAIP-2 chain of the called-out ref; null when the row carries none", "nullable": true, "type": "string" }, "perp": { "description": "Set only on a perp callout; maxPriceSol is 0 when set", "nullable": true, "type": "object", "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "leverageBps": { "type": "number" }, "entryPx": { "nullable": true, "type": "number" }, "closePx": { "nullable": true, "type": "number" }, "closedAt": { "nullable": true, "type": "string" } }, "required": [ "side", "leverageBps", "entryPx", "closePx", "closedAt" ], "additionalProperties": false }, "assetClass": { "description": "ASSET_CLASS_NFT_LIKE on a card callout (collectible set); absent on every token and perp row", "type": "string", "enum": [ "ASSET_CLASS_TOKEN", "ASSET_CLASS_PERPETUAL", "ASSET_CLASS_NFT_LIKE" ] }, "collectible": { "description": "NFT_LIKE card callouts only: the card (identity, grade, mark, insured value, buyback, listing); multiple is then the card mark over calloutPriceUsd. Absent on every token callout", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false }, "tailBuyers": { "nullable": true, "description": "Distinct users whose buy was attributed to this callout; null = unknown (callout predates tail tracking).", "type": "number" }, "tailCohort1h": { "nullable": true, "description": "Users tailPnl1hUsd covers (tailers whose first attributed buy landed before +1 h and whose window priced); null until the 1 h horizon is served.", "type": "number" }, "tailPnl1hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +1 h]; null until the 1 h horizon is served.", "type": "number" }, "tailCohort4h": { "nullable": true, "description": "Users tailPnl4hUsd covers (tailers whose first attributed buy landed before +4 h and whose window priced); null until the 4 h horizon is served.", "type": "number" }, "tailPnl4hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +4 h]; null until the 4 h horizon is served.", "type": "number" }, "tailCohort24h": { "nullable": true, "description": "Users tailPnl24hUsd covers (tailers whose first attributed buy landed before +24 h and whose window priced); null until the 24 h horizon is served.", "type": "number" }, "tailPnl24hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +24 h]; null until the 24 h horizon is served.", "type": "number" }, "tailPnlHist1h": { "nullable": true, "description": "Per-tailer 1 h PnL histogram of the tailing cohort (server-defined buckets); null until the 1 h horizon is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailPnlHist4h": { "nullable": true, "description": "Per-tailer 4 h PnL histogram of the tailing cohort (server-defined buckets); null until the 4 h horizon is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailPnlHist24h": { "nullable": true, "description": "Per-tailer 24 h PnL histogram of the tailing cohort (server-defined buckets); null until the 24 h horizon is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAth1hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 1 h tailing cohort: sum over tailers of max(0, in-window bought amount x highest outlier-screened 1 m candle high - in-window buy spend) over each tailer's own window [first in-window buy, +1 h]; >= 0; null until the 1 h ATH arm is served (one horizon after tailPnl1hUsd) or unavailable.", "type": "number" }, "tailAth4hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 4 h tailing cohort: sum over tailers of max(0, in-window bought amount x highest outlier-screened 1 m candle high - in-window buy spend) over each tailer's own window [first in-window buy, +4 h]; >= 0; null until the 4 h ATH arm is served (one horizon after tailPnl4hUsd) or unavailable.", "type": "number" }, "tailAth24hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 24 h tailing cohort: sum over tailers of max(0, in-window bought amount x highest outlier-screened 5 m candle high - in-window buy spend) over each tailer's own window [first in-window buy, +24 h]; >= 0; null until the 24 h ATH arm is served (one horizon after tailPnl24hUsd) or unavailable.", "type": "number" }, "tailAthHist1h": { "nullable": true, "description": "Per-tailer 1 h best-case-exit PnL histogram of the tailing cohort (tailer-anchored window, 1 m candle highs); five buckets from 0 up (first min 0, last max null), tailers sum to the 1 h ATH cohort and pnlUsd to tailAth1hUsd; null until served.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAthHist4h": { "nullable": true, "description": "Per-tailer 4 h best-case-exit PnL histogram of the tailing cohort (tailer-anchored window, 1 m candle highs); five buckets from 0 up (first min 0, last max null), tailers sum to the 4 h ATH cohort and pnlUsd to tailAth4hUsd; null until served.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAthHist24h": { "nullable": true, "description": "Per-tailer 24 h best-case-exit PnL histogram of the tailing cohort (tailer-anchored window, 5 m candle highs); five buckets from 0 up (first min 0, last max null), tailers sum to the 24 h ATH cohort and pnlUsd to tailAth24hUsd; null until served.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false } }, "required": [ "calloutId", "userId", "coinMint", "marketCap", "calloutPrice", "calloutPriceUsd", "multiple", "createdAt", "maxPriceSol", "maxPriceUsd", "user_uuid", "likes", "hasLiked", "hasReposted", "repostCount", "quoteCount", "updates", "updateCount", "commentCount", "replyCount", "maxMultiplier", "maxMultiplierAt", "mediaUrl", "quotedCalloutId", "quotedCallout", "tailBuyers", "tailCohort1h", "tailPnl1hUsd", "tailCohort4h", "tailPnl4hUsd", "tailCohort24h", "tailPnl24hUsd", "tailPnlHist1h", "tailPnlHist4h", "tailPnlHist24h", "tailAth1hUsd", "tailAth4hUsd", "tailAth24hUsd", "tailAthHist1h", "tailAthHist4h", "tailAthHist24h" ], "additionalProperties": false }, "description": "Can be shorter than the requested limit — rows whose callout is missing are dropped after the page is cut, so page on nextPageToken, not on array length" }, "nextPageToken": { "type": "string", "description": "Empty string on the last page; never omitted" } }, "required": [ "callouts", "nextPageToken" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "List callouts for a user (legacy shape). Optional window=daily|weekly|monthly|last_round re-scopes to the stats-strip windows; re-send it with every pageToken request." } }, "/callout/replies/list/{userId}": { "get": { "operationId": "get_callout_replies_list_by_userId", "tags": [ "content.read" ], "summary": "List a user's callout replies with thread context", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "content.read", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "beforeId", "in": "query", "required": false, "schema": { "description": "Keyset cursor: a reply id from a previous page", "type": "string" } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ALL", "REPLIES", "QUOTES" ] } } ], "responses": { "200": { "description": "List a user's callout replies with thread context. filter (ALL|REPLIES|QUOTES) narrows to plain replies or quote posts; omitted = ALL, the interleaved list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "replies": { "type": "array", "items": { "type": "object", "properties": { "callout": { "nullable": true, "description": "null when the callout is deleted or moderation-hidden", "type": "object", "properties": { "coinMint": { "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true; true for user-less callouts" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad callout: userId/userName/profileImage are the squad's while walletAddress is the acting admin's posting wallet; route the author press on userId + accountKind, never the wallet" }, "xUsername": { "nullable": true, "type": "string" }, "xFollowerCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "chain": { "description": "CAIP-2 chain of the called-out ref; absent when the callout carries none", "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "callout": { "$ref": "#/components/schemas/Shared_fceda4efe6cd" }, "coinName": { "nullable": true, "type": "string" }, "coinImage": { "nullable": true, "type": "string" }, "symbol": { "nullable": true, "type": "string" }, "marketCap": { "nullable": true, "type": "number" } }, "required": [ "coinMint", "walletAddress", "userId", "userName", "profileImage", "isVerified", "verifiedBadgeVisible", "accountKind", "xUsername", "xFollowerCount", "mediaUrl", "callout", "coinName", "coinImage", "symbol", "marketCap" ], "additionalProperties": false }, "parent": { "nullable": true, "description": "null when the reply targets the callout directly", "allOf": [ { "$ref": "#/components/schemas/Shared_3ba6ed1d0d06" } ] }, "reply": { "$ref": "#/components/schemas/Shared_3ba6ed1d0d06" } }, "required": [ "callout", "parent", "reply" ], "additionalProperties": false }, "description": "Newest first; a page shorter than the requested limit marks the end. The user's own dead replies are simply absent" } }, "required": [ "replies" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "List a user's callout replies with thread context. filter (ALL|REPLIES|QUOTES) narrows to plain replies or quote posts; omitted = ALL, the interleaved list." } }, "/callout/replies/{replyId}/chain": { "get": { "operationId": "get_callout_replies_by_replyId_chain", "tags": [ "content.read" ], "summary": "Get a reply's ancestor chain up to its callout", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN", "REPLY_NOT_FOUND" ], "x-api-scope": "content.read", "parameters": [ { "name": "replyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a reply's ancestor chain up to its callout", "content": { "application/json": { "schema": { "type": "object", "properties": { "callout": { "nullable": true, "description": "null when the callout is deleted or moderation-hidden (the chain still serves)", "allOf": [ { "$ref": "#/components/schemas/Shared_85bd3a13acc3" } ] }, "ancestors": { "type": "array", "items": { "$ref": "#/components/schemas/Shared_3ba6ed1d0d06" }, "description": "Thread top first, immediate parent last; [] when the reply is a thread top. A dead ancestor is a tombstone placeholder" }, "reply": { "$ref": "#/components/schemas/Shared_3ba6ed1d0d06" } }, "required": [ "callout", "ancestors", "reply" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Error payload on the envelope", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "timestamp": { "type": "string" }, "path": { "type": "string" } }, "required": [ "statusCode", "timestamp", "path" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "REPLY_NOT_FOUND" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/callout/replies/{replyId}/likers": { "get": { "operationId": "get_callout_replies_by_replyId_likers", "tags": [ "graph.read" ], "summary": "List the profiles who liked a callout reply", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "replyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "List the profiles who liked a callout reply", "content": { "application/json": { "schema": { "type": "object", "properties": { "likers": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "bio": { "type": "string" }, "profileImageUrl": { "type": "string" }, "headerImageUrl": { "type": "string" }, "followerCount": { "type": "number" }, "followingCount": { "type": "number" }, "createdAt": { "nullable": true, "type": "string" }, "updatedAt": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "socials": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "username": { "type": "string" }, "linkedAt": { "nullable": true, "type": "string" } }, "required": [ "provider", "username", "linkedAt" ], "additionalProperties": false } }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true. The verified state itself is isVerified." }, "resolvedAvatarDecoration": { "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border. Treat absent as null.", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "PERSON", "GROUP" ] }, "memberCount": { "type": "number" }, "membershipPolicy": { "nullable": true, "type": "string", "enum": [ "INVITE" ] }, "groupBadges": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "role": { "type": "string" } }, "required": [ "groupId", "username", "profileImageUrl", "role" ], "additionalProperties": false } }, "generatedMedia": { "nullable": true, "type": "object", "properties": { "pnlLoop": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" } }, "required": [ "uid", "durationSeconds" ], "additionalProperties": false }, "replayIntro": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" }, "fireAt": { "type": "number" } }, "required": [ "uid", "durationSeconds", "fireAt" ], "additionalProperties": false } }, "required": [ "pnlLoop" ], "additionalProperties": false }, "isPumpUser": { "description": "false = unclaimed shell: an identity minted when someone followed an outside wallet that never signed in, served under a generated username. Render it as a wallet (address or the viewer’s wallet label), never as an account. Treat absent as true.", "type": "boolean" }, "viewerFollows": { "description": "Absent on unauthenticated reads", "type": "boolean" } }, "required": [ "userId", "username", "bio", "profileImageUrl", "headerImageUrl", "followerCount", "followingCount", "createdAt", "updatedAt", "walletAddress", "socials", "isVerified", "verifiedBadgeVisible", "kind", "memberCount", "membershipPolicy", "groupBadges", "generatedMedia" ], "additionalProperties": false } }, "hasMore": { "type": "boolean" } }, "required": [ "likers", "hasMore" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/callout/replies/{replyId}/reposters": { "get": { "operationId": "get_callout_replies_by_replyId_reposters", "tags": [ "graph.read" ], "summary": "List the profiles who reposted a callout reply", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "replyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "List the profiles who reposted a callout reply", "content": { "application/json": { "schema": { "type": "object", "properties": { "reposters": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "bio": { "type": "string" }, "profileImageUrl": { "type": "string" }, "headerImageUrl": { "type": "string" }, "followerCount": { "type": "number" }, "followingCount": { "type": "number" }, "createdAt": { "nullable": true, "type": "string" }, "updatedAt": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "socials": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "username": { "type": "string" }, "linkedAt": { "nullable": true, "type": "string" } }, "required": [ "provider", "username", "linkedAt" ], "additionalProperties": false } }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true. The verified state itself is isVerified." }, "resolvedAvatarDecoration": { "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border. Treat absent as null.", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "PERSON", "GROUP" ] }, "memberCount": { "type": "number" }, "membershipPolicy": { "nullable": true, "type": "string", "enum": [ "INVITE" ] }, "groupBadges": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "role": { "type": "string" } }, "required": [ "groupId", "username", "profileImageUrl", "role" ], "additionalProperties": false } }, "generatedMedia": { "nullable": true, "type": "object", "properties": { "pnlLoop": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" } }, "required": [ "uid", "durationSeconds" ], "additionalProperties": false }, "replayIntro": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" }, "fireAt": { "type": "number" } }, "required": [ "uid", "durationSeconds", "fireAt" ], "additionalProperties": false } }, "required": [ "pnlLoop" ], "additionalProperties": false }, "isPumpUser": { "description": "false = unclaimed shell: an identity minted when someone followed an outside wallet that never signed in, served under a generated username. Render it as a wallet (address or the viewer’s wallet label), never as an account. Treat absent as true.", "type": "boolean" }, "viewerFollows": { "description": "Absent on unauthenticated reads", "type": "boolean" }, "position": { "description": "The reposter's own position in the callout's token; absent = none visible", "type": "object", "properties": { "amountHeld": { "type": "number" }, "valueUsd": { "nullable": true, "type": "number" }, "pnlUsd": { "nullable": true, "type": "number" }, "pnlPercentage": { "nullable": true, "type": "number" }, "isExited": { "type": "boolean" }, "costBasisAmount": { "type": "number", "description": "Use the amountBought pair there" }, "costBasisUsd": { "nullable": true, "type": "number" }, "amountBoughtUsd": { "nullable": true, "type": "number" }, "amountBought": { "nullable": true, "type": "number" }, "realizedPnlUsd": { "nullable": true, "type": "number" }, "avgEntryMcapUsd": { "nullable": true, "type": "number" }, "perp": { "nullable": true, "description": "The author's HyperCore position on a perp callout: live while open, the frozen close once closed; null on a spot position", "type": "object", "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "leverageBps": { "type": "number" }, "entryPx": { "nullable": true, "type": "number" }, "markPx": { "nullable": true, "type": "number" }, "closePx": { "nullable": true, "description": "The frozen close price; null while the position is open", "type": "number" }, "closedAt": { "nullable": true, "description": "ISO instant of the close; null while the position is open", "type": "string" }, "positionValueUsd": { "nullable": true, "type": "number" }, "marginUsd": { "nullable": true, "type": "number" }, "equityUsd": { "nullable": true, "description": "Account equity (USD) behind the position.", "type": "number" }, "stateAsOf": { "nullable": true, "description": "ISO instant of the clearinghouse state behind these figures", "type": "string" } }, "required": [ "side", "leverageBps", "entryPx", "markPx", "closePx", "closedAt", "positionValueUsd", "marginUsd", "equityUsd", "stateAsOf" ], "additionalProperties": false } }, "required": [ "amountHeld", "valueUsd", "pnlUsd", "pnlPercentage", "isExited", "costBasisAmount", "costBasisUsd", "amountBoughtUsd", "amountBought", "realizedPnlUsd", "avgEntryMcapUsd", "perp" ], "additionalProperties": false } }, "required": [ "userId", "username", "bio", "profileImageUrl", "headerImageUrl", "followerCount", "followingCount", "createdAt", "updatedAt", "walletAddress", "socials", "isVerified", "verifiedBadgeVisible", "kind", "memberCount", "membershipPolicy", "groupBadges", "generatedMedia" ], "additionalProperties": false } }, "hasMore": { "type": "boolean" } }, "required": [ "reposters", "hasMore" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/callout/reposts/list/{userId}": { "get": { "operationId": "get_callout_reposts_list_by_userId", "tags": [ "content.read" ], "summary": "List a user's reposts", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "content.read", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Opaque keyset cursor from the previous page's nextCursor", "type": "string" } }, { "name": "includeQuotes", "in": "query", "required": false, "schema": { "description": "Interleaves the user's quotes as kind='quote' rows; absent/false serves plain reposts only", "type": "boolean" } } ], "responses": { "200": { "description": "List a user's reposts", "content": { "application/json": { "schema": { "type": "object", "properties": { "reposts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "For kind 'quote' this is the quote MESSAGE id and is never valid for undo-repost" }, "kind": { "type": "string", "enum": [ "repost", "quote" ], "description": "Routing discriminator: 'quote' rows carry only id/createdAt/quote" }, "createdAt": { "nullable": true, "type": "string" }, "reposter": { "nullable": true, "type": "object", "properties": { "userId": { "type": "string" }, "userName": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad reposted it: userId/userName/profileImage are the squad's and walletAddress is null (groups are walletless)" }, "followerCount": { "type": "number" }, "followingCount": { "type": "number" } }, "required": [ "userId", "userName", "profileImage", "walletAddress", "isVerified", "verifiedBadgeVisible", "accountKind", "followerCount", "followingCount" ], "additionalProperties": false }, "callout": { "nullable": true, "type": "object", "properties": { "coinMint": { "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true; true for user-less callouts" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad callout: userId/userName/profileImage are the squad's while walletAddress is the acting admin's posting wallet; route the author press on userId + accountKind, never the wallet" }, "xUsername": { "nullable": true, "type": "string" }, "xFollowerCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "chain": { "description": "CAIP-2 chain of the called-out ref; absent when the callout carries none", "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "callout": { "$ref": "#/components/schemas/Shared_fceda4efe6cd" }, "coinName": { "nullable": true, "type": "string" }, "coinImage": { "nullable": true, "type": "string" }, "symbol": { "nullable": true, "type": "string" }, "marketCap": { "nullable": true, "type": "number" }, "position": { "nullable": true, "description": "null when the author has no visible position row", "type": "object", "properties": { "amountHeld": { "type": "number" }, "valueUsd": { "nullable": true, "type": "number" }, "pnlUsd": { "nullable": true, "type": "number" }, "pnlPercentage": { "nullable": true, "type": "number" }, "isExited": { "type": "boolean" }, "costBasisAmount": { "type": "number", "description": "Use the amountBought pair there" }, "costBasisUsd": { "nullable": true, "type": "number" }, "amountBoughtUsd": { "nullable": true, "type": "number" }, "amountBought": { "nullable": true, "type": "number" }, "realizedPnlUsd": { "nullable": true, "type": "number" }, "avgEntryMcapUsd": { "nullable": true, "type": "number" }, "perp": { "nullable": true, "description": "The author's HyperCore position on a perp callout: live while open, the frozen close once closed; null on a spot position", "type": "object", "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "leverageBps": { "type": "number" }, "entryPx": { "nullable": true, "type": "number" }, "markPx": { "nullable": true, "type": "number" }, "closePx": { "nullable": true, "description": "The frozen close price; null while the position is open", "type": "number" }, "closedAt": { "nullable": true, "description": "ISO instant of the close; null while the position is open", "type": "string" }, "positionValueUsd": { "nullable": true, "type": "number" }, "marginUsd": { "nullable": true, "type": "number" }, "equityUsd": { "nullable": true, "description": "Account equity (USD) behind the position.", "type": "number" }, "stateAsOf": { "nullable": true, "description": "ISO instant of the clearinghouse state behind these figures", "type": "string" } }, "required": [ "side", "leverageBps", "entryPx", "markPx", "closePx", "closedAt", "positionValueUsd", "marginUsd", "equityUsd", "stateAsOf" ], "additionalProperties": false } }, "required": [ "amountHeld", "valueUsd", "pnlUsd", "pnlPercentage", "isExited", "costBasisAmount", "costBasisUsd", "amountBoughtUsd", "amountBought", "realizedPnlUsd", "avgEntryMcapUsd", "perp" ], "additionalProperties": false } }, "required": [ "coinMint", "walletAddress", "userId", "userName", "profileImage", "isVerified", "verifiedBadgeVisible", "accountKind", "xUsername", "xFollowerCount", "mediaUrl", "callout", "coinName", "coinImage", "symbol", "marketCap", "position" ], "additionalProperties": false }, "reply": { "nullable": true, "description": "null for callout-target reposts and on quote rows", "allOf": [ { "$ref": "#/components/schemas/Shared_3ba6ed1d0d06" } ] }, "quote": { "nullable": true, "description": "null on plain reposts", "type": "object", "properties": { "callout": { "nullable": true, "description": "null when the callout is deleted or moderation-hidden", "type": "object", "properties": { "coinMint": { "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true; true for user-less callouts" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad callout: userId/userName/profileImage are the squad's while walletAddress is the acting admin's posting wallet; route the author press on userId + accountKind, never the wallet" }, "xUsername": { "nullable": true, "type": "string" }, "xFollowerCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "chain": { "description": "CAIP-2 chain of the called-out ref; absent when the callout carries none", "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "callout": { "$ref": "#/components/schemas/Shared_fceda4efe6cd" }, "coinName": { "nullable": true, "type": "string" }, "coinImage": { "nullable": true, "type": "string" }, "symbol": { "nullable": true, "type": "string" }, "marketCap": { "nullable": true, "type": "number" } }, "required": [ "coinMint", "walletAddress", "userId", "userName", "profileImage", "isVerified", "verifiedBadgeVisible", "accountKind", "xUsername", "xFollowerCount", "mediaUrl", "callout", "coinName", "coinImage", "symbol", "marketCap" ], "additionalProperties": false }, "parent": { "nullable": true, "description": "null when the reply targets the callout directly", "allOf": [ { "$ref": "#/components/schemas/Shared_3ba6ed1d0d06" } ] }, "reply": { "$ref": "#/components/schemas/Shared_3ba6ed1d0d06" } }, "required": [ "callout", "parent", "reply" ], "additionalProperties": false } }, "required": [ "id", "kind", "createdAt", "reposter", "callout", "reply", "quote" ], "additionalProperties": false }, "description": "Newest first; moderation-hidden rows and dead-target rows are absent" }, "nextCursor": { "nullable": true, "description": "null when there are no more results", "type": "string" } }, "required": [ "reposts", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/callout/user/{userId}/mint/{coinMint}": { "get": { "operationId": "get_callout_user_by_userId_mint_by_coinMint", "tags": [ "content.read" ], "summary": "Get a user callout for a coin", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "content.read", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "coinMint", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "quotesLimit", "in": "query", "required": false, "schema": { "description": "Absent or 0 = callout only", "type": "integer", "minimum": 0, "maximum": 20 } }, { "name": "chain", "in": "query", "required": false, "schema": { "description": "ton:-239 (TON mainnet) only: {coinMint} must then be the CRC-checked 48-char bounceable EQ jetton master. A malformed chain answers the eligibility route body; any other well-formed chain is a 400", "type": "string" } } ], "responses": { "200": { "description": "Get a user callout for a coin (legacy shape); quotesLimit adds the callout-sheet carousel quotes", "content": { "application/json": { "schema": { "type": "object", "properties": { "callout": { "nullable": true, "description": "null when the user holds no live callout on this coin", "type": "object", "properties": { "calloutId": { "type": "string" }, "userId": { "type": "string" }, "coinMint": { "type": "string" }, "marketCap": { "type": "number" }, "calloutPrice": { "type": "number", "description": "SOL-denominated; 0 both for a genuine zero and when the SOL price lookup failed open" }, "calloutPriceUsd": { "type": "number" }, "multiple": { "type": "number" }, "createdAt": { "type": "number", "description": "Epoch milliseconds; 0 when unparseable" }, "maxPriceSol": { "type": "number", "description": "SOL-denominated; 0 both for a genuine zero and when the SOL price lookup failed open" }, "maxPriceUsd": { "type": "number" }, "thesis": { "type": "string" }, "user_uuid": { "type": "string", "description": "Unread by every known caller; kept for wire compatibility, and always empty on the list read" }, "likes": { "type": "number" }, "hasLiked": { "nullable": true, "type": "boolean" }, "hasReposted": { "nullable": true, "type": "boolean" }, "repostCount": { "type": "number" }, "quoteCount": { "type": "number" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "createdAt": { "nullable": true, "type": "string" }, "likeCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "parentMessageId": { "nullable": true, "type": "string" }, "repostCount": { "type": "number" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" } }, "required": [ "id", "content", "createdAt", "likeCount", "mediaUrl", "parentMessageId", "repostCount" ], "additionalProperties": false }, "description": "Author updates (the author's own replies), newest first; empty when the route does not include them" }, "updateCount": { "type": "number" }, "commentCount": { "type": "number" }, "replyCount": { "type": "number" }, "maxMultiplier": { "nullable": true, "type": "number" }, "maxMultiplierAt": { "nullable": true, "type": "string" }, "viewCount": { "description": "The only counter here that is not zero-filled: absent means unknown (no counter row yet), never a real 0", "type": "number" }, "mediaUrl": { "nullable": true, "description": "Server-minted CDN URL; null when the callout carries no media", "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "quotedCalloutId": { "nullable": true, "description": "Set with quotedCallout null means the quote target is hidden or unavailable, never \"no quote\"", "type": "string" }, "quotedCallout": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Shared_85bd3a13acc3" } ] }, "chain": { "description": "CAIP-2 chain of the called-out ref; null when the row carries none", "nullable": true, "type": "string" }, "perp": { "description": "Set only on a perp callout; maxPriceSol is 0 when set", "nullable": true, "type": "object", "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "leverageBps": { "type": "number" }, "entryPx": { "nullable": true, "type": "number" }, "closePx": { "nullable": true, "type": "number" }, "closedAt": { "nullable": true, "type": "string" } }, "required": [ "side", "leverageBps", "entryPx", "closePx", "closedAt" ], "additionalProperties": false }, "assetClass": { "description": "ASSET_CLASS_NFT_LIKE on a card callout (collectible set); absent on every token and perp row", "type": "string", "enum": [ "ASSET_CLASS_TOKEN", "ASSET_CLASS_PERPETUAL", "ASSET_CLASS_NFT_LIKE" ] }, "collectible": { "description": "NFT_LIKE card callouts only: the card (identity, grade, mark, insured value, buyback, listing); multiple is then the card mark over calloutPriceUsd. Absent on every token callout", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false } }, "required": [ "calloutId", "userId", "coinMint", "marketCap", "calloutPrice", "calloutPriceUsd", "multiple", "createdAt", "maxPriceSol", "maxPriceUsd", "user_uuid", "likes", "hasLiked", "hasReposted", "repostCount", "quoteCount", "updates", "updateCount", "commentCount", "replyCount", "maxMultiplier", "maxMultiplierAt", "mediaUrl", "quotedCalloutId", "quotedCallout" ], "additionalProperties": false }, "quotes": { "type": "array", "items": { "type": "object", "properties": { "callout": { "nullable": true, "description": "null when the callout is deleted or moderation-hidden", "type": "object", "properties": { "coinMint": { "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true; true for user-less callouts" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad callout: userId/userName/profileImage are the squad's while walletAddress is the acting admin's posting wallet; route the author press on userId + accountKind, never the wallet" }, "xUsername": { "nullable": true, "type": "string" }, "xFollowerCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "chain": { "description": "CAIP-2 chain of the called-out ref; absent when the callout carries none", "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "callout": { "type": "object", "properties": { "calloutId": { "type": "string" }, "chain": { "description": "CAIP-2 chain of the called-out ref (hlcore:mainnet for a perp, ton:-239 for a TON callout, near:mainnet for a NEAR callout, starknet:SN_MAIN for a Starknet callout); null when the row carries none", "nullable": true, "type": "string" }, "assetClass": { "description": "Asset class of the called-out position: ASSET_CLASS_PERPETUAL on an hlcore (HyperCore perp) callout, ASSET_CLASS_NFT_LIKE on a card callout (collectible set), ASSET_CLASS_TOKEN on every other row, chainless ones included", "type": "string", "enum": [ "ASSET_CLASS_TOKEN", "ASSET_CLASS_PERPETUAL", "ASSET_CLASS_NFT_LIKE" ] }, "collectible": { "description": "ASSET_CLASS_NFT_LIKE callouts only: the card (identity, grade, mark, insured value, buyback, listing); multiple is then the card mark over calloutPrice. Absent on every token callout", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false }, "perp": { "description": "Set only on a perp callout, whose calledOutAtMcap is 0", "nullable": true, "type": "object", "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "leverageBps": { "type": "number" }, "entryPx": { "nullable": true, "type": "number" }, "closePx": { "nullable": true, "type": "number" }, "closedAt": { "nullable": true, "type": "string" } }, "required": [ "side", "leverageBps", "entryPx", "closePx", "closedAt" ], "additionalProperties": false }, "calledOutAtMcap": { "type": "number", "description": "USD market cap when the callout was made." }, "multiple": { "type": "number", "description": "Current multiplier (live price vs callout price), 1 for an untracked callout; maxMultiplier is the all-time peak" }, "thesis": { "nullable": true, "type": "string" }, "mediaUrl": { "nullable": true, "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "calloutTimestamp": { "nullable": true, "type": "string" }, "likes": { "type": "number" }, "hasLiked": { "nullable": true, "description": "null until a viewer is known", "type": "boolean" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "createdAt": { "nullable": true, "type": "string" }, "likeCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "parentMessageId": { "nullable": true, "type": "string" }, "repostCount": { "type": "number" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" } }, "required": [ "id", "content", "createdAt", "likeCount", "mediaUrl", "parentMessageId", "repostCount" ], "additionalProperties": false }, "description": "Author updates (the author's own replies), newest first; empty when the route does not include them" }, "updateCount": { "type": "number" }, "commentCount": { "type": "number", "description": "Live replies from users OTHER than the callout author" }, "replyCount": { "type": "number", "description": "All live replies, updates included" }, "maxMultiplier": { "nullable": true, "type": "number" }, "maxMultiplierAt": { "nullable": true, "type": "string" }, "calloutPrice": { "type": "number", "description": "Token price when the callout was made; 0 for callouts predating price capture, never null" }, "repostCount": { "type": "number", "description": "Live plain reposts of the callout itself; quotes do not count" }, "quoteCount": { "type": "number" }, "hasReposted": { "nullable": true, "description": "null until a viewer is known", "type": "boolean" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" }, "quotedCalloutId": { "description": "Set with quotedCallout null means \"quote of an unavailable callout\", never \"no quote\"", "nullable": true, "type": "string" }, "actingUserId": { "nullable": true, "description": "Squad callouts: the admin who posted on the squad's behalf; presence is not the squad discriminator, the author's kind is", "type": "string" }, "actingUser": { "nullable": true, "description": "actingUserId set with actingUser null means \"unresolved\", not \"absent\"", "type": "object", "properties": { "userId": { "type": "string" }, "userName": { "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "xUsername": { "nullable": true, "type": "string" } }, "required": [ "userId", "userName", "profileImage", "walletAddress", "isVerified", "verifiedBadgeVisible", "xUsername" ], "additionalProperties": false }, "quotedCallout": { "nullable": true, "description": "The quoted callout one level deep (its own quotedCallout is always null)", "allOf": [ { "$ref": "#/components/schemas/Shared_85bd3a13acc3" } ] } }, "required": [ "calloutId", "calledOutAtMcap", "multiple", "thesis", "mediaUrl", "calloutTimestamp", "likes", "hasLiked", "updates", "updateCount", "commentCount", "replyCount", "maxMultiplier", "maxMultiplierAt", "calloutPrice", "repostCount", "quoteCount", "hasReposted", "actingUserId", "actingUser", "quotedCallout" ], "additionalProperties": false }, "coinName": { "nullable": true, "type": "string" }, "coinImage": { "nullable": true, "type": "string" }, "symbol": { "nullable": true, "type": "string" }, "marketCap": { "nullable": true, "type": "number" } }, "required": [ "coinMint", "walletAddress", "userId", "userName", "profileImage", "isVerified", "verifiedBadgeVisible", "accountKind", "xUsername", "xFollowerCount", "mediaUrl", "callout", "coinName", "coinImage", "symbol", "marketCap" ], "additionalProperties": false }, "parent": { "nullable": true, "description": "null when the reply targets the callout directly", "allOf": [ { "$ref": "#/components/schemas/Shared_3ba6ed1d0d06" } ] }, "reply": { "$ref": "#/components/schemas/Shared_3ba6ed1d0d06" } }, "required": [ "callout", "parent", "reply" ], "additionalProperties": false }, "description": "The user's live reply-quotes on this coin, newest first, at most quotesLimit; always empty without quotesLimit or without a callout" } }, "required": [ "callout", "quotes" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Get a user callout for a coin (legacy shape); quotesLimit adds the callout-sheet carousel quotes" } }, "/callout/{calloutId}": { "get": { "operationId": "get_callout_by_calloutId", "tags": [ "content.read" ], "summary": "Get a callout by id with its author identity", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN", "CALLOUT_NOT_FOUND" ], "x-api-scope": "content.read", "parameters": [ { "name": "calloutId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a callout by id with its author identity", "content": { "application/json": { "schema": { "type": "object", "properties": { "callout": { "nullable": true, "description": "null when no callout carries that id and when the row could not be mapped to the legacy shape", "type": "object", "properties": { "calloutId": { "type": "string" }, "userId": { "type": "string" }, "coinMint": { "type": "string" }, "marketCap": { "type": "number" }, "calloutPrice": { "type": "number", "description": "SOL-denominated; 0 both for a genuine zero and when the SOL price lookup failed open" }, "calloutPriceUsd": { "type": "number" }, "multiple": { "type": "number" }, "createdAt": { "type": "number", "description": "Epoch milliseconds; 0 when unparseable" }, "maxPriceSol": { "type": "number", "description": "SOL-denominated; 0 both for a genuine zero and when the SOL price lookup failed open" }, "maxPriceUsd": { "type": "number" }, "thesis": { "type": "string" }, "user_uuid": { "type": "string", "description": "Unread by every known caller; kept for wire compatibility, and always empty on the list read" }, "likes": { "type": "number" }, "hasLiked": { "nullable": true, "type": "boolean" }, "hasReposted": { "nullable": true, "type": "boolean" }, "repostCount": { "type": "number" }, "quoteCount": { "type": "number" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "createdAt": { "nullable": true, "type": "string" }, "likeCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "parentMessageId": { "nullable": true, "type": "string" }, "repostCount": { "type": "number" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" } }, "required": [ "id", "content", "createdAt", "likeCount", "mediaUrl", "parentMessageId", "repostCount" ], "additionalProperties": false }, "description": "Author updates (the author's own replies), newest first; empty when the route does not include them" }, "updateCount": { "type": "number" }, "commentCount": { "type": "number" }, "replyCount": { "type": "number" }, "maxMultiplier": { "nullable": true, "type": "number" }, "maxMultiplierAt": { "nullable": true, "type": "string" }, "viewCount": { "description": "The only counter here that is not zero-filled: absent means unknown (no counter row yet), never a real 0", "type": "number" }, "mediaUrl": { "nullable": true, "description": "Server-minted CDN URL; null when the callout carries no media", "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "quotedCalloutId": { "nullable": true, "description": "Set with quotedCallout null means the quote target is hidden or unavailable, never \"no quote\"", "type": "string" }, "quotedCallout": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Shared_85bd3a13acc3" } ] }, "chain": { "description": "CAIP-2 chain of the called-out ref; null when the row carries none", "nullable": true, "type": "string" }, "perp": { "description": "Set only on a perp callout; maxPriceSol is 0 when set", "nullable": true, "type": "object", "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "leverageBps": { "type": "number" }, "entryPx": { "nullable": true, "type": "number" }, "closePx": { "nullable": true, "type": "number" }, "closedAt": { "nullable": true, "type": "string" } }, "required": [ "side", "leverageBps", "entryPx", "closePx", "closedAt" ], "additionalProperties": false }, "assetClass": { "description": "ASSET_CLASS_NFT_LIKE on a card callout (collectible set); absent on every token and perp row", "type": "string", "enum": [ "ASSET_CLASS_TOKEN", "ASSET_CLASS_PERPETUAL", "ASSET_CLASS_NFT_LIKE" ] }, "collectible": { "description": "NFT_LIKE card callouts only: the card (identity, grade, mark, insured value, buyback, listing); multiple is then the card mark over calloutPriceUsd. Absent on every token callout", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false }, "userName": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad callout: user_uuid/userName/profileImage are the squad's while userId is the acting admin's posting wallet; route the author press on user_uuid + accountKind" }, "xUsername": { "nullable": true, "type": "string" }, "xFollowerCount": { "type": "number" } }, "required": [ "calloutId", "userId", "coinMint", "marketCap", "calloutPrice", "calloutPriceUsd", "multiple", "createdAt", "maxPriceSol", "maxPriceUsd", "user_uuid", "likes", "hasLiked", "hasReposted", "repostCount", "quoteCount", "updates", "updateCount", "commentCount", "replyCount", "maxMultiplier", "maxMultiplierAt", "mediaUrl", "quotedCalloutId", "quotedCallout", "userName", "profileImage", "isVerified", "verifiedBadgeVisible", "accountKind", "xUsername", "xFollowerCount" ], "additionalProperties": false } }, "required": [ "callout" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Error payload on the envelope", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "timestamp": { "type": "string" }, "path": { "type": "string" } }, "required": [ "statusCode", "timestamp", "path" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "CALLOUT_NOT_FOUND" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/callout/{calloutId}/likers": { "get": { "operationId": "get_callout_by_calloutId_likers", "tags": [ "graph.read" ], "summary": "List the profiles who liked a callout", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "calloutId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "List the profiles who liked a callout", "content": { "application/json": { "schema": { "type": "object", "properties": { "likers": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "bio": { "type": "string" }, "profileImageUrl": { "type": "string" }, "headerImageUrl": { "type": "string" }, "followerCount": { "type": "number" }, "followingCount": { "type": "number" }, "createdAt": { "nullable": true, "type": "string" }, "updatedAt": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "socials": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "username": { "type": "string" }, "linkedAt": { "nullable": true, "type": "string" } }, "required": [ "provider", "username", "linkedAt" ], "additionalProperties": false } }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true. The verified state itself is isVerified." }, "resolvedAvatarDecoration": { "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border. Treat absent as null.", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "PERSON", "GROUP" ] }, "memberCount": { "type": "number" }, "membershipPolicy": { "nullable": true, "type": "string", "enum": [ "INVITE" ] }, "groupBadges": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "role": { "type": "string" } }, "required": [ "groupId", "username", "profileImageUrl", "role" ], "additionalProperties": false } }, "generatedMedia": { "nullable": true, "type": "object", "properties": { "pnlLoop": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" } }, "required": [ "uid", "durationSeconds" ], "additionalProperties": false }, "replayIntro": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" }, "fireAt": { "type": "number" } }, "required": [ "uid", "durationSeconds", "fireAt" ], "additionalProperties": false } }, "required": [ "pnlLoop" ], "additionalProperties": false }, "isPumpUser": { "description": "false = unclaimed shell: an identity minted when someone followed an outside wallet that never signed in, served under a generated username. Render it as a wallet (address or the viewer’s wallet label), never as an account. Treat absent as true.", "type": "boolean" }, "viewerFollows": { "description": "Absent on unauthenticated reads", "type": "boolean" } }, "required": [ "userId", "username", "bio", "profileImageUrl", "headerImageUrl", "followerCount", "followingCount", "createdAt", "updatedAt", "walletAddress", "socials", "isVerified", "verifiedBadgeVisible", "kind", "memberCount", "membershipPolicy", "groupBadges", "generatedMedia" ], "additionalProperties": false } }, "hasMore": { "type": "boolean" } }, "required": [ "likers", "hasMore" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/callout/{calloutId}/quotes": { "get": { "operationId": "get_callout_by_calloutId_quotes", "tags": [ "content.read" ], "summary": "List quote posts of a callout", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "content.read", "parameters": [ { "name": "calloutId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "List quote posts of a callout", "content": { "application/json": { "schema": { "type": "object", "properties": { "quotes": { "type": "array", "items": { "$ref": "#/components/schemas/Shared_5643735df9ab" }, "description": "Reply-shaped quotes only, newest first — the pre-quote-callout shape, kept for readers that predate items" }, "items": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "reply" ] }, "reply": { "$ref": "#/components/schemas/Shared_5643735df9ab" } }, "required": [ "kind", "reply" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "callout" ] }, "callout": { "$ref": "#/components/schemas/Shared_35fd92fdd6a3" } }, "required": [ "kind", "callout" ], "additionalProperties": false } ] }, "description": "The full page, newest first, both shapes merged; scope matches quoteCount exactly. hasMore answers this merged page, not quotes" }, "hasMore": { "type": "boolean" } }, "required": [ "quotes", "items", "hasMore" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/callout/{calloutId}/replies": { "get": { "operationId": "get_callout_by_calloutId_replies", "tags": [ "content.read" ], "summary": "List replies on a callout", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN", "PARENT_REPLY_NOT_FOUND" ], "x-api-scope": "content.read", "parameters": [ { "name": "calloutId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "beforeId", "in": "query", "required": false, "schema": { "description": "Keyset cursor.", "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "description": "Offset page for POSITION walks (rank has no keyset)", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ALL", "EXCLUDE_AUTHOR", "AUTHOR_ONLY" ] } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "RECENCY", "POSITION", "PNL" ] } }, { "name": "parentReplyId", "in": "query", "required": false, "schema": { "description": "Page one reply's direct children instead of the callout's top level", "type": "string" } }, { "name": "nestedLimit", "in": "query", "required": false, "schema": { "description": "Hydrate up to N newest preview children per row.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "List replies on a callout", "content": { "application/json": { "schema": { "type": "object", "properties": { "replies": { "type": "array", "items": { "$ref": "#/components/schemas/Shared_5643735df9ab" }, "description": "One tree level, newest first; a page shorter than the requested limit marks the end of that level. On the ALL filter a dead reply whose subtree still holds live rows rides the page as a tombstone stub" } }, "required": [ "replies" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Error payload on the envelope", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "timestamp": { "type": "string" }, "path": { "type": "string" } }, "required": [ "statusCode", "timestamp", "path" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "PARENT_REPLY_NOT_FOUND" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/callout/{calloutId}/reposters": { "get": { "operationId": "get_callout_by_calloutId_reposters", "tags": [ "graph.read" ], "summary": "List the profiles who reposted a callout", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "calloutId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "List the profiles who reposted a callout", "content": { "application/json": { "schema": { "type": "object", "properties": { "reposters": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "bio": { "type": "string" }, "profileImageUrl": { "type": "string" }, "headerImageUrl": { "type": "string" }, "followerCount": { "type": "number" }, "followingCount": { "type": "number" }, "createdAt": { "nullable": true, "type": "string" }, "updatedAt": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "socials": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "username": { "type": "string" }, "linkedAt": { "nullable": true, "type": "string" } }, "required": [ "provider", "username", "linkedAt" ], "additionalProperties": false } }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true. The verified state itself is isVerified." }, "resolvedAvatarDecoration": { "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border. Treat absent as null.", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "PERSON", "GROUP" ] }, "memberCount": { "type": "number" }, "membershipPolicy": { "nullable": true, "type": "string", "enum": [ "INVITE" ] }, "groupBadges": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "role": { "type": "string" } }, "required": [ "groupId", "username", "profileImageUrl", "role" ], "additionalProperties": false } }, "generatedMedia": { "nullable": true, "type": "object", "properties": { "pnlLoop": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" } }, "required": [ "uid", "durationSeconds" ], "additionalProperties": false }, "replayIntro": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" }, "fireAt": { "type": "number" } }, "required": [ "uid", "durationSeconds", "fireAt" ], "additionalProperties": false } }, "required": [ "pnlLoop" ], "additionalProperties": false }, "isPumpUser": { "description": "false = unclaimed shell: an identity minted when someone followed an outside wallet that never signed in, served under a generated username. Render it as a wallet (address or the viewer’s wallet label), never as an account. Treat absent as true.", "type": "boolean" }, "viewerFollows": { "description": "Absent on unauthenticated reads", "type": "boolean" }, "position": { "description": "The reposter's own position in the callout's token; absent = none visible", "type": "object", "properties": { "amountHeld": { "type": "number" }, "valueUsd": { "nullable": true, "type": "number" }, "pnlUsd": { "nullable": true, "type": "number" }, "pnlPercentage": { "nullable": true, "type": "number" }, "isExited": { "type": "boolean" }, "costBasisAmount": { "type": "number", "description": "Use the amountBought pair there" }, "costBasisUsd": { "nullable": true, "type": "number" }, "amountBoughtUsd": { "nullable": true, "type": "number" }, "amountBought": { "nullable": true, "type": "number" }, "realizedPnlUsd": { "nullable": true, "type": "number" }, "avgEntryMcapUsd": { "nullable": true, "type": "number" }, "perp": { "nullable": true, "description": "The author's HyperCore position on a perp callout: live while open, the frozen close once closed; null on a spot position", "type": "object", "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "leverageBps": { "type": "number" }, "entryPx": { "nullable": true, "type": "number" }, "markPx": { "nullable": true, "type": "number" }, "closePx": { "nullable": true, "description": "The frozen close price; null while the position is open", "type": "number" }, "closedAt": { "nullable": true, "description": "ISO instant of the close; null while the position is open", "type": "string" }, "positionValueUsd": { "nullable": true, "type": "number" }, "marginUsd": { "nullable": true, "type": "number" }, "equityUsd": { "nullable": true, "description": "Account equity (USD) behind the position.", "type": "number" }, "stateAsOf": { "nullable": true, "description": "ISO instant of the clearinghouse state behind these figures", "type": "string" } }, "required": [ "side", "leverageBps", "entryPx", "markPx", "closePx", "closedAt", "positionValueUsd", "marginUsd", "equityUsd", "stateAsOf" ], "additionalProperties": false } }, "required": [ "amountHeld", "valueUsd", "pnlUsd", "pnlPercentage", "isExited", "costBasisAmount", "costBasisUsd", "amountBoughtUsd", "amountBought", "realizedPnlUsd", "avgEntryMcapUsd", "perp" ], "additionalProperties": false } }, "required": [ "userId", "username", "bio", "profileImageUrl", "headerImageUrl", "followerCount", "followingCount", "createdAt", "updatedAt", "walletAddress", "socials", "isVerified", "verifiedBadgeVisible", "kind", "memberCount", "membershipPolicy", "groupBadges", "generatedMedia" ], "additionalProperties": false } }, "hasMore": { "type": "boolean" } }, "required": [ "reposters", "hasMore" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/callout/{calloutId}/tailers": { "get": { "operationId": "get_callout_by_calloutId_tailers", "tags": [ "content.read" ], "summary": "List the wallets that tailed a callout", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "content.read", "parameters": [ { "name": "calloutId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "List the wallets that tailed a callout", "content": { "application/json": { "schema": { "type": "object", "properties": { "tailers": { "type": "array", "items": { "type": "object", "properties": { "profile": { "description": "Absent when the wallet resolves to no user", "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "bio": { "type": "string" }, "profileImageUrl": { "type": "string" }, "headerImageUrl": { "type": "string" }, "followerCount": { "type": "number" }, "followingCount": { "type": "number" }, "createdAt": { "nullable": true, "type": "string" }, "updatedAt": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "socials": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "username": { "type": "string" }, "linkedAt": { "nullable": true, "type": "string" } }, "required": [ "provider", "username", "linkedAt" ], "additionalProperties": false } }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true. The verified state itself is isVerified." }, "resolvedAvatarDecoration": { "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border. Treat absent as null.", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "PERSON", "GROUP" ] }, "memberCount": { "type": "number" }, "membershipPolicy": { "nullable": true, "type": "string", "enum": [ "INVITE" ] }, "groupBadges": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "role": { "type": "string" } }, "required": [ "groupId", "username", "profileImageUrl", "role" ], "additionalProperties": false } }, "generatedMedia": { "nullable": true, "type": "object", "properties": { "pnlLoop": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" } }, "required": [ "uid", "durationSeconds" ], "additionalProperties": false }, "replayIntro": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" }, "fireAt": { "type": "number" } }, "required": [ "uid", "durationSeconds", "fireAt" ], "additionalProperties": false } }, "required": [ "pnlLoop" ], "additionalProperties": false }, "isPumpUser": { "description": "false = unclaimed shell: an identity minted when someone followed an outside wallet that never signed in, served under a generated username. Render it as a wallet (address or the viewer’s wallet label), never as an account. Treat absent as true.", "type": "boolean" } }, "required": [ "userId", "username", "bio", "profileImageUrl", "headerImageUrl", "followerCount", "followingCount", "createdAt", "updatedAt", "walletAddress", "socials", "isVerified", "verifiedBadgeVisible", "kind", "memberCount", "membershipPolicy", "groupBadges", "generatedMedia" ], "additionalProperties": false }, "walletAddress": { "type": "string" }, "chainId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "firstSeenAt": { "nullable": true, "description": "Epoch ms of the tailer's first buy after the callout", "type": "number" }, "pnl1hUsd": { "nullable": true, "type": "number" }, "pnl4hUsd": { "nullable": true, "type": "number" }, "pnl24hUsd": { "nullable": true, "type": "number" }, "ath1hUsd": { "nullable": true, "description": "USD, the tailer's best-case-exit PnL over its own window [first in-window buy, +1 h]: max(0, in-window bought amount x highest outlier-screened 1 m candle high - in-window buy spend); >= 0; null until the 1 h ATH arm is served, when unavailable, or outside that horizon's cohort.", "type": "number" }, "ath4hUsd": { "nullable": true, "description": "USD, the tailer's best-case-exit PnL over its own window [first in-window buy, +4 h]: max(0, in-window bought amount x highest outlier-screened 1 m candle high - in-window buy spend); >= 0; null until the 4 h ATH arm is served, when unavailable, or outside that horizon's cohort.", "type": "number" }, "ath24hUsd": { "nullable": true, "description": "USD, the tailer's best-case-exit PnL over its own window [first in-window buy, +24 h]: max(0, in-window bought amount x highest outlier-screened 5 m candle high - in-window buy spend); >= 0; null until the 24 h ATH arm is served, when unavailable, or outside that horizon's cohort.", "type": "number" }, "positionUsd": { "nullable": true, "type": "number" }, "amountHeld": { "nullable": true, "type": "number" }, "pnlUsd": { "nullable": true, "type": "number" }, "isExited": { "nullable": true, "type": "boolean" } }, "required": [ "walletAddress", "chainId", "firstSeenAt", "pnl1hUsd", "pnl4hUsd", "pnl24hUsd", "ath1hUsd", "ath4hUsd", "ath24hUsd", "positionUsd", "amountHeld", "pnlUsd", "isExited" ], "additionalProperties": false, "description": "One tailer of a callout; null = unknown, never a real 0" }, "description": "Oldest tail first" }, "hasMore": { "type": "boolean" } }, "required": [ "tailers", "hasMore" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "description": "Error payload on the envelope. Also the shared envelope at this status: a platform refusal, or a validation refusal whose `message` is a string array and whose `error` is the HTTP reason phrase.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "timestamp": { "type": "string" }, "path": { "type": "string" }, "error": { "type": "string", "enum": [ "API_CREDENTIAL_NOT_ALLOWED" ] }, "message": { "type": "string" } }, "required": [ "statusCode", "timestamp", "path", "error", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "timestamp": { "type": "string" }, "path": { "type": "string" }, "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "statusCode", "timestamp", "path", "error", "message" ] }, { "$ref": "#/components/schemas/Error" } ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "timestamp": { "type": "string" }, "path": { "type": "string" } }, "required": [ "statusCode", "timestamp", "path" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Not Found" ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "error", "message" ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/competitions": { "get": { "operationId": "get_competitions", "tags": [ "leaderboards.read" ], "summary": "Every competition in three viewer-independent buckets", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "leaderboards.read", "responses": { "200": { "description": "Every competition in three viewer-independent buckets: upcoming, live (registration or live) and past (the 50 latest ended)", "content": { "application/json": { "schema": { "type": "object", "properties": { "upcoming": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "group", "person" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Who competes: squads (group) or individual traders (person); squads ship first, so treat an unknown value as unsupported. Known values: group, person" }, "title": { "type": "string" }, "description": { "type": "string", "description": "May be empty" }, "prizeCopy": { "type": "string", "description": "Free-text prize headline shown as-is (prizes are paid by hand); may be empty. The per-rank amounts are prizes" }, "imageUrl": { "nullable": true, "description": "Card image URL on the images CDN; null when none is set", "type": "string" }, "prizes": { "type": "array", "items": { "type": "object", "properties": { "rankFrom": { "type": "number", "description": "First rank the tier covers, 1-based" }, "rankTo": { "type": "number", "description": "Last rank the tier covers, inclusive; >= rankFrom" }, "amount": { "type": "string", "description": "Display text of the prize per rank, e.g. \"$5,000\" or \"2 SOL\"; a squad prize goes to the squad" } }, "required": [ "rankFrom", "rankTo", "amount" ], "additionalProperties": false }, "description": "Per-rank prize tiers, rankFrom ascending and non-overlapping (gaps allowed); empty when none are set" }, "registrationOpensAt": { "nullable": true, "description": "ISO 8601; when registration opens. Before it the competition is listed as upcoming and register answers COMPETITION_REGISTRATION_NOT_OPEN", "type": "string" }, "registrationClosesAt": { "nullable": true, "description": "ISO 8601; equal to endsAt when joining stays open for the run", "type": "string" }, "startsAt": { "nullable": true, "description": "ISO 8601, on the hour UTC; every entry scores from here whenever it registered", "type": "string" }, "endsAt": { "nullable": true, "description": "ISO 8601, on the hour UTC", "type": "string" }, "minMembers": { "type": "number", "description": "1 for person competitions" }, "maxMembers": { "type": "number", "description": "1 for person competitions" }, "maxEntries": { "type": "number", "description": "Registration cap" }, "entriesCount": { "type": "number", "description": "Entries registered so far, struck ones included" }, "participants": { "type": "number", "description": "Entries not struck (squads for a squad competition, traders for a person one); 0 when none or the count read failed" }, "joinable": { "type": "boolean", "description": "Registration is open now (registrationOpensAt <= now < registrationClosesAt) and the competition is not full; says nothing about the caller's own eligibility" }, "phase": { "anyOf": [ { "type": "string", "enum": [ "upcoming", "registration", "live", "ended" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Scores freeze once isFinal). Known values: upcoming, registration, live, ended" }, "isFinal": { "type": "boolean", "description": "True once the final result is persisted; scores no longer move, though a later strike or hide still drops a row" }, "top": { "type": "array", "items": { "type": "object", "properties": { "entryId": { "type": "string" }, "participantId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "group", "person" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Who competes: squads (group) or individual traders (person); squads ship first, so treat an unknown value as unsupported. Known values: group, person" }, "rank": { "type": "number", "description": "1-based ordinal rank by pnlUsd descending; a tie goes to the earlier registration, then entry id. 0 = not ranked: struck, a squad hidden from the PnL boards, no scoring wallet, or before the first build" }, "pnlUsd": { "type": "number", "description": "Sum of the roster's window PnL in USD (realized + unrealized) — the ranking key" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "buySpendSol": { "type": "number" }, "memberCount": { "type": "number", "description": "Roster size (snapshot rows, walletless members included); 0 before the snapshot at startsAt" }, "membersFresh": { "type": "number", "description": "Roster members whose leg is inside the freshness bound; a stale member keeps its last-good legs in the sum" }, "struck": { "type": "boolean", "description": "Disqualified for this competition: rank 0 and left out of the leaderboard entries, totalRanked, participants, top and winners; still served as the caller's own viewer entry and by entry detail" }, "lastRefreshedAtMs": { "type": "number", "description": "Oldest refresh among the summed members (unix ms); the finalize time on a final board; 0 before the first build" }, "positionsCount": { "type": "number", "description": "Person rows: the participant's live positions count, never sliced by positionsLimit; 0 for squads and on a final board" }, "topPositions": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri" ], "additionalProperties": false }, "description": "Person rows: largest fresh USD value first, sliced to positionsLimit; empty for squads and on a final board" }, "walletAddress": { "nullable": true, "description": "Person rows: the trader's Solana board wallet snapshotted at competition start (base58); null for squads, a walletless member, and a rank-0 row before the first build", "type": "string" }, "username": { "nullable": true, "description": "Null when the lookup missed", "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" } }, "required": [ "entryId", "participantId", "kind", "rank", "pnlUsd", "realizedPnlUsd", "unrealizedPnlUsd", "buySpendSol", "memberCount", "membersFresh", "struck", "lastRefreshedAtMs", "positionsCount", "topPositions", "walletAddress", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible" ], "additionalProperties": false }, "description": "Always present, [] when not applicable: phase registration or live only, the latest board build's ranks 1..3, rank ascending; [] before the first build, on a board read fault (list only) and in every other phase" }, "winners": { "type": "array", "items": { "type": "object", "properties": { "entryId": { "type": "string" }, "participantId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "group", "person" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Who competes: squads (group) or individual traders (person); squads ship first, so treat an unknown value as unsupported. Known values: group, person" }, "rank": { "type": "number", "description": "1-based ordinal rank by pnlUsd descending; a tie goes to the earlier registration, then entry id. 0 = not ranked: struck, a squad hidden from the PnL boards, no scoring wallet, or before the first build" }, "pnlUsd": { "type": "number", "description": "Sum of the roster's window PnL in USD (realized + unrealized) — the ranking key" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "buySpendSol": { "type": "number" }, "memberCount": { "type": "number", "description": "Roster size (snapshot rows, walletless members included); 0 before the snapshot at startsAt" }, "membersFresh": { "type": "number", "description": "Roster members whose leg is inside the freshness bound; a stale member keeps its last-good legs in the sum" }, "struck": { "type": "boolean", "description": "Disqualified for this competition: rank 0 and left out of the leaderboard entries, totalRanked, participants, top and winners; still served as the caller's own viewer entry and by entry detail" }, "lastRefreshedAtMs": { "type": "number", "description": "Oldest refresh among the summed members (unix ms); the finalize time on a final board; 0 before the first build" }, "positionsCount": { "type": "number", "description": "Person rows: the participant's live positions count, never sliced by positionsLimit; 0 for squads and on a final board" }, "topPositions": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri" ], "additionalProperties": false }, "description": "Person rows: largest fresh USD value first, sliced to positionsLimit; empty for squads and on a final board" }, "walletAddress": { "nullable": true, "description": "Person rows: the trader's Solana board wallet snapshotted at competition start (base58); null for squads, a walletless member, and a rank-0 row before the first build", "type": "string" }, "username": { "nullable": true, "description": "Null when the lookup missed", "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "prize": { "nullable": true, "description": "The amount of the prizes tier covering this row's rank; null when no tier covers it", "type": "string" } }, "required": [ "entryId", "participantId", "kind", "rank", "pnlUsd", "realizedPnlUsd", "unrealizedPnlUsd", "buySpendSol", "memberCount", "membersFresh", "struck", "lastRefreshedAtMs", "positionsCount", "topPositions", "walletAddress", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible", "prize" ], "additionalProperties": false }, "description": "Always present, [] when not applicable: phase ended only, the served ranks 1..N (N = the largest prizes rankTo, or 3 when prizes is empty) with the current strikes and hides applied, rank ascending; [] when nothing ranked, on a board read fault (list only) and in every other phase" } }, "required": [ "id", "slug", "kind", "title", "description", "prizeCopy", "imageUrl", "prizes", "registrationOpensAt", "registrationClosesAt", "startsAt", "endsAt", "minMembers", "maxMembers", "maxEntries", "entriesCount", "participants", "joinable", "phase", "isFinal", "top", "winners" ], "additionalProperties": false }, "description": "now < registrationOpensAt (phase upcoming), startsAt ascending" }, "live": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "group", "person" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Who competes: squads (group) or individual traders (person); squads ship first, so treat an unknown value as unsupported. Known values: group, person" }, "title": { "type": "string" }, "description": { "type": "string", "description": "May be empty" }, "prizeCopy": { "type": "string", "description": "Free-text prize headline shown as-is (prizes are paid by hand); may be empty. The per-rank amounts are prizes" }, "imageUrl": { "nullable": true, "description": "Card image URL on the images CDN; null when none is set", "type": "string" }, "prizes": { "type": "array", "items": { "type": "object", "properties": { "rankFrom": { "type": "number", "description": "First rank the tier covers, 1-based" }, "rankTo": { "type": "number", "description": "Last rank the tier covers, inclusive; >= rankFrom" }, "amount": { "type": "string", "description": "Display text of the prize per rank, e.g. \"$5,000\" or \"2 SOL\"; a squad prize goes to the squad" } }, "required": [ "rankFrom", "rankTo", "amount" ], "additionalProperties": false }, "description": "Per-rank prize tiers, rankFrom ascending and non-overlapping (gaps allowed); empty when none are set" }, "registrationOpensAt": { "nullable": true, "description": "ISO 8601; when registration opens. Before it the competition is listed as upcoming and register answers COMPETITION_REGISTRATION_NOT_OPEN", "type": "string" }, "registrationClosesAt": { "nullable": true, "description": "ISO 8601; equal to endsAt when joining stays open for the run", "type": "string" }, "startsAt": { "nullable": true, "description": "ISO 8601, on the hour UTC; every entry scores from here whenever it registered", "type": "string" }, "endsAt": { "nullable": true, "description": "ISO 8601, on the hour UTC", "type": "string" }, "minMembers": { "type": "number", "description": "1 for person competitions" }, "maxMembers": { "type": "number", "description": "1 for person competitions" }, "maxEntries": { "type": "number", "description": "Registration cap" }, "entriesCount": { "type": "number", "description": "Entries registered so far, struck ones included" }, "participants": { "type": "number", "description": "Entries not struck (squads for a squad competition, traders for a person one); 0 when none or the count read failed" }, "joinable": { "type": "boolean", "description": "Registration is open now (registrationOpensAt <= now < registrationClosesAt) and the competition is not full; says nothing about the caller's own eligibility" }, "phase": { "anyOf": [ { "type": "string", "enum": [ "upcoming", "registration", "live", "ended" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Scores freeze once isFinal). Known values: upcoming, registration, live, ended" }, "isFinal": { "type": "boolean", "description": "True once the final result is persisted; scores no longer move, though a later strike or hide still drops a row" }, "top": { "type": "array", "items": { "type": "object", "properties": { "entryId": { "type": "string" }, "participantId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "group", "person" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Who competes: squads (group) or individual traders (person); squads ship first, so treat an unknown value as unsupported. Known values: group, person" }, "rank": { "type": "number", "description": "1-based ordinal rank by pnlUsd descending; a tie goes to the earlier registration, then entry id. 0 = not ranked: struck, a squad hidden from the PnL boards, no scoring wallet, or before the first build" }, "pnlUsd": { "type": "number", "description": "Sum of the roster's window PnL in USD (realized + unrealized) — the ranking key" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "buySpendSol": { "type": "number" }, "memberCount": { "type": "number", "description": "Roster size (snapshot rows, walletless members included); 0 before the snapshot at startsAt" }, "membersFresh": { "type": "number", "description": "Roster members whose leg is inside the freshness bound; a stale member keeps its last-good legs in the sum" }, "struck": { "type": "boolean", "description": "Disqualified for this competition: rank 0 and left out of the leaderboard entries, totalRanked, participants, top and winners; still served as the caller's own viewer entry and by entry detail" }, "lastRefreshedAtMs": { "type": "number", "description": "Oldest refresh among the summed members (unix ms); the finalize time on a final board; 0 before the first build" }, "positionsCount": { "type": "number", "description": "Person rows: the participant's live positions count, never sliced by positionsLimit; 0 for squads and on a final board" }, "topPositions": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri" ], "additionalProperties": false }, "description": "Person rows: largest fresh USD value first, sliced to positionsLimit; empty for squads and on a final board" }, "walletAddress": { "nullable": true, "description": "Person rows: the trader's Solana board wallet snapshotted at competition start (base58); null for squads, a walletless member, and a rank-0 row before the first build", "type": "string" }, "username": { "nullable": true, "description": "Null when the lookup missed", "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" } }, "required": [ "entryId", "participantId", "kind", "rank", "pnlUsd", "realizedPnlUsd", "unrealizedPnlUsd", "buySpendSol", "memberCount", "membersFresh", "struck", "lastRefreshedAtMs", "positionsCount", "topPositions", "walletAddress", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible" ], "additionalProperties": false }, "description": "Always present, [] when not applicable: phase registration or live only, the latest board build's ranks 1..3, rank ascending; [] before the first build, on a board read fault (list only) and in every other phase" }, "winners": { "type": "array", "items": { "type": "object", "properties": { "entryId": { "type": "string" }, "participantId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "group", "person" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Who competes: squads (group) or individual traders (person); squads ship first, so treat an unknown value as unsupported. Known values: group, person" }, "rank": { "type": "number", "description": "1-based ordinal rank by pnlUsd descending; a tie goes to the earlier registration, then entry id. 0 = not ranked: struck, a squad hidden from the PnL boards, no scoring wallet, or before the first build" }, "pnlUsd": { "type": "number", "description": "Sum of the roster's window PnL in USD (realized + unrealized) — the ranking key" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "buySpendSol": { "type": "number" }, "memberCount": { "type": "number", "description": "Roster size (snapshot rows, walletless members included); 0 before the snapshot at startsAt" }, "membersFresh": { "type": "number", "description": "Roster members whose leg is inside the freshness bound; a stale member keeps its last-good legs in the sum" }, "struck": { "type": "boolean", "description": "Disqualified for this competition: rank 0 and left out of the leaderboard entries, totalRanked, participants, top and winners; still served as the caller's own viewer entry and by entry detail" }, "lastRefreshedAtMs": { "type": "number", "description": "Oldest refresh among the summed members (unix ms); the finalize time on a final board; 0 before the first build" }, "positionsCount": { "type": "number", "description": "Person rows: the participant's live positions count, never sliced by positionsLimit; 0 for squads and on a final board" }, "topPositions": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri" ], "additionalProperties": false }, "description": "Person rows: largest fresh USD value first, sliced to positionsLimit; empty for squads and on a final board" }, "walletAddress": { "nullable": true, "description": "Person rows: the trader's Solana board wallet snapshotted at competition start (base58); null for squads, a walletless member, and a rank-0 row before the first build", "type": "string" }, "username": { "nullable": true, "description": "Null when the lookup missed", "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "prize": { "nullable": true, "description": "The amount of the prizes tier covering this row's rank; null when no tier covers it", "type": "string" } }, "required": [ "entryId", "participantId", "kind", "rank", "pnlUsd", "realizedPnlUsd", "unrealizedPnlUsd", "buySpendSol", "memberCount", "membersFresh", "struck", "lastRefreshedAtMs", "positionsCount", "topPositions", "walletAddress", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible", "prize" ], "additionalProperties": false }, "description": "Always present, [] when not applicable: phase ended only, the served ranks 1..N (N = the largest prizes rankTo, or 3 when prizes is empty) with the current strikes and hides applied, rank ascending; [] when nothing ranked, on a board read fault (list only) and in every other phase" } }, "required": [ "id", "slug", "kind", "title", "description", "prizeCopy", "imageUrl", "prizes", "registrationOpensAt", "registrationClosesAt", "startsAt", "endsAt", "minMembers", "maxMembers", "maxEntries", "entriesCount", "participants", "joinable", "phase", "isFinal", "top", "winners" ], "additionalProperties": false }, "description": "registrationOpensAt <= now < endsAt (phase registration or live), startsAt ascending; these carry top" }, "past": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "group", "person" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Who competes: squads (group) or individual traders (person); squads ship first, so treat an unknown value as unsupported. Known values: group, person" }, "title": { "type": "string" }, "description": { "type": "string", "description": "May be empty" }, "prizeCopy": { "type": "string", "description": "Free-text prize headline shown as-is (prizes are paid by hand); may be empty. The per-rank amounts are prizes" }, "imageUrl": { "nullable": true, "description": "Card image URL on the images CDN; null when none is set", "type": "string" }, "prizes": { "type": "array", "items": { "type": "object", "properties": { "rankFrom": { "type": "number", "description": "First rank the tier covers, 1-based" }, "rankTo": { "type": "number", "description": "Last rank the tier covers, inclusive; >= rankFrom" }, "amount": { "type": "string", "description": "Display text of the prize per rank, e.g. \"$5,000\" or \"2 SOL\"; a squad prize goes to the squad" } }, "required": [ "rankFrom", "rankTo", "amount" ], "additionalProperties": false }, "description": "Per-rank prize tiers, rankFrom ascending and non-overlapping (gaps allowed); empty when none are set" }, "registrationOpensAt": { "nullable": true, "description": "ISO 8601; when registration opens. Before it the competition is listed as upcoming and register answers COMPETITION_REGISTRATION_NOT_OPEN", "type": "string" }, "registrationClosesAt": { "nullable": true, "description": "ISO 8601; equal to endsAt when joining stays open for the run", "type": "string" }, "startsAt": { "nullable": true, "description": "ISO 8601, on the hour UTC; every entry scores from here whenever it registered", "type": "string" }, "endsAt": { "nullable": true, "description": "ISO 8601, on the hour UTC", "type": "string" }, "minMembers": { "type": "number", "description": "1 for person competitions" }, "maxMembers": { "type": "number", "description": "1 for person competitions" }, "maxEntries": { "type": "number", "description": "Registration cap" }, "entriesCount": { "type": "number", "description": "Entries registered so far, struck ones included" }, "participants": { "type": "number", "description": "Entries not struck (squads for a squad competition, traders for a person one); 0 when none or the count read failed" }, "joinable": { "type": "boolean", "description": "Registration is open now (registrationOpensAt <= now < registrationClosesAt) and the competition is not full; says nothing about the caller's own eligibility" }, "phase": { "anyOf": [ { "type": "string", "enum": [ "upcoming", "registration", "live", "ended" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Scores freeze once isFinal). Known values: upcoming, registration, live, ended" }, "isFinal": { "type": "boolean", "description": "True once the final result is persisted; scores no longer move, though a later strike or hide still drops a row" }, "top": { "type": "array", "items": { "type": "object", "properties": { "entryId": { "type": "string" }, "participantId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "group", "person" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Who competes: squads (group) or individual traders (person); squads ship first, so treat an unknown value as unsupported. Known values: group, person" }, "rank": { "type": "number", "description": "1-based ordinal rank by pnlUsd descending; a tie goes to the earlier registration, then entry id. 0 = not ranked: struck, a squad hidden from the PnL boards, no scoring wallet, or before the first build" }, "pnlUsd": { "type": "number", "description": "Sum of the roster's window PnL in USD (realized + unrealized) — the ranking key" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "buySpendSol": { "type": "number" }, "memberCount": { "type": "number", "description": "Roster size (snapshot rows, walletless members included); 0 before the snapshot at startsAt" }, "membersFresh": { "type": "number", "description": "Roster members whose leg is inside the freshness bound; a stale member keeps its last-good legs in the sum" }, "struck": { "type": "boolean", "description": "Disqualified for this competition: rank 0 and left out of the leaderboard entries, totalRanked, participants, top and winners; still served as the caller's own viewer entry and by entry detail" }, "lastRefreshedAtMs": { "type": "number", "description": "Oldest refresh among the summed members (unix ms); the finalize time on a final board; 0 before the first build" }, "positionsCount": { "type": "number", "description": "Person rows: the participant's live positions count, never sliced by positionsLimit; 0 for squads and on a final board" }, "topPositions": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri" ], "additionalProperties": false }, "description": "Person rows: largest fresh USD value first, sliced to positionsLimit; empty for squads and on a final board" }, "walletAddress": { "nullable": true, "description": "Person rows: the trader's Solana board wallet snapshotted at competition start (base58); null for squads, a walletless member, and a rank-0 row before the first build", "type": "string" }, "username": { "nullable": true, "description": "Null when the lookup missed", "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" } }, "required": [ "entryId", "participantId", "kind", "rank", "pnlUsd", "realizedPnlUsd", "unrealizedPnlUsd", "buySpendSol", "memberCount", "membersFresh", "struck", "lastRefreshedAtMs", "positionsCount", "topPositions", "walletAddress", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible" ], "additionalProperties": false }, "description": "Always present, [] when not applicable: phase registration or live only, the latest board build's ranks 1..3, rank ascending; [] before the first build, on a board read fault (list only) and in every other phase" }, "winners": { "type": "array", "items": { "type": "object", "properties": { "entryId": { "type": "string" }, "participantId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "group", "person" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Who competes: squads (group) or individual traders (person); squads ship first, so treat an unknown value as unsupported. Known values: group, person" }, "rank": { "type": "number", "description": "1-based ordinal rank by pnlUsd descending; a tie goes to the earlier registration, then entry id. 0 = not ranked: struck, a squad hidden from the PnL boards, no scoring wallet, or before the first build" }, "pnlUsd": { "type": "number", "description": "Sum of the roster's window PnL in USD (realized + unrealized) — the ranking key" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "buySpendSol": { "type": "number" }, "memberCount": { "type": "number", "description": "Roster size (snapshot rows, walletless members included); 0 before the snapshot at startsAt" }, "membersFresh": { "type": "number", "description": "Roster members whose leg is inside the freshness bound; a stale member keeps its last-good legs in the sum" }, "struck": { "type": "boolean", "description": "Disqualified for this competition: rank 0 and left out of the leaderboard entries, totalRanked, participants, top and winners; still served as the caller's own viewer entry and by entry detail" }, "lastRefreshedAtMs": { "type": "number", "description": "Oldest refresh among the summed members (unix ms); the finalize time on a final board; 0 before the first build" }, "positionsCount": { "type": "number", "description": "Person rows: the participant's live positions count, never sliced by positionsLimit; 0 for squads and on a final board" }, "topPositions": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri" ], "additionalProperties": false }, "description": "Person rows: largest fresh USD value first, sliced to positionsLimit; empty for squads and on a final board" }, "walletAddress": { "nullable": true, "description": "Person rows: the trader's Solana board wallet snapshotted at competition start (base58); null for squads, a walletless member, and a rank-0 row before the first build", "type": "string" }, "username": { "nullable": true, "description": "Null when the lookup missed", "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "prize": { "nullable": true, "description": "The amount of the prizes tier covering this row's rank; null when no tier covers it", "type": "string" } }, "required": [ "entryId", "participantId", "kind", "rank", "pnlUsd", "realizedPnlUsd", "unrealizedPnlUsd", "buySpendSol", "memberCount", "membersFresh", "struck", "lastRefreshedAtMs", "positionsCount", "topPositions", "walletAddress", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible", "prize" ], "additionalProperties": false }, "description": "Always present, [] when not applicable: phase ended only, the served ranks 1..N (N = the largest prizes rankTo, or 3 when prizes is empty) with the current strikes and hides applied, rank ascending; [] when nothing ranked, on a board read fault (list only) and in every other phase" } }, "required": [ "id", "slug", "kind", "title", "description", "prizeCopy", "imageUrl", "prizes", "registrationOpensAt", "registrationClosesAt", "startsAt", "endsAt", "minMembers", "maxMembers", "maxEntries", "entriesCount", "participants", "joinable", "phase", "isFinal", "top", "winners" ], "additionalProperties": false }, "description": "At most 50 competitions with now >= endsAt (phase ended), the latest endsAt first; these carry winners" } }, "required": [ "upcoming", "live", "past" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Every competition in three viewer-independent buckets: upcoming, live (registration or live) and past (the 50 latest ended)" } }, "/competitions/{idOrSlug}": { "get": { "operationId": "get_competitions_by_idOrSlug", "tags": [ "leaderboards.read" ], "summary": "One competition by id or slug with its ranked board", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "leaderboards.read", "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "schema": { "type": "string", "description": "Competition id (UUID) or slug" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Leaderboard rows served (default and ceiling 100; out-of-range values clamp).", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "positionsLimit", "in": "query", "required": false, "schema": { "description": "Top positions returned per row (leaderboard, top, winners, viewer entry) as icons (default 3; values above 5 clamp to 5; 0 = count only). Squad rows carry none.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "One competition by id or slug with its ranked board. `viewer` (own entry and eligibility) is viewer-relative: present on a signed-in read, absent on the API host", "content": { "application/json": { "schema": { "type": "object", "properties": { "competition": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "group", "person" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Who competes: squads (group) or individual traders (person); squads ship first, so treat an unknown value as unsupported. Known values: group, person" }, "title": { "type": "string" }, "description": { "type": "string", "description": "May be empty" }, "prizeCopy": { "type": "string", "description": "Free-text prize headline shown as-is (prizes are paid by hand); may be empty. The per-rank amounts are prizes" }, "imageUrl": { "nullable": true, "description": "Card image URL on the images CDN; null when none is set", "type": "string" }, "prizes": { "type": "array", "items": { "type": "object", "properties": { "rankFrom": { "type": "number", "description": "First rank the tier covers, 1-based" }, "rankTo": { "type": "number", "description": "Last rank the tier covers, inclusive; >= rankFrom" }, "amount": { "type": "string", "description": "Display text of the prize per rank, e.g. \"$5,000\" or \"2 SOL\"; a squad prize goes to the squad" } }, "required": [ "rankFrom", "rankTo", "amount" ], "additionalProperties": false }, "description": "Per-rank prize tiers, rankFrom ascending and non-overlapping (gaps allowed); empty when none are set" }, "registrationOpensAt": { "nullable": true, "description": "ISO 8601; when registration opens. Before it the competition is listed as upcoming and register answers COMPETITION_REGISTRATION_NOT_OPEN", "type": "string" }, "registrationClosesAt": { "nullable": true, "description": "ISO 8601; equal to endsAt when joining stays open for the run", "type": "string" }, "startsAt": { "nullable": true, "description": "ISO 8601, on the hour UTC; every entry scores from here whenever it registered", "type": "string" }, "endsAt": { "nullable": true, "description": "ISO 8601, on the hour UTC", "type": "string" }, "minMembers": { "type": "number", "description": "1 for person competitions" }, "maxMembers": { "type": "number", "description": "1 for person competitions" }, "maxEntries": { "type": "number", "description": "Registration cap" }, "entriesCount": { "type": "number", "description": "Entries registered so far, struck ones included" }, "participants": { "type": "number", "description": "Entries not struck (squads for a squad competition, traders for a person one); 0 when none or the count read failed" }, "joinable": { "type": "boolean", "description": "Registration is open now (registrationOpensAt <= now < registrationClosesAt) and the competition is not full; says nothing about the caller's own eligibility" }, "phase": { "anyOf": [ { "type": "string", "enum": [ "upcoming", "registration", "live", "ended" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Scores freeze once isFinal). Known values: upcoming, registration, live, ended" }, "isFinal": { "type": "boolean", "description": "True once the final result is persisted; scores no longer move, though a later strike or hide still drops a row" }, "top": { "type": "array", "items": { "type": "object", "properties": { "entryId": { "type": "string" }, "participantId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "group", "person" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Who competes: squads (group) or individual traders (person); squads ship first, so treat an unknown value as unsupported. Known values: group, person" }, "rank": { "type": "number", "description": "1-based ordinal rank by pnlUsd descending; a tie goes to the earlier registration, then entry id. 0 = not ranked: struck, a squad hidden from the PnL boards, no scoring wallet, or before the first build" }, "pnlUsd": { "type": "number", "description": "Sum of the roster's window PnL in USD (realized + unrealized) — the ranking key" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "buySpendSol": { "type": "number" }, "memberCount": { "type": "number", "description": "Roster size (snapshot rows, walletless members included); 0 before the snapshot at startsAt" }, "membersFresh": { "type": "number", "description": "Roster members whose leg is inside the freshness bound; a stale member keeps its last-good legs in the sum" }, "struck": { "type": "boolean", "description": "Disqualified for this competition: rank 0 and left out of the leaderboard entries, totalRanked, participants, top and winners; still served as the caller's own viewer entry and by entry detail" }, "lastRefreshedAtMs": { "type": "number", "description": "Oldest refresh among the summed members (unix ms); the finalize time on a final board; 0 before the first build" }, "positionsCount": { "type": "number", "description": "Person rows: the participant's live positions count, never sliced by positionsLimit; 0 for squads and on a final board" }, "topPositions": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri" ], "additionalProperties": false }, "description": "Person rows: largest fresh USD value first, sliced to positionsLimit; empty for squads and on a final board" }, "walletAddress": { "nullable": true, "description": "Person rows: the trader's Solana board wallet snapshotted at competition start (base58); null for squads, a walletless member, and a rank-0 row before the first build", "type": "string" }, "username": { "nullable": true, "description": "Null when the lookup missed", "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" } }, "required": [ "entryId", "participantId", "kind", "rank", "pnlUsd", "realizedPnlUsd", "unrealizedPnlUsd", "buySpendSol", "memberCount", "membersFresh", "struck", "lastRefreshedAtMs", "positionsCount", "topPositions", "walletAddress", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible" ], "additionalProperties": false }, "description": "Always present, [] when not applicable: phase registration or live only, the latest board build's ranks 1..3, rank ascending; [] before the first build, on a board read fault (list only) and in every other phase" }, "winners": { "type": "array", "items": { "type": "object", "properties": { "entryId": { "type": "string" }, "participantId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "group", "person" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Who competes: squads (group) or individual traders (person); squads ship first, so treat an unknown value as unsupported. Known values: group, person" }, "rank": { "type": "number", "description": "1-based ordinal rank by pnlUsd descending; a tie goes to the earlier registration, then entry id. 0 = not ranked: struck, a squad hidden from the PnL boards, no scoring wallet, or before the first build" }, "pnlUsd": { "type": "number", "description": "Sum of the roster's window PnL in USD (realized + unrealized) — the ranking key" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "buySpendSol": { "type": "number" }, "memberCount": { "type": "number", "description": "Roster size (snapshot rows, walletless members included); 0 before the snapshot at startsAt" }, "membersFresh": { "type": "number", "description": "Roster members whose leg is inside the freshness bound; a stale member keeps its last-good legs in the sum" }, "struck": { "type": "boolean", "description": "Disqualified for this competition: rank 0 and left out of the leaderboard entries, totalRanked, participants, top and winners; still served as the caller's own viewer entry and by entry detail" }, "lastRefreshedAtMs": { "type": "number", "description": "Oldest refresh among the summed members (unix ms); the finalize time on a final board; 0 before the first build" }, "positionsCount": { "type": "number", "description": "Person rows: the participant's live positions count, never sliced by positionsLimit; 0 for squads and on a final board" }, "topPositions": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri" ], "additionalProperties": false }, "description": "Person rows: largest fresh USD value first, sliced to positionsLimit; empty for squads and on a final board" }, "walletAddress": { "nullable": true, "description": "Person rows: the trader's Solana board wallet snapshotted at competition start (base58); null for squads, a walletless member, and a rank-0 row before the first build", "type": "string" }, "username": { "nullable": true, "description": "Null when the lookup missed", "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "prize": { "nullable": true, "description": "The amount of the prizes tier covering this row's rank; null when no tier covers it", "type": "string" } }, "required": [ "entryId", "participantId", "kind", "rank", "pnlUsd", "realizedPnlUsd", "unrealizedPnlUsd", "buySpendSol", "memberCount", "membersFresh", "struck", "lastRefreshedAtMs", "positionsCount", "topPositions", "walletAddress", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible", "prize" ], "additionalProperties": false }, "description": "Always present, [] when not applicable: phase ended only, the served ranks 1..N (N = the largest prizes rankTo, or 3 when prizes is empty) with the current strikes and hides applied, rank ascending; [] when nothing ranked, on a board read fault (list only) and in every other phase" } }, "required": [ "id", "slug", "kind", "title", "description", "prizeCopy", "imageUrl", "prizes", "registrationOpensAt", "registrationClosesAt", "startsAt", "endsAt", "minMembers", "maxMembers", "maxEntries", "entriesCount", "participants", "joinable", "phase", "isFinal", "top", "winners" ], "additionalProperties": false }, "leaderboard": { "type": "object", "properties": { "builtAtMs": { "type": "number", "description": "When the served board was built (unix ms); 0 before the first build" }, "startSec": { "type": "number", "description": "Scoring window start (calendar unix seconds) = startsAt — unlike windowStartSec on the rolling boards" }, "endSec": { "type": "number", "description": "Scoring window end the served legs were read at (unix seconds): the last build while live, endsAt once final" }, "totalRanked": { "type": "number", "description": "Ranked entries on the whole board (rank 1 and up); rank-0 rows are not counted" }, "isFinal": { "type": "boolean", "description": "True when serving the persisted final result, overlaid with the current strikes and hides (ranks re-densify at read)" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "entryId": { "type": "string" }, "participantId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "group", "person" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Who competes: squads (group) or individual traders (person); squads ship first, so treat an unknown value as unsupported. Known values: group, person" }, "rank": { "type": "number", "description": "1-based ordinal rank by pnlUsd descending; a tie goes to the earlier registration, then entry id. 0 = not ranked: struck, a squad hidden from the PnL boards, no scoring wallet, or before the first build" }, "pnlUsd": { "type": "number", "description": "Sum of the roster's window PnL in USD (realized + unrealized) — the ranking key" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "buySpendSol": { "type": "number" }, "memberCount": { "type": "number", "description": "Roster size (snapshot rows, walletless members included); 0 before the snapshot at startsAt" }, "membersFresh": { "type": "number", "description": "Roster members whose leg is inside the freshness bound; a stale member keeps its last-good legs in the sum" }, "struck": { "type": "boolean", "description": "Disqualified for this competition: rank 0 and left out of the leaderboard entries, totalRanked, participants, top and winners; still served as the caller's own viewer entry and by entry detail" }, "lastRefreshedAtMs": { "type": "number", "description": "Oldest refresh among the summed members (unix ms); the finalize time on a final board; 0 before the first build" }, "positionsCount": { "type": "number", "description": "Person rows: the participant's live positions count, never sliced by positionsLimit; 0 for squads and on a final board" }, "topPositions": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri" ], "additionalProperties": false }, "description": "Person rows: largest fresh USD value first, sliced to positionsLimit; empty for squads and on a final board" }, "walletAddress": { "nullable": true, "description": "Person rows: the trader's Solana board wallet snapshotted at competition start (base58); null for squads, a walletless member, and a rank-0 row before the first build", "type": "string" }, "username": { "nullable": true, "description": "Null when the lookup missed", "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "isViewer": { "description": "Present only on a response with an authenticated viewer", "type": "boolean" }, "viewerFollows": { "description": "Null means unknown or nothing to follow", "nullable": true, "type": "boolean" } }, "required": [ "entryId", "participantId", "kind", "rank", "pnlUsd", "realizedPnlUsd", "unrealizedPnlUsd", "buySpendSol", "memberCount", "membersFresh", "struck", "lastRefreshedAtMs", "positionsCount", "topPositions", "walletAddress", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible" ], "additionalProperties": false }, "description": "Empty before the first build. isViewer/viewerFollows ride person rows on an authenticated read only" } }, "required": [ "builtAtMs", "startSec", "endSec", "totalRanked", "isFinal", "entries" ], "additionalProperties": false }, "viewer": { "description": "The caller's own entry (at any rank, rank 0 included) and eligibility. omitted, never null, when anonymous, or when the viewer read failed or missed its 1 s wait", "type": "object", "properties": { "entry": { "nullable": true, "description": "The entry counting the viewer at any rank, rank 0 included; null when no entry counts them", "type": "object", "properties": { "entryId": { "type": "string" }, "participantId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "group", "person" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Who competes: squads (group) or individual traders (person); squads ship first, so treat an unknown value as unsupported. Known values: group, person" }, "rank": { "type": "number", "description": "1-based ordinal rank by pnlUsd descending; a tie goes to the earlier registration, then entry id. 0 = not ranked: struck, a squad hidden from the PnL boards, no scoring wallet, or before the first build" }, "pnlUsd": { "type": "number", "description": "Sum of the roster's window PnL in USD (realized + unrealized) — the ranking key" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "buySpendSol": { "type": "number" }, "memberCount": { "type": "number", "description": "Roster size (snapshot rows, walletless members included); 0 before the snapshot at startsAt" }, "membersFresh": { "type": "number", "description": "Roster members whose leg is inside the freshness bound; a stale member keeps its last-good legs in the sum" }, "struck": { "type": "boolean", "description": "Disqualified for this competition: rank 0 and left out of the leaderboard entries, totalRanked, participants, top and winners; still served as the caller's own viewer entry and by entry detail" }, "lastRefreshedAtMs": { "type": "number", "description": "Oldest refresh among the summed members (unix ms); the finalize time on a final board; 0 before the first build" }, "positionsCount": { "type": "number", "description": "Person rows: the participant's live positions count, never sliced by positionsLimit; 0 for squads and on a final board" }, "topPositions": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri" ], "additionalProperties": false }, "description": "Person rows: largest fresh USD value first, sliced to positionsLimit; empty for squads and on a final board" }, "walletAddress": { "nullable": true, "description": "Person rows: the trader's Solana board wallet snapshotted at competition start (base58); null for squads, a walletless member, and a rank-0 row before the first build", "type": "string" }, "username": { "nullable": true, "description": "Null when the lookup missed", "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" } }, "required": [ "entryId", "participantId", "kind", "rank", "pnlUsd", "realizedPnlUsd", "unrealizedPnlUsd", "buySpendSol", "memberCount", "membersFresh", "struck", "lastRefreshedAtMs", "positionsCount", "topPositions", "walletAddress", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible" ], "additionalProperties": false }, "eligibility": { "type": "object", "properties": { "canRegister": { "type": "boolean", "description": "True when register would add a new entry now; false when an entry already counts the viewer, even with no reasons" }, "reasons": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "REGISTRATION_CLOSED", "NOT_OWNER", "SIZE_BELOW_MIN", "SIZE_ABOVE_MAX", "HIDDEN", "BANNED", "NO_WALLET", "FULL", "KIND_MISMATCH", "NO_GROUP", "REGISTRATION_NOT_OPEN" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Each one is also the COMPETITION_ 409 the register route answers. Known values: REGISTRATION_CLOSED, NOT_OWNER, SIZE_BELOW_MIN, SIZE_ABOVE_MAX, HIDDEN, BANNED, NO_WALLET, FULL, KIND_MISMATCH, NO_GROUP, REGISTRATION_NOT_OPEN" }, "description": "Every reason blocking registration; empty when canRegister" }, "groupId": { "nullable": true, "description": "Squad competitions: the viewer's active squad; null when none (groupRole is then UNSPECIFIED)", "type": "string" }, "groupRole": { "anyOf": [ { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "UNSPECIFIED" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Known values: OWNER, ADMIN, MEMBER, UNSPECIFIED" } }, "required": [ "canRegister", "reasons", "groupId", "groupRole" ], "additionalProperties": false }, "tosAcceptedAt": { "nullable": true, "description": "When the viewer accepted the trade competition terms (ISO 8601; one global acceptance per user, not per competition); null until they accept", "type": "string" } }, "required": [ "entry", "eligibility", "tosAcceptedAt" ], "additionalProperties": false } }, "required": [ "competition", "leaderboard" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "One competition by id or slug with its ranked board. `viewer` (own entry and eligibility) is viewer-relative: present on a signed-in read, absent on the API host" } }, "/competitions/{id}/entries/{entryId}": { "get": { "operationId": "get_competitions_by_id_entries_by_entryId", "tags": [ "leaderboards.read" ], "summary": "One entry with its snapshot roster and each member's…", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "leaderboards.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Competition id (UUID)" } }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "description": "Entry id (UUID)" } } ], "responses": { "200": { "description": "One entry with its snapshot roster and each member's counted legs, pnlUsd descending", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "entryId": { "type": "string" }, "participantId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "group", "person" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Who competes: squads (group) or individual traders (person); squads ship first, so treat an unknown value as unsupported. Known values: group, person" }, "rank": { "type": "number", "description": "1-based ordinal rank by pnlUsd descending; a tie goes to the earlier registration, then entry id. 0 = not ranked: struck, a squad hidden from the PnL boards, no scoring wallet, or before the first build" }, "pnlUsd": { "type": "number", "description": "Sum of the roster's window PnL in USD (realized + unrealized) — the ranking key" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "buySpendSol": { "type": "number" }, "memberCount": { "type": "number", "description": "Roster size (snapshot rows, walletless members included); 0 before the snapshot at startsAt" }, "membersFresh": { "type": "number", "description": "Roster members whose leg is inside the freshness bound; a stale member keeps its last-good legs in the sum" }, "struck": { "type": "boolean", "description": "Disqualified for this competition: rank 0 and left out of the leaderboard entries, totalRanked, participants, top and winners; still served as the caller's own viewer entry and by entry detail" }, "lastRefreshedAtMs": { "type": "number", "description": "Oldest refresh among the summed members (unix ms); the finalize time on a final board; 0 before the first build" }, "positionsCount": { "type": "number", "description": "Person rows: the participant's live positions count, never sliced by positionsLimit; 0 for squads and on a final board" }, "topPositions": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri" ], "additionalProperties": false }, "description": "Person rows: largest fresh USD value first, sliced to positionsLimit; empty for squads and on a final board" }, "walletAddress": { "nullable": true, "description": "Person rows: the trader's Solana board wallet snapshotted at competition start (base58); null for squads, a walletless member, and a rank-0 row before the first build", "type": "string" }, "username": { "nullable": true, "description": "Null when the lookup missed", "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" } }, "required": [ "entryId", "participantId", "kind", "rank", "pnlUsd", "realizedPnlUsd", "unrealizedPnlUsd", "buySpendSol", "memberCount", "membersFresh", "struck", "lastRefreshedAtMs", "positionsCount", "topPositions", "walletAddress", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible" ], "additionalProperties": false }, "members": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "walletAddress": { "nullable": true, "description": "The Solana board wallet snapshotted at competition start; null when the member had none (counted in memberCount, scores nothing)", "type": "string" }, "pnlUsd": { "type": "number", "description": "The member's window PnL in USD (realized + unrealized)" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "buySpendSol": { "type": "number" }, "fresh": { "type": "boolean", "description": "False when the sum carries the member's last-good leg (or none)" }, "lastRefreshedAtMs": { "type": "number", "description": "Unix ms; 0 when never refreshed" }, "username": { "nullable": true, "description": "Null when the lookup missed", "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" } }, "required": [ "userId", "walletAddress", "pnlUsd", "realizedPnlUsd", "unrealizedPnlUsd", "buySpendSol", "fresh", "lastRefreshedAtMs", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible" ], "additionalProperties": false }, "description": "Snapshot roster with counted legs, pnlUsd descending; empty before the snapshot at startsAt" } }, "required": [ "entry", "members" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "One entry with its snapshot roster and each member's counted legs, pnlUsd descending" } }, "/competitions/{id}/entries/{entryId}/highlights": { "get": { "operationId": "get_competitions_by_id_entries_by_entryId_highlights", "tags": [ "leaderboards.read" ], "summary": "One entry's highlight reel", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "leaderboards.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Competition id (UUID)" } }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "description": "Entry id (UUID)" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Tokens returned (default and ceiling 10; out-of-range values clamp)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "One entry's highlight reel: its top tokens by PnL during the competition window, coin display fields attached", "content": { "application/json": { "schema": { "type": "object", "properties": { "entryId": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" }, "pnlUsd": { "type": "number", "description": "Realized + unrealized PnL in USD on this token during the competition window — the reel is sorted by it, descending" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "buySpendUsd": { "type": "number", "description": "Buy spend in USD inside the window" }, "members": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "walletAddress": { "nullable": true, "description": "The member's Solana board wallet snapshotted with the roster, the wallet this leg was scored from; null when the member had none", "type": "string" }, "pnlUsd": { "type": "number", "description": "The member's own realized + unrealized PnL in USD on this token inside the window" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "buySpendUsd": { "type": "number", "description": "The member's own buy spend in USD on this token inside the window" } }, "required": [ "userId", "walletAddress", "pnlUsd", "realizedPnlUsd", "unrealizedPnlUsd", "buySpendUsd" ], "additionalProperties": false }, "description": "Which roster members made this token's PnL, pnlUsd descending then userId. Their pnlUsd, realizedPnlUsd, unrealizedPnlUsd and buySpendUsd sum to the token's. Each member contributes only their own top-10 tokens by window PnL, so a member whose position on this token fell outside their own top 10 is absent here and uncounted in the token's sums. [] on a reel persisted before members shipped" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri", "pnlUsd", "realizedPnlUsd", "unrealizedPnlUsd", "buySpendUsd", "members" ], "additionalProperties": false }, "description": "Top tokens by window PnL summed across the entry's roster, descending, banned mints excluded, each carrying the roster members whose legs it sums; from the live fold while the competition runs, frozen with the final board once it ends. Empty before the first build and for competitions finalized before the reel shipped" } }, "required": [ "entryId", "tokens" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "One entry's highlight reel: its top tokens by PnL during the competition window, coin display fields attached" } }, "/competitions/{id}/highlights": { "get": { "operationId": "get_competitions_by_id_highlights", "tags": [ "leaderboards.read" ], "summary": "The competition's biggest winning legs across every…", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "leaderboards.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Competition id (UUID)" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Rows returned (default and ceiling 20; 0 and negatives clamp to 1, values above the cap to the cap)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "perMemberLimit", "in": "query", "required": false, "schema": { "description": "Rows per trader (default 1, ceiling 10; 0 and negatives clamp to 1, values above the cap to the cap)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "The competition's biggest winning legs across every ranked entry, one card per trader by default, coin and profile display fields attached. Rows are capped per trader before any chain filter: a client that drops chains thins the list instead of refilling it, so ask for every chain or raise perMemberLimit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "competitionId": { "type": "string" }, "builtAtMs": { "type": "number", "description": "When the board build these rows come from ran (epoch ms)" }, "isFinal": { "type": "boolean", "description": "true once the competition ended and the rows derive from the persisted final board; false while live" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" }, "username": { "nullable": true, "description": "Null when the lookup missed", "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "entryId": { "type": "string", "description": "The ranked entry the trader counts for" }, "rank": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The entry's board rank (1-based)" }, "userId": { "type": "string" }, "walletAddress": { "nullable": true, "description": "The board wallet the leg scored on.", "type": "string" }, "pnlUsd": { "type": "number", "description": "The trader's realized + unrealized PnL in USD on this token during the competition window, always > 0 — rows sort by it, descending" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "buySpendUsd": { "type": "number", "description": "Buy spend in USD inside the window" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible", "entryId", "rank", "userId", "walletAddress", "pnlUsd", "realizedPnlUsd", "unrealizedPnlUsd", "buySpendUsd" ], "additionalProperties": false }, "description": "Wins only (pnlUsd > 0): every ranked entry's members' top-token legs, pnlUsd descending, at most perMemberLimit per trader; from the live board build while the competition runs, from the final board (strikes, hides and bans applied) once it ends. Empty before the first build and for final boards persisted before token members shipped" } }, "required": [ "competitionId", "builtAtMs", "isFinal", "rows" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "The competition's biggest winning legs across every ranked entry, one card per trader by default, coin and profile display fields attached. Rows are capped per trader before any chain filter: a client that drops chains thins the list instead of refilling it, so ask for every chain or raise perMemberLimit." } }, "/feed/video-feed": { "get": { "operationId": "get_feed_video_feed", "tags": [ "content.read" ], "summary": "Get the curated video feed", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "content.read", "responses": { "200": { "description": "Get the curated video feed", "content": { "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "feedItemType": { "type": "string", "enum": [ "clip" ] }, "clip": { "type": "object", "properties": { "roomName": { "type": "string", "description": "The coin mint the clip was recorded in" }, "clipId": { "type": "string" }, "startTime": { "type": "string", "description": "ISO 8601" }, "endTime": { "type": "string", "description": "ISO 8601" }, "duration": { "type": "number", "description": "Seconds" }, "playlistUrl": { "description": "HLS playlist for playback", "type": "string" }, "mp4Url": { "type": "string" }, "mp4S3Key": { "type": "string" }, "mp4SizeBytes": { "type": "number" }, "mp4CreatedAt": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "thumbnailS3Key": { "type": "string" }, "playlistS3Key": { "type": "string" }, "variants": { "description": "ABR variants (low/mid/high)", "type": "array", "items": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "enum": [ "low", "mid", "high" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Known values: low, mid, high" }, "height": { "type": "number" }, "playlistUrl": { "type": "string" }, "playlistS3Key": { "type": "string" } }, "required": [ "name", "height", "playlistUrl" ], "additionalProperties": false } }, "title": { "type": "string" }, "hidden": { "description": "Always false here: hidden clips are filtered out of the feed", "type": "boolean" }, "hiddenReason": { "description": "`banned` | `user_hidden`", "type": "string" }, "sessionId": { "type": "string" }, "clipType": { "description": "e.g. `HIGHLIGHT`", "type": "string" }, "createdAt": { "type": "string" }, "highlightCreatorAddress": { "type": "string" }, "viewCount": { "description": "Total across all shards", "type": "number" }, "pinnedAt": { "description": "Set means pinned", "type": "string" }, "deletionStatus": { "description": "`ACTIVE` | `SOFT_DELETED` | `HARD_DELETED`", "type": "string" }, "softDeletedAt": { "type": "string" }, "hardDeleteScheduledAt": { "type": "string" }, "hardDeletedAt": { "type": "string" }, "deletionReason": { "description": "`manual` | `expired` | `unpinned_expired` | `policy_violation`", "type": "string" } }, "required": [ "roomName", "clipId", "startTime", "endTime", "duration", "thumbnailUrl", "thumbnailS3Key", "playlistS3Key" ], "additionalProperties": false }, "coin": { "type": "object", "properties": { "mint": { "type": "string", "description": "The only field guaranteed on every coin row; every other field can be absent" }, "initialized": { "type": "boolean" }, "name": { "description": "Render the mint, never a blank string", "type": "string" }, "symbol": { "description": "Render the mint, never a blank string", "type": "string" }, "description": { "description": "Never the empty string: the server collapses \"\" to absent, so presence alone says whether there is a value", "type": "string" }, "image_uri": { "description": "Never the empty string: the server collapses \"\" to absent, so presence alone says whether there is a value", "type": "string" }, "image_backdrop": { "description": "Surface to paint behind image_uri when it is a bare mark on transparency: light for a dark mark, dark for a light one. Absent = paint the image as-is (an opaque tile, an unassessed image, or no image). Served on HyperCore perp rows only, and only beside image_uri", "type": "string", "enum": [ "light", "dark" ] }, "metadata_uri": { "description": "Never the empty string: the server collapses \"\" to absent, so presence alone says whether there is a value", "type": "string" }, "video_uri": { "type": "string" }, "banner_uri": { "type": "string" }, "twitter": { "type": "string" }, "telegram": { "type": "string" }, "website": { "type": "string" }, "bonding_curve": { "type": "string" }, "associated_bonding_curve": { "type": "string" }, "creator": { "description": "Creator wallet of the coin; the system program id 11111111111111111111111111111111 when the coin was created without one.", "type": "string" }, "signer": { "type": "string" }, "created_timestamp": { "description": "Unix epoch milliseconds", "type": "number" }, "complete": { "description": "Whether the bonding curve has completed", "type": "boolean" }, "virtual_sol_reserves": { "type": "number" }, "virtual_token_reserves": { "type": "number" }, "virtual_quote_reserves": { "type": "number" }, "total_supply": { "description": "Raw base-unit total supply as a JSON number; values above 2^53 are imprecise (BONK is 8799515941776938000 here and \"8799515941776937984\" in total_supply_str). Read total_supply_str when exactness matters. Absent when no supply is known or the raw value exceeds uint64.", "type": "number" }, "total_supply_str": { "description": "Apply base_decimals for a human value); string-typed because raw 18-decimal EVM values exceed uint64, and exact where total_supply is imprecise. Absent when the producer holds no supply.", "type": "string" }, "circulating_supply_str": { "description": "Raw on-chain circulating supply as a base-10 integer string; string-typed because raw 18-decimal EVM values exceed uint64", "type": "string" }, "show_name": { "type": "boolean" }, "last_trade_timestamp": { "description": "Unix epoch milliseconds", "type": "number" }, "king_of_the_hill_timestamp": { "description": "Unix epoch milliseconds", "type": "number" }, "market_cap": { "description": "Legacy market cap in the chain's native unit (SOL on SVM), never converted to USD (#3272). On EVM rows applyUsdMarketCap overwrites it with the USD figure, so there it equals usd_market_cap and is absent with it.", "type": "number" }, "market_cap_quote": { "description": "Market cap in quote_mint units (SOL, USDC,...; usd_market_cap is served from market_cap_usd whenever that is set and falls back to this field only for a USDC-quoted coin with none (getUsdMarketCap).", "type": "number" }, "market_cap_usd": { "description": "Unset only for a dormant coin that never had one populated. usd_market_cap is served from it.", "type": "number" }, "market_id": { "type": "string" }, "inverted": { "description": "Inverted (special) pricing mode", "type": "boolean" }, "nsfw": { "type": "boolean" }, "is_banned": { "type": "boolean" }, "hidden": { "type": "boolean" }, "real_sol_reserves": { "type": "number" }, "real_token_reserves": { "type": "number" }, "real_quote_reserves": { "type": "number" }, "updated_at": { "description": "Unix epoch milliseconds", "type": "number" }, "livestream_ban_expiry": { "description": "Unix epoch milliseconds", "type": "number" }, "last_reply": { "description": "Unix epoch milliseconds", "type": "number" }, "reply_count": { "type": "number" }, "is_currently_live": { "type": "boolean" }, "thumbnail": { "description": "Livestream thumbnail URL; set only while is_currently_live", "type": "string" }, "thumbnail_updated_at": { "description": "Unix epoch milliseconds; set only while is_currently_live", "type": "number" }, "num_participants": { "description": "Livestream participant count; set only while is_currently_live", "type": "number" }, "ath_market_cap": { "type": "number" }, "ath_market_cap_timestamp": { "description": "Unix epoch milliseconds", "type": "number" }, "hide_banner": { "type": "boolean" }, "program": { "description": "Launch program of the mint; absent on off-platform mints (presence is the gate for swap-api / advanced-indexer reads)", "type": "string" }, "token_program": { "type": "string" }, "usd_market_cap": { "description": "Absent, never 0, when no USD figure is known (#3272 served DJT at $700 by converting a SOL cap); treat absence as unknown and sink it in value sorts.", "type": "number" }, "price_usd": { "description": "Present on TON only for now, absent when the card carries none.", "type": "number" }, "platform": { "type": "string" }, "base_decimals": { "type": "number" }, "quote_decimals": { "type": "number" }, "quote_mint": { "type": "string" }, "quote_token_program": { "description": "SPL Token or Token-2022 program id owning the quote mint; absent on older rows", "type": "string" }, "mayhem_state": { "anyOf": [ { "type": "string", "enum": [ "enabled", "active", "paused", "completed" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Mayhem lifecycle state, an open set; a value not listed here is still a coin in mayhem. Known values: enabled, active, paused, completed" }, "mayhem": { "type": "object", "properties": { "state": { "anyOf": [ { "type": "string", "enum": [ "enabled", "active", "paused", "completed" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Mayhem lifecycle state, an open set; a value not listed here is still a coin in mayhem. Known values: enabled, active, paused, completed" }, "mode": { "anyOf": [ { "type": "string", "enum": [ "auto", "manual" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Trading mode, an open set; served as stored, never defaulted here. Known values: auto, manual" }, "pause_reason": { "anyOf": [ { "type": "string", "enum": [ "mcap_floor", "unprofitable", "low_reserves", "creator_paused", "below_initial_buy_floor", "low_sol_reserves", "low_stable_reserves", "unprofitable_fees" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Why the coin is paused, an open set; present only while state is paused. Known values: mcap_floor, unprofitable, low_reserves, creator_paused, below_initial_buy_floor, low_sol_reserves, low_stable_reserves, unprofitable_fees" }, "complete_reason": { "anyOf": [ { "type": "string", "enum": [ "max_age_reached", "sol_reserve_errors", "zero_base_amount", "sell_zero_amount", "buy_zero_amount", "mayhem_mode_ended", "overflow" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Why the coin completed, an open set; present only once state is completed. Known values: max_age_reached, sol_reserve_errors, zero_base_amount, sell_zero_amount, buy_zero_amount, mayhem_mode_ended, overflow" } }, "additionalProperties": false }, "security_verdict": { "description": "Absent until the verdict writer has processed the coin", "type": "object", "properties": { "verdict": { "type": "string", "description": "Resolved token-security verdict: \"blocked\" | \"warn\" | \"allow\" | \"unknown\"" }, "scope": { "type": "string", "description": "Hiding scope, meaningful only when verdict is \"blocked\": \"all\" hides the coin everywhere, \"discovery\" only from feeds" }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "token-trust reason slugs, e.g. \"honeypot\", \"rugpull\"" }, "decided_by": { "type": "string", "description": "Resolver tier that decided: \"blacklist\" | \"bypass\" | \"vendor\" | \"trust\" | \"soft\" | \"default\"" }, "provider": { "type": "string", "description": "Security data provider(s) consulted: \"blockaid\" | \"goplus\" | \"both\" | \"solana-rpc\" | \"heuristic\" | \"none\"" }, "malicious_score": { "description": "Provider-reported malicious score, when one was returned", "type": "number" }, "version": { "type": "number", "description": "Per-coin monotonic write version" }, "updated_at": { "description": "Unix epoch milliseconds", "type": "number" }, "source": { "type": "string", "description": "Writer identity, e.g. \"token-trust\"" } }, "required": [ "verdict", "scope", "reasons", "decided_by", "provider", "version", "source" ], "additionalProperties": false }, "is_test": { "type": "boolean" }, "username": { "type": "string" }, "profile_image": { "type": "string" }, "cto_address": { "type": "string" }, "cto_username": { "type": "string" }, "cto_profile_image": { "type": "string" }, "indexed_by_pump": { "type": "boolean" }, "is_cashback_enabled": { "type": "boolean" }, "is_holder_reward": { "type": "boolean" }, "transfer_fee_bps": { "description": "Base mint Token-2022 transfer fee in basis points (newer TransferFeeConfig step, Coin field 76); 0 = fee-less, absent = not inspected", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "transfer_hook_program": { "description": "Base-mint Token-2022 TransferHook program (base58). Empty string: inspected, no hook or revoked at graduation. Absent: not inspected.", "type": "string" }, "is_charity": { "type": "boolean" }, "tokenized_agent": { "type": "boolean" }, "verified": { "type": "boolean" }, "raydium_pool": { "type": "string" }, "pump_swap_pool": { "type": "string" }, "depth": { "description": "Pump curve nesting level; 0 for SOL/USDC/whitelisted quotes and for coins created before the depth rung.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "volume_1h_usd": { "type": "number" }, "chain_id": { "type": "string" }, "multichain_family": { "type": "number" }, "protocol": { "type": "string" }, "pool_address": { "type": "string" }, "canonical_pool_liquidity_usd": { "type": "number" }, "boost_mode": { "description": "Boost-mode lifecycle state: \"NONE\" | \"IN_PROGRESS\" | \"COMPLETED\"", "type": "string" }, "asset_class": { "description": "Tokenized-equity class of the coin, when it has one; null = classified as neither.", "nullable": true, "type": "string", "enum": [ "tokenized_stock", "pre_ipo_synthetic" ] }, "issuer": { "description": "Tokenized-equity issuer; set only alongside asset_class", "nullable": true, "type": "string", "enum": [ "xstocks", "ondo", "backpack", "prestocks", "tessera", "robinhood", "coinbase", "binance" ] }, "underlying_symbol": { "description": "Underlying equity ticker derived from the token symbol (issuer affix stripped where recognised); set only alongside asset_class", "nullable": true, "type": "string" }, "canonical_stock": { "description": "Stock badge: true = the one canonical coin for its underlying stock, false = another variant of a stock that has a canonical coin, null = not a stock; absent = no verdict on this path (badge off either way)", "nullable": true, "type": "boolean" }, "chain": { "description": "CAIP-2 chain; set on a perp row (hlcore:mainnet, where mint is the HyperCore coin name verbatim: BTC, kPEPE, xyz:TSLA), on a TON row (ton:-239, where mint is the jetton master's friendly address), on a NEAR row (near:mainnet, where mint is the token's account id) and on a Starknet row (starknet:SN_MAIN, where mint is the token's 0x + 64 lowercase hex address)", "type": "string" }, "assetClass": { "description": "Asset class of the coin: ASSET_CLASS_PERPETUAL on a perp row, ASSET_CLASS_NFT_LIKE on a card body (collectible set, market cap and pool absent); absent on every token row.", "type": "string", "enum": [ "ASSET_CLASS_PERPETUAL", "ASSET_CLASS_NFT_LIKE" ] }, "perp": { "type": "object", "properties": { "markPx": { "nullable": true, "description": "USD as a decimal string; null when the store carries no mark", "type": "string" }, "oraclePx": { "nullable": true, "description": "USD as a decimal string; null when the store carries no mark", "type": "string" }, "fundingRateHourly": { "nullable": true, "description": "Hourly funding rate as a decimal string; null when unknown", "type": "string" }, "openInterestUsd": { "nullable": true, "description": "USD as a decimal string; null when the store carries no mark", "type": "string" }, "nextFundingAt": { "nullable": true, "description": "ISO 8601", "type": "string" }, "asOf": { "nullable": true, "description": "ISO 8601; when the HL market context was last observed", "type": "string" }, "stale": { "type": "boolean", "description": "true when the context is older than 120 s; perp values are the last observed" }, "maxLeverage": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "szDecimals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "onlyIsolated": { "type": "boolean" }, "dex": { "nullable": true, "description": "HIP-3 dex name; null on the main perp dex", "type": "string" }, "category": { "nullable": true, "description": "crypto | stocks | commodities; null when unknown", "type": "string" }, "isDelisted": { "type": "boolean" }, "volume24hUsd": { "nullable": true, "description": "24h notional volume in USD as a decimal string from the HL market context (dayNtlVlmUsd); falls back to the 24h fold window; null when neither is present", "type": "string" }, "priceChange24hBps": { "nullable": true, "description": "24h price change in bps from the HL market context (markPx vs prevDayPx); falls back to the 24h fold window; null when neither is present", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "markPx", "oraclePx", "fundingRateHourly", "openInterestUsd", "nextFundingAt", "asOf", "stale", "maxLeverage", "szDecimals", "onlyIsolated", "dex", "category", "isDelisted", "volume24hUsd", "priceChange24hBps" ], "additionalProperties": false, "description": "HyperCore perp state; set on perp rows only" }, "collectible": { "description": "NFT_LIKE card only: the card block (identity, grade, mark, insured value, buyback, listing); a card has no pool, so branch on it before mounting chart or trade panels. Absent on every token coin", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false } }, "required": [ "mint" ], "additionalProperties": false } }, "required": [ "feedItemType", "clip", "coin" ], "additionalProperties": false }, { "type": "object", "properties": { "feedItemType": { "type": "string", "enum": [ "live" ] }, "coin": { "type": "object", "properties": { "mint": { "type": "string", "description": "The only field guaranteed on every coin row; every other field can be absent" }, "initialized": { "type": "boolean" }, "name": { "description": "Render the mint, never a blank string", "type": "string" }, "symbol": { "description": "Render the mint, never a blank string", "type": "string" }, "description": { "description": "Never the empty string: the server collapses \"\" to absent, so presence alone says whether there is a value", "type": "string" }, "image_uri": { "description": "Never the empty string: the server collapses \"\" to absent, so presence alone says whether there is a value", "type": "string" }, "image_backdrop": { "description": "Surface to paint behind image_uri when it is a bare mark on transparency: light for a dark mark, dark for a light one. Absent = paint the image as-is (an opaque tile, an unassessed image, or no image). Served on HyperCore perp rows only, and only beside image_uri", "type": "string", "enum": [ "light", "dark" ] }, "metadata_uri": { "description": "Never the empty string: the server collapses \"\" to absent, so presence alone says whether there is a value", "type": "string" }, "video_uri": { "type": "string" }, "banner_uri": { "type": "string" }, "twitter": { "type": "string" }, "telegram": { "type": "string" }, "website": { "type": "string" }, "bonding_curve": { "type": "string" }, "associated_bonding_curve": { "type": "string" }, "creator": { "description": "Creator wallet of the coin; the system program id 11111111111111111111111111111111 when the coin was created without one.", "type": "string" }, "signer": { "type": "string" }, "created_timestamp": { "description": "Unix epoch milliseconds", "type": "number" }, "complete": { "description": "Whether the bonding curve has completed", "type": "boolean" }, "virtual_sol_reserves": { "type": "number" }, "virtual_token_reserves": { "type": "number" }, "virtual_quote_reserves": { "type": "number" }, "total_supply": { "description": "Raw base-unit total supply as a JSON number; values above 2^53 are imprecise (BONK is 8799515941776938000 here and \"8799515941776937984\" in total_supply_str). Read total_supply_str when exactness matters. Absent when no supply is known or the raw value exceeds uint64.", "type": "number" }, "total_supply_str": { "description": "Apply base_decimals for a human value); string-typed because raw 18-decimal EVM values exceed uint64, and exact where total_supply is imprecise. Absent when the producer holds no supply.", "type": "string" }, "circulating_supply_str": { "description": "Raw on-chain circulating supply as a base-10 integer string; string-typed because raw 18-decimal EVM values exceed uint64", "type": "string" }, "show_name": { "type": "boolean" }, "last_trade_timestamp": { "description": "Unix epoch milliseconds", "type": "number" }, "king_of_the_hill_timestamp": { "description": "Unix epoch milliseconds", "type": "number" }, "market_cap": { "description": "Legacy market cap in the chain's native unit (SOL on SVM), never converted to USD (#3272). On EVM rows applyUsdMarketCap overwrites it with the USD figure, so there it equals usd_market_cap and is absent with it.", "type": "number" }, "market_cap_quote": { "description": "Market cap in quote_mint units (SOL, USDC,...; usd_market_cap is served from market_cap_usd whenever that is set and falls back to this field only for a USDC-quoted coin with none (getUsdMarketCap).", "type": "number" }, "market_cap_usd": { "description": "Unset only for a dormant coin that never had one populated. usd_market_cap is served from it.", "type": "number" }, "market_id": { "type": "string" }, "inverted": { "description": "Inverted (special) pricing mode", "type": "boolean" }, "nsfw": { "type": "boolean" }, "is_banned": { "type": "boolean" }, "hidden": { "type": "boolean" }, "real_sol_reserves": { "type": "number" }, "real_token_reserves": { "type": "number" }, "real_quote_reserves": { "type": "number" }, "updated_at": { "description": "Unix epoch milliseconds", "type": "number" }, "livestream_ban_expiry": { "description": "Unix epoch milliseconds", "type": "number" }, "last_reply": { "description": "Unix epoch milliseconds", "type": "number" }, "reply_count": { "type": "number" }, "is_currently_live": { "type": "boolean" }, "thumbnail": { "description": "Livestream thumbnail URL; set only while is_currently_live", "type": "string" }, "thumbnail_updated_at": { "description": "Unix epoch milliseconds; set only while is_currently_live", "type": "number" }, "num_participants": { "description": "Livestream participant count; set only while is_currently_live", "type": "number" }, "ath_market_cap": { "type": "number" }, "ath_market_cap_timestamp": { "description": "Unix epoch milliseconds", "type": "number" }, "hide_banner": { "type": "boolean" }, "program": { "description": "Launch program of the mint; absent on off-platform mints (presence is the gate for swap-api / advanced-indexer reads)", "type": "string" }, "token_program": { "type": "string" }, "usd_market_cap": { "description": "Absent, never 0, when no USD figure is known (#3272 served DJT at $700 by converting a SOL cap); treat absence as unknown and sink it in value sorts.", "type": "number" }, "price_usd": { "description": "Present on TON only for now, absent when the card carries none.", "type": "number" }, "platform": { "type": "string" }, "base_decimals": { "type": "number" }, "quote_decimals": { "type": "number" }, "quote_mint": { "type": "string" }, "quote_token_program": { "description": "SPL Token or Token-2022 program id owning the quote mint; absent on older rows", "type": "string" }, "mayhem_state": { "anyOf": [ { "type": "string", "enum": [ "enabled", "active", "paused", "completed" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Mayhem lifecycle state, an open set; a value not listed here is still a coin in mayhem. Known values: enabled, active, paused, completed" }, "mayhem": { "type": "object", "properties": { "state": { "anyOf": [ { "type": "string", "enum": [ "enabled", "active", "paused", "completed" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Mayhem lifecycle state, an open set; a value not listed here is still a coin in mayhem. Known values: enabled, active, paused, completed" }, "mode": { "anyOf": [ { "type": "string", "enum": [ "auto", "manual" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Trading mode, an open set; served as stored, never defaulted here. Known values: auto, manual" }, "pause_reason": { "anyOf": [ { "type": "string", "enum": [ "mcap_floor", "unprofitable", "low_reserves", "creator_paused", "below_initial_buy_floor", "low_sol_reserves", "low_stable_reserves", "unprofitable_fees" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Why the coin is paused, an open set; present only while state is paused. Known values: mcap_floor, unprofitable, low_reserves, creator_paused, below_initial_buy_floor, low_sol_reserves, low_stable_reserves, unprofitable_fees" }, "complete_reason": { "anyOf": [ { "type": "string", "enum": [ "max_age_reached", "sol_reserve_errors", "zero_base_amount", "sell_zero_amount", "buy_zero_amount", "mayhem_mode_ended", "overflow" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Why the coin completed, an open set; present only once state is completed. Known values: max_age_reached, sol_reserve_errors, zero_base_amount, sell_zero_amount, buy_zero_amount, mayhem_mode_ended, overflow" } }, "additionalProperties": false }, "security_verdict": { "description": "Absent until the verdict writer has processed the coin", "type": "object", "properties": { "verdict": { "type": "string", "description": "Resolved token-security verdict: \"blocked\" | \"warn\" | \"allow\" | \"unknown\"" }, "scope": { "type": "string", "description": "Hiding scope, meaningful only when verdict is \"blocked\": \"all\" hides the coin everywhere, \"discovery\" only from feeds" }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "token-trust reason slugs, e.g. \"honeypot\", \"rugpull\"" }, "decided_by": { "type": "string", "description": "Resolver tier that decided: \"blacklist\" | \"bypass\" | \"vendor\" | \"trust\" | \"soft\" | \"default\"" }, "provider": { "type": "string", "description": "Security data provider(s) consulted: \"blockaid\" | \"goplus\" | \"both\" | \"solana-rpc\" | \"heuristic\" | \"none\"" }, "malicious_score": { "description": "Provider-reported malicious score, when one was returned", "type": "number" }, "version": { "type": "number", "description": "Per-coin monotonic write version" }, "updated_at": { "description": "Unix epoch milliseconds", "type": "number" }, "source": { "type": "string", "description": "Writer identity, e.g. \"token-trust\"" } }, "required": [ "verdict", "scope", "reasons", "decided_by", "provider", "version", "source" ], "additionalProperties": false }, "is_test": { "type": "boolean" }, "username": { "type": "string" }, "profile_image": { "type": "string" }, "cto_address": { "type": "string" }, "cto_username": { "type": "string" }, "cto_profile_image": { "type": "string" }, "indexed_by_pump": { "type": "boolean" }, "is_cashback_enabled": { "type": "boolean" }, "is_holder_reward": { "type": "boolean" }, "transfer_fee_bps": { "description": "Base mint Token-2022 transfer fee in basis points (newer TransferFeeConfig step, Coin field 76); 0 = fee-less, absent = not inspected", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "transfer_hook_program": { "description": "Base-mint Token-2022 TransferHook program (base58). Empty string: inspected, no hook or revoked at graduation. Absent: not inspected.", "type": "string" }, "is_charity": { "type": "boolean" }, "tokenized_agent": { "type": "boolean" }, "verified": { "type": "boolean" }, "raydium_pool": { "type": "string" }, "pump_swap_pool": { "type": "string" }, "depth": { "description": "Pump curve nesting level; 0 for SOL/USDC/whitelisted quotes and for coins created before the depth rung.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "volume_1h_usd": { "type": "number" }, "chain_id": { "type": "string" }, "multichain_family": { "type": "number" }, "protocol": { "type": "string" }, "pool_address": { "type": "string" }, "canonical_pool_liquidity_usd": { "type": "number" }, "boost_mode": { "description": "Boost-mode lifecycle state: \"NONE\" | \"IN_PROGRESS\" | \"COMPLETED\"", "type": "string" }, "asset_class": { "description": "Tokenized-equity class of the coin, when it has one; null = classified as neither.", "nullable": true, "type": "string", "enum": [ "tokenized_stock", "pre_ipo_synthetic" ] }, "issuer": { "description": "Tokenized-equity issuer; set only alongside asset_class", "nullable": true, "type": "string", "enum": [ "xstocks", "ondo", "backpack", "prestocks", "tessera", "robinhood", "coinbase", "binance" ] }, "underlying_symbol": { "description": "Underlying equity ticker derived from the token symbol (issuer affix stripped where recognised); set only alongside asset_class", "nullable": true, "type": "string" }, "canonical_stock": { "description": "Stock badge: true = the one canonical coin for its underlying stock, false = another variant of a stock that has a canonical coin, null = not a stock; absent = no verdict on this path (badge off either way)", "nullable": true, "type": "boolean" }, "chain": { "description": "CAIP-2 chain; set on a perp row (hlcore:mainnet, where mint is the HyperCore coin name verbatim: BTC, kPEPE, xyz:TSLA), on a TON row (ton:-239, where mint is the jetton master's friendly address), on a NEAR row (near:mainnet, where mint is the token's account id) and on a Starknet row (starknet:SN_MAIN, where mint is the token's 0x + 64 lowercase hex address)", "type": "string" }, "assetClass": { "description": "Asset class of the coin: ASSET_CLASS_PERPETUAL on a perp row, ASSET_CLASS_NFT_LIKE on a card body (collectible set, market cap and pool absent); absent on every token row.", "type": "string", "enum": [ "ASSET_CLASS_PERPETUAL", "ASSET_CLASS_NFT_LIKE" ] }, "perp": { "type": "object", "properties": { "markPx": { "nullable": true, "description": "USD as a decimal string; null when the store carries no mark", "type": "string" }, "oraclePx": { "nullable": true, "description": "USD as a decimal string; null when the store carries no mark", "type": "string" }, "fundingRateHourly": { "nullable": true, "description": "Hourly funding rate as a decimal string; null when unknown", "type": "string" }, "openInterestUsd": { "nullable": true, "description": "USD as a decimal string; null when the store carries no mark", "type": "string" }, "nextFundingAt": { "nullable": true, "description": "ISO 8601", "type": "string" }, "asOf": { "nullable": true, "description": "ISO 8601; when the HL market context was last observed", "type": "string" }, "stale": { "type": "boolean", "description": "true when the context is older than 120 s; perp values are the last observed" }, "maxLeverage": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "szDecimals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "onlyIsolated": { "type": "boolean" }, "dex": { "nullable": true, "description": "HIP-3 dex name; null on the main perp dex", "type": "string" }, "category": { "nullable": true, "description": "crypto | stocks | commodities; null when unknown", "type": "string" }, "isDelisted": { "type": "boolean" }, "volume24hUsd": { "nullable": true, "description": "24h notional volume in USD as a decimal string from the HL market context (dayNtlVlmUsd); falls back to the 24h fold window; null when neither is present", "type": "string" }, "priceChange24hBps": { "nullable": true, "description": "24h price change in bps from the HL market context (markPx vs prevDayPx); falls back to the 24h fold window; null when neither is present", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "markPx", "oraclePx", "fundingRateHourly", "openInterestUsd", "nextFundingAt", "asOf", "stale", "maxLeverage", "szDecimals", "onlyIsolated", "dex", "category", "isDelisted", "volume24hUsd", "priceChange24hBps" ], "additionalProperties": false, "description": "HyperCore perp state; set on perp rows only" }, "collectible": { "description": "NFT_LIKE card only: the card block (identity, grade, mark, insured value, buyback, listing); a card has no pool, so branch on it before mounting chart or trade panels. Absent on every token coin", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false } }, "required": [ "mint" ], "additionalProperties": false } }, "required": [ "feedItemType", "coin" ], "additionalProperties": false } ] } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/following/single/{id}": { "get": { "operationId": "get_following_single_by_id", "tags": [ "graph.read" ], "summary": "Get a single follow relationship", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a single follow relationship", "content": { "application/json": { "schema": { "type": "object", "properties": { "follow": { "nullable": true, "description": "Null when the viewer does not follow the target", "type": "object", "properties": { "following_id": { "type": "string" }, "user_id": { "type": "string" }, "timestamp": { "description": "Epoch ms the edge was made.", "nullable": true, "type": "number" } }, "required": [ "following_id", "user_id" ], "additionalProperties": false } }, "required": [ "follow" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/following/v3/followers/count/{userId}": { "get": { "operationId": "get_following_v3_followers_count_by_userId", "tags": [ "graph.read" ], "summary": "Get a user follower count", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a user follower count (v3)", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "number" } }, "required": [ "count" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Get a user follower count (v3)" } }, "/following/v3/followers/search/{userId}": { "get": { "operationId": "get_following_v3_followers_search_by_userId", "tags": [ "graph.read" ], "summary": "Search within a user's followers", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "searchTerm", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Search term, relevance-ranked; trimmed. Fewer than 2 characters after trimming answers [] without a search. Longer than 50 characters is a 400." } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, default 20. Out-of-range values are rejected with 400, not clamped.", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "description": "0-indexed offset into the ranked matches, default 0", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Search within a user's followers", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "userId": { "type": "string" }, "username": { "nullable": true, "type": "string" }, "profile_image": { "nullable": true, "type": "string" }, "header_image_url": { "nullable": true, "type": "string" }, "avatar_decoration": { "description": "The owner's avatar decoration (border effect) PICK as a decoration key — `legendary`, `epic`, `none` (an explicit no-border), `achievement:` — never a url: the client owns the key -> artwork catalog. For the owner's chooser (which tile is selected); the border to draw is resolved_avatar_decoration. null or absent means no pick. Served on GET /users/{id} and POST /users/batch rows.", "nullable": true, "type": "string" }, "resolved_avatar_decoration": { "description": "The border to draw on this avatar, resolved from the owner's pick and achievements: the pick while still earned, else the rarest tier ring the achievements earn (`legendary`, `epic`); null means no border (an explicit `none` pick, or nothing earned). Same key grammar as avatar_decoration. Served on GET /users/{id} and POST /users/batch rows — never fetch a user's achievements to draw a border. A newly earned tier can take up to an hour to show to other viewers; the owner's own view updates immediately", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "person", "group" ] }, "member_count": { "type": "number" }, "group_badges": { "type": "array", "items": { "type": "object", "properties": { "group_id": { "type": "string" }, "username": { "type": "string" }, "profile_image_url": { "nullable": true, "type": "string" }, "role": { "anyOf": [ { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "UNSPECIFIED" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Known values: OWNER, ADMIN, MEMBER, UNSPECIFIED" } }, "required": [ "group_id", "username", "profile_image_url", "role" ], "additionalProperties": false } }, "bio": { "nullable": true, "type": "string" }, "followers": { "type": "number" }, "following": { "type": "number" }, "last_username_update_timestamp": { "description": "Unix epoch ms of the last username change; null when never renamed. Served by the single-profile read and on labelled-wallet search rows; absent from batch and hydrated search-v2 rows", "nullable": true, "type": "number" }, "x_username": { "nullable": true, "type": "string" }, "wallet_label": { "type": "string" }, "is_pump_user": { "type": "boolean" }, "is_banned": { "type": "boolean" }, "canonical_svm_wallet": { "type": "string" }, "canonical_evm_wallet": { "type": "string" }, "last_active_at": { "description": "ISO time of the account's latest authenticated request (~1 min granularity, kept for one day). Viewer-relative: served on GET /users/{id} and POST /users/batch rows to a signed-in viewer, for accounts the viewer follows and the viewer's own row, null otherwise (not followed, never seen, degraded read) — render null as unknown. Absent for anonymous callers, on the API host, and on every other row-serving read", "nullable": true, "type": "string" }, "mutuals": { "description": "Accounts the viewer follows that also follow this follower — up to 3 previews, most-followed first, plus the exact totalCount; the shape the suggestions route serves. Viewer-relative: only on a signed-in read of a page of at most 100 rows, never on the API host; absent = signal unavailable (never zero), totalCount 0 = none shared.", "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "profileImage": { "nullable": true, "type": "string" } }, "required": [ "userId", "username", "profileImage" ], "additionalProperties": false } }, "totalCount": { "type": "number" } }, "required": [ "users", "totalCount" ], "additionalProperties": false } }, "required": [ "address", "username", "profile_image", "bio", "followers", "following", "x_username" ], "additionalProperties": false }, "description": "UserProfile-shaped rows in relevance order. `mutuals` is viewer-relative: on a signed-in read every row carries it (a row without it means the signal was unavailable, never zero); it is never populated on the API host, which has no signed-in viewer" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/following/v3/followers/{userId}": { "get": { "operationId": "get_following_v3_followers_by_userId", "tags": [ "graph.read" ], "summary": "One page of a user's followers", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, default 20. Out-of-range values are rejected with 400, not clamped.", "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "required": false, "schema": { "description": "0-indexed offset into the sorted list, default 0", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "sort", "in": "query", "required": false, "schema": { "description": "Row order: `followers` (default) is most-followed first, `recent` is newest follow edge first.", "type": "string", "enum": [ "followers", "recent" ] } } ], "responses": { "200": { "description": "One page of a user's followers", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "username": { "nullable": true, "type": "string" }, "profile_image": { "nullable": true, "type": "string" }, "resolved_avatar_decoration": { "nullable": true, "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border.", "type": "string" }, "address": { "type": "string", "description": "Canonical Solana wallet, else the canonical EVM wallet; \"\" for a walletless account (a group)" }, "userId": { "type": "string" }, "user_id": { "type": "string", "description": "Deprecated alias of userId, served for shipped clients (docs/route-deprecations.md); read userId" }, "kind": { "type": "string", "enum": [ "person", "group" ] }, "timestamp": { "nullable": true, "type": "number" }, "followers": { "type": "number" }, "mutuals": { "description": "Accounts the viewer follows that also follow this follower — up to 3 previews, most-followed first, plus the exact totalCount; the shape the suggestions route serves. Viewer-relative: only on a signed-in read of a page of at most 100 rows, never on the API host; absent = signal unavailable (never zero), totalCount 0 = none shared.", "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "profileImage": { "nullable": true, "type": "string" } }, "required": [ "userId", "username", "profileImage" ], "additionalProperties": false } }, "totalCount": { "type": "number" } }, "required": [ "users", "totalCount" ], "additionalProperties": false } }, "required": [ "username", "profile_image", "resolved_avatar_decoration", "address", "userId", "user_id", "kind", "timestamp", "followers" ], "additionalProperties": false }, "description": "Plain-list rows in the requested order. `mutuals` is viewer-relative: on a signed-in read every row of a page of at most 100 rows carries it (a row without it means the signal was unavailable, never zero); it is never populated on the API host, which has no signed-in viewer. 503 when the follow read is unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Status-only; the body is the fixed 5xx envelope" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/following/v3/following/count/{userId}": { "get": { "operationId": "get_following_v3_following_count_by_userId", "tags": [ "graph.read" ], "summary": "Get a user following count", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a user following count (v3)", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "number" } }, "required": [ "count" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Get a user following count (v3)" } }, "/following/v3/following/search/{userId}": { "get": { "operationId": "get_following_v3_following_search_by_userId", "tags": [ "graph.read" ], "summary": "Search within the users a user is following", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "searchTerm", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Search term, relevance-ranked; trimmed. Fewer than 2 characters after trimming answers [] without a search. Longer than 50 characters is a 400." } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, default 20. Out-of-range values are rejected with 400, not clamped.", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "description": "0-indexed offset into the ranked matches, default 0", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Search within the users a user is following", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "userId": { "type": "string" }, "username": { "nullable": true, "type": "string" }, "profile_image": { "nullable": true, "type": "string" }, "header_image_url": { "nullable": true, "type": "string" }, "avatar_decoration": { "description": "The owner's avatar decoration (border effect) PICK as a decoration key — `legendary`, `epic`, `none` (an explicit no-border), `achievement:` — never a url: the client owns the key -> artwork catalog. For the owner's chooser (which tile is selected); the border to draw is resolved_avatar_decoration. null or absent means no pick. Served on GET /users/{id} and POST /users/batch rows.", "nullable": true, "type": "string" }, "resolved_avatar_decoration": { "description": "The border to draw on this avatar, resolved from the owner's pick and achievements: the pick while still earned, else the rarest tier ring the achievements earn (`legendary`, `epic`); null means no border (an explicit `none` pick, or nothing earned). Same key grammar as avatar_decoration. Served on GET /users/{id} and POST /users/batch rows — never fetch a user's achievements to draw a border. A newly earned tier can take up to an hour to show to other viewers; the owner's own view updates immediately", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "person", "group" ] }, "member_count": { "type": "number" }, "group_badges": { "type": "array", "items": { "type": "object", "properties": { "group_id": { "type": "string" }, "username": { "type": "string" }, "profile_image_url": { "nullable": true, "type": "string" }, "role": { "anyOf": [ { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "UNSPECIFIED" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Known values: OWNER, ADMIN, MEMBER, UNSPECIFIED" } }, "required": [ "group_id", "username", "profile_image_url", "role" ], "additionalProperties": false } }, "bio": { "nullable": true, "type": "string" }, "followers": { "type": "number" }, "following": { "type": "number" }, "last_username_update_timestamp": { "description": "Unix epoch ms of the last username change; null when never renamed. Served by the single-profile read and on labelled-wallet search rows; absent from batch and hydrated search-v2 rows", "nullable": true, "type": "number" }, "x_username": { "nullable": true, "type": "string" }, "wallet_label": { "type": "string" }, "is_pump_user": { "type": "boolean" }, "is_banned": { "type": "boolean" }, "canonical_svm_wallet": { "type": "string" }, "canonical_evm_wallet": { "type": "string" }, "last_active_at": { "description": "ISO time of the account's latest authenticated request (~1 min granularity, kept for one day). Viewer-relative: served on GET /users/{id} and POST /users/batch rows to a signed-in viewer, for accounts the viewer follows and the viewer's own row, null otherwise (not followed, never seen, degraded read) — render null as unknown. Absent for anonymous callers, on the API host, and on every other row-serving read", "nullable": true, "type": "string" } }, "required": [ "address", "username", "profile_image", "bio", "followers", "following", "x_username" ], "additionalProperties": false }, "description": "UserProfile-shaped rows in relevance order" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/following/v3/following/{userId}": { "get": { "operationId": "get_following_v3_following_by_userId", "tags": [ "graph.read" ], "summary": "One page of the users a user is following", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, default 20. Out-of-range values are rejected with 400, not clamped.", "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "required": false, "schema": { "description": "0-indexed offset into the sorted list, default 0", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "sort", "in": "query", "required": false, "schema": { "description": "Row order: `followers` (default) is most-followed first, `recent` is newest follow edge first.", "type": "string", "enum": [ "followers", "recent" ] } } ], "responses": { "200": { "description": "One page of the users a user is following", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "username": { "nullable": true, "type": "string" }, "profile_image": { "nullable": true, "type": "string" }, "resolved_avatar_decoration": { "nullable": true, "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border.", "type": "string" }, "address": { "type": "string", "description": "Canonical Solana wallet, else the canonical EVM wallet; \"\" for a walletless account (a group)" }, "userId": { "type": "string" }, "user_id": { "type": "string", "description": "Deprecated alias of userId, served for shipped clients (docs/route-deprecations.md); read userId" }, "kind": { "type": "string", "enum": [ "person", "group" ] }, "timestamp": { "nullable": true, "type": "number" }, "followers": { "type": "number" } }, "required": [ "username", "profile_image", "resolved_avatar_decoration", "address", "userId", "user_id", "kind", "timestamp", "followers" ], "additionalProperties": false }, "description": "Plain-list rows in the requested order. 503 when the follow read is unavailable" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Status-only; the body is the fixed 5xx envelope" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/groups/{groupId}/members": { "get": { "operationId": "get_groups_by_groupId_members", "tags": [ "graph.read" ], "summary": "A page of a group's members, owner first", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "description": "Omitted matches every status", "type": "string", "enum": [ "INVITED", "ACTIVE" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "A page of a group's members, owner first (the INVITED view is owner/admin-only)", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "properties": { "profile": { "nullable": true, "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "bio": { "type": "string" }, "profileImageUrl": { "type": "string" }, "headerImageUrl": { "type": "string" }, "followerCount": { "type": "number" }, "followingCount": { "type": "number" }, "createdAt": { "nullable": true, "type": "string" }, "updatedAt": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "socials": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "username": { "type": "string" }, "linkedAt": { "nullable": true, "type": "string" } }, "required": [ "provider", "username", "linkedAt" ], "additionalProperties": false } }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true. The verified state itself is isVerified." }, "resolvedAvatarDecoration": { "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border. Treat absent as null.", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "PERSON", "GROUP" ] }, "memberCount": { "type": "number" }, "membershipPolicy": { "nullable": true, "type": "string", "enum": [ "INVITE" ] }, "groupBadges": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "role": { "type": "string" } }, "required": [ "groupId", "username", "profileImageUrl", "role" ], "additionalProperties": false } }, "generatedMedia": { "nullable": true, "type": "object", "properties": { "pnlLoop": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" } }, "required": [ "uid", "durationSeconds" ], "additionalProperties": false }, "replayIntro": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" }, "fireAt": { "type": "number" } }, "required": [ "uid", "durationSeconds", "fireAt" ], "additionalProperties": false } }, "required": [ "pnlLoop" ], "additionalProperties": false }, "isPumpUser": { "description": "false = unclaimed shell: an identity minted when someone followed an outside wallet that never signed in, served under a generated username. Render it as a wallet (address or the viewer’s wallet label), never as an account. Treat absent as true.", "type": "boolean" } }, "required": [ "userId", "username", "bio", "profileImageUrl", "headerImageUrl", "followerCount", "followingCount", "createdAt", "updatedAt", "walletAddress", "socials", "isVerified", "verifiedBadgeVisible", "kind", "memberCount", "membershipPolicy", "groupBadges", "generatedMedia" ], "additionalProperties": false }, "role": { "anyOf": [ { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "UNSPECIFIED" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Known values: OWNER, ADMIN, MEMBER, UNSPECIFIED" }, "status": { "anyOf": [ { "type": "string", "enum": [ "INVITED", "ACTIVE", "UNSPECIFIED" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Known values: INVITED, ACTIVE, UNSPECIFIED" }, "invitedBy": { "nullable": true, "description": "Null when the inviter's account was deleted", "type": "string" }, "createdAt": { "nullable": true, "description": "Invite time (ISO 8601), unchanged by acceptance", "type": "string" } }, "required": [ "profile", "role", "status", "invitedBy", "createdAt" ], "additionalProperties": false } }, "hasMore": { "type": "boolean" } }, "required": [ "members", "hasMore" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "A page of a group's members, owner first (the INVITED view is owner/admin-only)" } }, "/groups/{groupId}/members/pnl": { "get": { "operationId": "get_groups_by_groupId_members_pnl", "tags": [ "graph.read" ], "summary": "The group's active members ranked by windowed PnL", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "1d", "1w", "1m" ] } } ], "responses": { "200": { "description": "The group's active members ranked by windowed PnL (members tab); empty rows when no fold is published", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string" }, "builtAtMs": { "type": "number", "description": "0 when no fold is published" }, "windowStartSec": { "type": "number", "description": "Window start (unix seconds)" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "walletAddress": { "type": "string", "description": "The canonical SVM wallet the row was folded for (base58)" }, "pnlUsd": { "type": "number", "description": "Windowed PnL in USD (realized + unrealized) for the period" } }, "required": [ "userId", "walletAddress", "pnlUsd" ], "additionalProperties": false }, "description": "Active members with a counted fold row, pnlUsd descending; empty when the group has none or the fold is stale" } }, "required": [ "period", "builtAtMs", "windowStartSec", "rows" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "The group's active members ranked by windowed PnL (members tab); empty rows when no fold is published" } }, "/home-feed": { "get": { "operationId": "get_home_feed", "tags": [ "content.read" ], "summary": "Get the paginated home feed of trending coins and…", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "content.read", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "description": "Opaque continuation token from a previous response's nextPageToken; an unrecognized value serves a fresh first batch", "type": "string", "maxLength": 256 } }, { "name": "forceRefresh", "in": "query", "required": false, "schema": { "description": "Pull-to-refresh: skip the short ranking response cache and start the walk over", "type": "boolean" } }, { "name": "chain", "in": "query", "required": false, "schema": { "description": "Unset or 'all' = every supported chain", "type": "string", "enum": [ "all", "solana", "ethereum", "base", "bsc", "robinhood", "hyperevm", "ink", "arc", "megaeth", "xlayer", "monad", "polygon" ] } }, { "name": "chains", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "description": "Comma-separated feed chains merged into one page and one cursor: each chain's own ranking, interleaved by rank, so every requested chain with rows appears. Exclusive with chain (400 when both are sent); one slug behaves exactly like chain=. Not yet honoured: the parameter is ignored today", "maxItems": 12, "type": "array", "items": { "type": "string", "enum": [ "solana", "ethereum", "base", "bsc", "robinhood", "hyperevm", "ink", "arc", "megaeth", "xlayer", "monad", "polygon" ] } } }, { "name": "minMarketCapUsd", "in": "query", "required": false, "schema": { "description": "Serve only positions in coins whose CURRENT market cap is >= this USD; applied before ranking, so a banded page still fills. Coins with no known market cap drop while either bound is set", "type": "number", "minimum": 0 } }, { "name": "maxMarketCapUsd", "in": "query", "required": false, "schema": { "description": "Current market cap ceiling in USD; must be >= minMarketCapUsd when both are set (400 otherwise)", "type": "number", "minimum": 0 } }, { "name": "minCostBasisUsd", "in": "query", "required": false, "schema": { "description": "Position size: serve only positions whose net USD cost basis is >= this, applied before ranking. Positions with no cost basis drop while either bound is set", "type": "number", "minimum": 0 } }, { "name": "maxCostBasisUsd", "in": "query", "required": false, "schema": { "description": "Position size ceiling in USD of net cost basis; must be >= minCostBasisUsd when both are set (400 otherwise)", "type": "number", "minimum": 0 } }, { "name": "includeFollowedHolders", "in": "query", "required": false, "schema": { "description": "Attach the followed-holders facepile per coin", "type": "boolean" } }, { "name": "followedHoldersLimit", "in": "query", "required": false, "schema": { "description": "Default 3; values above 10 clamp to 10", "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "recsys", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "updatesLimit", "in": "query", "required": false, "schema": { "description": "Top-level author updates served per callout; unset serves the fetched window untrimmed", "type": "integer", "minimum": 1, "maximum": 10 } }, { "name": "userId", "in": "query", "required": false, "schema": { "description": "Requester's wallet address, the ranker's personalization identity", "type": "string" } }, { "name": "session_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "device_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 } }, { "name": "session_start_timestamp_ms", "in": "query", "required": false, "schema": { "description": "Epoch-ms the client's current session (session_id) started at; a session-age signal for the ranking", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "country", "in": "query", "required": false, "schema": { "description": "ISO 3166-1 alpha-2 country code — device-locale hint, not auth", "type": "string" } }, { "name": "os", "in": "query", "required": false, "schema": { "description": "Device OS the client declares", "type": "string" } }, { "name": "platform", "in": "query", "required": false, "schema": { "description": "Client surface (APP or WEB), exact-match only; absent, the server default applies", "type": "string", "enum": [ "APP", "WEB" ] } } ], "responses": { "200": { "description": "Get the paginated home feed of trending coins and callout positions", "content": { "application/json": { "schema": { "type": "object", "properties": { "coins": { "type": "array", "items": { "type": "object", "properties": { "coinMint": { "type": "string" }, "coinName": { "nullable": true, "type": "string" }, "coinImage": { "nullable": true, "type": "string" }, "symbol": { "nullable": true, "type": "string" }, "coinDescription": { "type": "string", "nullable": true, "enum": [ null ], "description": "Always null: retired with the narrative feature; the key stays for shipped clients" }, "marketCap": { "nullable": true, "type": "number" }, "protocol": { "nullable": true, "description": "An EVM coin's launchpad identity", "type": "string" }, "platform": { "nullable": true, "description": "Solana launchpad platform (`bonk`, `bags`, `believe`); null on EVM rows", "type": "string" }, "program": { "nullable": true, "description": "Solana program slug (`pump`, `meteora_dbc`, `raydium_launchpad`); null on EVM rows", "type": "string" }, "chain": { "nullable": true, "description": "null when the coin's chain can't be proven", "type": "string", "enum": [ "solana", "ethereum", "base", "bsc", "robinhood", "hyperevm", "ink", "arc", "megaeth", "xlayer", "monad", "polygon" ] }, "chain_id": { "description": "CAIP-2 chain on a NEAR row (`near:mainnet`, whose coinMint is a case-sensitive NEAR account id) or a Starknet row (`starknet:SN_MAIN`, whose coinMint is the canonical 0x+64 felt) only; absent on SVM/EVM rows", "type": "string" }, "narrative": { "type": "string", "nullable": true, "enum": [ null ], "description": "Always null: the narrative producer is retired and its rows drained; the key stays for shipped clients" }, "position": { "nullable": true, "description": "The featured entry, or null when there is none", "type": "object", "properties": { "userId": { "type": "string" }, "userName": { "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "resolvedAvatarDecoration": { "nullable": true, "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border.", "type": "string" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad row: userId/userName/profileImage are the squad's while walletAddress is the acting admin's posting wallet; route the author press on userId + accountKind" }, "followerCount": { "nullable": true, "description": "The holder profile's pump follower count (a squad row: the squad's).", "type": "number" }, "xUsername": { "nullable": true, "description": "null when no X link exists or the holder marked it private (redacted at the ranking hop)", "type": "string" }, "xProfileImage": { "nullable": true, "description": "The holder's picture on X (400x400), not their pump pfp. X URLs rot when the avatar changes — display-only, never persist", "type": "string" }, "totalCallouts": { "type": "number" }, "amountHeld": { "type": "number" }, "valueUsd": { "nullable": true, "description": "null when no price source resolves", "type": "number" }, "pnlUsd": { "nullable": true, "type": "number" }, "pnlPercentage": { "nullable": true, "type": "number" }, "realizedPnlUsd": { "type": "number", "description": "Realized leg only: unrealized = pnlUsd - realizedPnlUsd. Never reconstruct value as costBasisUsd + pnlUsd, which overstates by exactly this" }, "tokenPriceUsd": { "nullable": true, "description": "The price valueUsd/pnlUsd are marked at; re-mark at a live price p as (amountHeld * p - costBasisUsd) + realizedPnlUsd", "type": "number" }, "costBasisAmount": { "type": "number", "description": "Both cost-basis legs shrink on sells — open positions only; the amountBought pair is the lifetime entry that survives exit" }, "costBasisUsd": { "nullable": true, "type": "number" }, "amountBoughtUsd": { "nullable": true, "description": "Lifetime buy total, never sell-reduced — the pnlPercentage denominator. Null when not yet available; EVM rows stay null", "type": "number" }, "amountBought": { "nullable": true, "type": "number" }, "callout": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Shared_fceda4efe6cd" } ] }, "contentKind": { "type": "string", "enum": [ "callout", "quote" ], "description": "Which content the card should feature. The callout fields stay populated either way, so clients that ignore this render the legacy card" }, "quote": { "nullable": true, "description": "The selected quote repost; null for contentKind 'callout'", "type": "object", "properties": { "callout": { "nullable": true, "description": "null when the callout is deleted or moderation-hidden", "type": "object", "properties": { "coinMint": { "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true; true for user-less callouts" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad callout: userId/userName/profileImage are the squad's while walletAddress is the acting admin's posting wallet; route the author press on userId + accountKind, never the wallet" }, "xUsername": { "nullable": true, "type": "string" }, "xFollowerCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "chain": { "description": "CAIP-2 chain of the called-out ref; absent when the callout carries none", "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "callout": { "$ref": "#/components/schemas/Shared_fceda4efe6cd" }, "coinName": { "nullable": true, "type": "string" }, "coinImage": { "nullable": true, "type": "string" }, "symbol": { "nullable": true, "type": "string" }, "marketCap": { "nullable": true, "type": "number" } }, "required": [ "coinMint", "walletAddress", "userId", "userName", "profileImage", "isVerified", "verifiedBadgeVisible", "accountKind", "xUsername", "xFollowerCount", "mediaUrl", "callout", "coinName", "coinImage", "symbol", "marketCap" ], "additionalProperties": false }, "parent": { "nullable": true, "description": "null when the reply targets the callout directly", "allOf": [ { "$ref": "#/components/schemas/Shared_3ba6ed1d0d06" } ] }, "reply": { "$ref": "#/components/schemas/Shared_3ba6ed1d0d06" } }, "required": [ "callout", "parent", "reply" ], "additionalProperties": false } }, "required": [ "userId", "userName", "profileImage", "walletAddress", "isVerified", "verifiedBadgeVisible", "resolvedAvatarDecoration", "accountKind", "followerCount", "xUsername", "xProfileImage", "totalCallouts", "amountHeld", "valueUsd", "pnlUsd", "pnlPercentage", "realizedPnlUsd", "tokenPriceUsd", "costBasisAmount", "costBasisUsd", "amountBoughtUsd", "amountBought", "callout", "contentKind", "quote" ], "additionalProperties": false }, "recommendationId": { "description": "Recsys path only: the ranking response id, the join key for impression/action attribution. Absent — never null — on the legacy path", "type": "string" }, "recommendationRank": { "description": "This card's 1-based rank in that ranking response, unique only within its recommendationId: a chains= page interleaves one ranking per chain, so ranks repeat and are not the served position", "type": "number" }, "followedHolders": { "nullable": true, "type": "object", "properties": { "holders": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "resolvedAvatarDecoration": { "nullable": true, "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border. Always null on a facepile whose holders carry no profile (coin-card facepiles).", "type": "string" }, "walletAddress": { "nullable": true, "description": "Null when the account has none. Never an EVM address (an EVM value is mapped to its SVM wallet or dropped to null)", "type": "string" } }, "required": [ "userId", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible", "resolvedAvatarDecoration", "walletAddress" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Size of the whole followed-holder set for the coin, not just the embedded page — the \"and N others\" figure" } }, "required": [ "holders", "totalCount" ], "additionalProperties": false } }, "required": [ "coinMint", "coinName", "coinImage", "symbol", "coinDescription", "marketCap", "protocol", "platform", "program", "chain", "narrative", "position", "followedHolders" ], "additionalProperties": false }, "description": "Can be shorter than the requested pageSize — unhydratable rows are dropped after the page is cut" }, "nextPageToken": { "description": "Send back as pageToken for the next batch. Empty string means the end of the feed for now, not permanently. Absent on the legacy page-based path and on every degraded fallback", "type": "string" } }, "required": [ "coins" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Get the paginated home feed of trending coins and callout positions" } }, "/home-feed/new": { "get": { "operationId": "get_home_feed_new", "tags": [ "content.read" ], "summary": "The global \"New\" callouts feed", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "content.read", "parameters": [ { "name": "pageSize", "in": "query", "required": false, "schema": { "description": "Default 25; a short page means the 24h window is exhausted, not that a filter cut it. A chains= page is cut at the least-advanced chain and can run short with rows remaining, so nextPageToken is the only end signal there", "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "description": "A previous response's nextPageToken; omit for the first page", "type": "string" } }, { "name": "updatesLimit", "in": "query", "required": false, "schema": { "description": "Top-level author updates served per callout, as /home-feed", "type": "integer", "minimum": 1, "maximum": 10 } }, { "name": "chain", "in": "query", "required": false, "schema": { "description": "Unset/'all' = every feed chain; a slug = that chain only (the registry's `feed` set)", "type": "string", "enum": [ "all", "solana", "ethereum", "base", "bsc", "robinhood", "hyperevm", "ink", "arc", "megaeth", "xlayer", "monad", "polygon" ] } }, { "name": "chains", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "description": "Comma-separated feed chains merged in exact recency order under one cursor. Exclusive with chain (400 when both are sent); one slug behaves exactly like chain=. Not yet honoured: the parameter is ignored today", "maxItems": 12, "type": "array", "items": { "type": "string", "enum": [ "solana", "ethereum", "base", "bsc", "robinhood", "hyperevm", "ink", "arc", "megaeth", "xlayer", "monad", "polygon" ] } } }, { "name": "minCostBasisUsd", "in": "query", "required": false, "schema": { "description": "Position size: serve only callouts whose live position has a net USD cost basis >= this. Rows with no cost basis drop while set", "type": "number", "minimum": 0 } }, { "name": "maxCostBasisUsd", "in": "query", "required": false, "schema": { "description": "Position size ceiling: net USD cost basis <= this; rows with no cost basis drop while set; must be >= minCostBasisUsd when both are set (400 otherwise)", "type": "number", "minimum": 0 } }, { "name": "minCalloutMarketCapUsd", "in": "query", "required": false, "schema": { "description": "Serve only callouts whose coin's market cap AT CALLOUT TIME was >= this USD; the card's marketCap is the coin's live figure and may differ", "type": "number", "minimum": 0 } }, { "name": "maxCalloutMarketCapUsd", "in": "query", "required": false, "schema": { "description": "Market cap AT CALLOUT TIME <= this USD; must be >= minCalloutMarketCapUsd when both are set (400 otherwise)", "type": "number", "minimum": 0 } }, { "name": "minMarketCapUsd", "in": "query", "required": false, "schema": { "description": "Serve only callouts whose coin's CURRENT market cap (the card's marketCap) is >= this USD, unlike minCalloutMarketCapUsd's at-callout-time figure. Rows whose coin has no known market cap drop while either bound is set", "type": "number", "minimum": 0 } }, { "name": "maxMarketCapUsd", "in": "query", "required": false, "schema": { "description": "CURRENT market cap <= this USD; must be >= minMarketCapUsd when both are set (400 otherwise)", "type": "number", "minimum": 0 } } ], "responses": { "200": { "description": "The global \"New\" callouts feed: every live-position-backed callout across all users, newest first with no ranking, cursor-paged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "coins": { "type": "array", "items": { "type": "object", "properties": { "coinMint": { "type": "string" }, "coinName": { "nullable": true, "type": "string" }, "coinImage": { "nullable": true, "type": "string" }, "symbol": { "nullable": true, "type": "string" }, "coinDescription": { "type": "string", "nullable": true, "enum": [ null ], "description": "Always null: retired with the narrative feature; the key stays for shipped clients" }, "marketCap": { "nullable": true, "type": "number" }, "protocol": { "nullable": true, "description": "An EVM coin's launchpad identity", "type": "string" }, "platform": { "nullable": true, "description": "Solana launchpad platform (`bonk`, `bags`, `believe`); null on EVM rows", "type": "string" }, "program": { "nullable": true, "description": "Solana program slug (`pump`, `meteora_dbc`, `raydium_launchpad`); null on EVM rows", "type": "string" }, "chain": { "nullable": true, "description": "null when the coin's chain can't be proven", "type": "string", "enum": [ "solana", "ethereum", "base", "bsc", "robinhood", "hyperevm", "ink", "arc", "megaeth", "xlayer", "monad", "polygon" ] }, "chain_id": { "description": "CAIP-2 chain on a NEAR row (`near:mainnet`, whose coinMint is a case-sensitive NEAR account id) or a Starknet row (`starknet:SN_MAIN`, whose coinMint is the canonical 0x+64 felt) only; absent on SVM/EVM rows", "type": "string" }, "narrative": { "type": "string", "nullable": true, "enum": [ null ], "description": "Always null: the narrative producer is retired and its rows drained; the key stays for shipped clients" }, "position": { "nullable": true, "description": "The featured entry, or null when there is none", "type": "object", "properties": { "userId": { "type": "string" }, "userName": { "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "resolvedAvatarDecoration": { "nullable": true, "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border.", "type": "string" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad row: userId/userName/profileImage are the squad's while walletAddress is the acting admin's posting wallet; route the author press on userId + accountKind" }, "followerCount": { "nullable": true, "description": "The holder profile's pump follower count (a squad row: the squad's).", "type": "number" }, "xUsername": { "nullable": true, "description": "null when no X link exists or the holder marked it private (redacted at the ranking hop)", "type": "string" }, "xProfileImage": { "nullable": true, "description": "The holder's picture on X (400x400), not their pump pfp. X URLs rot when the avatar changes — display-only, never persist", "type": "string" }, "totalCallouts": { "type": "number" }, "amountHeld": { "type": "number" }, "valueUsd": { "nullable": true, "description": "null when no price source resolves", "type": "number" }, "pnlUsd": { "nullable": true, "type": "number" }, "pnlPercentage": { "nullable": true, "type": "number" }, "realizedPnlUsd": { "type": "number", "description": "Realized leg only: unrealized = pnlUsd - realizedPnlUsd. Never reconstruct value as costBasisUsd + pnlUsd, which overstates by exactly this" }, "tokenPriceUsd": { "nullable": true, "description": "The price valueUsd/pnlUsd are marked at; re-mark at a live price p as (amountHeld * p - costBasisUsd) + realizedPnlUsd", "type": "number" }, "costBasisAmount": { "type": "number", "description": "Both cost-basis legs shrink on sells — open positions only; the amountBought pair is the lifetime entry that survives exit" }, "costBasisUsd": { "nullable": true, "type": "number" }, "amountBoughtUsd": { "nullable": true, "description": "Lifetime buy total, never sell-reduced — the pnlPercentage denominator. Null when not yet available; EVM rows stay null", "type": "number" }, "amountBought": { "nullable": true, "type": "number" }, "callout": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Shared_fceda4efe6cd" } ] }, "contentKind": { "type": "string", "enum": [ "callout", "quote" ], "description": "Which content the card should feature. The callout fields stay populated either way, so clients that ignore this render the legacy card" }, "quote": { "nullable": true, "description": "The selected quote repost; null for contentKind 'callout'", "type": "object", "properties": { "callout": { "nullable": true, "description": "null when the callout is deleted or moderation-hidden", "type": "object", "properties": { "coinMint": { "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true; true for user-less callouts" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad callout: userId/userName/profileImage are the squad's while walletAddress is the acting admin's posting wallet; route the author press on userId + accountKind, never the wallet" }, "xUsername": { "nullable": true, "type": "string" }, "xFollowerCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "chain": { "description": "CAIP-2 chain of the called-out ref; absent when the callout carries none", "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "callout": { "$ref": "#/components/schemas/Shared_fceda4efe6cd" }, "coinName": { "nullable": true, "type": "string" }, "coinImage": { "nullable": true, "type": "string" }, "symbol": { "nullable": true, "type": "string" }, "marketCap": { "nullable": true, "type": "number" } }, "required": [ "coinMint", "walletAddress", "userId", "userName", "profileImage", "isVerified", "verifiedBadgeVisible", "accountKind", "xUsername", "xFollowerCount", "mediaUrl", "callout", "coinName", "coinImage", "symbol", "marketCap" ], "additionalProperties": false }, "parent": { "nullable": true, "description": "null when the reply targets the callout directly", "allOf": [ { "$ref": "#/components/schemas/Shared_3ba6ed1d0d06" } ] }, "reply": { "$ref": "#/components/schemas/Shared_3ba6ed1d0d06" } }, "required": [ "callout", "parent", "reply" ], "additionalProperties": false } }, "required": [ "userId", "userName", "profileImage", "walletAddress", "isVerified", "verifiedBadgeVisible", "resolvedAvatarDecoration", "accountKind", "followerCount", "xUsername", "xProfileImage", "totalCallouts", "amountHeld", "valueUsd", "pnlUsd", "pnlPercentage", "realizedPnlUsd", "tokenPriceUsd", "costBasisAmount", "costBasisUsd", "amountBoughtUsd", "amountBought", "callout", "contentKind", "quote" ], "additionalProperties": false }, "recommendationId": { "description": "Recsys path only: the ranking response id, the join key for impression/action attribution. Absent — never null — on the legacy path", "type": "string" }, "recommendationRank": { "description": "This card's 1-based rank in that ranking response, unique only within its recommendationId: a chains= page interleaves one ranking per chain, so ranks repeat and are not the served position", "type": "number" }, "followedHolders": { "nullable": true, "type": "object", "properties": { "holders": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "resolvedAvatarDecoration": { "nullable": true, "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border. Always null on a facepile whose holders carry no profile (coin-card facepiles).", "type": "string" }, "walletAddress": { "nullable": true, "description": "Null when the account has none. Never an EVM address (an EVM value is mapped to its SVM wallet or dropped to null)", "type": "string" } }, "required": [ "userId", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible", "resolvedAvatarDecoration", "walletAddress" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Size of the whole followed-holder set for the coin, not just the embedded page — the \"and N others\" figure" } }, "required": [ "holders", "totalCount" ], "additionalProperties": false } }, "required": [ "coinMint", "coinName", "coinImage", "symbol", "coinDescription", "marketCap", "protocol", "platform", "program", "chain", "narrative", "position", "followedHolders" ], "additionalProperties": false }, "description": "/home-feed cards, newest first; recommendationId/recommendationRank are absent (no ranking response)" }, "nextPageToken": { "description": "Send back as pageToken for the next batch; absent = the 24h window is exhausted", "type": "string" }, "headToken": { "nullable": true, "description": "Pin it as `since` until the pill is tapped or chain/filters change — never replace it with a count response or a head message. Null on continuation pages and when the window is empty (then every head row is new)", "type": "string" }, "liveSubject": { "type": "string", "description": "Subscribe verbatim while the New tab is visible, the way the Following tab subscribes followingFeed.user.{id}. Each message is a full snapshot that replaces the last one applied; drop a message whose asOf is older than that. Pending = rows newer than the pinned `since` that pass the filters and are not flagged: the pill count is their number (25 rows all newer = \"25+\"), the avatar preview is their coinMint, and revealing refetches page 1 and re-pins since. Call /home-feed/new/count only on reconnect/resume or after 90s with no message. On a chains= page this is the all-chains subject, which misses most of a minority selection: subscribe to liveSubjects instead and ignore this field. The head carries no current market cap, so a count from it ignores minMarketCapUsd/maxMarketCapUsd and can overcount; /home-feed/new/count applies that band." }, "liveSubjects": { "description": "chains= pages only: one subject per requested chain, the complete set to subscribe to; pending = the union of their heads newer than the pinned `since`. When present, ignore liveSubject: it is the all-chains subject, a 25-row global snapshot that carries almost none of a minority selection's rows", "type": "array", "items": { "type": "string" } } }, "required": [ "coins", "headToken", "liveSubject" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "The global \"New\" callouts feed: every live-position-backed callout across all users, newest first with no ranking, cursor-paged." } }, "/mayhem/{mint}/top-traders": { "get": { "operationId": "get_mayhem_by_mint_top_traders", "tags": [ "leaderboards.read" ], "summary": "Get the trader leaderboard for a mayhem coin", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "leaderboards.read", "parameters": [ { "name": "mint", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get the trader leaderboard for a mayhem coin", "content": { "application/json": { "schema": { "type": "object", "properties": { "mint": { "type": "string" }, "updatedAt": { "type": "number", "description": "Epoch ms when this snapshot was taken" }, "traders": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "number" }, "address": { "type": "string" }, "username": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "realisedPnlUsd": { "type": "number" }, "averageEntryMarketCapUsd": { "nullable": true, "type": "number" }, "averageExitMarketCapUsd": { "nullable": true, "type": "number" }, "totalBoughtUsd": { "type": "number" }, "totalSoldUsd": { "type": "number" }, "buyTransactionCount": { "type": "number" }, "sellTransactionCount": { "type": "number" }, "tokenBalance": { "type": "string", "description": "Raw token amount as a string (may exceed Number.MAX_SAFE_INTEGER)" }, "tokenAmountBought": { "type": "number" }, "tokenAmountSold": { "type": "number" }, "lastActivityAt": { "type": "number", "description": "Epoch seconds" } }, "required": [ "rank", "address", "username", "profileImage", "realisedPnlUsd", "averageEntryMarketCapUsd", "averageExitMarketCapUsd", "totalBoughtUsd", "totalSoldUsd", "buyTransactionCount", "sellTransactionCount", "tokenBalance", "tokenAmountBought", "tokenAmountSold", "lastActivityAt" ], "additionalProperties": false } } }, "required": [ "mint", "updatedAt", "traders" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/mint-positions/{mint}": { "get": { "operationId": "get_mint_positions_by_mint", "tags": [ "positions.read" ], "summary": "Get the users holding a position in a mint", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "positions.read", "parameters": [ { "name": "mint", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "description": "Order of the list. CLOSED_PNL serves the mint's fully exited positions (booked realized PnL) ranked by realized PnL USD descending, losses last, and requires withThesis=true; every other sort serves open holders.", "type": "string", "enum": [ "LATEST", "TOP", "LOWEST_ENTRY", "RANKED", "CLOSED_PNL" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "withThesis", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "updatesLimit", "in": "query", "required": false, "schema": { "description": "Max author updates per callout (omitted serves 5); 0 skips update enrichment entirely", "type": "integer", "minimum": 0, "maximum": 20 } }, { "name": "includeProfile", "in": "query", "required": false, "schema": { "description": "Embed each holder's full registry profile on the row; off by default", "type": "boolean" } }, { "name": "dustFloorUsd", "in": "query", "required": false, "schema": { "description": "Rejected with sortBy=CLOSED_PNL, which ranks by realized PnL instead", "type": "number", "minimum": 0, "maximum": 100000 } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "description": "RANKED only: cursor from a previous RANKED response. Mutually exclusive with `page`", "type": "string", "maxLength": 256 } }, { "name": "forceRefresh", "in": "query", "required": false, "schema": { "description": "RANKED only: pull-to-refresh — skip the ranking-cache read and restart the walk", "type": "boolean" } }, { "name": "chainId", "in": "query", "required": false, "schema": { "description": "Solana mints never need it; an unresolvable 0x mint without it is a 400", "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "session_id", "in": "query", "required": false, "schema": { "description": "RANKED only: required for a nextPageToken; without it RANKED serves one page and no token", "type": "string", "maxLength": 128 } }, { "name": "device_id", "in": "query", "required": false, "schema": { "description": "RANKED only: persisted install/device id, forwarded to the ranker", "type": "string", "maxLength": 128 } }, { "name": "country", "in": "query", "required": false, "schema": { "description": "RANKED only: ISO 3166-1 alpha-2 country code — device-locale hint, not auth", "type": "string", "minLength": 2, "maxLength": 8 } }, { "name": "os", "in": "query", "required": false, "schema": { "description": "RANKED only: device OS the client declares", "type": "string", "maxLength": 16 } }, { "name": "platform", "in": "query", "required": false, "schema": { "description": "RANKED only: client surface", "type": "string", "maxLength": 16 } }, { "name": "chain", "in": "query", "required": false, "schema": { "description": "CAIP-2 chain of a perp, NEAR, Starknet or TON coin: hlcore:mainnet makes {mint} the HL coin key verbatim (BTC, xyz:TSLA) and serves the coin's HyperCore perp holders (assetClass ASSET_CLASS_PERPETUAL, chainId 0, perp block); near:mainnet makes {mint} a NEAR account id verbatim (wrap.near) and serves its NEAR holders (chain near:mainnet, chainId null, walletAddress the account id); starknet:SN_MAIN makes {mint} a Starknet address (0x + 1..64 hex, any case, a 0x+40 included; served as 0x + 64 lowercase hex, 400 otherwise) and serves its Starknet holders (chain starknet:SN_MAIN, chainId null, coinMint and walletAddress 0x + 64 lowercase hex); ton:-239 makes {mint} the CRC-checked 48-char bounceable EQ jetton master (400 otherwise) and serves its TON holders (chain ton:-239, chainId null, walletAddress the holder's TON wallet); RANKED serves TOP there. Absent = the spot path. 400, with the hlcore:mainnet body, when holders are not available for that chain", "type": "string", "pattern": "^(?:(?:hlcore|near):mainnet|starknet:SN_MAIN|ton:-239)$" } }, { "name": "scope", "in": "query", "required": false, "schema": { "description": "Which callouts the list reads. mint (default, same as omitted) = the coin's own holders. pairs = the coin's callout rows plus every coin whose launch quote is this mint, each row tagged with its coinMint and the page's coins served in `coins`; requires withThesis=true and sortBy TOP, LATEST or CLOSED_PNL, and rejects chain, dustFloorUsd and pageToken", "type": "string", "enum": [ "mint", "pairs" ] } } ], "responses": { "200": { "description": "Get the users holding a position in a mint", "content": { "application/json": { "schema": { "type": "object", "properties": { "positions": { "type": "array", "items": { "type": "object", "properties": { "coinMint": { "type": "string" }, "chainId": { "nullable": true, "description": "Positions are keyed (wallet, mint, chain), so userId alone never keys a row. Typed nullable so older readers still parse", "type": "number" }, "chain": { "description": "CAIP-2 chain of an hlcore row (hlcore:mainnet), a NEAR row (near:mainnet, walletAddress the NEAR account id), a Starknet row (starknet:SN_MAIN, coinMint and walletAddress 0x + 64 lowercase hex) or a TON row (ton:-239, coinMint the EQ jetton master, walletAddress the TON wallet); absent on every other spot row", "type": "string" }, "assetClass": { "description": "ASSET_CLASS_PERPETUAL on hlcore rows; absent on every spot row", "type": "string", "enum": [ "ASSET_CLASS_TOKEN", "ASSET_CLASS_PERPETUAL" ] }, "perp": { "description": "hlcore rows only: the HyperCore position (live while open, the frozen close once closed); null when the position has no side. On these rows amountHeld = |size|, costBasisUsd = margin (null when unknown), amountBought = |size|, amountBoughtUsd = |size| x entry, pnlPercentage = ROE", "nullable": true, "type": "object", "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "leverageBps": { "type": "number" }, "entryPx": { "nullable": true, "type": "number" }, "markPx": { "nullable": true, "type": "number" }, "closePx": { "nullable": true, "description": "The frozen close price; null while the position is open", "type": "number" }, "closedAt": { "nullable": true, "description": "ISO instant of the close; null while the position is open", "type": "string" }, "positionValueUsd": { "nullable": true, "type": "number" }, "marginUsd": { "nullable": true, "type": "number" }, "equityUsd": { "nullable": true, "description": "Account equity (USD) behind the position.", "type": "number" }, "stateAsOf": { "nullable": true, "description": "ISO instant of the clearinghouse state behind these figures", "type": "string" } }, "required": [ "side", "leverageBps", "entryPx", "markPx", "closePx", "closedAt", "positionValueUsd", "marginUsd", "equityUsd", "stateAsOf" ], "additionalProperties": false }, "userId": { "type": "string", "description": "Empty string for wallet-only holders with no registry profile" }, "userName": { "type": "string", "description": "Empty string for wallet-only holders with no registry profile" }, "profileImage": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "description": "The chain-correct HOLDING wallet, not the profile's canonical wallet; EVM addresses are scrubbed to SVM before serving", "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "resolvedAvatarDecoration": { "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border. Treat absent as null.", "nullable": true, "type": "string" }, "xUsername": { "nullable": true, "type": "string" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad row: route the author press on userId + accountKind, never the wallet" }, "amountHeld": { "type": "number" }, "pnlUsd": { "nullable": true, "type": "number" }, "pnlPercentage": { "nullable": true, "type": "number" }, "realizedPnlUsd": { "type": "number", "description": "pnlUsd = realizedPnlUsd + read-time unrealized" }, "costBasisAmount": { "type": "number", "description": "Net cost basis; avg entry = costBasisUsd / costBasisAmount" }, "costBasisUsd": { "nullable": true, "type": "number" }, "amountBoughtUsd": { "nullable": true, "description": "Lifetime buy total, never reduced by sells", "type": "number" }, "amountBought": { "nullable": true, "type": "number" }, "callout": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Shared_fceda4efe6cd" } ] }, "profile": { "description": "Present only when includeProfile=true, null there for wallet-only holders with no profile", "nullable": true, "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "bio": { "type": "string" }, "profileImageUrl": { "type": "string" }, "headerImageUrl": { "type": "string" }, "followerCount": { "type": "number" }, "followingCount": { "type": "number" }, "createdAt": { "nullable": true, "type": "string" }, "updatedAt": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "socials": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "username": { "type": "string" }, "linkedAt": { "nullable": true, "type": "string" } }, "required": [ "provider", "username", "linkedAt" ], "additionalProperties": false } }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true. The verified state itself is isVerified." }, "resolvedAvatarDecoration": { "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border. Treat absent as null.", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "PERSON", "GROUP" ] }, "memberCount": { "type": "number" }, "membershipPolicy": { "nullable": true, "type": "string", "enum": [ "INVITE" ] }, "groupBadges": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "role": { "type": "string" } }, "required": [ "groupId", "username", "profileImageUrl", "role" ], "additionalProperties": false } }, "generatedMedia": { "nullable": true, "type": "object", "properties": { "pnlLoop": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" } }, "required": [ "uid", "durationSeconds" ], "additionalProperties": false }, "replayIntro": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" }, "fireAt": { "type": "number" } }, "required": [ "uid", "durationSeconds", "fireAt" ], "additionalProperties": false } }, "required": [ "pnlLoop" ], "additionalProperties": false }, "isPumpUser": { "description": "false = unclaimed shell: an identity minted when someone followed an outside wallet that never signed in, served under a generated username. Render it as a wallet (address or the viewer’s wallet label), never as an account. Treat absent as true.", "type": "boolean" } }, "required": [ "userId", "username", "bio", "profileImageUrl", "headerImageUrl", "followerCount", "followingCount", "createdAt", "updatedAt", "walletAddress", "socials", "isVerified", "verifiedBadgeVisible", "kind", "memberCount", "membershipPolicy", "groupBadges", "generatedMedia" ], "additionalProperties": false }, "recommendationId": { "description": "RANKED path only: the ranking response id, the join key for impression/action attribution. Absent — never null — on every other sort", "type": "string" }, "recommendationRank": { "description": "This row's 1-based rank in that RANKED ranking response", "type": "number" }, "lowQuality": { "description": "Clients roll tagged rows up behind a show-more row. Absent when no verdict is available", "type": "boolean" } }, "required": [ "coinMint", "chainId", "userId", "userName", "profileImage", "walletAddress", "isVerified", "verifiedBadgeVisible", "xUsername", "accountKind", "amountHeld", "pnlUsd", "pnlPercentage", "realizedPnlUsd", "costBasisAmount", "costBasisUsd", "amountBoughtUsd", "amountBought", "callout" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "LATEST/TOP/LOWEST_ENTRY count the mint's open holders. sortBy=CLOSED_PNL counts the closed holders that have a callout for this mint, and is INFORMATIONAL ONLY — do not page on it: page on hasMore. scope=pairs counts the in-scope callout rows (the coin and its pairs), exact and pageable." }, "hasMore": { "type": "boolean", "description": "Whether another page exists. Offset sorts (TOP/LATEST/LOWEST_ENTRY/CLOSED_PNL, and every scope=pairs sort) derive it from totalCount; RANKED sets it from nextPageToken. Always false on an empty page. On a thesis-filtered list it may still be true for the last non-empty page, in which case the next page comes back empty with hasMore false — so following hasMore alone costs at most one empty request, never an endless walk" }, "coins": { "description": "scope=pairs only: lean coin per distinct coinMint on the page; absent when the verdict gate hid the coin", "type": "object", "additionalProperties": { "type": "object", "properties": { "name": { "nullable": true, "type": "string" }, "symbol": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" }, "imageBackdrop": { "description": "Surface to paint behind imageUri when it is a bare mark on transparency: light for a dark mark, dark for a light one. null = paint the image as-is (an opaque tile, an unassessed image, no image, or any non-perp coin). Absent on routes that do not serve perp coin cards", "nullable": true, "type": "string", "enum": [ "light", "dark" ] }, "marketCapUsd": { "nullable": true, "type": "number" }, "totalSupply": { "nullable": true, "description": "UI-normalized supply (raw / 10^decimals) on the basis marketCapUsd is computed on: circulating supply when an EVM record carries one (it may exceed total), else total supply — implied unit price = marketCapUsd / totalSupply; null means do not derive a price from marketCapUsd", "type": "number" }, "protocol": { "nullable": true, "description": "An EVM coin's launchpad identity", "type": "string" }, "platform": { "nullable": true, "description": "Solana launchpad platform (`bonk`, `bags`, `believe`); null on EVM rows", "type": "string" }, "program": { "nullable": true, "description": "Solana program slug (`pump`, `meteora_dbc`, `raydium_launchpad`); null on EVM rows", "type": "string" }, "collectible": { "description": "ASSET_CLASS_NFT_LIKE rows only: the card (identity, grade, mark, insured value, buyback, listing); absent on every token row", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false } }, "required": [ "name", "symbol", "imageUri", "marketCapUsd", "totalSupply", "protocol", "platform", "program" ], "additionalProperties": false } }, "nextPageToken": { "description": "RANKED only; absent = end of list or no session_id", "type": "string" } }, "required": [ "positions", "totalCount", "hasMore" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/moderation/ban/address/{address}": { "get": { "operationId": "get_moderation_ban_address_by_address", "tags": [ "moderation.read" ], "summary": "Check whether a wallet address is banned", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "moderation.read", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Check whether a wallet address is banned", "content": { "application/json": { "schema": { "type": "boolean", "description": "true while the address is banned (a permanent ban, or a temporary ban that has not expired); false otherwise. Never null." } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/payouts/leaderboard": { "get": { "operationId": "get_payouts_leaderboard", "tags": [ "leaderboards.read" ], "summary": "The confirmed-payout leaderboard", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "leaderboards.read", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "period", "in": "query", "required": false, "schema": { "description": "Absent = all-time", "type": "string", "enum": [ "1d", "1w", "1m" ] } } ], "responses": { "200": { "description": "The confirmed-payout leaderboard (top-500 board, paged; all-time or a rolling 1d/1w/1m window via period) plus the in-window earner count. Per-row follow state is viewer-relative: present on a signed-in read, absent on the API host", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "number", "description": "1-based rank in the confirmed-total ordering, consistent across pages" }, "userId": { "nullable": true, "description": "Owning user's id (UUID); null when no user row claims the wallet — user-less earners stay visible as bare-wallet rows", "type": "string" }, "username": { "nullable": true, "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean", "description": "Manually-set verified badge; always false on bare-wallet rows" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true; true on bare-wallet rows" }, "twitterId": { "nullable": true, "type": "string" }, "twitterUrl": { "nullable": true, "description": "Rename-stable X profile URL (x.com/i/user/{id}); null when no linked X account", "type": "string" }, "wallets": { "type": "array", "items": { "type": "string" }, "description": "Every wallet the entry's confirmed payouts paid, in sorted order — so an EVM address can come first" }, "totalPaidUsdc": { "type": "number", "description": "Confirmed-only paid total in whole USDC — in-flight/failed/rejected never count" }, "payoutCount": { "type": "number" }, "lastPaidAt": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "description": "The owning account's canonical Solana wallet; null on bare-wallet and EVM-only rows", "type": "string" }, "isViewer": { "description": "Viewer-relative: present only on a signed-in read, never on the API host", "type": "boolean" }, "viewerFollows": { "description": "Whether the viewer follows this earner (by userId); false on the viewer's own row, null when unknown or when there is nothing to follow", "nullable": true, "type": "boolean" } }, "required": [ "rank", "userId", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible", "twitterId", "twitterUrl", "wallets", "totalPaidUsdc", "payoutCount", "lastPaidAt", "walletAddress" ], "additionalProperties": false } }, "totalEarners": { "type": "number", "description": "Total distinct earners on the whole board (not capped), independent of the served page" }, "generatedAt": { "nullable": true, "description": "At most ~60s old)", "type": "string" } }, "required": [ "entries", "totalEarners", "generatedAt" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "The confirmed-payout leaderboard (top-500 board, paged; all-time or a rolling 1d/1w/1m window via period) plus the in-window earner count. Per-row follow state is viewer-relative: present on a signed-in read, absent on the API host" } }, "/pnl-leaderboard": { "get": { "operationId": "get_pnl_leaderboard", "tags": [ "leaderboards.read" ], "summary": "Get the PNL leaderboard for a period", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "leaderboards.read", "parameters": [ { "name": "period", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "realized", "unrealized", "combined" ] } }, { "name": "positionsLimit", "in": "query", "required": false, "schema": { "description": "Top positions returned per row as icons (default 3; values above 5 clamp to 5; 0 = count only).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Rows served; default and ceiling 100", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Get the PNL leaderboard for a period. `viewer` (the caller's own rank off the same board snapshot) is viewer-relative: present on a signed-in read, absent on the API host", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "number" }, "pnlSol": { "type": "number" }, "pnlUsd": { "type": "number" }, "pnlPercent": { "type": "number" }, "buySpendSol": { "type": "number" }, "lastRefreshedAtMs": { "type": "number" }, "realizedPnlSol": { "type": "number" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlSol": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "positionsCount": { "type": "number", "description": "The row's whole holdings count, never sliced by positionsLimit" }, "topPositions": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri" ], "additionalProperties": false }, "description": "Largest fresh USD value first, sliced to positionsLimit" }, "walletAddress": { "type": "string" }, "username": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "xUsername": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "userId": { "nullable": true, "description": "Null when the profile lookup missed", "type": "string" }, "isViewer": { "description": "Present only on a response with an authenticated viewer", "type": "boolean" }, "viewerFollows": { "description": "Null means unknown or nothing to follow", "nullable": true, "type": "boolean" } }, "required": [ "rank", "pnlSol", "pnlUsd", "pnlPercent", "buySpendSol", "lastRefreshedAtMs", "realizedPnlSol", "realizedPnlUsd", "unrealizedPnlSol", "unrealizedPnlUsd", "positionsCount", "topPositions", "walletAddress", "username", "profileImage", "xUsername", "isVerified", "verifiedBadgeVisible", "userId" ], "additionalProperties": false } }, "periodType": { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] } ] }, "periodLabel": { "type": "string" }, "windowStartSec": { "type": "number" }, "viewer": { "description": "The caller's own rank, checked against this same board snapshot (a row the board lists wins). Viewer-relative: present only on a signed-in read (an invalid token reads as anonymous); the key is omitted, never null, on an anonymous read and on the API host.", "type": "object", "properties": { "found": { "type": "boolean" }, "projectedRank": { "type": "number" }, "onBoard": { "type": "boolean" }, "approximate": { "type": "boolean" }, "entry": { "type": "object", "properties": { "rank": { "type": "number" }, "pnlSol": { "type": "number" }, "pnlUsd": { "type": "number" }, "pnlPercent": { "type": "number" }, "buySpendSol": { "type": "number" }, "lastRefreshedAtMs": { "type": "number" }, "realizedPnlSol": { "type": "number" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlSol": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "positionsCount": { "type": "number", "description": "The row's whole holdings count, never sliced by positionsLimit" }, "topPositions": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri" ], "additionalProperties": false }, "description": "Largest fresh USD value first, sliced to positionsLimit" }, "walletAddress": { "type": "string" }, "username": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "xUsername": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "userId": { "nullable": true, "description": "Null when the profile lookup missed", "type": "string" } }, "required": [ "rank", "pnlSol", "pnlUsd", "pnlPercent", "buySpendSol", "lastRefreshedAtMs", "realizedPnlSol", "realizedPnlUsd", "unrealizedPnlSol", "unrealizedPnlUsd", "positionsCount", "topPositions", "walletAddress", "username", "profileImage", "xUsername", "isVerified", "verifiedBadgeVisible", "userId" ], "additionalProperties": false }, "totalRanked": { "type": "number" }, "periodLabel": { "type": "string" }, "windowStartSec": { "type": "number" } }, "required": [ "found", "projectedRank", "onBoard", "approximate", "totalRanked", "periodLabel", "windowStartSec" ], "additionalProperties": false } }, "required": [ "entries", "periodType", "periodLabel", "windowStartSec" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Get the PNL leaderboard for a period. `viewer` (the caller's own rank off the same board snapshot) is viewer-relative: present on a signed-in read, absent on the API host" } }, "/pnl-leaderboard/follow-suggestions": { "get": { "operationId": "get_pnl_leaderboard_follow_suggestions", "tags": [ "graph.read" ], "summary": "Get follow suggestions sampled from the PNL leaderboard", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "description": "Default 5, capped at 25", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Get follow suggestions sampled from the PNL leaderboard", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "number" }, "pnlSol": { "type": "number" }, "pnlUsd": { "type": "number" }, "pnlPercent": { "type": "number" }, "buySpendSol": { "type": "number" }, "lastRefreshedAtMs": { "type": "number" }, "realizedPnlSol": { "type": "number" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlSol": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "positionsCount": { "type": "number", "description": "The row's whole holdings count, never sliced by positionsLimit" }, "topPositions": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri" ], "additionalProperties": false }, "description": "Largest fresh USD value first, sliced to positionsLimit" }, "walletAddress": { "type": "string" }, "username": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "xUsername": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "userId": { "nullable": true, "description": "Null when the profile lookup missed", "type": "string" }, "isViewer": { "description": "Present only on a response with an authenticated viewer", "type": "boolean" }, "viewerFollows": { "description": "Null means unknown or nothing to follow", "nullable": true, "type": "boolean" } }, "required": [ "rank", "pnlSol", "pnlUsd", "pnlPercent", "buySpendSol", "lastRefreshedAtMs", "realizedPnlSol", "realizedPnlUsd", "unrealizedPnlSol", "unrealizedPnlUsd", "positionsCount", "topPositions", "walletAddress", "username", "profileImage", "xUsername", "isVerified", "verifiedBadgeVisible", "userId" ], "additionalProperties": false } }, "periodLabel": { "type": "string" }, "windowStartSec": { "type": "number" } }, "required": [ "entries", "periodLabel", "windowStartSec" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/pnl-leaderboard/groups": { "get": { "operationId": "get_pnl_leaderboard_groups", "tags": [ "leaderboards.read" ], "summary": "Get the group PNL leaderboard for a period", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "leaderboards.read", "parameters": [ { "name": "period", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "realized", "unrealized", "combined" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Rows served (default and ceiling 100; out-of-range values clamp).", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "positionsLimit", "in": "query", "required": false, "schema": { "description": "Top positions returned per row as icons (default 3; values above 5 clamp to 5; 0 = count only).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Get the group PNL leaderboard for a period", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "number" }, "pnlSol": { "type": "number" }, "pnlUsd": { "type": "number" }, "pnlPercent": { "type": "number" }, "buySpendSol": { "type": "number" }, "lastRefreshedAtMs": { "type": "number" }, "realizedPnlSol": { "type": "number" }, "realizedPnlUsd": { "type": "number" }, "unrealizedPnlSol": { "type": "number" }, "unrealizedPnlUsd": { "type": "number" }, "positionsCount": { "type": "number", "description": "The row's whole holdings count, never sliced by positionsLimit" }, "topPositions": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "type": "number" }, "symbol": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" } }, "required": [ "mint", "chainId", "symbol", "name", "imageUri" ], "additionalProperties": false }, "description": "Largest fresh USD value first, sliced to positionsLimit" }, "groupId": { "type": "string" }, "memberCount": { "type": "number" }, "membersCounted": { "type": "number" }, "username": { "nullable": true, "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" } }, "required": [ "rank", "pnlSol", "pnlUsd", "pnlPercent", "buySpendSol", "lastRefreshedAtMs", "realizedPnlSol", "realizedPnlUsd", "unrealizedPnlSol", "unrealizedPnlUsd", "positionsCount", "topPositions", "groupId", "memberCount", "membersCounted", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible" ], "additionalProperties": false } }, "periodType": { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] } ] }, "periodLabel": { "type": "string" }, "windowStartSec": { "type": "number" }, "totalRanked": { "type": "number" } }, "required": [ "entries", "periodType", "periodLabel", "windowStartSec", "totalRanked" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/pnl-leaderboard/onboarding-suggestions": { "get": { "operationId": "get_pnl_leaderboard_onboarding_suggestions", "tags": [ "graph.read" ], "summary": "Get the scored, sampled follow suggestions for the…", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "description": "Default 10, capped at 25", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Get the scored, sampled follow suggestions for the mobile onboarding step", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "userId": { "nullable": true, "description": "Null when the profile lookup missed", "type": "string" }, "username": { "type": "string", "description": "Never null — a row with no username is dropped, not blanked" }, "profileImage": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "pnlUsd": { "nullable": true, "description": "The account's live 24h PnL in USD, the same figure the PnL board shows — read off that board when the account is on it, otherwise from the portfolio summary GET /pnl-leaderboard/rank uses for an off-board row. NOT the scored table's pnl_usd_24h, which is net cash flow and disagrees with the board by tens of thousands of dollars. Null means only that the lookup failed or timed out; it is rare, and the row is still a valid suggestion, so render it without the amount rather than dropping it.", "type": "number" }, "followers": { "nullable": true, "description": "Follower count carried through from profile enrichment; null on the degraded path, where the board rows carry none", "type": "number" }, "isViewer": { "description": "Present only on a response with an authenticated viewer", "type": "boolean" }, "viewerFollows": { "description": "Null means unknown or nothing to follow", "nullable": true, "type": "boolean" } }, "required": [ "walletAddress", "userId", "username", "profileImage", "isVerified", "verifiedBadgeVisible", "pnlUsd", "followers" ], "additionalProperties": false } } }, "required": [ "entries" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Get the scored, sampled follow suggestions for the mobile onboarding step" } }, "/pnl-leaderboard/positions": { "get": { "operationId": "get_pnl_leaderboard_positions", "tags": [ "leaderboards.read" ], "summary": "Get the PNL position leaderboard for a period", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "leaderboards.read", "parameters": [ { "name": "period", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "daily", "weekly" ] } }, { "name": "includeFollowedHolders", "in": "query", "required": false, "schema": { "description": "Opt-in: attach the followed-holders facepile per entry. Viewer-relative: the API host has no viewer, so followedHolders is null there. Off by default.", "type": "boolean" } }, { "name": "followedHoldersLimit", "in": "query", "required": false, "schema": { "description": "Followed holders returned per entry (default 3; values above 10 clamp to 10).", "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Rows served; default and ceiling 25", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Get the PNL position leaderboard for a period", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "number" }, "walletAddress": { "type": "string" }, "coinMint": { "type": "string" }, "pnlUsd": { "nullable": true, "type": "number" }, "pnlPercentage": { "nullable": true, "type": "number" }, "amountHeld": { "nullable": true, "type": "number" }, "isExited": { "nullable": true, "type": "boolean" }, "costBasisAmount": { "nullable": true, "type": "number" }, "costBasisUsd": { "nullable": true, "type": "number" }, "amountBoughtUsd": { "nullable": true, "type": "number" }, "amountBought": { "nullable": true, "type": "number" }, "realizedPnlUsd": { "nullable": true, "description": "Raw stored realized leg, NOT transfer-adjusted", "type": "number" }, "avgEntryMcapUsd": { "nullable": true, "type": "number" }, "callout": { "type": "object", "properties": { "calloutId": { "type": "string" }, "chain": { "description": "CAIP-2 chain of the called-out ref (hlcore:mainnet for a perp, ton:-239 for a TON callout, near:mainnet for a NEAR callout, starknet:SN_MAIN for a Starknet callout); null when the row carries none", "nullable": true, "type": "string" }, "assetClass": { "description": "Asset class of the called-out position: ASSET_CLASS_PERPETUAL on an hlcore (HyperCore perp) callout, ASSET_CLASS_NFT_LIKE on a card callout (collectible set), ASSET_CLASS_TOKEN on every other row, chainless ones included", "type": "string", "enum": [ "ASSET_CLASS_TOKEN", "ASSET_CLASS_PERPETUAL", "ASSET_CLASS_NFT_LIKE" ] }, "collectible": { "description": "ASSET_CLASS_NFT_LIKE callouts only: the card (identity, grade, mark, insured value, buyback, listing); multiple is then the card mark over calloutPrice. Absent on every token callout", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false }, "perp": { "description": "Set only on a perp callout, whose calledOutAtMcap is 0", "nullable": true, "type": "object", "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "leverageBps": { "type": "number" }, "entryPx": { "nullable": true, "type": "number" }, "closePx": { "nullable": true, "type": "number" }, "closedAt": { "nullable": true, "type": "string" } }, "required": [ "side", "leverageBps", "entryPx", "closePx", "closedAt" ], "additionalProperties": false }, "calledOutAtMcap": { "type": "number", "description": "USD market cap when the callout was made." }, "multiple": { "type": "number", "description": "Current multiplier (live price vs callout price), 1 for an untracked callout; maxMultiplier is the all-time peak" }, "thesis": { "nullable": true, "type": "string" }, "mediaUrl": { "nullable": true, "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "calloutTimestamp": { "nullable": true, "type": "string" }, "likes": { "type": "number" }, "hasLiked": { "nullable": true, "description": "null until a viewer is known", "type": "boolean" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "createdAt": { "nullable": true, "type": "string" }, "likeCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "parentMessageId": { "nullable": true, "type": "string" }, "repostCount": { "type": "number" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" } }, "required": [ "id", "content", "createdAt", "likeCount", "mediaUrl", "parentMessageId", "repostCount" ], "additionalProperties": false }, "description": "Author updates (the author's own replies), newest first; empty when the route does not include them" }, "updateCount": { "type": "number" }, "commentCount": { "type": "number", "description": "Live replies from users OTHER than the callout author" }, "replyCount": { "type": "number", "description": "All live replies, updates included" }, "maxMultiplier": { "nullable": true, "type": "number" }, "maxMultiplierAt": { "nullable": true, "type": "string" }, "calloutPrice": { "type": "number", "description": "Token price when the callout was made; 0 for callouts predating price capture, never null" }, "repostCount": { "type": "number", "description": "Live plain reposts of the callout itself; quotes do not count" }, "quoteCount": { "type": "number" }, "hasReposted": { "nullable": true, "description": "null until a viewer is known", "type": "boolean" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" }, "quotedCalloutId": { "description": "Set with quotedCallout null means \"quote of an unavailable callout\", never \"no quote\"", "nullable": true, "type": "string" }, "actingUserId": { "nullable": true, "description": "Squad callouts: the admin who posted on the squad's behalf; presence is not the squad discriminator, the author's kind is", "type": "string" }, "actingUser": { "nullable": true, "description": "actingUserId set with actingUser null means \"unresolved\", not \"absent\"", "type": "object", "properties": { "userId": { "type": "string" }, "userName": { "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "xUsername": { "nullable": true, "type": "string" } }, "required": [ "userId", "userName", "profileImage", "walletAddress", "isVerified", "verifiedBadgeVisible", "xUsername" ], "additionalProperties": false }, "quotedCallout": { "$ref": "#/components/schemas/Shared_43ac27dd04b0" } }, "required": [ "calloutId", "calledOutAtMcap", "multiple", "thesis", "mediaUrl", "calloutTimestamp", "likes", "hasLiked", "updates", "updateCount", "commentCount", "replyCount", "maxMultiplier", "maxMultiplierAt", "calloutPrice", "repostCount", "quoteCount", "hasReposted", "actingUserId", "actingUser", "quotedCallout" ], "additionalProperties": false, "description": "Never null — a row without a callout is dropped from the board" }, "leaderboardPnlUsd": { "type": "number" }, "heldValueSol": { "type": "number" }, "valueUsd": { "nullable": true, "type": "number" }, "lastRefreshedAtMs": { "type": "number" }, "username": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "xUsername": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true", "type": "boolean" }, "userId": { "description": "Profile fields are present only when the board had at least one wallet to enrich", "nullable": true, "type": "string" }, "followedHolders": { "description": "Present only when the request opted in via includeFollowedHolders; null when there is no viewer or the overlay degraded", "nullable": true, "type": "object", "properties": { "holders": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "resolvedAvatarDecoration": { "nullable": true, "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border. Always null on a facepile whose holders carry no profile (coin-card facepiles).", "type": "string" }, "walletAddress": { "nullable": true, "description": "Null when the account has none. Never an EVM address (an EVM value is mapped to its SVM wallet or dropped to null)", "type": "string" } }, "required": [ "userId", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible", "resolvedAvatarDecoration", "walletAddress" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Size of the whole followed-holder set for the coin, not just the embedded page — the \"and N others\" figure" } }, "required": [ "holders", "totalCount" ], "additionalProperties": false }, "isViewer": { "description": "Present only on a response with an authenticated viewer", "type": "boolean" }, "viewerFollows": { "description": "Null means unknown or nothing to follow", "nullable": true, "type": "boolean" } }, "required": [ "rank", "walletAddress", "coinMint", "pnlUsd", "pnlPercentage", "amountHeld", "isExited", "costBasisAmount", "costBasisUsd", "amountBoughtUsd", "amountBought", "realizedPnlUsd", "avgEntryMcapUsd", "callout", "leaderboardPnlUsd", "heldValueSol", "valueUsd", "lastRefreshedAtMs" ], "additionalProperties": false } }, "periodLabel": { "type": "string" }, "windowStartSec": { "type": "number" }, "totalRanked": { "type": "number" } }, "required": [ "entries", "periodLabel", "windowStartSec", "totalRanked" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/pnl-leaderboard/top-trader-trades/{mint}": { "get": { "operationId": "get_pnl_leaderboard_top_trader_trades_by_mint", "tags": [ "leaderboards.read" ], "summary": "A coin's trades from accounts ranked in the top 50 of…", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "leaderboards.read", "parameters": [ { "name": "mint", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chainId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "to", "in": "query", "required": false, "schema": { "description": "Serve trades at or before this instant (epoch ms); omitted = now. Honoured only while the server pages (see `page`).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Continuation from the previous response's page.nextCursor; omit for the newest page", "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Trades per page; default and ceiling 500", "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "A coin's trades from accounts ranked in the top 50 of any PNL leaderboard period, across all their wallets on either chain (chart marks)", "content": { "application/json": { "schema": { "type": "object", "properties": { "mint": { "type": "string" }, "traders": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "walletAddress": { "type": "string", "description": "The wallet ranked on the board(s)" }, "username": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "bestRank": { "type": "number", "description": "Best (lowest) rank across the boards the wallet appears on" }, "periods": { "type": "array", "items": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "description": "Boards (top 50) the wallet ranks on, in period order" }, "tradingWallets": { "type": "array", "items": { "type": "string" }, "description": "The distinct walletAddress values of this trader's served rows, sorted (all base58)" }, "tradeCount": { "type": "number" } }, "required": [ "userId", "walletAddress", "username", "profileImage", "isVerified", "verifiedBadgeVisible", "bestRank", "periods", "tradingWallets", "tradeCount" ], "additionalProperties": false }, "description": "Only top traders with at least one served trade on the coin, best rank first" }, "trades": { "type": "array", "items": { "type": "object", "properties": { "tx": { "type": "string", "description": "Transaction signature — not unique by itself: each fill of a multi-fill transaction is its own row" }, "isBuy": { "type": "boolean" }, "timestamp": { "nullable": true, "type": "string" }, "amountUsd": { "nullable": true, "type": "number" }, "baseAmount": { "nullable": true, "description": "Token amount in UI units (decimals applied)", "type": "number" }, "priceUsd": { "nullable": true, "type": "number" }, "mint": { "type": "string" }, "chainId": { "type": "number" }, "walletAddress": { "type": "string", "description": "Always base58: an SVM fill carries the wallet that filled (one of its trader's tradingWallets, not necessarily the board wallet); an EVM fill is served under its trader's board wallet — an EVM wallet never reaches a client" }, "userId": { "type": "string", "description": "Joins traders." }, "slotIndexId": { "type": "string", "description": "26-digit zero-padded chain-ordered id — the row's stable identity and same-second tiebreak" }, "amountSol": { "nullable": true, "description": "Native-currency notional of the fill; null when the source carries none", "type": "number" } }, "required": [ "tx", "isBuy", "timestamp", "amountUsd", "baseAmount", "priceUsd", "mint", "chainId", "walletAddress", "userId", "slotIndexId", "amountSol" ], "additionalProperties": false }, "description": "Every returned trader's trades on the coin, newest first; the newest `limit` (default 500) across all of them" }, "boardsBuiltAtMs": { "type": "number", "description": "Build time of the OLDEST board in the union — how fresh \"top trader\" is at worst (a held board keeps its stamp)" }, "generatedAtMs": { "type": "number" }, "page": { "nullable": true, "description": "Present only when the server honoured to/cursor/limit — the paging capability marker. Null means the response is the whole set: keep the single-fetch behaviour. A degraded read is served as an empty page with page null and a 200, never a 5xx; on a 429 back off and keep the last good set.", "type": "object", "properties": { "nextCursor": { "nullable": true, "description": "Pass as `cursor` for the trades older than this page; null = nothing older", "type": "string" }, "to": { "nullable": true, "description": "The `to` this page was served for; null = now", "type": "number" }, "limit": { "type": "number" } }, "required": [ "nextCursor", "to", "limit" ], "additionalProperties": false } }, "required": [ "mint", "traders", "trades", "boardsBuiltAtMs", "generatedAtMs", "page" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "A coin's trades from accounts ranked in the top 50 of any PNL leaderboard period, across all their wallets on either chain (chart marks)" } }, "/portfolio-summary": { "get": { "operationId": "get_portfolio_summary", "tags": [ "positions.read" ], "summary": "Merged Solana+EVM portfolio PnL for a wallet…", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN", "API_USER_REQUIRED" ], "x-api-scope": "positions.read", "parameters": [ { "name": "user", "in": "query", "required": false, "schema": { "description": "Identity to serve: Solana wallet, EVM wallet, username, a NEAR account id (served its NEAR realized PnL alone) or a Starknet address 0x+64 (served its Starknet realized PnL alone). Required when calling with an API key (api.pump.fun); optional with a session, where omitted = the signed-in user. Omitted with an API key answers 400 API_USER_REQUIRED.", "type": "string", "maxLength": 66 } }, { "name": "period", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "1d", "1w", "1m", "all" ], "description": "PnL window: 1d / 1w / 1m trail now; all = from the data floor 2026-07-01T00:00Z on every chain but NEAR and Starknet (all carries no NEAR or Starknet realized leg; a NEAR account id or Starknet address answers all with null pnl and realizedPnl). Every period marks the bags held at its start (markHeld)." } }, { "name": "periods", "in": "query", "required": false, "schema": { "description": "Comma-separated periods, e.g. `1d,1w,1m,all` (1-4, duplicates collapsed, order kept): each is served under `windows` beside the top-level `period` body. Omitted = no `windows`.", "type": "string", "maxLength": 15, "pattern": "^(1d|1w|1m|all)(,(1d|1w|1m|all))*$" } }, { "name": "fresh", "in": "query", "required": false, "schema": { "description": "Owner refresh (1/true): applies only to a signed-in owner of the served wallet, within 60 fresh reads per minute, whose body is then refilled past every cache and answers cache.fresh: true. Anyone else, every API-host caller included, is served the cached body, never a 429", "type": "boolean" } }, { "name": "holdings", "in": "query", "required": false, "schema": { "description": "Serve `holdings` (1/true): the balance leg's top 25 priced rows; omitted = no `holdings` key", "type": "boolean" } } ], "responses": { "200": { "description": "Merged Solana+EVM portfolio PnL for a wallet, username, or the authenticated user; a group id or group username serves the squad aggregate over active members", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "number" }, "to": { "type": "number" }, "pnl": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "realizedPnl": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "unrealizedPnl": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "percentage": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false, "description": "The usd leg rebased onto the account total; the sol leg is not rebased. The usd leg is null when a NEAR realized leg is folded into pnl: the NEAR leg carries no capital to rebase it on" }, "totalBuySpend": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "heldOpenValue": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "maxCapitalDeployed": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "equityAtWindowStart": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "missingPriceMints": { "type": "array", "items": { "type": "string" } }, "tradePercentage": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false, "description": "Capital-deployed percentage. The usd leg is null when a NEAR realized leg is folded into pnl: the NEAR leg carries no capital deployed" }, "totalValueUsd": { "nullable": true, "type": "number" }, "cache": { "type": "object", "properties": { "filledAtMs": { "type": "number", "description": "Unix milliseconds the served body was computed" }, "ttlSeconds": { "type": "number", "description": "Seconds past filledAtMs before a poll can see a different body; a poll sooner than that returns these bytes" }, "fresh": { "description": "true = this body was refilled for its owner's `fresh` read; absent otherwise", "type": "boolean" } }, "required": [ "filledAtMs", "ttlSeconds" ], "additionalProperties": false, "description": "Freshness of the memoized body: derive the poll interval from ttlSeconds and never poll faster" }, "wallet": { "type": "string" }, "tokenCount": { "nullable": true, "description": "Tokens in the window; null when the PnL leg was unavailable and the balance leg serves alone (every PnL leg null, totalValueUsd served)", "type": "number" }, "solPriceUsd": { "nullable": true, "type": "number" }, "nativeBalanceSol": { "nullable": true, "type": "number" }, "computedAt": { "type": "number", "description": "Epoch ms the served body was built; a cache hit carries the stored stamp" }, "evmAddress": { "description": "The linked EVM wallet, lowercased 0x; null = none linked; absent = the mapping lookup failed this request, keep the last-known value", "nullable": true, "type": "string" }, "windows": { "description": "Present only when `periods` is sent: one entry per requested period; null = that window was refused or failed, never zero legs. The `period` entry equals the top-level legs.", "type": "object", "additionalProperties": { "nullable": true, "type": "object", "properties": { "from": { "type": "number" }, "to": { "type": "number" }, "pnl": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "realizedPnl": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "unrealizedPnl": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "percentage": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false, "description": "The usd leg rebased onto the account total; the sol leg is not rebased. The usd leg is null when a NEAR realized leg is folded into pnl: the NEAR leg carries no capital to rebase it on" }, "totalBuySpend": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "heldOpenValue": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "maxCapitalDeployed": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "equityAtWindowStart": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "missingPriceMints": { "type": "array", "items": { "type": "string" } }, "tradePercentage": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false, "description": "Capital-deployed percentage. The usd leg is null when a NEAR realized leg is folded into pnl: the NEAR leg carries no capital deployed" } }, "required": [ "from", "to", "pnl", "realizedPnl", "unrealizedPnl", "percentage", "totalBuySpend", "heldOpenValue", "maxCapitalDeployed", "equityAtWindowStart", "missingPriceMints", "tradePercentage" ], "additionalProperties": false } }, "holdings": { "description": "Present only when `holdings` is sent: the balance leg's top N rows by computed value, N = reprice.depth (native excluded, linked EVM rows merged), off the same read as totalValueUsd; the tail is reprice.tailValueUsd; null = unavailable (including a body cached before holdings were stored)", "nullable": true, "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "string", "description": "Chain slug the row is held on" }, "mint": { "type": "string" }, "amount": { "type": "number", "description": "UI amount held" }, "priceUsd": { "type": "number", "description": "USD price the row was valued at, the one in the wallet's served total: the live price when repriced, else computedPriceUsd" }, "valueUsd": { "type": "number", "description": "amount x priceUsd" }, "marketCapUsd": { "nullable": true, "type": "number" }, "computedPriceUsd": { "description": "Absent when the body was filled outside the reprice", "type": "number" }, "contribUsd": { "description": "amount x computedPriceUsd: this row's share of the computed total", "type": "number" }, "computedPlane": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "string" } ], "x-open-enum": true }, "markUsd": { "description": "Null when the server held this row's PnL leg (spam, missing price, amount skew, no PnL row, no live price, or a failed pairs read); a number only when the served pnl legs moved on this row", "nullable": true, "type": "number" }, "markSource": { "nullable": true, "type": "string", "enum": [ "pnl_row", "ps_mark" ] }, "repriced": { "description": "true = priceUsd is the live pairs price and the totals moved with it", "type": "boolean" }, "livePlane": { "nullable": true, "type": "string", "enum": [ "content_pairs", "portfolio_pairs" ] } }, "required": [ "chain", "mint", "amount", "priceUsd", "valueUsd", "marketCapUsd" ], "additionalProperties": false } }, "reprice": { "description": "Present only when `holdings` is sent and the body was filled inside the reprice scope (every fill once portfolioSummaryPsHoldingsV2 is on, else the owner's fresh reads); null = holdings unavailable", "nullable": true, "type": "object", "properties": { "plane": { "type": "string", "enum": [ "content_pairs", "portfolio_pairs", "none" ], "description": "The live plane the rows were repriced on; none = no reprice ran" }, "mode": { "type": "string", "enum": [ "fill", "fresh" ], "description": "fill / fresh = applied on a wallet fill / an owner fresh fill" }, "asOf": { "type": "number", "description": "Epoch ms of the pairs read; a client tick older than asOf is stale for repriced rows" }, "depth": { "type": "number" }, "repricedRows": { "type": "number" }, "deltaTotalUsd": { "type": "number", "description": "Sum over repriced rows of amount x (live - computedPriceUsd)" }, "deltaPnlUsd": { "type": "number", "description": "Sum over repriced rows with a PnL mark, spam excluded, of amount x (live - markUsd); applied to pnl and unrealizedPnl" }, "tailValueUsd": { "nullable": true, "description": "Rows past the depth, at their computed price; 0 when every row was sent; null when a bucket it would absorb cannot be separated (identity.reasons.tailValueUsd)", "type": "number" }, "capSuspectUsd": { "type": "number", "description": "contribUsd of rows held at their computed price because the live price looks liquidity-capped" }, "unrepriced": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chain": { "type": "string" }, "reason": { "type": "string", "enum": [ "no_row", "unpriced", "cap_suspect", "no_evm_key", "over_cap_keys", "no_pnl_row", "mark_skew", "price_missing" ] }, "contribUsd": { "type": "number" }, "capValueUsd": { "type": "number" } }, "required": [ "mint", "chain", "reason", "contribUsd" ], "additionalProperties": false }, "description": "Up to 50 rows by contribUsd that stayed at their computed price (no_pnl_row: the Total repriced, the PnL leg not, no exact mark; mark_skew: the Total repriced, the PnL leg not, the trade row marks a different amount than the bag; price_missing: the engine booked no unrealized for the mint (missing_price_mints), so the PnL leg is not shifted)" }, "unrepricedUsd": { "type": "number", "description": "contribUsd of every row the Total did not reprice" }, "amountSkew": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "psAmount": { "type": "number" }, "ccAmount": { "type": "number" }, "basis": { "type": "string", "enum": [ "content", "pnl_row" ] } }, "required": [ "mint", "psAmount", "ccAmount", "basis" ], "additionalProperties": false } }, "spamExcludedRows": { "type": "number" }, "pnlUncoveredUsd": { "type": "object", "properties": { "1d": { "nullable": true, "type": "number" }, "1w": { "nullable": true, "type": "number" }, "1m": { "nullable": true, "type": "number" }, "all": { "nullable": true, "type": "number" } }, "required": [ "1d", "1w", "1m", "all" ], "additionalProperties": false, "description": "Per window: the unrealized leg no PnL row explains; null when the window was not served" }, "pnlPartial": { "type": "object", "properties": { "1d": { "type": "boolean" }, "1w": { "type": "boolean" }, "1m": { "type": "boolean" }, "all": { "type": "boolean" } }, "required": [ "1d", "1w", "1m", "all" ], "additionalProperties": false, "description": "Per window: true when pnlUncoveredUsd exceeds half the unrealized leg" }, "reason": { "nullable": true, "description": "Why no reprice ran (error, timeout, breaker_open, holdings_null, truncated); null when it ran", "type": "string" } }, "required": [ "plane", "mode", "asOf", "depth", "repricedRows", "deltaTotalUsd", "deltaPnlUsd", "tailValueUsd", "capSuspectUsd", "unrepriced", "unrepricedUsd", "amountSkew", "spamExcludedRows", "pnlUncoveredUsd", "pnlPartial", "reason" ], "additionalProperties": false }, "identity": { "description": "The named buckets between totalValueUsd and the holdings rows, beside reprice; a bucket the server cannot compute is null with a reason, never 0", "nullable": true, "type": "object", "properties": { "solUsd": { "nullable": true, "type": "number" }, "perpsUsd": { "nullable": true, "description": "The perps leg folded into the served total; null when either total is unknown", "type": "number" }, "evmNativeUsd": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "string" }, "usd": { "type": "number" } }, "required": [ "chain", "usd" ], "additionalProperties": false } }, "psHiddenUsd": { "nullable": true, "type": "number" }, "spamGroupedUsd": { "nullable": true, "type": "number" }, "hiddenStablesUsd": { "nullable": true, "type": "number" }, "subCentUsd": { "nullable": true, "type": "number" }, "rowsRemark": { "type": "string" }, "reasons": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Why each null bucket is null" } }, "required": [ "solUsd", "perpsUsd", "evmNativeUsd", "psHiddenUsd", "spamGroupedUsd", "hiddenStablesUsd", "subCentUsd", "rowsRemark", "reasons" ], "additionalProperties": false } }, "required": [ "from", "to", "pnl", "realizedPnl", "unrealizedPnl", "percentage", "totalBuySpend", "heldOpenValue", "maxCapitalDeployed", "equityAtWindowStart", "missingPriceMints", "tradePercentage", "totalValueUsd", "cache", "wallet", "tokenCount", "solPriceUsd", "nativeBalanceSol", "computedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "number" }, "to": { "type": "number" }, "pnl": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "realizedPnl": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "unrealizedPnl": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "percentage": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false, "description": "The usd leg rebased onto the account total; the sol leg is not rebased. The usd leg is null when a NEAR realized leg is folded into pnl: the NEAR leg carries no capital to rebase it on" }, "totalBuySpend": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "heldOpenValue": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "maxCapitalDeployed": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "equityAtWindowStart": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false }, "missingPriceMints": { "type": "array", "items": { "type": "string" } }, "tradePercentage": { "type": "object", "properties": { "sol": { "nullable": true, "type": "number" }, "usd": { "nullable": true, "type": "number" } }, "required": [ "sol", "usd" ], "additionalProperties": false, "description": "Capital-deployed percentage. The usd leg is null when a NEAR realized leg is folded into pnl: the NEAR leg carries no capital deployed" }, "totalValueUsd": { "nullable": true, "type": "number" }, "cache": { "type": "object", "properties": { "filledAtMs": { "type": "number", "description": "Unix milliseconds the served body was computed" }, "ttlSeconds": { "type": "number", "description": "Seconds past filledAtMs before a poll can see a different body; a poll sooner than that returns these bytes" }, "fresh": { "description": "true = this body was refilled for its owner's `fresh` read; absent otherwise", "type": "boolean" } }, "required": [ "filledAtMs", "ttlSeconds" ], "additionalProperties": false, "description": "Freshness of the memoized body: derive the poll interval from ttlSeconds and never poll faster" }, "groupId": { "type": "string" }, "memberCount": { "type": "number" }, "membersIncluded": { "type": "number" } }, "required": [ "from", "to", "pnl", "realizedPnl", "unrealizedPnl", "percentage", "totalBuySpend", "heldOpenValue", "maxCapitalDeployed", "equityAtWindowStart", "missingPriceMints", "tradePercentage", "totalValueUsd", "cache", "groupId", "memberCount", "membersIncluded" ], "additionalProperties": false } ], "description": "A wallet's windowed PnL also carries its derived NEAR account's realized PnL (an unavailable NEAR component is left out, never zero); a NEAR account id whose top-level period is unavailable answers 503 with degraded_lanes [trade_api.get_realized_pnl], and an unavailable window under `windows` is null. A Starknet address 0x+64 is served its Starknet realized PnL alone under the same rules" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "description": "Error payload on the envelope. Also the shared envelope at this status: a platform refusal, or a validation refusal whose `message` is a string array and whose `error` is the HTTP reason phrase.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "timestamp": { "type": "string" }, "path": { "type": "string" }, "error": { "type": "string", "enum": [ "API_CREDENTIAL_NOT_ALLOWED", "API_USER_REQUIRED" ] }, "message": { "type": "string" } }, "required": [ "statusCode", "timestamp", "path", "error", "message" ] }, { "$ref": "#/components/schemas/Error" } ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Merged Solana+EVM portfolio PnL for a wallet, username, or the authenticated user; a group id or group username serves the squad aggregate over active members" } }, "/portfolio-summary/balances": { "post": { "operationId": "post_portfolio_summary_balances", "tags": [ "positions.read" ], "summary": "Multichain balance totals for a page of wallets in one…", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "positions.read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "wallets": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$" }, "description": "Solana wallets (base58) to read balances for; linked EVM arms are aggregated server-side." }, "fresh": { "description": "Owner refresh for a signed-in viewer's own wallets on the page: read past every cache under GET /portfolio-summary's `fresh` rules; ignored for every other wallet, and on the API host", "type": "boolean" }, "holdings": { "description": "Serve `holdings` on the viewer's own wallets; every other wallet never carries the key", "type": "boolean" } }, "required": [ "wallets" ] } } } }, "responses": { "200": { "description": "Multichain balance totals for a page of wallets in one read, off the same aggregate as /portfolio-summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallets": { "type": "object", "additionalProperties": { "nullable": true, "type": "object", "properties": { "totalValueUsd": { "nullable": true, "description": "Multichain balance total in USD.", "type": "number" }, "solPriceUsd": { "nullable": true, "description": "SOL price the Solana leg was valued at; null when that leg is fail-open", "type": "number" }, "nativeBalanceSol": { "nullable": true, "type": "number" }, "perpCashUsd": { "nullable": true, "description": "The linked HyperCore account's cash (the summary's perp leg, cash only), served only for a signed-in viewer's own wallets: 0 = no perp account; null for every other wallet (so always null on the API host), or when the perp read was unavailable. Not folded into totalValueUsd", "type": "number" }, "holdings": { "description": "Present only on the viewer's own wallets when `holdings` is sent: the top 25 rows by valueUsd, off the same read as totalValueUsd; null = unavailable", "nullable": true, "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "string", "description": "Chain slug the row is held on" }, "mint": { "type": "string" }, "amount": { "type": "number", "description": "UI amount held" }, "priceUsd": { "type": "number", "description": "USD price the row was valued at, the one in the wallet's served total: the live price when repriced, else computedPriceUsd" }, "valueUsd": { "type": "number", "description": "amount x priceUsd" }, "marketCapUsd": { "nullable": true, "type": "number" }, "computedPriceUsd": { "description": "Absent when the body was filled outside the reprice", "type": "number" }, "contribUsd": { "description": "amount x computedPriceUsd: this row's share of the computed total", "type": "number" }, "computedPlane": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "string" } ], "x-open-enum": true }, "markUsd": { "description": "Null when the server held this row's PnL leg (spam, missing price, amount skew, no PnL row, no live price, or a failed pairs read); a number only when the served pnl legs moved on this row", "nullable": true, "type": "number" }, "markSource": { "nullable": true, "type": "string", "enum": [ "pnl_row", "ps_mark" ] }, "repriced": { "description": "true = priceUsd is the live pairs price and the totals moved with it", "type": "boolean" }, "livePlane": { "nullable": true, "type": "string", "enum": [ "content_pairs", "portfolio_pairs" ] } }, "required": [ "chain", "mint", "amount", "priceUsd", "valueUsd", "marketCapUsd" ], "additionalProperties": false } } }, "required": [ "totalValueUsd", "solPriceUsd", "nativeBalanceSol", "perpCashUsd" ], "additionalProperties": false }, "description": "Every requested wallet is a key; null = the read failed for that wallet; retry on the next load" } }, "required": [ "wallets" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Multichain balance totals for a page of wallets in one read, off the same aggregate as /portfolio-summary" } }, "/portfolio-summary/chart": { "get": { "operationId": "get_portfolio_summary_chart", "tags": [ "positions.read" ], "summary": "Portfolio value series", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN", "API_USER_REQUIRED" ], "x-api-scope": "positions.read", "parameters": [ { "name": "user", "in": "query", "required": false, "schema": { "description": "Identity to serve: Solana wallet, EVM wallet, username, or a Starknet address 0x+64 (served its Starknet value series alone). Required when calling with an API key (api.pump.fun); optional with a session, where omitted = the signed-in user. Omitted with an API key answers 400 API_USER_REQUIRED.", "type": "string", "maxLength": 66 } }, { "name": "period", "in": "query", "required": false, "schema": { "default": "1d", "description": "Chart window; maps to swap-api 1D / 7D / 30D / ALL (all = from the data floor, 2026-07-01T00:00Z on every chain; the response meta carries coverageFrom)", "type": "string", "enum": [ "1d", "1w", "1m", "all" ] } } ], "responses": { "200": { "description": "Portfolio value series (tokens at trusted marks plus cash, linked EVM chains folded in) for a wallet, username, or the authenticated user; a group id or group username answers 404 (no squad charts)", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string", "enum": [ "1d", "1w", "1m", "all" ] }, "range": { "type": "string", "enum": [ "1D", "7D", "30D", "ALL" ], "description": "swap-api range the period mapped to" }, "currency": { "type": "string", "enum": [ "USD" ] }, "points": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "number", "description": "Bucket start, UTC seconds" }, "value": { "type": "number", "description": "Portfolio value at the bucket, in `currency`" } }, "required": [ "time", "value" ], "additionalProperties": false }, "description": "Time-ascending; buckets before equityFrom are absent, never zero-filled" }, "equityFrom": { "nullable": true, "description": "UTC seconds; the earliest bucket the union covers; null when no wallet answered", "type": "number" }, "resolutionSec": { "type": "number", "description": "Bucket width in seconds" }, "valueNow": { "nullable": true, "description": "The last point value; null when the series is empty", "type": "number" }, "meta": { "type": "object", "properties": { "walletsRequested": { "type": "number", "description": "Distinct wallets looked up" }, "walletsAnswered": { "type": "number", "description": "Wallets whose series made it into the union" }, "walletsUnanswered": { "type": "array", "items": { "type": "object", "properties": { "wallet": { "type": "string" }, "reason": { "anyOf": [ { "type": "string", "enum": [ "unavailable", "deadline", "mixed_regime" ] }, { "type": "string" } ], "x-open-enum": true, "description": "swap-api-owned reason the wallet is missing from the union. Known values: unavailable, deadline, mixed_regime" } }, "required": [ "wallet", "reason" ], "additionalProperties": false } }, "walletsDegraded": { "type": "array", "items": { "type": "string" }, "description": "Answered wallets whose series is partial (a cash, EVM or chain leg unavailable)" }, "coverageFrom": { "nullable": true, "description": "Unix seconds: the earliest instant the series can start (the data floor across the answered wallets); null when no wallet answered. period=all starts here.", "type": "number" } }, "required": [ "walletsRequested", "walletsAnswered", "walletsUnanswered", "walletsDegraded", "coverageFrom" ], "additionalProperties": false } }, "required": [ "period", "range", "currency", "points", "equityFrom", "resolutionSec", "valueNow", "meta" ], "additionalProperties": false, "description": "While the chart is still being built the route answers 503 with `status: \"computing\"`, `retryAfterSeconds` and a Retry-After header: keep the loading state and re-ask after the hint (no partial series is ever served). Other 503s are not retryable. The series also carries the wallet's derived NEAR account; a Starknet address 0x+64 is served its Starknet value series alone. When a chain's series is unavailable the route answers 503 with degraded_lanes [trade_api.get_portfolio_chart]" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "description": "Error payload on the envelope. Also the shared envelope at this status: a platform refusal, or a validation refusal whose `message` is a string array and whose `error` is the HTTP reason phrase.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "timestamp": { "type": "string" }, "path": { "type": "string" }, "error": { "type": "string", "enum": [ "API_CREDENTIAL_NOT_ALLOWED", "API_USER_REQUIRED" ] }, "message": { "type": "string" } }, "required": [ "statusCode", "timestamp", "path", "error", "message" ] }, { "$ref": "#/components/schemas/Error" } ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Status-only; the body is the fixed 5xx envelope" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Portfolio value series (tokens at trusted marks plus cash, linked EVM chains folded in) for a wallet, username, or the authenticated user; a group id or group username answers 404 (no squad charts)" } }, "/posts": { "get": { "operationId": "get_posts", "tags": [ "content.read" ], "summary": "Posts by id", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "content.read", "parameters": [ { "name": "ids", "in": "query", "required": true, "style": "form", "explode": false, "schema": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Comma-separated post ids (UUID), at most 100; duplicates collapse" } } ], "responses": { "200": { "description": "Posts by id (at most 100), with one-level embeds and viewer stamps when signed in. Unknown, hidden and deleted ids are simply absent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Shared_47a8d5353d95" }, "description": "Request order; unknown, hidden and deleted ids leave no placeholder" } }, "required": [ "posts" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Posts by id (at most 100), with one-level embeds and viewer stamps when signed in. Unknown, hidden and deleted ids are simply absent." } }, "/posts/{postId}": { "get": { "operationId": "get_posts_by_postId", "tags": [ "content.read" ], "summary": "One post with its one-level embeds and viewer stamps…", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "content.read", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "One post with its one-level embeds and viewer stamps when signed in. 404 for unknown, hidden or deleted posts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "post": { "$ref": "#/components/schemas/Shared_47a8d5353d95" } }, "required": [ "post" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "One post with its one-level embeds and viewer stamps when signed in. 404 for unknown, hidden or deleted posts." } }, "/posts/{postId}/likers": { "get": { "operationId": "get_posts_by_postId_likers", "tags": [ "graph.read" ], "summary": "Profiles who liked a post, newest like first…", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size; default 50, clamped to 200", "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "offset", "in": "query", "required": false, "schema": { "description": "Offset paging (no keyset on this read); default 0", "type": "integer", "minimum": 0, "maximum": 10000 } } ], "responses": { "200": { "description": "Profiles who liked a post, newest like first, offset-paginated; viewerFollows stamped when signed in. 404 unless the post is live.", "content": { "application/json": { "schema": { "type": "object", "properties": { "likers": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "bio": { "type": "string" }, "profileImageUrl": { "type": "string" }, "headerImageUrl": { "type": "string" }, "followerCount": { "type": "number" }, "followingCount": { "type": "number" }, "createdAt": { "nullable": true, "type": "string" }, "updatedAt": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "socials": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "username": { "type": "string" }, "linkedAt": { "nullable": true, "type": "string" } }, "required": [ "provider", "username", "linkedAt" ], "additionalProperties": false } }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true. The verified state itself is isVerified." }, "resolvedAvatarDecoration": { "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border. Treat absent as null.", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "PERSON", "GROUP" ] }, "memberCount": { "type": "number" }, "membershipPolicy": { "nullable": true, "type": "string", "enum": [ "INVITE" ] }, "groupBadges": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "role": { "type": "string" } }, "required": [ "groupId", "username", "profileImageUrl", "role" ], "additionalProperties": false } }, "generatedMedia": { "nullable": true, "type": "object", "properties": { "pnlLoop": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" } }, "required": [ "uid", "durationSeconds" ], "additionalProperties": false }, "replayIntro": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" }, "fireAt": { "type": "number" } }, "required": [ "uid", "durationSeconds", "fireAt" ], "additionalProperties": false } }, "required": [ "pnlLoop" ], "additionalProperties": false }, "isPumpUser": { "description": "false = unclaimed shell: an identity minted when someone followed an outside wallet that never signed in, served under a generated username. Render it as a wallet (address or the viewer’s wallet label), never as an account. Treat absent as true.", "type": "boolean" }, "viewerFollows": { "description": "Whether the authenticated viewer follows this user; absent on unauthenticated reads", "type": "boolean" } }, "required": [ "userId", "username", "bio", "profileImageUrl", "headerImageUrl", "followerCount", "followingCount", "createdAt", "updatedAt", "walletAddress", "socials", "isVerified", "verifiedBadgeVisible", "kind", "memberCount", "membershipPolicy", "groupBadges", "generatedMedia" ], "additionalProperties": false }, "description": "Newest like first" }, "hasMore": { "type": "boolean" } }, "required": [ "likers", "hasMore" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Profiles who liked a post, newest like first, offset-paginated; viewerFollows stamped when signed in. 404 unless the post is live." } }, "/posts/{postId}/quotes": { "get": { "operationId": "get_posts_by_postId_quotes", "tags": [ "content.read" ], "summary": "Live quotes of a post, newest first, keyset-paginated", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "content.read", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Keyset cursor from the previous response's nextCursor; omit for the first page", "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size; default 50, clamped to 200", "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Live quotes of a post, newest first, keyset-paginated (nextCursor null = end). 404 unless the post is live.", "content": { "application/json": { "schema": { "type": "object", "properties": { "quotes": { "type": "array", "items": { "$ref": "#/components/schemas/Shared_47a8d5353d95" }, "description": "Live quotes, newest first" }, "nextCursor": { "nullable": true, "description": "null means end of list", "type": "string" } }, "required": [ "quotes", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Live quotes of a post, newest first, keyset-paginated (nextCursor null = end). 404 unless the post is live." } }, "/posts/{postId}/replies": { "get": { "operationId": "get_posts_by_postId_replies", "tags": [ "content.read" ], "summary": "Direct live replies to a post, newest first…", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "content.read", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Keyset cursor from the previous response's nextCursor; omit for the first page", "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size; default 50, clamped to 200", "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Direct live replies to a post, newest first, keyset-paginated (nextCursor null = end). 404 unless the post is live.", "content": { "application/json": { "schema": { "type": "object", "properties": { "replies": { "type": "array", "items": { "$ref": "#/components/schemas/Shared_47a8d5353d95" }, "description": "Direct live replies, newest first; page on nextCursor, not array length" }, "nextCursor": { "nullable": true, "description": "null means end of list", "type": "string" } }, "required": [ "replies", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Direct live replies to a post, newest first, keyset-paginated (nextCursor null = end). 404 unless the post is live." } }, "/posts/{postId}/reposters": { "get": { "operationId": "get_posts_by_postId_reposters", "tags": [ "graph.read" ], "summary": "Profiles who plain-reposted a post, newest first…", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "graph.read", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size; default 50, clamped to 200", "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "offset", "in": "query", "required": false, "schema": { "description": "Offset paging (no keyset on this read); default 0", "type": "integer", "minimum": 0, "maximum": 10000 } } ], "responses": { "200": { "description": "Profiles who plain-reposted a post, newest first, offset-paginated; viewerFollows stamped when signed in. 404 unless the post is live.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reposters": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "bio": { "type": "string" }, "profileImageUrl": { "type": "string" }, "headerImageUrl": { "type": "string" }, "followerCount": { "type": "number" }, "followingCount": { "type": "number" }, "createdAt": { "nullable": true, "type": "string" }, "updatedAt": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "socials": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "username": { "type": "string" }, "linkedAt": { "nullable": true, "type": "string" } }, "required": [ "provider", "username", "linkedAt" ], "additionalProperties": false } }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true. The verified state itself is isVerified." }, "resolvedAvatarDecoration": { "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border. Treat absent as null.", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "PERSON", "GROUP" ] }, "memberCount": { "type": "number" }, "membershipPolicy": { "nullable": true, "type": "string", "enum": [ "INVITE" ] }, "groupBadges": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "role": { "type": "string" } }, "required": [ "groupId", "username", "profileImageUrl", "role" ], "additionalProperties": false } }, "generatedMedia": { "nullable": true, "type": "object", "properties": { "pnlLoop": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" } }, "required": [ "uid", "durationSeconds" ], "additionalProperties": false }, "replayIntro": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" }, "fireAt": { "type": "number" } }, "required": [ "uid", "durationSeconds", "fireAt" ], "additionalProperties": false } }, "required": [ "pnlLoop" ], "additionalProperties": false }, "isPumpUser": { "description": "false = unclaimed shell: an identity minted when someone followed an outside wallet that never signed in, served under a generated username. Render it as a wallet (address or the viewer’s wallet label), never as an account. Treat absent as true.", "type": "boolean" }, "viewerFollows": { "description": "Whether the authenticated viewer follows this user; absent on unauthenticated reads", "type": "boolean" } }, "required": [ "userId", "username", "bio", "profileImageUrl", "headerImageUrl", "followerCount", "followingCount", "createdAt", "updatedAt", "walletAddress", "socials", "isVerified", "verifiedBadgeVisible", "kind", "memberCount", "membershipPolicy", "groupBadges", "generatedMedia" ], "additionalProperties": false }, "description": "Newest repost first; plain reposts only" }, "hasMore": { "type": "boolean" } }, "required": [ "reposters", "hasMore" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Profiles who plain-reposted a post, newest first, offset-paginated; viewerFollows stamped when signed in. 404 unless the post is live." } }, "/profiles/generated-media": { "post": { "operationId": "post_profiles_generated_media", "tags": [ "profiles.read" ], "summary": "Verified badge plus generated share media", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "profiles.read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "Wallet addresses (Solana base58 or EVM 0x) or user ids (UUID), disambiguated by format." } }, "required": [ "ids" ] } } } }, "responses": { "201": { "description": "Verified badge plus generated share media (PnL loop, replay intro) for a list of wallets or user ids", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": { "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true; true for ids with no user" }, "unseen": { "description": "Owner-only: present on the authenticated caller's own entry when it carries media; true until POST /profiles/generated-media/seen acknowledges it. Absent on every other entry.", "type": "boolean" }, "pnlLoop": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" } }, "required": [ "uid", "durationSeconds" ], "additionalProperties": false }, "replayIntro": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" }, "fireAt": { "type": "number" } }, "required": [ "uid", "durationSeconds", "fireAt" ], "additionalProperties": false } }, "required": [ "isVerified", "verifiedBadgeVisible" ], "additionalProperties": false } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Verified badge plus generated share media (PnL loop, replay intro) for a list of wallets or user ids" } }, "/profiles/verified": { "get": { "operationId": "get_profiles_verified", "tags": [ "profiles.read" ], "summary": "The ten top daily PnL leaders", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "profiles.read", "responses": { "200": { "description": "The ten top daily PnL leaders (the onboarding follow suggestions)", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "bio": { "type": "string" }, "profileImageUrl": { "type": "string" }, "headerImageUrl": { "type": "string" }, "followerCount": { "type": "number" }, "followingCount": { "type": "number" }, "createdAt": { "nullable": true, "type": "string" }, "updatedAt": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "socials": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "username": { "type": "string" }, "linkedAt": { "nullable": true, "type": "string" } }, "required": [ "provider", "username", "linkedAt" ], "additionalProperties": false } }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true. The verified state itself is isVerified." }, "resolvedAvatarDecoration": { "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border. Treat absent as null.", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "PERSON", "GROUP" ] }, "memberCount": { "type": "number" }, "membershipPolicy": { "nullable": true, "type": "string", "enum": [ "INVITE" ] }, "groupBadges": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "role": { "type": "string" } }, "required": [ "groupId", "username", "profileImageUrl", "role" ], "additionalProperties": false } }, "generatedMedia": { "nullable": true, "type": "object", "properties": { "pnlLoop": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" } }, "required": [ "uid", "durationSeconds" ], "additionalProperties": false }, "replayIntro": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" }, "fireAt": { "type": "number" } }, "required": [ "uid", "durationSeconds", "fireAt" ], "additionalProperties": false } }, "required": [ "pnlLoop" ], "additionalProperties": false }, "isPumpUser": { "description": "false = unclaimed shell: an identity minted when someone followed an outside wallet that never signed in, served under a generated username. Render it as a wallet (address or the viewer’s wallet label), never as an account. Treat absent as true.", "type": "boolean" } }, "required": [ "userId", "username", "bio", "profileImageUrl", "headerImageUrl", "followerCount", "followingCount", "createdAt", "updatedAt", "walletAddress", "socials", "isVerified", "verifiedBadgeVisible", "kind", "memberCount", "membershipPolicy", "groupBadges", "generatedMedia" ], "additionalProperties": false } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "The ten top daily PnL leaders (the onboarding follow suggestions)" }, "post": { "operationId": "post_profiles_verified", "tags": [ "profiles.read" ], "summary": "Verified status for a list of wallets or user ids", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "profiles.read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "Wallet addresses (Solana base58 or EVM 0x) or user ids (UUID), disambiguated by format." } }, "required": [ "ids" ] } } } }, "responses": { "201": { "description": "Verified (KOL/influencer badge) status for a list of wallets or user ids", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Requested id -> whether the verified checkmark renders (isVerified AND verifiedBadgeVisible); ids with no user, and verified users whose badge an admin hid, are false" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Verified (KOL/influencer badge) status for a list of wallets or user ids" } }, "/search/resolve": { "get": { "operationId": "get_search_resolve", "tags": [ "profiles.read" ], "summary": "Classify 1-5 identifiers in one hop", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "profiles.read", "parameters": [ { "name": "identifiers", "in": "query", "required": true, "style": "form", "explode": false, "schema": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "maxLength": 128 }, "description": "Comma-separated identifiers (repeated and mixed forms parse identically): a coin address (mint, bonding curve or pool), a Solana wallet, an EVM address, a TON, NEAR or Starknet token address (while coin cards for that chain are served; a 0x plus 40-hex address is always EVM), or a pump.fun user id" } } ], "responses": { "200": { "description": "Classify 1-5 identifiers in one hop: what each one is, which chain it is on, and the coin or account payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string", "description": "The caller's identifier string, echoed verbatim" }, "kind": { "type": "string", "enum": [ "coin", "user", "squad", "external_wallet", "unknown" ], "description": "What the identifier is. 'external_wallet' = a well-formed address that no coin and no account claims; 'unknown' = either a shape this route does not route at all, or a verdict a leg could not decide — `definitive` is what tells those two apart" }, "chain": { "nullable": true, "description": "The chain the identifier belongs to by shape; null when its shape names no chain (a pump.fun user id, or text that is not an address). 'ton' only while TON coin cards are served: until then a friendly TON address is null. 'near' only while NEAR coin cards are served, and only for a dotted or 64-hex account id: until then it is null. 'starknet' only while Starknet coin cards are served, and only for 0x plus 1 to 64 hex digits that is not a 40-hex EVM address: until then it is null", "type": "string", "enum": [ "solana", "evm", "ton", "near", "starknet" ] }, "coin": { "nullable": true, "description": "The resolved coin; null unless kind is 'coin'", "type": "object", "properties": { "mint": { "type": "string", "description": "The only field guaranteed on every coin row; every other field can be absent" }, "initialized": { "type": "boolean" }, "name": { "description": "Render the mint, never a blank string", "type": "string" }, "symbol": { "description": "Render the mint, never a blank string", "type": "string" }, "description": { "description": "Never the empty string: the server collapses \"\" to absent, so presence alone says whether there is a value", "type": "string" }, "image_uri": { "description": "Never the empty string: the server collapses \"\" to absent, so presence alone says whether there is a value", "type": "string" }, "image_backdrop": { "description": "Surface to paint behind image_uri when it is a bare mark on transparency: light for a dark mark, dark for a light one. Absent = paint the image as-is (an opaque tile, an unassessed image, or no image). Served on HyperCore perp rows only, and only beside image_uri", "type": "string", "enum": [ "light", "dark" ] }, "metadata_uri": { "description": "Never the empty string: the server collapses \"\" to absent, so presence alone says whether there is a value", "type": "string" }, "video_uri": { "type": "string" }, "banner_uri": { "type": "string" }, "twitter": { "type": "string" }, "telegram": { "type": "string" }, "website": { "type": "string" }, "bonding_curve": { "type": "string" }, "associated_bonding_curve": { "type": "string" }, "creator": { "description": "Creator wallet of the coin; the system program id 11111111111111111111111111111111 when the coin was created without one.", "type": "string" }, "signer": { "type": "string" }, "created_timestamp": { "description": "Unix epoch milliseconds", "type": "number" }, "complete": { "description": "Whether the bonding curve has completed", "type": "boolean" }, "virtual_sol_reserves": { "type": "number" }, "virtual_token_reserves": { "type": "number" }, "virtual_quote_reserves": { "type": "number" }, "total_supply": { "description": "Raw base-unit total supply as a JSON number; values above 2^53 are imprecise (BONK is 8799515941776938000 here and \"8799515941776937984\" in total_supply_str). Read total_supply_str when exactness matters. Absent when no supply is known or the raw value exceeds uint64.", "type": "number" }, "total_supply_str": { "description": "Apply base_decimals for a human value); string-typed because raw 18-decimal EVM values exceed uint64, and exact where total_supply is imprecise. Absent when the producer holds no supply.", "type": "string" }, "circulating_supply_str": { "description": "Raw on-chain circulating supply as a base-10 integer string; string-typed because raw 18-decimal EVM values exceed uint64", "type": "string" }, "show_name": { "type": "boolean" }, "last_trade_timestamp": { "description": "Unix epoch milliseconds", "type": "number" }, "king_of_the_hill_timestamp": { "description": "Unix epoch milliseconds", "type": "number" }, "market_cap": { "description": "Legacy market cap in the chain's native unit (SOL on SVM), never converted to USD (#3272). On EVM rows applyUsdMarketCap overwrites it with the USD figure, so there it equals usd_market_cap and is absent with it.", "type": "number" }, "market_cap_quote": { "description": "Market cap in quote_mint units (SOL, USDC,...; usd_market_cap is served from market_cap_usd whenever that is set and falls back to this field only for a USDC-quoted coin with none (getUsdMarketCap).", "type": "number" }, "market_cap_usd": { "description": "Unset only for a dormant coin that never had one populated. usd_market_cap is served from it.", "type": "number" }, "market_id": { "type": "string" }, "inverted": { "description": "Inverted (special) pricing mode", "type": "boolean" }, "nsfw": { "type": "boolean" }, "is_banned": { "type": "boolean" }, "hidden": { "type": "boolean" }, "real_sol_reserves": { "type": "number" }, "real_token_reserves": { "type": "number" }, "real_quote_reserves": { "type": "number" }, "updated_at": { "description": "Unix epoch milliseconds", "type": "number" }, "livestream_ban_expiry": { "description": "Unix epoch milliseconds", "type": "number" }, "last_reply": { "description": "Unix epoch milliseconds", "type": "number" }, "reply_count": { "type": "number" }, "is_currently_live": { "type": "boolean" }, "thumbnail": { "description": "Livestream thumbnail URL; set only while is_currently_live", "type": "string" }, "thumbnail_updated_at": { "description": "Unix epoch milliseconds; set only while is_currently_live", "type": "number" }, "num_participants": { "description": "Livestream participant count; set only while is_currently_live", "type": "number" }, "ath_market_cap": { "type": "number" }, "ath_market_cap_timestamp": { "description": "Unix epoch milliseconds", "type": "number" }, "hide_banner": { "type": "boolean" }, "program": { "description": "Launch program of the mint; absent on off-platform mints (presence is the gate for swap-api / advanced-indexer reads)", "type": "string" }, "token_program": { "type": "string" }, "usd_market_cap": { "description": "Absent, never 0, when no USD figure is known (#3272 served DJT at $700 by converting a SOL cap); treat absence as unknown and sink it in value sorts.", "type": "number" }, "price_usd": { "description": "Present on TON only for now, absent when the card carries none.", "type": "number" }, "platform": { "type": "string" }, "base_decimals": { "type": "number" }, "quote_decimals": { "type": "number" }, "quote_mint": { "type": "string" }, "quote_token_program": { "description": "SPL Token or Token-2022 program id owning the quote mint; absent on older rows", "type": "string" }, "mayhem_state": { "anyOf": [ { "type": "string", "enum": [ "enabled", "active", "paused", "completed" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Mayhem lifecycle state, an open set; a value not listed here is still a coin in mayhem. Known values: enabled, active, paused, completed" }, "mayhem": { "type": "object", "properties": { "state": { "anyOf": [ { "type": "string", "enum": [ "enabled", "active", "paused", "completed" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Mayhem lifecycle state, an open set; a value not listed here is still a coin in mayhem. Known values: enabled, active, paused, completed" }, "mode": { "anyOf": [ { "type": "string", "enum": [ "auto", "manual" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Trading mode, an open set; served as stored, never defaulted here. Known values: auto, manual" }, "pause_reason": { "anyOf": [ { "type": "string", "enum": [ "mcap_floor", "unprofitable", "low_reserves", "creator_paused", "below_initial_buy_floor", "low_sol_reserves", "low_stable_reserves", "unprofitable_fees" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Why the coin is paused, an open set; present only while state is paused. Known values: mcap_floor, unprofitable, low_reserves, creator_paused, below_initial_buy_floor, low_sol_reserves, low_stable_reserves, unprofitable_fees" }, "complete_reason": { "anyOf": [ { "type": "string", "enum": [ "max_age_reached", "sol_reserve_errors", "zero_base_amount", "sell_zero_amount", "buy_zero_amount", "mayhem_mode_ended", "overflow" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Why the coin completed, an open set; present only once state is completed. Known values: max_age_reached, sol_reserve_errors, zero_base_amount, sell_zero_amount, buy_zero_amount, mayhem_mode_ended, overflow" } }, "additionalProperties": false }, "security_verdict": { "description": "Absent until the verdict writer has processed the coin", "type": "object", "properties": { "verdict": { "type": "string", "description": "Resolved token-security verdict: \"blocked\" | \"warn\" | \"allow\" | \"unknown\"" }, "scope": { "type": "string", "description": "Hiding scope, meaningful only when verdict is \"blocked\": \"all\" hides the coin everywhere, \"discovery\" only from feeds" }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "token-trust reason slugs, e.g. \"honeypot\", \"rugpull\"" }, "decided_by": { "type": "string", "description": "Resolver tier that decided: \"blacklist\" | \"bypass\" | \"vendor\" | \"trust\" | \"soft\" | \"default\"" }, "provider": { "type": "string", "description": "Security data provider(s) consulted: \"blockaid\" | \"goplus\" | \"both\" | \"solana-rpc\" | \"heuristic\" | \"none\"" }, "malicious_score": { "description": "Provider-reported malicious score, when one was returned", "type": "number" }, "version": { "type": "number", "description": "Per-coin monotonic write version" }, "updated_at": { "description": "Unix epoch milliseconds", "type": "number" }, "source": { "type": "string", "description": "Writer identity, e.g. \"token-trust\"" } }, "required": [ "verdict", "scope", "reasons", "decided_by", "provider", "version", "source" ], "additionalProperties": false }, "is_test": { "type": "boolean" }, "username": { "type": "string" }, "profile_image": { "type": "string" }, "cto_address": { "type": "string" }, "cto_username": { "type": "string" }, "cto_profile_image": { "type": "string" }, "indexed_by_pump": { "type": "boolean" }, "is_cashback_enabled": { "type": "boolean" }, "is_holder_reward": { "type": "boolean" }, "transfer_fee_bps": { "description": "Base mint Token-2022 transfer fee in basis points (newer TransferFeeConfig step, Coin field 76); 0 = fee-less, absent = not inspected", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "transfer_hook_program": { "description": "Base-mint Token-2022 TransferHook program (base58). Empty string: inspected, no hook or revoked at graduation. Absent: not inspected.", "type": "string" }, "is_charity": { "type": "boolean" }, "tokenized_agent": { "type": "boolean" }, "verified": { "type": "boolean" }, "raydium_pool": { "type": "string" }, "pump_swap_pool": { "type": "string" }, "depth": { "description": "Pump curve nesting level; 0 for SOL/USDC/whitelisted quotes and for coins created before the depth rung.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "volume_1h_usd": { "type": "number" }, "chain_id": { "type": "string" }, "multichain_family": { "type": "number" }, "protocol": { "type": "string" }, "pool_address": { "type": "string" }, "canonical_pool_liquidity_usd": { "type": "number" }, "boost_mode": { "description": "Boost-mode lifecycle state: \"NONE\" | \"IN_PROGRESS\" | \"COMPLETED\"", "type": "string" }, "asset_class": { "description": "Tokenized-equity class of the coin, when it has one; null = classified as neither.", "nullable": true, "type": "string", "enum": [ "tokenized_stock", "pre_ipo_synthetic" ] }, "issuer": { "description": "Tokenized-equity issuer; set only alongside asset_class", "nullable": true, "type": "string", "enum": [ "xstocks", "ondo", "backpack", "prestocks", "tessera", "robinhood", "coinbase", "binance" ] }, "underlying_symbol": { "description": "Underlying equity ticker derived from the token symbol (issuer affix stripped where recognised); set only alongside asset_class", "nullable": true, "type": "string" }, "canonical_stock": { "description": "Stock badge: true = the one canonical coin for its underlying stock, false = another variant of a stock that has a canonical coin, null = not a stock; absent = no verdict on this path (badge off either way)", "nullable": true, "type": "boolean" }, "chain": { "description": "CAIP-2 chain; set on a perp row (hlcore:mainnet, where mint is the HyperCore coin name verbatim: BTC, kPEPE, xyz:TSLA), on a TON row (ton:-239, where mint is the jetton master's friendly address), on a NEAR row (near:mainnet, where mint is the token's account id) and on a Starknet row (starknet:SN_MAIN, where mint is the token's 0x + 64 lowercase hex address)", "type": "string" }, "assetClass": { "description": "Asset class of the coin: ASSET_CLASS_PERPETUAL on a perp row, ASSET_CLASS_NFT_LIKE on a card body (collectible set, market cap and pool absent); absent on every token row.", "type": "string", "enum": [ "ASSET_CLASS_PERPETUAL", "ASSET_CLASS_NFT_LIKE" ] }, "perp": { "type": "object", "properties": { "markPx": { "nullable": true, "description": "USD as a decimal string; null when the store carries no mark", "type": "string" }, "oraclePx": { "nullable": true, "description": "USD as a decimal string; null when the store carries no mark", "type": "string" }, "fundingRateHourly": { "nullable": true, "description": "Hourly funding rate as a decimal string; null when unknown", "type": "string" }, "openInterestUsd": { "nullable": true, "description": "USD as a decimal string; null when the store carries no mark", "type": "string" }, "nextFundingAt": { "nullable": true, "description": "ISO 8601", "type": "string" }, "asOf": { "nullable": true, "description": "ISO 8601; when the HL market context was last observed", "type": "string" }, "stale": { "type": "boolean", "description": "true when the context is older than 120 s; perp values are the last observed" }, "maxLeverage": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "szDecimals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "onlyIsolated": { "type": "boolean" }, "dex": { "nullable": true, "description": "HIP-3 dex name; null on the main perp dex", "type": "string" }, "category": { "nullable": true, "description": "crypto | stocks | commodities; null when unknown", "type": "string" }, "isDelisted": { "type": "boolean" }, "volume24hUsd": { "nullable": true, "description": "24h notional volume in USD as a decimal string from the HL market context (dayNtlVlmUsd); falls back to the 24h fold window; null when neither is present", "type": "string" }, "priceChange24hBps": { "nullable": true, "description": "24h price change in bps from the HL market context (markPx vs prevDayPx); falls back to the 24h fold window; null when neither is present", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "markPx", "oraclePx", "fundingRateHourly", "openInterestUsd", "nextFundingAt", "asOf", "stale", "maxLeverage", "szDecimals", "onlyIsolated", "dex", "category", "isDelisted", "volume24hUsd", "priceChange24hBps" ], "additionalProperties": false, "description": "HyperCore perp state; set on perp rows only" }, "collectible": { "description": "NFT_LIKE card only: the card block (identity, grade, mark, insured value, buyback, listing); a card has no pool, so branch on it before mounting chart or trade panels. Absent on every token coin", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false } }, "required": [ "mint" ], "additionalProperties": false }, "user": { "nullable": true, "description": "The resolved account row; null unless kind is 'user' or 'squad'. Deliberately NOT presence-overlaid (no online/last-seen enrichment): resolve answers a routing question, not a profile render — read the profile routes for a rendered row", "type": "object", "properties": { "address": { "type": "string" }, "userId": { "type": "string" }, "username": { "nullable": true, "type": "string" }, "profile_image": { "nullable": true, "type": "string" }, "header_image_url": { "nullable": true, "type": "string" }, "avatar_decoration": { "description": "The owner's avatar decoration (border effect) PICK as a decoration key — `legendary`, `epic`, `none` (an explicit no-border), `achievement:` — never a url: the client owns the key -> artwork catalog. For the owner's chooser (which tile is selected); the border to draw is resolved_avatar_decoration. null or absent means no pick. Served on GET /users/{id} and POST /users/batch rows.", "nullable": true, "type": "string" }, "resolved_avatar_decoration": { "description": "The border to draw on this avatar, resolved from the owner's pick and achievements: the pick while still earned, else the rarest tier ring the achievements earn (`legendary`, `epic`); null means no border (an explicit `none` pick, or nothing earned). Same key grammar as avatar_decoration. Served on GET /users/{id} and POST /users/batch rows — never fetch a user's achievements to draw a border. A newly earned tier can take up to an hour to show to other viewers; the owner's own view updates immediately", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "person", "group" ] }, "member_count": { "type": "number" }, "group_badges": { "type": "array", "items": { "type": "object", "properties": { "group_id": { "type": "string" }, "username": { "type": "string" }, "profile_image_url": { "nullable": true, "type": "string" }, "role": { "anyOf": [ { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "UNSPECIFIED" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Known values: OWNER, ADMIN, MEMBER, UNSPECIFIED" } }, "required": [ "group_id", "username", "profile_image_url", "role" ], "additionalProperties": false } }, "bio": { "nullable": true, "type": "string" }, "followers": { "type": "number" }, "following": { "type": "number" }, "last_username_update_timestamp": { "description": "Unix epoch ms of the last username change; null when never renamed. Served by the single-profile read and on labelled-wallet search rows; absent from batch and hydrated search-v2 rows", "nullable": true, "type": "number" }, "x_username": { "nullable": true, "type": "string" }, "wallet_label": { "type": "string" }, "is_pump_user": { "type": "boolean" }, "is_banned": { "type": "boolean" }, "canonical_svm_wallet": { "type": "string" }, "canonical_evm_wallet": { "type": "string" }, "last_active_at": { "description": "ISO time of the account's latest authenticated request (~1 min granularity, kept for one day). Viewer-relative: served on GET /users/{id} and POST /users/batch rows to a signed-in viewer, for accounts the viewer follows and the viewer's own row, null otherwise (not followed, never seen, degraded read) — render null as unknown. Absent for anonymous callers, on the API host, and on every other row-serving read", "nullable": true, "type": "string" } }, "required": [ "address", "username", "profile_image", "bio", "followers", "following", "x_username" ], "additionalProperties": false }, "resolvedVia": { "nullable": true, "description": "Which lookup answered: 'coin_registry' = the address is an indexed pump.fun coin (mint, bonding curve or pool); 'codex_fallback' = an un-indexed SPL mint on the verified list, its card synthesized from market data; 'cc_user'/'group' = resolved to a pump.fun account or group; 'trade_api' = resolved to a token on a non-Solana chain (TON, NEAR or Starknet). null when nothing matched the identifier", "type": "string", "enum": [ "coin_registry", "codex_fallback", "cc_user", "group", "trade_api" ] }, "definitive": { "type": "boolean", "description": "true = every lookup that decides this kind answered, so the verdict is the real answer and may be cached. false = at least one of them was unavailable: a provisional verdict that must never be cached as an absence, and that a client should fall back from rather than act on" } }, "required": [ "identifier", "kind", "chain", "coin", "user", "resolvedVia", "definitive" ], "additionalProperties": false }, "description": "One entry per requested identifier, in the order sent" }, "degraded": { "type": "array", "items": { "type": "string", "enum": [ "coin_upstream", "user_upstream", "evm_fallback_unavailable" ] }, "description": "Deduped, request-level reasons a leg could not answer; load-bearing, not diagnostics. 'coin_upstream'/'user_upstream' = the coin or account lookup failed or timed out on at least one identifier. 'evm_fallback_unavailable' = an EVM address the coin registry does not claim could not be checked further, so that result's 'external_wallet' is provisional and clients keep their own EVM lookup chain" } }, "required": [ "results", "degraded" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Classify 1-5 identifiers in one hop: what each one is, which chain it is on, and the coin or account payload" } }, "/user-portfolio/{userId}": { "get": { "operationId": "get_user_portfolio_by_userId", "tags": [ "positions.read" ], "summary": "A user's whole-portfolio positions", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN", "PORTFOLIO_BUILDING" ], "x-api-scope": "positions.read", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "filter", "in": "query", "required": false, "schema": { "description": "Position set to serve; omitted defaults to OPEN", "type": "string" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "description": "Row order; omitted defaults to PNL", "type": "string" } }, { "name": "totalsOnly", "in": "query", "required": false, "schema": { "description": "Return only the summary (positionCount), skipping the positions list", "type": "boolean" } }, { "name": "filterSpam", "in": "query", "required": false, "schema": { "description": "true drops the spam-grouped rows (potentialSpam && !userMarkedNonSpam) before the page slice, with summary.positionCount reporting the filtered total", "type": "boolean" } }, { "name": "spamOnly", "in": "query", "required": false, "schema": { "description": "true serves ONLY the spam-grouped rows (potentialSpam && !userMarkedNonSpam) before the page slice — the inverse of filterSpam, with summary.positionCount reporting the spam total; mutually exclusive with filterSpam (400)", "type": "boolean" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "chainId", "in": "query", "required": false, "schema": { "description": "Omitted means all chains", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "A user's whole-portfolio positions (open/closed/all) with net PnL. totalsOnly returns just the summary (positionCount, no list); the summary carries no PnL or value totals. filterSpam=true serves pages from the non-spam set (filtered before the page slice, positionCount = filtered total); spamOnly=true serves pages from the spam group alone, for clients excluding flagged coins from balance rows that carry no verdict (positionCount = spam total; mutually exclusive with filterSpam, 400). A group id serves the group's member-aggregate portfolio (SUM over active members' positions) with every row's walletAddress null. Group and over-cap reads are paged by the serving source, so their positionCount is that source's and clients stop on an empty page. Owner-only marks (spam / not-spam, the owner's dust floor, dustFloorFiltered) apply only to a read the owner makes signed in, never on the API host; every other read serves the public spam verdict and the callout exemption alone, never a rescue, and every row dustFloorFiltered false. HyperCore perp rows, summary.cash and hlAccount ride this route only, read for the wallet paired with its linked EVM wallet; /user-positions stays mints-only", "content": { "application/json": { "schema": { "type": "object", "properties": { "positions": { "type": "array", "items": { "type": "object", "properties": { "coinMint": { "type": "string" }, "chainId": { "nullable": true, "description": "Key those rows by chain, and tell a perp row by chain and assetClass, never by chainId. Typed nullable so older readers still parse", "type": "number" }, "chain": { "description": "CAIP-2 id of this row's chain (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp, eip155:8453, hlcore:mainnet, ton:-239, near:mainnet, starknet:SN_MAIN); absent on rows served without chain information", "type": "string" }, "assetClass": { "description": "Asset class of the row: ASSET_CLASS_TOKEN, ASSET_CLASS_PERPETUAL or ASSET_CLASS_NFT_LIKE. Some rows carry it only when it is not ASSET_CLASS_TOKEN; absent means a token row", "type": "string" }, "perp": { "description": "ASSET_CLASS_PERPETUAL rows only: the HyperCore position state; absent on every token row", "type": "object", "properties": { "side": { "type": "string", "description": "long | short" }, "entryPx": { "nullable": true, "type": "number" }, "markPx": { "nullable": true, "type": "number" }, "liquidationPx": { "nullable": true, "description": "null when the account carries no liquidation price", "type": "number" }, "leverageBps": { "type": "number" }, "isCross": { "type": "boolean", "description": "Deprecated: always false (cross-margin positions are excluded server side)" }, "marginUsed": { "nullable": true, "type": "number" }, "equity": { "nullable": true, "description": "Margin + unrealized: the figure totals and sorts read", "type": "number" }, "notional": { "nullable": true, "description": "The row's valueUsd: size x mark", "type": "number" }, "fundingSinceOpen": { "nullable": true, "type": "number" }, "fundingAllTime": { "nullable": true, "type": "number" }, "roeBps": { "type": "number", "description": "Return on equity in bps; 0 on a clearinghouse snapshot miss, so read stateAsOf != null first" }, "maxLeverage": { "type": "number" }, "dex": { "nullable": true, "description": "HIP-3 dex; null on the main dex (the coin key carries the dex: prefix)", "type": "string" }, "category": { "nullable": true, "description": "crypto | stocks | commodities; null when unknown", "type": "string" }, "stateAsOf": { "nullable": true, "description": "ISO instant of the clearinghouse state behind these figures", "type": "string" }, "openedAt": { "nullable": true, "description": "ISO instant of the position's first fill; null when the server carries no first trade", "type": "string" }, "closedAt": { "nullable": true, "description": "ISO instant of the lifecycle's last fill on an exited row (its close, also the row's updatedAt); null while the position is open", "type": "string" } }, "required": [ "side", "entryPx", "markPx", "liquidationPx", "leverageBps", "isCross", "marginUsed", "equity", "notional", "fundingSinceOpen", "fundingAllTime", "roeBps", "maxLeverage", "dex", "category", "stateAsOf", "openedAt", "closedAt" ], "additionalProperties": false }, "collectible": { "description": "ASSET_CLASS_NFT_LIKE rows only: the card (identity, grade, mark, insured value, buyback, listing); absent on every token row", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false }, "isExited": { "type": "boolean" }, "walletAddress": { "nullable": true, "type": "string" }, "amountHeld": { "type": "number" }, "pnlUsd": { "nullable": true, "description": "PnL in USD; null when the position's PnL is not yet available", "type": "number" }, "pnlPercentage": { "nullable": true, "type": "number" }, "costBasisAmount": { "nullable": true, "description": "Net cost-basis quantity of the position (on most rows the quantity currently held); null on balance-hydrated holdings.", "type": "number" }, "costBasisUsd": { "nullable": true, "type": "number" }, "amountBoughtUsd": { "nullable": true, "description": "Lifetime buy total, never reduced by sells; survives full exit unlike the cost-basis pair", "type": "number" }, "amountBought": { "nullable": true, "type": "number" }, "callout": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Shared_fceda4efe6cd" } ] }, "valueUsd": { "description": "Absent or null both mean no fresh price known, never 0; never reconstruct it as costBasisUsd + pnlUsd", "nullable": true, "type": "number" }, "tokenPriceUsd": { "nullable": true, "description": "The per-token USD price mark behind valueUsd; Always present on both /user-positions and /user-portfolio rows", "type": "number" }, "realizedPnlUsd": { "description": "Treat absent and null the same", "nullable": true, "type": "number" }, "hasTransfers": { "description": "False means no transfer marker was seen, NOT provably trade-only; absent when the source cannot say", "type": "boolean" }, "likelyLost": { "description": "Label only; the row itself is unchanged. Always false on Solana rows; may be absent on other rows", "type": "boolean" }, "hasUntrustedUsdBasis": { "description": "True when the USD cost basis is untrusted (a leg was booked with no USD mark): costBasisUsd, pnlUsd, realizedPnlUsd and pnlPercentage do not reflect a real basis, so mask them rather than render $0 / 0%; amountBoughtUsd, amountHeld and valueUsd are unaffected. Absent on rows that carry no verdict (for example balance-derived rows).", "type": "boolean" }, "hasUntrustedSolBasis": { "description": "True when the SOL (native) cost basis is untrusted: native-denominated basis and PnL figures do not reflect a real basis, so mask them. Absent on rows that carry no verdict (for example balance-derived rows).", "type": "boolean" }, "updatedAt": { "description": "block time of the position's last ledger leg as ISO — the RECENCY sort instant; the stored row's write clock only where the pair has no ledger row; absent on balance-hydrated rows", "nullable": true, "type": "string" }, "openedAt": { "description": "ISO instant the CURRENT position opened (re-stamped on re-entry, so the latest entry, not the lifetime first buy); absent when unknown and on exited and group rows — never a fallback to updatedAt. Anchors a position chart or 'held since' without walking the trade history", "type": "string" }, "amountSoldUsd": { "description": "Lifetime gross sell proceeds in USD (venue trades only); amountBoughtUsd + amountSoldUsd is the lifetime trade volume. Absent when no sell total is known — never 0", "type": "number" }, "tradeCount": { "description": "The wallet's lifetime venue-trade count on this mint (one per transaction carrying a trade leg; transfers excluded) — the exact figure for a transactions header without paging trades. Absent when no exact count is known: absent means unknown, never 0; a present 0 is exact", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastSlotIndexId": { "description": "26-digit slot(12) tx_index(6) ev(8) ledger cursor of the last folded leg; block number in the slot field on EVM; compare the 12-char prefix; absent = unknown", "type": "string" }, "potentialSpam": { "description": "/user-portfolio only; spam group = potentialSpam && !userMarkedNonSpam", "type": "boolean" }, "userMarkedNonSpam": { "description": "/user-portfolio only", "type": "boolean" }, "dustFloorFiltered": { "description": "/user-portfolio only, stamped on the owner's own authed read (a public read serves false); grouping hint: nothing is hidden and totals are untouched", "type": "boolean" }, "isNative": { "description": "/user-portfolio only: the row is a chain's native gas token, served under the bare \"native\" wire mint", "type": "boolean" }, "groupHolders": { "description": "Group-subject reads only; present-but-empty when no member currently holds", "type": "object", "properties": { "holders": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "amountHeld": { "type": "number", "description": "The member's open holdings summed across their wallets" } }, "required": [ "userId", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible", "amountHeld" ], "additionalProperties": false }, "description": "Sorted amountHeld desc, server-capped" }, "totalCount": { "type": "number", "description": "The uncapped figure" } }, "required": [ "holders", "totalCount" ], "additionalProperties": false }, "coin": { "description": "/user-portfolio only; null = no chain-matching record, never attached on native rows", "nullable": true, "type": "object", "properties": { "name": { "nullable": true, "type": "string" }, "symbol": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" }, "imageBackdrop": { "description": "Surface to paint behind imageUri when it is a bare mark on transparency: light for a dark mark, dark for a light one. null = paint the image as-is (an opaque tile, an unassessed image, no image, or any non-perp coin). Absent on routes that do not serve perp coin cards", "nullable": true, "type": "string", "enum": [ "light", "dark" ] }, "marketCapUsd": { "nullable": true, "type": "number" }, "totalSupply": { "nullable": true, "description": "UI-normalized supply (raw / 10^decimals) on the basis marketCapUsd is computed on: circulating supply when an EVM record carries one (it may exceed total), else total supply — implied unit price = marketCapUsd / totalSupply; null means do not derive a price from marketCapUsd", "type": "number" }, "protocol": { "nullable": true, "description": "An EVM coin's launchpad identity", "type": "string" }, "platform": { "nullable": true, "description": "Solana launchpad platform (`bonk`, `bags`, `believe`); null on EVM rows", "type": "string" }, "program": { "nullable": true, "description": "Solana program slug (`pump`, `meteora_dbc`, `raydium_launchpad`); null on EVM rows", "type": "string" }, "collectible": { "description": "ASSET_CLASS_NFT_LIKE rows only: the card (identity, grade, mark, insured value, buyback, listing); absent on every token row", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false } }, "required": [ "name", "symbol", "imageUri", "marketCapUsd", "totalSupply", "protocol", "platform", "program" ], "additionalProperties": false } }, "required": [ "coinMint", "chainId", "isExited", "walletAddress", "amountHeld", "pnlUsd", "pnlPercentage", "costBasisAmount", "costBasisUsd", "amountBoughtUsd", "amountBought", "callout", "tokenPriceUsd" ], "additionalProperties": false }, "description": "The filtered positions for the requested page; empty when totalsOnly" }, "summary": { "type": "object", "properties": { "positionCount": { "type": "number", "description": "Rows in the filtered set (filterSpam/spamOnly: the kept rows); paginate until a page comes back empty" }, "cash": { "description": "HyperCore account cash; never a positions row, absent when the account reports none", "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "string", "description": "CAIP-2 chain of the cash balance" }, "amount": { "type": "number" }, "valueUsd": { "nullable": true, "type": "number" } }, "required": [ "chain", "amount", "valueUsd" ], "additionalProperties": false } }, "withdrawable": { "description": "HyperCore withdrawable USDC beside cash; absent when the HyperCore snapshot is missing", "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "string", "description": "CAIP-2 chain of the balance" }, "amount": { "type": "number" }, "valueUsd": { "nullable": true, "type": "number" } }, "required": [ "chain", "amount", "valueUsd" ], "additionalProperties": false } }, "hlAccount": { "description": "HyperCore account state; absent when the account reports none", "type": "string", "enum": [ "unknown", "missing", "active" ] } }, "required": [ "positionCount" ], "additionalProperties": false }, "updatesApplied": { "type": "boolean", "description": "Clients must read empty updates as \"unknown\" when this is false" } }, "required": [ "positions", "summary", "updatesApplied" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Error payload on the envelope", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "timestamp": { "type": "string" }, "path": { "type": "string" } }, "required": [ "statusCode", "timestamp", "path" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "PORTFOLIO_BUILDING" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "A user's whole-portfolio positions (open/closed/all) with net PnL. totalsOnly returns just the summary (positionCount, no list); the summary carries no PnL or value totals. filterSpam=true serves pages from the non-spam set (filtered before the page slice, positionCount = filtered total); spamOnly=true serves pages from the spam group alone, for clients excluding flagged coins from balance rows that carry no verdict (positionCount = spam total; mutually exclusive with filterSpam, 400). A group id serves the group's member-aggregate portfolio (SUM over active members' positions) with every row's walletAddress null. Group and over-cap reads are paged by the serving source, so their positionCount is that source's and clients stop on an empty page. Owner-only marks (spam / not-spam, the owner's dust floor, dustFloorFiltered) apply only to a read the owner makes signed in, never on the API host; every other read serves the public spam verdict and the callout exemption alone, never a rescue, and every row dustFloorFiltered false. HyperCore perp rows, summary.cash and hlAccount ride this route only, read for the wallet paired with its linked EVM wallet; /user-positions stays mints-only" } }, "/user-positions/{userId}": { "get": { "operationId": "get_user_positions_by_userId", "tags": [ "positions.read" ], "summary": "Get a user's position", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "positions.read", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "mints", "in": "query", "required": true, "style": "form", "explode": false, "schema": { "maxItems": 200, "type": "array", "items": { "type": "string" }, "description": "Comma-separated mint list on the wire, max 200 entries; a perp coin is hlcore:: (hlcore:mainnet:BTC) and serves one row with coinMint = the coin key, chain = the CAIP-2, chainId 0, assetClass ASSET_CLASS_PERPETUAL and perp{}" } }, { "name": "updatesLimit", "in": "query", "required": false, "schema": { "description": "Max author updates per callout (omitted serves 5); 0 skips update enrichment entirely", "type": "integer", "minimum": 0, "maximum": 20 } } ], "responses": { "200": { "description": "Get a user's position (total PnL + callout) in each of the given mints; a group id serves the group's member-aggregate position per mint (walletAddress null, no callout link)", "content": { "application/json": { "schema": { "type": "object", "properties": { "positions": { "type": "array", "items": { "type": "object", "properties": { "coinMint": { "type": "string" }, "chainId": { "nullable": true, "description": "Key those rows by chain, and tell a perp row by chain and assetClass, never by chainId. Typed nullable so older readers still parse", "type": "number" }, "chain": { "description": "CAIP-2 id of this row's chain (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp, eip155:8453, hlcore:mainnet, ton:-239, near:mainnet, starknet:SN_MAIN); absent on rows served without chain information", "type": "string" }, "assetClass": { "description": "Asset class of the row: ASSET_CLASS_TOKEN, ASSET_CLASS_PERPETUAL or ASSET_CLASS_NFT_LIKE. Some rows carry it only when it is not ASSET_CLASS_TOKEN; absent means a token row", "type": "string" }, "perp": { "description": "ASSET_CLASS_PERPETUAL rows only: the HyperCore position state; absent on every token row", "type": "object", "properties": { "side": { "type": "string", "description": "long | short" }, "entryPx": { "nullable": true, "type": "number" }, "markPx": { "nullable": true, "type": "number" }, "liquidationPx": { "nullable": true, "description": "null when the account carries no liquidation price", "type": "number" }, "leverageBps": { "type": "number" }, "isCross": { "type": "boolean", "description": "Deprecated: always false (cross-margin positions are excluded server side)" }, "marginUsed": { "nullable": true, "type": "number" }, "equity": { "nullable": true, "description": "Margin + unrealized: the figure totals and sorts read", "type": "number" }, "notional": { "nullable": true, "description": "The row's valueUsd: size x mark", "type": "number" }, "fundingSinceOpen": { "nullable": true, "type": "number" }, "fundingAllTime": { "nullable": true, "type": "number" }, "roeBps": { "type": "number", "description": "Return on equity in bps; 0 on a clearinghouse snapshot miss, so read stateAsOf != null first" }, "maxLeverage": { "type": "number" }, "dex": { "nullable": true, "description": "HIP-3 dex; null on the main dex (the coin key carries the dex: prefix)", "type": "string" }, "category": { "nullable": true, "description": "crypto | stocks | commodities; null when unknown", "type": "string" }, "stateAsOf": { "nullable": true, "description": "ISO instant of the clearinghouse state behind these figures", "type": "string" }, "openedAt": { "nullable": true, "description": "ISO instant of the position's first fill; null when the server carries no first trade", "type": "string" }, "closedAt": { "nullable": true, "description": "ISO instant of the lifecycle's last fill on an exited row (its close, also the row's updatedAt); null while the position is open", "type": "string" } }, "required": [ "side", "entryPx", "markPx", "liquidationPx", "leverageBps", "isCross", "marginUsed", "equity", "notional", "fundingSinceOpen", "fundingAllTime", "roeBps", "maxLeverage", "dex", "category", "stateAsOf", "openedAt", "closedAt" ], "additionalProperties": false }, "collectible": { "description": "ASSET_CLASS_NFT_LIKE rows only: the card (identity, grade, mark, insured value, buyback, listing); absent on every token row", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false }, "isExited": { "type": "boolean" }, "walletAddress": { "nullable": true, "type": "string" }, "amountHeld": { "type": "number" }, "pnlUsd": { "nullable": true, "description": "PnL in USD; null when the position's PnL is not yet available", "type": "number" }, "pnlPercentage": { "nullable": true, "type": "number" }, "costBasisAmount": { "nullable": true, "description": "Net cost-basis quantity of the position (on most rows the quantity currently held); null on balance-hydrated holdings.", "type": "number" }, "costBasisUsd": { "nullable": true, "type": "number" }, "amountBoughtUsd": { "nullable": true, "description": "Lifetime buy total, never reduced by sells; survives full exit unlike the cost-basis pair", "type": "number" }, "amountBought": { "nullable": true, "type": "number" }, "callout": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Shared_fceda4efe6cd" } ] }, "valueUsd": { "description": "Absent or null both mean no fresh price known, never 0; never reconstruct it as costBasisUsd + pnlUsd", "nullable": true, "type": "number" }, "tokenPriceUsd": { "nullable": true, "description": "The per-token USD price mark behind valueUsd; Always present on both /user-positions and /user-portfolio rows", "type": "number" }, "realizedPnlUsd": { "description": "Treat absent and null the same", "nullable": true, "type": "number" }, "hasTransfers": { "description": "False means no transfer marker was seen, NOT provably trade-only; absent when the source cannot say", "type": "boolean" }, "likelyLost": { "description": "Label only; the row itself is unchanged. Always false on Solana rows; may be absent on other rows", "type": "boolean" }, "hasUntrustedUsdBasis": { "description": "True when the USD cost basis is untrusted (a leg was booked with no USD mark): costBasisUsd, pnlUsd, realizedPnlUsd and pnlPercentage do not reflect a real basis, so mask them rather than render $0 / 0%; amountBoughtUsd, amountHeld and valueUsd are unaffected. Absent on rows that carry no verdict (for example balance-derived rows).", "type": "boolean" }, "hasUntrustedSolBasis": { "description": "True when the SOL (native) cost basis is untrusted: native-denominated basis and PnL figures do not reflect a real basis, so mask them. Absent on rows that carry no verdict (for example balance-derived rows).", "type": "boolean" }, "updatedAt": { "description": "block time of the position's last ledger leg as ISO — the RECENCY sort instant; the stored row's write clock only where the pair has no ledger row; absent on balance-hydrated rows", "nullable": true, "type": "string" }, "openedAt": { "description": "ISO instant the CURRENT position opened (re-stamped on re-entry, so the latest entry, not the lifetime first buy); absent when unknown and on exited and group rows — never a fallback to updatedAt. Anchors a position chart or 'held since' without walking the trade history", "type": "string" }, "amountSoldUsd": { "description": "Lifetime gross sell proceeds in USD (venue trades only); amountBoughtUsd + amountSoldUsd is the lifetime trade volume. Absent when no sell total is known — never 0", "type": "number" }, "tradeCount": { "description": "The wallet's lifetime venue-trade count on this mint (one per transaction carrying a trade leg; transfers excluded) — the exact figure for a transactions header without paging trades. Absent when no exact count is known: absent means unknown, never 0; a present 0 is exact", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastSlotIndexId": { "description": "26-digit slot(12) tx_index(6) ev(8) ledger cursor of the last folded leg; block number in the slot field on EVM; compare the 12-char prefix; absent = unknown", "type": "string" }, "potentialSpam": { "description": "/user-portfolio only; spam group = potentialSpam && !userMarkedNonSpam", "type": "boolean" }, "userMarkedNonSpam": { "description": "/user-portfolio only", "type": "boolean" }, "dustFloorFiltered": { "description": "/user-portfolio only, stamped on the owner's own authed read (a public read serves false); grouping hint: nothing is hidden and totals are untouched", "type": "boolean" }, "isNative": { "description": "/user-portfolio only: the row is a chain's native gas token, served under the bare \"native\" wire mint", "type": "boolean" }, "groupHolders": { "description": "Group-subject reads only; present-but-empty when no member currently holds", "type": "object", "properties": { "holders": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "amountHeld": { "type": "number", "description": "The member's open holdings summed across their wallets" } }, "required": [ "userId", "username", "profileImageUrl", "isVerified", "verifiedBadgeVisible", "amountHeld" ], "additionalProperties": false }, "description": "Sorted amountHeld desc, server-capped" }, "totalCount": { "type": "number", "description": "The uncapped figure" } }, "required": [ "holders", "totalCount" ], "additionalProperties": false }, "coin": { "description": "/user-portfolio only; null = no chain-matching record, never attached on native rows", "nullable": true, "type": "object", "properties": { "name": { "nullable": true, "type": "string" }, "symbol": { "nullable": true, "type": "string" }, "imageUri": { "nullable": true, "type": "string" }, "imageBackdrop": { "description": "Surface to paint behind imageUri when it is a bare mark on transparency: light for a dark mark, dark for a light one. null = paint the image as-is (an opaque tile, an unassessed image, no image, or any non-perp coin). Absent on routes that do not serve perp coin cards", "nullable": true, "type": "string", "enum": [ "light", "dark" ] }, "marketCapUsd": { "nullable": true, "type": "number" }, "totalSupply": { "nullable": true, "description": "UI-normalized supply (raw / 10^decimals) on the basis marketCapUsd is computed on: circulating supply when an EVM record carries one (it may exceed total), else total supply — implied unit price = marketCapUsd / totalSupply; null means do not derive a price from marketCapUsd", "type": "number" }, "protocol": { "nullable": true, "description": "An EVM coin's launchpad identity", "type": "string" }, "platform": { "nullable": true, "description": "Solana launchpad platform (`bonk`, `bags`, `believe`); null on EVM rows", "type": "string" }, "program": { "nullable": true, "description": "Solana program slug (`pump`, `meteora_dbc`, `raydium_launchpad`); null on EVM rows", "type": "string" }, "collectible": { "description": "ASSET_CLASS_NFT_LIKE rows only: the card (identity, grade, mark, insured value, buyback, listing); absent on every token row", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false } }, "required": [ "name", "symbol", "imageUri", "marketCapUsd", "totalSupply", "protocol", "platform", "program" ], "additionalProperties": false } }, "required": [ "coinMint", "chainId", "isExited", "walletAddress", "amountHeld", "pnlUsd", "pnlPercentage", "costBasisAmount", "costBasisUsd", "amountBoughtUsd", "amountBought", "callout", "tokenPriceUsd" ], "additionalProperties": false }, "description": "One row per requested mint the user has a position in; a group id serves the group's member-aggregate position per mint" } }, "required": [ "positions" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Get a user's position (total PnL + callout) in each of the given mints; a group id serves the group's member-aggregate position per mint (walletAddress null, no callout link)" } }, "/user-trades/{id}": { "get": { "operationId": "get_user_trades_by_id", "tags": [ "positions.read" ], "summary": "One page of an account's trades, newest first", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "positions.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "mint", "in": "query", "required": false, "schema": { "description": "Restrict to one token's trades (the position-sheet shape); omitted serves all mints", "type": "string" } }, { "name": "chainId", "in": "query", "required": false, "schema": { "description": "Omitted serves every covered chain (SVM and EVM: a raw wallet serves its own family, a user id the union of its CANONICAL wallets (SVM and EVM), a squad id the union of its active members' wallets)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "chain", "in": "query", "required": false, "schema": { "description": "ton:-239 (TON mainnet): serves the id's derived TON wallet's swaps on mint (the 48-char bounceable EQ form, required); a non-SVM id serves the empty page. starknet:SN_MAIN (Starknet mainnet): serves the id's swaps across every coin, the id itself a Starknet address (0x + 1 to 64 hex digits, any case; any other id is a 400, no user or squad id), mint is a 400; rows carry tx, mint and walletAddress as 0x + 64 lowercase hex. Either chain: keyed by chain alone (chainId is a 400), trades only (types=transfers is a 400), rows chainId 0 with amountSol null, coins empty (key a row's coin by (mint, chain)). near:mainnet: id is a Solana wallet (its derived 64-hex implicit account is read) or a raw NEAR account id (dotted or 64-hex); mint is optional, an account id when present (the position-sheet shape); keyed by chain alone (chainId is a 400), trades only (types=transfers is a 400), rows chainId null with amountSol null, coins carrying the NEAR coin card; any other id serves the empty page. On every chain trades may be empty while nextCursor is non-null (a bounded window of the wallet's trades is scanned per page): keep paging until nextCursor is null", "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Opaque keyset cursor from the previous page's nextCursor", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Rows per page.", "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "types", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "description": "Comma-separated row kinds on the wire; omitted = trades only, and rows carry kind only when this is set", "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "trades", "transfers" ] } } } ], "responses": { "200": { "description": "One page of an account's trades, newest first — id is a wallet, a user id, or a squad (group) id; a user id serves the union of its CANONICAL wallets (SVM and EVM), a squad the union of its active members' trades. mint narrows to one token (the position-sheet shape). types (CSV of trades|transfers) interleaves ledger transfer legs valued at the transfer-minute mark (amountUsd/priceUsd/amountSol each null independently when that leg is unpriced, never 0), each row then carrying kind; omitted = trades only, today's exact shape. chain=near:mainnet serves the id's NEAR account's swaps, every coin or mint's, rows chainId null. X-Degraded: trades-stale = a mint page served from its last complete copy, at most 120 s old, while a slow or degraded rebuild runs on.", "content": { "application/json": { "schema": { "type": "object", "properties": { "trades": { "type": "array", "items": { "type": "object", "properties": { "tx": { "type": "string", "description": "Transaction signature — not unique by itself: each fill of a multi-fill transaction is its own row" }, "isBuy": { "type": "boolean" }, "timestamp": { "nullable": true, "type": "string" }, "amountUsd": { "nullable": true, "type": "number" }, "baseAmount": { "nullable": true, "type": "number" }, "priceUsd": { "nullable": true, "type": "number" }, "mint": { "type": "string" }, "chainId": { "nullable": true, "description": "0 on a HyperCore or ton:-239 row, null on a near:mainnet row: key the token identity by (mint, chain) when it is null", "type": "number" }, "walletAddress": { "type": "string" }, "userId": { "nullable": true, "type": "string" }, "slotIndexId": { "type": "string", "description": "26-digit zero-padded chain-ordered id — the row's stable identity and same-second tiebreak" }, "amountSol": { "nullable": true, "description": "SOL notional of the fill, or on transfer rows baseAmount x the transfer-minute SOL mark; null when the source carries none", "type": "number" }, "kind": { "description": "Present only on filtered (?types=...) requests: 'transfer' = ledger transfer leg valued at the transfer-minute mark, 'trade' = swap fill", "type": "string", "enum": [ "trade", "transfer" ] }, "collectibleLeg": { "anyOf": [ { "type": "string", "enum": [ "pull", "buyback", "market_buy", "market_sale", "gift", "transfer", "redeem", "seize", "burn" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Absent on every token row, so a client that ignores it labels the row by its BUY/SELL/SEND/RECEIVE type. Known values: pull, buyback, market_buy, market_sale, gift, transfer, redeem, seize, burn" }, "collectible": { "description": "Card legs only (collectibleLeg set): the card block; absent on every token row and when the card lookup misses", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false } }, "required": [ "tx", "isBuy", "timestamp", "amountUsd", "baseAmount", "priceUsd", "mint", "chainId", "walletAddress", "userId", "slotIndexId", "amountSol" ], "additionalProperties": false }, "description": "Newest first" }, "traders": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "userName": { "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" } }, "required": [ "userId", "userName", "profileImage", "walletAddress", "isVerified", "verifiedBadgeVisible" ], "additionalProperties": false }, "description": "Distinct trader profiles behind this page's rows (a person request carries at most one)" }, "coins": { "type": "array", "items": { "type": "object", "properties": { "mint": { "type": "string" }, "chainId": { "nullable": true, "description": "0 on a HyperCore or ton:-239 row, null on a near:mainnet row: key the token identity by (mint, chain) when it is null", "type": "number" }, "name": { "nullable": true, "type": "string" }, "symbol": { "nullable": true, "type": "string" }, "image": { "nullable": true, "type": "string" } }, "required": [ "mint", "chainId", "name", "symbol", "image" ], "additionalProperties": false }, "description": "Token identity for this page's rows: one entry per distinct (mint, chainId), joined to trades by both (chainId null on a near:mainnet page: join by mint alone, identity from the NEAR coin card); a mint the security verdict hides is omitted, and a degraded verdict read serves no tail entry" }, "nextCursor": { "nullable": true, "description": "null when there are no more results", "type": "string" } }, "required": [ "trades", "traders", "coins", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "description": "Error payload on the envelope. Also the shared envelope at this status: a platform refusal, or a validation refusal whose `message` is a string array and whose `error` is the HTTP reason phrase.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "timestamp": { "type": "string" }, "path": { "type": "string" }, "error": { "type": "string", "enum": [ "API_KEY_RATE_LIMITED" ] }, "message": { "type": "string" }, "retryAfterMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Milliseconds until the bucket admits a request again" }, "limit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The ceiling that refused: the 60-second bucket (60 x the key's per-second rate), the daily limit, the per-IP failed-auth budget, or the per-IP lookup budget" }, "window": { "type": "string", "enum": [ "burst", "day", "auth", "lookup" ], "description": "Which ceiling refused: burst (the per-key 60-second bucket), day (the per-key UTC daily limit), auth (per-IP failed authentications, charged on failed outcomes only), lookup (per-IP budget of uncached key lookups)" } }, "required": [ "statusCode", "timestamp", "path", "error", "message", "retryAfterMs", "limit", "window" ] }, { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ] }, "timestamp": { "type": "string" }, "path": { "type": "string" }, "message": { "type": "string" }, "retryAfterMs": { "type": "number" } }, "required": [ "statusCode", "timestamp", "path", "message", "retryAfterMs" ], "description": "A request with no mint whose types contain transfers, over its per-IP budget (20 per minute, burst 40); Retry-After carries the wait. A mint-scoped request is never counted" }, { "$ref": "#/components/schemas/Error" } ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "One page of an account's trades, newest first — id is a wallet, a user id, or a squad (group) id; a user id serves the union of its CANONICAL wallets (SVM and EVM), a squad the union of its active members' trades. mint narrows to one token (the position-sheet shape). types (CSV of trades|transfers) interleaves ledger transfer legs valued at the transfer-minute mark (amountUsd/priceUsd/amountSol each null independently when that leg is unpriced, never 0), each row then carrying kind; omitted = trades only, today's exact shape. chain=near:mainnet serves the id's NEAR account's swaps, every coin or mint's, rows chainId null. X-Degraded: trades-stale = a mint page served from its last complete copy, at most 120 s old, while a slow or degraded rebuild runs on." } }, "/users": { "get": { "operationId": "get_users", "tags": [ "profiles.read" ], "summary": "List users", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "profiles.read", "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "List users", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "userId": { "type": "string" }, "username": { "nullable": true, "type": "string" }, "profile_image": { "nullable": true, "type": "string" }, "header_image_url": { "nullable": true, "type": "string" }, "avatar_decoration": { "description": "The owner's avatar decoration (border effect) PICK as a decoration key — `legendary`, `epic`, `none` (an explicit no-border), `achievement:` — never a url: the client owns the key -> artwork catalog. For the owner's chooser (which tile is selected); the border to draw is resolved_avatar_decoration. null or absent means no pick. Served on GET /users/{id} and POST /users/batch rows.", "nullable": true, "type": "string" }, "resolved_avatar_decoration": { "description": "The border to draw on this avatar, resolved from the owner's pick and achievements: the pick while still earned, else the rarest tier ring the achievements earn (`legendary`, `epic`); null means no border (an explicit `none` pick, or nothing earned). Same key grammar as avatar_decoration. Served on GET /users/{id} and POST /users/batch rows — never fetch a user's achievements to draw a border. A newly earned tier can take up to an hour to show to other viewers; the owner's own view updates immediately", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "person", "group" ] }, "member_count": { "type": "number" }, "group_badges": { "type": "array", "items": { "type": "object", "properties": { "group_id": { "type": "string" }, "username": { "type": "string" }, "profile_image_url": { "nullable": true, "type": "string" }, "role": { "anyOf": [ { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "UNSPECIFIED" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Known values: OWNER, ADMIN, MEMBER, UNSPECIFIED" } }, "required": [ "group_id", "username", "profile_image_url", "role" ], "additionalProperties": false } }, "bio": { "nullable": true, "type": "string" }, "followers": { "type": "number" }, "following": { "type": "number" }, "last_username_update_timestamp": { "description": "Unix epoch ms of the last username change; null when never renamed. Served by the single-profile read and on labelled-wallet search rows; absent from batch and hydrated search-v2 rows", "nullable": true, "type": "number" }, "x_username": { "nullable": true, "type": "string" }, "wallet_label": { "type": "string" }, "is_pump_user": { "type": "boolean" }, "is_banned": { "type": "boolean" }, "canonical_svm_wallet": { "type": "string" }, "canonical_evm_wallet": { "type": "string" }, "last_active_at": { "description": "ISO time of the account's latest authenticated request (~1 min granularity, kept for one day). Viewer-relative: served on GET /users/{id} and POST /users/batch rows to a signed-in viewer, for accounts the viewer follows and the viewer's own row, null otherwise (not followed, never seen, degraded read) — render null as unknown. Absent for anonymous callers, on the API host, and on every other row-serving read", "nullable": true, "type": "string" } }, "required": [ "address", "username", "profile_image", "bio", "followers", "following", "x_username" ], "additionalProperties": false } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/users/batch": { "post": { "operationId": "post_users_batch", "tags": [ "profiles.read" ], "summary": "Fetch users by addresses in batch", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "profiles.read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "addresses": { "maxItems": 100, "type": "array", "items": { "type": "string" } }, "forceFetch": { "type": "boolean" } }, "required": [ "addresses" ] } } } }, "responses": { "201": { "description": "Fetch users by addresses in batch", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "userId": { "type": "string" }, "username": { "nullable": true, "type": "string" }, "profile_image": { "nullable": true, "type": "string" }, "header_image_url": { "nullable": true, "type": "string" }, "avatar_decoration": { "description": "The owner's avatar decoration (border effect) PICK as a decoration key — `legendary`, `epic`, `none` (an explicit no-border), `achievement:` — never a url: the client owns the key -> artwork catalog. For the owner's chooser (which tile is selected); the border to draw is resolved_avatar_decoration. null or absent means no pick. Served on GET /users/{id} and POST /users/batch rows.", "nullable": true, "type": "string" }, "resolved_avatar_decoration": { "description": "The border to draw on this avatar, resolved from the owner's pick and achievements: the pick while still earned, else the rarest tier ring the achievements earn (`legendary`, `epic`); null means no border (an explicit `none` pick, or nothing earned). Same key grammar as avatar_decoration. Served on GET /users/{id} and POST /users/batch rows — never fetch a user's achievements to draw a border. A newly earned tier can take up to an hour to show to other viewers; the owner's own view updates immediately", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "person", "group" ] }, "member_count": { "type": "number" }, "group_badges": { "type": "array", "items": { "type": "object", "properties": { "group_id": { "type": "string" }, "username": { "type": "string" }, "profile_image_url": { "nullable": true, "type": "string" }, "role": { "anyOf": [ { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "UNSPECIFIED" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Known values: OWNER, ADMIN, MEMBER, UNSPECIFIED" } }, "required": [ "group_id", "username", "profile_image_url", "role" ], "additionalProperties": false } }, "bio": { "nullable": true, "type": "string" }, "followers": { "type": "number" }, "following": { "type": "number" }, "last_username_update_timestamp": { "description": "Unix epoch ms of the last username change; null when never renamed. Served by the single-profile read and on labelled-wallet search rows; absent from batch and hydrated search-v2 rows", "nullable": true, "type": "number" }, "x_username": { "nullable": true, "type": "string" }, "wallet_label": { "type": "string" }, "is_pump_user": { "type": "boolean" }, "is_banned": { "type": "boolean" }, "canonical_svm_wallet": { "type": "string" }, "canonical_evm_wallet": { "type": "string" }, "last_active_at": { "description": "ISO time of the account's latest authenticated request (~1 min granularity, kept for one day). Viewer-relative: served on GET /users/{id} and POST /users/batch rows to a signed-in viewer, for accounts the viewer follows and the viewer's own row, null otherwise (not followed, never seen, degraded read) — render null as unknown. Absent for anonymous callers, on the API host, and on every other row-serving read", "nullable": true, "type": "string" } }, "required": [ "address", "username", "profile_image", "bio", "followers", "following", "x_username" ], "additionalProperties": false } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/users/search-v2": { "get": { "operationId": "get_users_search_v2", "tags": [ "profiles.read" ], "summary": "Search users", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "profiles.read", "parameters": [ { "name": "searchTerm", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "includeLabelledWallets", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Search users (v2)", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "userId": { "type": "string" }, "username": { "nullable": true, "type": "string" }, "profile_image": { "nullable": true, "type": "string" }, "header_image_url": { "nullable": true, "type": "string" }, "avatar_decoration": { "description": "The owner's avatar decoration (border effect) PICK as a decoration key — `legendary`, `epic`, `none` (an explicit no-border), `achievement:` — never a url: the client owns the key -> artwork catalog. For the owner's chooser (which tile is selected); the border to draw is resolved_avatar_decoration. null or absent means no pick. Served on GET /users/{id} and POST /users/batch rows.", "nullable": true, "type": "string" }, "resolved_avatar_decoration": { "description": "The border to draw on this avatar, resolved from the owner's pick and achievements: the pick while still earned, else the rarest tier ring the achievements earn (`legendary`, `epic`); null means no border (an explicit `none` pick, or nothing earned). Same key grammar as avatar_decoration. Served on GET /users/{id} and POST /users/batch rows — never fetch a user's achievements to draw a border. A newly earned tier can take up to an hour to show to other viewers; the owner's own view updates immediately", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "person", "group" ] }, "member_count": { "type": "number" }, "group_badges": { "type": "array", "items": { "type": "object", "properties": { "group_id": { "type": "string" }, "username": { "type": "string" }, "profile_image_url": { "nullable": true, "type": "string" }, "role": { "anyOf": [ { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "UNSPECIFIED" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Known values: OWNER, ADMIN, MEMBER, UNSPECIFIED" } }, "required": [ "group_id", "username", "profile_image_url", "role" ], "additionalProperties": false } }, "bio": { "nullable": true, "type": "string" }, "followers": { "type": "number" }, "following": { "type": "number" }, "last_username_update_timestamp": { "description": "Unix epoch ms of the last username change; null when never renamed. Served by the single-profile read and on labelled-wallet search rows; absent from batch and hydrated search-v2 rows", "nullable": true, "type": "number" }, "x_username": { "nullable": true, "type": "string" }, "wallet_label": { "type": "string" }, "is_pump_user": { "type": "boolean" }, "is_banned": { "type": "boolean" }, "canonical_svm_wallet": { "type": "string" }, "canonical_evm_wallet": { "type": "string" }, "last_active_at": { "description": "ISO time of the account's latest authenticated request (~1 min granularity, kept for one day). Viewer-relative: served on GET /users/{id} and POST /users/batch rows to a signed-in viewer, for accounts the viewer follows and the viewer's own row, null otherwise (not followed, never seen, degraded read) — render null as unknown. Absent for anonymous callers, on the API host, and on every other row-serving read", "nullable": true, "type": "string" } }, "required": [ "address", "username", "profile_image", "bio", "followers", "following", "x_username" ], "additionalProperties": false } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "Search users (v2)" } }, "/users/username-exists/{username}": { "get": { "operationId": "get_users_username_exists_by_username", "tags": [ "profiles.read" ], "summary": "Check if a username exists", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "profiles.read", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Check if a username exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "exists_flag": { "type": "boolean", "description": "Whether the handle is already reserved. The check has no viewer, so the caller's own current handle reads true, as does a banned or unclaimed owner's handle. Always present." } }, "required": [ "exists_flag" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/users/{address}/achievements": { "get": { "operationId": "get_users_by_address_achievements", "tags": [ "profiles.read" ], "summary": "A user's achievement unlocks plus live progress on…", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "profiles.read", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A user's achievement unlocks plus live progress on every track. Unlock facts are public-profile data; `seen` is viewer-relative, served only to the signed-in owner and absent on the API host.", "content": { "application/json": { "schema": { "type": "object", "properties": { "achievements": { "type": "array", "items": { "type": "object", "properties": { "achievementId": { "type": "string" }, "unlockedAt": { "nullable": true, "description": "ISO-8601 grant time.", "type": "string" }, "value": { "nullable": true, "description": "Metric value frozen at grant time; null for grants whose rule has no scalar metric.", "type": "number" }, "seen": { "type": "boolean", "description": "Whether the owner has acknowledged the unlock. Always false for anonymous and third-party viewers." }, "holderCount": { "nullable": true, "description": "Population: how many users hold this achievement, the subject included, as of a snapshot a few minutes old (never below 1 for a holder).", "type": "number" }, "holderPercent": { "nullable": true, "description": "holderCount as a percentage (0-100) of all accounts, against the planner estimate of the user table. Null whenever holderCount is, and when the account estimate is unavailable.", "type": "number" }, "evidence": { "nullable": true, "description": "What earned the unlock: the callout that reached a multiple tier, or the closed leaderboard periods behind a board badge.", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "callout", "leaderboard" ], "description": "Which arm is populated: \"callout\" for the multiple track, \"leaderboard\" for the board track." }, "callout": { "nullable": true, "description": "Set when kind is \"callout\"; null otherwise.", "type": "object", "properties": { "calloutId": { "type": "string", "description": "The callout credited with the tier (UUID)." }, "mint": { "type": "string", "description": "Token address the callout was made on." }, "multiple": { "type": "number", "description": "The callout's whole-number peak multiple at read time; at least the tier's threshold." }, "calledOutAt": { "nullable": true, "description": "ISO-8601 time the callout was made.", "type": "string" }, "peakedAt": { "nullable": true, "description": "ISO-8601 time the peak multiple was last raised; null when the peak predates tracking.", "type": "string" } }, "required": [ "calloutId", "mint", "multiple", "calledOutAt", "peakedAt" ], "additionalProperties": false }, "leaderboard": { "nullable": true, "description": "Set when kind is \"leaderboard\"; null otherwise.", "type": "object", "properties": { "finishes": { "type": "array", "items": { "type": "object", "properties": { "periodType": { "type": "string", "enum": [ "weekly", "monthly" ], "description": "Which board the finish was on." }, "periodLabel": { "type": "string", "description": "ISO week label (\"2026-W37\") or calendar month (\"2026-08\")." }, "rank": { "type": "number", "description": "1-based rank in that period." }, "periodStart": { "nullable": true, "description": "ISO-8601 UTC start of the period (Monday 00:00 for a week, the 1st for a month).", "type": "string" } }, "required": [ "periodType", "periodLabel", "rank", "periodStart" ], "additionalProperties": false }, "description": "The closed leaderboard periods that satisfied the badge's rule, chronological and capped at the rule's own count. Never empty." } }, "required": [ "finishes" ], "additionalProperties": false } }, "required": [ "kind", "callout", "leaderboard" ], "additionalProperties": false } }, "required": [ "achievementId", "unlockedAt", "value", "seen", "holderCount", "holderPercent", "evidence" ], "additionalProperties": false }, "description": "Unlocked achievements, ordered by catalog sortOrder." }, "progress": { "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string" }, "currentValue": { "type": "number" }, "nextThreshold": { "nullable": true, "description": "Threshold of the next locked tier; null when the track is maxed out.", "type": "number" }, "nextAchievementId": { "nullable": true, "description": "Catalog id of the next locked tier; null when the track is maxed out.", "type": "string" }, "previousThreshold": { "nullable": true, "description": "Threshold of the highest tier already reached (the floor of the current rung); null when no tier is reached yet. A bar renders as (currentValue - previousThreshold) / (nextThreshold - previousThreshold).", "type": "number" }, "previousAchievementId": { "nullable": true, "description": "Catalog id of the highest tier already reached; null when none is.", "type": "string" } }, "required": [ "metric", "currentValue", "nextThreshold", "nextAchievementId", "previousThreshold", "previousAchievementId" ], "additionalProperties": false }, "description": "Trader-family live values are deliberately absent." }, "catalogVersion": { "type": "string", "description": "Catalog version the unlocks were resolved against; empty when the response is a degraded fallback." } }, "required": [ "achievements", "progress", "catalogVersion" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "A user's achievement unlocks plus live progress on every track. Unlock facts are public-profile data; `seen` is viewer-relative, served only to the signed-in owner and absent on the API host." } }, "/users/{address}/callout-stats": { "get": { "operationId": "get_users_by_address_callout_stats", "tags": [ "profiles.read" ], "summary": "A user's callout performance stats", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "profiles.read", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A user's callout performance stats (peak-multiple hit rates, averages, time to peak, distribution), every window (daily/weekly/monthly/allTime, plus lastRound = callouts created between the two newest executed payout round cuts) in one response. Public like the callout list itself — derived from publicly visible callouts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "daily": { "description": "The daily window. Absent only when stats are unavailable (the route fails open to {} rather than 5xx) or predate windowed stats; present with zeros for a user with no callouts. When present every field is populated.", "type": "object", "properties": { "totalCallouts": { "type": "number" }, "calloutsWithMultiple": { "type": "number" }, "twoXPercent": { "type": "number" }, "onePointFiveXPercent": { "type": "number" }, "onePointTwoXPercent": { "type": "number" }, "averageMultiple": { "type": "number" }, "medianMultiple": { "type": "number" }, "averageTimeToPeakMs": { "nullable": true, "description": "Whole milliseconds; null when no callout in the window recorded a peak.", "type": "number" }, "tailBuyers": { "nullable": true, "description": "Sum over the window's callouts (those created after tail tracking went live) of distinct users whose buy was attributed to the callout; null when none qualifies.", "type": "number" }, "tailCallouts": { "nullable": true, "description": "Callouts in the window with tail tracking, the denominator of tailBuyers; null when 0.", "type": "number" }, "tailCallouts1h": { "nullable": true, "description": "Callouts in the window whose 1 h tailing-cohort PnL is served; null when 0.", "type": "number" }, "tailCohort1h": { "nullable": true, "description": "Users tailPnl1hUsd covers (tailers whose first attributed buy landed before +1 h and whose window priced); null when no callout is served.", "type": "number" }, "tailPnl1hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +1 h], summed over served callouts; null when none.", "type": "number" }, "tailCallouts4h": { "nullable": true, "description": "Callouts in the window whose 4 h tailing-cohort PnL is served; null when 0.", "type": "number" }, "tailCohort4h": { "nullable": true, "description": "Users tailPnl4hUsd covers (tailers whose first attributed buy landed before +4 h and whose window priced); null when no callout is served.", "type": "number" }, "tailPnl4hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +4 h], summed over served callouts; null when none.", "type": "number" }, "tailCallouts24h": { "nullable": true, "description": "Callouts in the window whose 24 h tailing-cohort PnL is served; null when 0.", "type": "number" }, "tailCohort24h": { "nullable": true, "description": "Users tailPnl24hUsd covers (tailers whose first attributed buy landed before +24 h and whose window priced); null when no callout is served.", "type": "number" }, "tailPnl24hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +24 h], summed over served callouts; null when none.", "type": "number" }, "tailUniqueBuyers": { "nullable": true, "description": "Distinct wallets that tailed at least one of the window's callouts (one wallet tailing five callouts counts once); always <= tailBuyers; null when unknown.", "type": "number" }, "tailVolumeUsd": { "nullable": true, "description": "USD of the tailers' attributed buys through the window's callouts (SOL at the current SOL price plus USDC), author and reply-author self-buys excluded; null when unknown or unpriced.", "type": "number" }, "tailPnlHist1h": { "nullable": true, "description": "Per-tailer 1 h PnL histogram summed over served callouts (server-defined buckets); null when no callout is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailPnlHist4h": { "nullable": true, "description": "Per-tailer 4 h PnL histogram summed over served callouts (server-defined buckets); null when no callout is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailPnlHist24h": { "nullable": true, "description": "Per-tailer 24 h PnL histogram summed over served callouts (server-defined buckets); null when no callout is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAth1hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 1 h tailing cohort summed over the window's callouts whose 1 h ATH arm is served (per tailer max(0, in-window bought amount x highest outlier-screened 1 m candle high - in-window buy spend) over its own window [first in-window buy, +1 h]); >= 0; null when no callout in the window is served or unavailable.", "type": "number" }, "tailAth4hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 4 h tailing cohort summed over the window's callouts whose 4 h ATH arm is served (per tailer max(0, in-window bought amount x highest outlier-screened 1 m candle high - in-window buy spend) over its own window [first in-window buy, +4 h]); >= 0; null when no callout in the window is served or unavailable.", "type": "number" }, "tailAth24hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 24 h tailing cohort summed over the window's callouts whose 24 h ATH arm is served (per tailer max(0, in-window bought amount x highest outlier-screened 5 m candle high - in-window buy spend) over its own window [first in-window buy, +24 h]); >= 0; null when no callout in the window is served or unavailable.", "type": "number" }, "tailAthHist1h": { "nullable": true, "description": "Per-tailer 1 h best-case-exit PnL histogram (tailer-anchored window, 1 m candle highs) summed elementwise over served callouts; five buckets from 0 up (first min 0, last max null), callouts = how many contributed; null when no callout carries one, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAthHist4h": { "nullable": true, "description": "Per-tailer 4 h best-case-exit PnL histogram (tailer-anchored window, 1 m candle highs) summed elementwise over served callouts; five buckets from 0 up (first min 0, last max null), callouts = how many contributed; null when no callout carries one, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAthHist24h": { "nullable": true, "description": "Per-tailer 24 h best-case-exit PnL histogram (tailer-anchored window, 5 m candle highs) summed elementwise over served callouts; five buckets from 0 up (first min 0, last max null), callouts = how many contributed; null when no callout carries one, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "distribution": { "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number", "description": "Inclusive lower bound of the bucket's multiple range." }, "max": { "nullable": true, "description": "Exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "count": { "type": "number" } }, "required": [ "min", "max", "count" ], "additionalProperties": false }, "description": "Server-defined buckets; [] for a user with no callouts." }, "ranks": { "description": "Percentile ranks of this window's tail stats against every author in the same window.", "nullable": true, "type": "object", "properties": { "tailBuyers": { "description": "Raw percentile 0..100 of tailBuyers among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailVolumeUsd": { "description": "Raw percentile 0..100 of tailVolumeUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailCohort1h": { "description": "Raw percentile 0..100 of tailCohort1h among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailCohort4h": { "description": "Raw percentile 0..100 of tailCohort4h among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailCohort24h": { "description": "Raw percentile 0..100 of tailCohort24h among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailPnl1hUsd": { "description": "Raw percentile 0..100 of tailPnl1hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailPnl4hUsd": { "description": "Raw percentile 0..100 of tailPnl4hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailPnl24hUsd": { "description": "Raw percentile 0..100 of tailPnl24hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailAth1hUsd": { "description": "Raw percentile 0..100 of tailAth1hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailAth4hUsd": { "description": "Raw percentile 0..100 of tailAth4hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailAth24hUsd": { "description": "Raw percentile 0..100 of tailAth24hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "population": { "description": "Authors ranked in this window (the population every rank is against).", "nullable": true, "type": "number" }, "generatedAt": { "description": "Epoch ms at which the window's rank ladder was built.", "nullable": true, "type": "number" } }, "additionalProperties": false } }, "required": [ "totalCallouts", "calloutsWithMultiple", "twoXPercent", "onePointFiveXPercent", "onePointTwoXPercent", "averageMultiple", "medianMultiple", "averageTimeToPeakMs", "tailBuyers", "tailCallouts", "tailCallouts1h", "tailCohort1h", "tailPnl1hUsd", "tailCallouts4h", "tailCohort4h", "tailPnl4hUsd", "tailCallouts24h", "tailCohort24h", "tailPnl24hUsd", "tailUniqueBuyers", "tailVolumeUsd", "tailPnlHist1h", "tailPnlHist4h", "tailPnlHist24h", "tailAth1hUsd", "tailAth4hUsd", "tailAth24hUsd", "tailAthHist1h", "tailAthHist4h", "tailAthHist24h", "distribution" ], "additionalProperties": false }, "weekly": { "description": "The weekly window. Absent only when stats are unavailable (the route fails open to {} rather than 5xx) or predate windowed stats; present with zeros for a user with no callouts. When present every field is populated.", "type": "object", "properties": { "totalCallouts": { "type": "number" }, "calloutsWithMultiple": { "type": "number" }, "twoXPercent": { "type": "number" }, "onePointFiveXPercent": { "type": "number" }, "onePointTwoXPercent": { "type": "number" }, "averageMultiple": { "type": "number" }, "medianMultiple": { "type": "number" }, "averageTimeToPeakMs": { "nullable": true, "description": "Whole milliseconds; null when no callout in the window recorded a peak.", "type": "number" }, "tailBuyers": { "nullable": true, "description": "Sum over the window's callouts (those created after tail tracking went live) of distinct users whose buy was attributed to the callout; null when none qualifies.", "type": "number" }, "tailCallouts": { "nullable": true, "description": "Callouts in the window with tail tracking, the denominator of tailBuyers; null when 0.", "type": "number" }, "tailCallouts1h": { "nullable": true, "description": "Callouts in the window whose 1 h tailing-cohort PnL is served; null when 0.", "type": "number" }, "tailCohort1h": { "nullable": true, "description": "Users tailPnl1hUsd covers (tailers whose first attributed buy landed before +1 h and whose window priced); null when no callout is served.", "type": "number" }, "tailPnl1hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +1 h], summed over served callouts; null when none.", "type": "number" }, "tailCallouts4h": { "nullable": true, "description": "Callouts in the window whose 4 h tailing-cohort PnL is served; null when 0.", "type": "number" }, "tailCohort4h": { "nullable": true, "description": "Users tailPnl4hUsd covers (tailers whose first attributed buy landed before +4 h and whose window priced); null when no callout is served.", "type": "number" }, "tailPnl4hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +4 h], summed over served callouts; null when none.", "type": "number" }, "tailCallouts24h": { "nullable": true, "description": "Callouts in the window whose 24 h tailing-cohort PnL is served; null when 0.", "type": "number" }, "tailCohort24h": { "nullable": true, "description": "Users tailPnl24hUsd covers (tailers whose first attributed buy landed before +24 h and whose window priced); null when no callout is served.", "type": "number" }, "tailPnl24hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +24 h], summed over served callouts; null when none.", "type": "number" }, "tailUniqueBuyers": { "nullable": true, "description": "Distinct wallets that tailed at least one of the window's callouts (one wallet tailing five callouts counts once); always <= tailBuyers; null when unknown.", "type": "number" }, "tailVolumeUsd": { "nullable": true, "description": "USD of the tailers' attributed buys through the window's callouts (SOL at the current SOL price plus USDC), author and reply-author self-buys excluded; null when unknown or unpriced.", "type": "number" }, "tailPnlHist1h": { "nullable": true, "description": "Per-tailer 1 h PnL histogram summed over served callouts (server-defined buckets); null when no callout is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailPnlHist4h": { "nullable": true, "description": "Per-tailer 4 h PnL histogram summed over served callouts (server-defined buckets); null when no callout is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailPnlHist24h": { "nullable": true, "description": "Per-tailer 24 h PnL histogram summed over served callouts (server-defined buckets); null when no callout is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAth1hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 1 h tailing cohort summed over the window's callouts whose 1 h ATH arm is served (per tailer max(0, in-window bought amount x highest outlier-screened 1 m candle high - in-window buy spend) over its own window [first in-window buy, +1 h]); >= 0; null when no callout in the window is served or unavailable.", "type": "number" }, "tailAth4hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 4 h tailing cohort summed over the window's callouts whose 4 h ATH arm is served (per tailer max(0, in-window bought amount x highest outlier-screened 1 m candle high - in-window buy spend) over its own window [first in-window buy, +4 h]); >= 0; null when no callout in the window is served or unavailable.", "type": "number" }, "tailAth24hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 24 h tailing cohort summed over the window's callouts whose 24 h ATH arm is served (per tailer max(0, in-window bought amount x highest outlier-screened 5 m candle high - in-window buy spend) over its own window [first in-window buy, +24 h]); >= 0; null when no callout in the window is served or unavailable.", "type": "number" }, "tailAthHist1h": { "nullable": true, "description": "Per-tailer 1 h best-case-exit PnL histogram (tailer-anchored window, 1 m candle highs) summed elementwise over served callouts; five buckets from 0 up (first min 0, last max null), callouts = how many contributed; null when no callout carries one, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAthHist4h": { "nullable": true, "description": "Per-tailer 4 h best-case-exit PnL histogram (tailer-anchored window, 1 m candle highs) summed elementwise over served callouts; five buckets from 0 up (first min 0, last max null), callouts = how many contributed; null when no callout carries one, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAthHist24h": { "nullable": true, "description": "Per-tailer 24 h best-case-exit PnL histogram (tailer-anchored window, 5 m candle highs) summed elementwise over served callouts; five buckets from 0 up (first min 0, last max null), callouts = how many contributed; null when no callout carries one, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "distribution": { "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number", "description": "Inclusive lower bound of the bucket's multiple range." }, "max": { "nullable": true, "description": "Exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "count": { "type": "number" } }, "required": [ "min", "max", "count" ], "additionalProperties": false }, "description": "Server-defined buckets; [] for a user with no callouts." }, "ranks": { "description": "Percentile ranks of this window's tail stats against every author in the same window.", "nullable": true, "type": "object", "properties": { "tailBuyers": { "description": "Raw percentile 0..100 of tailBuyers among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailVolumeUsd": { "description": "Raw percentile 0..100 of tailVolumeUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailCohort1h": { "description": "Raw percentile 0..100 of tailCohort1h among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailCohort4h": { "description": "Raw percentile 0..100 of tailCohort4h among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailCohort24h": { "description": "Raw percentile 0..100 of tailCohort24h among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailPnl1hUsd": { "description": "Raw percentile 0..100 of tailPnl1hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailPnl4hUsd": { "description": "Raw percentile 0..100 of tailPnl4hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailPnl24hUsd": { "description": "Raw percentile 0..100 of tailPnl24hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailAth1hUsd": { "description": "Raw percentile 0..100 of tailAth1hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailAth4hUsd": { "description": "Raw percentile 0..100 of tailAth4hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailAth24hUsd": { "description": "Raw percentile 0..100 of tailAth24hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "population": { "description": "Authors ranked in this window (the population every rank is against).", "nullable": true, "type": "number" }, "generatedAt": { "description": "Epoch ms at which the window's rank ladder was built.", "nullable": true, "type": "number" } }, "additionalProperties": false } }, "required": [ "totalCallouts", "calloutsWithMultiple", "twoXPercent", "onePointFiveXPercent", "onePointTwoXPercent", "averageMultiple", "medianMultiple", "averageTimeToPeakMs", "tailBuyers", "tailCallouts", "tailCallouts1h", "tailCohort1h", "tailPnl1hUsd", "tailCallouts4h", "tailCohort4h", "tailPnl4hUsd", "tailCallouts24h", "tailCohort24h", "tailPnl24hUsd", "tailUniqueBuyers", "tailVolumeUsd", "tailPnlHist1h", "tailPnlHist4h", "tailPnlHist24h", "tailAth1hUsd", "tailAth4hUsd", "tailAth24hUsd", "tailAthHist1h", "tailAthHist4h", "tailAthHist24h", "distribution" ], "additionalProperties": false }, "monthly": { "description": "The monthly window. Absent only when stats are unavailable (the route fails open to {} rather than 5xx) or predate windowed stats; present with zeros for a user with no callouts. When present every field is populated.", "type": "object", "properties": { "totalCallouts": { "type": "number" }, "calloutsWithMultiple": { "type": "number" }, "twoXPercent": { "type": "number" }, "onePointFiveXPercent": { "type": "number" }, "onePointTwoXPercent": { "type": "number" }, "averageMultiple": { "type": "number" }, "medianMultiple": { "type": "number" }, "averageTimeToPeakMs": { "nullable": true, "description": "Whole milliseconds; null when no callout in the window recorded a peak.", "type": "number" }, "tailBuyers": { "nullable": true, "description": "Sum over the window's callouts (those created after tail tracking went live) of distinct users whose buy was attributed to the callout; null when none qualifies.", "type": "number" }, "tailCallouts": { "nullable": true, "description": "Callouts in the window with tail tracking, the denominator of tailBuyers; null when 0.", "type": "number" }, "tailCallouts1h": { "nullable": true, "description": "Callouts in the window whose 1 h tailing-cohort PnL is served; null when 0.", "type": "number" }, "tailCohort1h": { "nullable": true, "description": "Users tailPnl1hUsd covers (tailers whose first attributed buy landed before +1 h and whose window priced); null when no callout is served.", "type": "number" }, "tailPnl1hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +1 h], summed over served callouts; null when none.", "type": "number" }, "tailCallouts4h": { "nullable": true, "description": "Callouts in the window whose 4 h tailing-cohort PnL is served; null when 0.", "type": "number" }, "tailCohort4h": { "nullable": true, "description": "Users tailPnl4hUsd covers (tailers whose first attributed buy landed before +4 h and whose window priced); null when no callout is served.", "type": "number" }, "tailPnl4hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +4 h], summed over served callouts; null when none.", "type": "number" }, "tailCallouts24h": { "nullable": true, "description": "Callouts in the window whose 24 h tailing-cohort PnL is served; null when 0.", "type": "number" }, "tailCohort24h": { "nullable": true, "description": "Users tailPnl24hUsd covers (tailers whose first attributed buy landed before +24 h and whose window priced); null when no callout is served.", "type": "number" }, "tailPnl24hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +24 h], summed over served callouts; null when none.", "type": "number" }, "tailUniqueBuyers": { "nullable": true, "description": "Distinct wallets that tailed at least one of the window's callouts (one wallet tailing five callouts counts once); always <= tailBuyers; null when unknown.", "type": "number" }, "tailVolumeUsd": { "nullable": true, "description": "USD of the tailers' attributed buys through the window's callouts (SOL at the current SOL price plus USDC), author and reply-author self-buys excluded; null when unknown or unpriced.", "type": "number" }, "tailPnlHist1h": { "nullable": true, "description": "Per-tailer 1 h PnL histogram summed over served callouts (server-defined buckets); null when no callout is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailPnlHist4h": { "nullable": true, "description": "Per-tailer 4 h PnL histogram summed over served callouts (server-defined buckets); null when no callout is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailPnlHist24h": { "nullable": true, "description": "Per-tailer 24 h PnL histogram summed over served callouts (server-defined buckets); null when no callout is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAth1hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 1 h tailing cohort summed over the window's callouts whose 1 h ATH arm is served (per tailer max(0, in-window bought amount x highest outlier-screened 1 m candle high - in-window buy spend) over its own window [first in-window buy, +1 h]); >= 0; null when no callout in the window is served or unavailable.", "type": "number" }, "tailAth4hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 4 h tailing cohort summed over the window's callouts whose 4 h ATH arm is served (per tailer max(0, in-window bought amount x highest outlier-screened 1 m candle high - in-window buy spend) over its own window [first in-window buy, +4 h]); >= 0; null when no callout in the window is served or unavailable.", "type": "number" }, "tailAth24hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 24 h tailing cohort summed over the window's callouts whose 24 h ATH arm is served (per tailer max(0, in-window bought amount x highest outlier-screened 5 m candle high - in-window buy spend) over its own window [first in-window buy, +24 h]); >= 0; null when no callout in the window is served or unavailable.", "type": "number" }, "tailAthHist1h": { "nullable": true, "description": "Per-tailer 1 h best-case-exit PnL histogram (tailer-anchored window, 1 m candle highs) summed elementwise over served callouts; five buckets from 0 up (first min 0, last max null), callouts = how many contributed; null when no callout carries one, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAthHist4h": { "nullable": true, "description": "Per-tailer 4 h best-case-exit PnL histogram (tailer-anchored window, 1 m candle highs) summed elementwise over served callouts; five buckets from 0 up (first min 0, last max null), callouts = how many contributed; null when no callout carries one, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAthHist24h": { "nullable": true, "description": "Per-tailer 24 h best-case-exit PnL histogram (tailer-anchored window, 5 m candle highs) summed elementwise over served callouts; five buckets from 0 up (first min 0, last max null), callouts = how many contributed; null when no callout carries one, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "distribution": { "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number", "description": "Inclusive lower bound of the bucket's multiple range." }, "max": { "nullable": true, "description": "Exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "count": { "type": "number" } }, "required": [ "min", "max", "count" ], "additionalProperties": false }, "description": "Server-defined buckets; [] for a user with no callouts." }, "ranks": { "description": "Percentile ranks of this window's tail stats against every author in the same window.", "nullable": true, "type": "object", "properties": { "tailBuyers": { "description": "Raw percentile 0..100 of tailBuyers among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailVolumeUsd": { "description": "Raw percentile 0..100 of tailVolumeUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailCohort1h": { "description": "Raw percentile 0..100 of tailCohort1h among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailCohort4h": { "description": "Raw percentile 0..100 of tailCohort4h among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailCohort24h": { "description": "Raw percentile 0..100 of tailCohort24h among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailPnl1hUsd": { "description": "Raw percentile 0..100 of tailPnl1hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailPnl4hUsd": { "description": "Raw percentile 0..100 of tailPnl4hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailPnl24hUsd": { "description": "Raw percentile 0..100 of tailPnl24hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailAth1hUsd": { "description": "Raw percentile 0..100 of tailAth1hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailAth4hUsd": { "description": "Raw percentile 0..100 of tailAth4hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailAth24hUsd": { "description": "Raw percentile 0..100 of tailAth24hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "population": { "description": "Authors ranked in this window (the population every rank is against).", "nullable": true, "type": "number" }, "generatedAt": { "description": "Epoch ms at which the window's rank ladder was built.", "nullable": true, "type": "number" } }, "additionalProperties": false } }, "required": [ "totalCallouts", "calloutsWithMultiple", "twoXPercent", "onePointFiveXPercent", "onePointTwoXPercent", "averageMultiple", "medianMultiple", "averageTimeToPeakMs", "tailBuyers", "tailCallouts", "tailCallouts1h", "tailCohort1h", "tailPnl1hUsd", "tailCallouts4h", "tailCohort4h", "tailPnl4hUsd", "tailCallouts24h", "tailCohort24h", "tailPnl24hUsd", "tailUniqueBuyers", "tailVolumeUsd", "tailPnlHist1h", "tailPnlHist4h", "tailPnlHist24h", "tailAth1hUsd", "tailAth4hUsd", "tailAth24hUsd", "tailAthHist1h", "tailAthHist4h", "tailAthHist24h", "distribution" ], "additionalProperties": false }, "allTime": { "description": "The all-time window. Absent only when stats are unavailable (the route fails open to {} rather than 5xx) or predate windowed stats; present with zeros for a user with no callouts. When present every field is populated.", "type": "object", "properties": { "totalCallouts": { "type": "number" }, "calloutsWithMultiple": { "type": "number" }, "twoXPercent": { "type": "number" }, "onePointFiveXPercent": { "type": "number" }, "onePointTwoXPercent": { "type": "number" }, "averageMultiple": { "type": "number" }, "medianMultiple": { "type": "number" }, "averageTimeToPeakMs": { "nullable": true, "description": "Whole milliseconds; null when no callout in the window recorded a peak.", "type": "number" }, "tailBuyers": { "nullable": true, "description": "Sum over the window's callouts (those created after tail tracking went live) of distinct users whose buy was attributed to the callout; null when none qualifies.", "type": "number" }, "tailCallouts": { "nullable": true, "description": "Callouts in the window with tail tracking, the denominator of tailBuyers; null when 0.", "type": "number" }, "tailCallouts1h": { "nullable": true, "description": "Callouts in the window whose 1 h tailing-cohort PnL is served; null when 0.", "type": "number" }, "tailCohort1h": { "nullable": true, "description": "Users tailPnl1hUsd covers (tailers whose first attributed buy landed before +1 h and whose window priced); null when no callout is served.", "type": "number" }, "tailPnl1hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +1 h], summed over served callouts; null when none.", "type": "number" }, "tailCallouts4h": { "nullable": true, "description": "Callouts in the window whose 4 h tailing-cohort PnL is served; null when 0.", "type": "number" }, "tailCohort4h": { "nullable": true, "description": "Users tailPnl4hUsd covers (tailers whose first attributed buy landed before +4 h and whose window priced); null when no callout is served.", "type": "number" }, "tailPnl4hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +4 h], summed over served callouts; null when none.", "type": "number" }, "tailCallouts24h": { "nullable": true, "description": "Callouts in the window whose 24 h tailing-cohort PnL is served; null when 0.", "type": "number" }, "tailCohort24h": { "nullable": true, "description": "Users tailPnl24hUsd covers (tailers whose first attributed buy landed before +24 h and whose window priced); null when no callout is served.", "type": "number" }, "tailPnl24hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +24 h], summed over served callouts; null when none.", "type": "number" }, "tailUniqueBuyers": { "nullable": true, "description": "Distinct wallets that tailed at least one of the window's callouts (one wallet tailing five callouts counts once); always <= tailBuyers; null when unknown.", "type": "number" }, "tailVolumeUsd": { "nullable": true, "description": "USD of the tailers' attributed buys through the window's callouts (SOL at the current SOL price plus USDC), author and reply-author self-buys excluded; null when unknown or unpriced.", "type": "number" }, "tailPnlHist1h": { "nullable": true, "description": "Per-tailer 1 h PnL histogram summed over served callouts (server-defined buckets); null when no callout is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailPnlHist4h": { "nullable": true, "description": "Per-tailer 4 h PnL histogram summed over served callouts (server-defined buckets); null when no callout is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailPnlHist24h": { "nullable": true, "description": "Per-tailer 24 h PnL histogram summed over served callouts (server-defined buckets); null when no callout is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAth1hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 1 h tailing cohort summed over the window's callouts whose 1 h ATH arm is served (per tailer max(0, in-window bought amount x highest outlier-screened 1 m candle high - in-window buy spend) over its own window [first in-window buy, +1 h]); >= 0; null when no callout in the window is served or unavailable.", "type": "number" }, "tailAth4hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 4 h tailing cohort summed over the window's callouts whose 4 h ATH arm is served (per tailer max(0, in-window bought amount x highest outlier-screened 1 m candle high - in-window buy spend) over its own window [first in-window buy, +4 h]); >= 0; null when no callout in the window is served or unavailable.", "type": "number" }, "tailAth24hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 24 h tailing cohort summed over the window's callouts whose 24 h ATH arm is served (per tailer max(0, in-window bought amount x highest outlier-screened 5 m candle high - in-window buy spend) over its own window [first in-window buy, +24 h]); >= 0; null when no callout in the window is served or unavailable.", "type": "number" }, "tailAthHist1h": { "nullable": true, "description": "Per-tailer 1 h best-case-exit PnL histogram (tailer-anchored window, 1 m candle highs) summed elementwise over served callouts; five buckets from 0 up (first min 0, last max null), callouts = how many contributed; null when no callout carries one, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAthHist4h": { "nullable": true, "description": "Per-tailer 4 h best-case-exit PnL histogram (tailer-anchored window, 1 m candle highs) summed elementwise over served callouts; five buckets from 0 up (first min 0, last max null), callouts = how many contributed; null when no callout carries one, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAthHist24h": { "nullable": true, "description": "Per-tailer 24 h best-case-exit PnL histogram (tailer-anchored window, 5 m candle highs) summed elementwise over served callouts; five buckets from 0 up (first min 0, last max null), callouts = how many contributed; null when no callout carries one, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "distribution": { "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number", "description": "Inclusive lower bound of the bucket's multiple range." }, "max": { "nullable": true, "description": "Exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "count": { "type": "number" } }, "required": [ "min", "max", "count" ], "additionalProperties": false }, "description": "Server-defined buckets; [] for a user with no callouts." }, "ranks": { "description": "Percentile ranks of this window's tail stats against every author in the same window.", "nullable": true, "type": "object", "properties": { "tailBuyers": { "description": "Raw percentile 0..100 of tailBuyers among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailVolumeUsd": { "description": "Raw percentile 0..100 of tailVolumeUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailCohort1h": { "description": "Raw percentile 0..100 of tailCohort1h among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailCohort4h": { "description": "Raw percentile 0..100 of tailCohort4h among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailCohort24h": { "description": "Raw percentile 0..100 of tailCohort24h among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailPnl1hUsd": { "description": "Raw percentile 0..100 of tailPnl1hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailPnl4hUsd": { "description": "Raw percentile 0..100 of tailPnl4hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailPnl24hUsd": { "description": "Raw percentile 0..100 of tailPnl24hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailAth1hUsd": { "description": "Raw percentile 0..100 of tailAth1hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailAth4hUsd": { "description": "Raw percentile 0..100 of tailAth4hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailAth24hUsd": { "description": "Raw percentile 0..100 of tailAth24hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "population": { "description": "Authors ranked in this window (the population every rank is against).", "nullable": true, "type": "number" }, "generatedAt": { "description": "Epoch ms at which the window's rank ladder was built.", "nullable": true, "type": "number" } }, "additionalProperties": false } }, "required": [ "totalCallouts", "calloutsWithMultiple", "twoXPercent", "onePointFiveXPercent", "onePointTwoXPercent", "averageMultiple", "medianMultiple", "averageTimeToPeakMs", "tailBuyers", "tailCallouts", "tailCallouts1h", "tailCohort1h", "tailPnl1hUsd", "tailCallouts4h", "tailCohort4h", "tailPnl4hUsd", "tailCallouts24h", "tailCohort24h", "tailPnl24hUsd", "tailUniqueBuyers", "tailVolumeUsd", "tailPnlHist1h", "tailPnlHist4h", "tailPnlHist24h", "tailAth1hUsd", "tailAth4hUsd", "tailAth24hUsd", "tailAthHist1h", "tailAthHist4h", "tailAthHist24h", "distribution" ], "additionalProperties": false }, "lastRound": { "description": "The last payout round window. Absent only when stats are unavailable (the route fails open to {} rather than 5xx) or predate windowed stats; present with zeros for a user with no callouts. When present every field is populated.", "type": "object", "properties": { "totalCallouts": { "type": "number" }, "calloutsWithMultiple": { "type": "number" }, "twoXPercent": { "type": "number" }, "onePointFiveXPercent": { "type": "number" }, "onePointTwoXPercent": { "type": "number" }, "averageMultiple": { "type": "number" }, "medianMultiple": { "type": "number" }, "averageTimeToPeakMs": { "nullable": true, "description": "Whole milliseconds; null when no callout in the window recorded a peak.", "type": "number" }, "tailBuyers": { "nullable": true, "description": "Sum over the window's callouts (those created after tail tracking went live) of distinct users whose buy was attributed to the callout; null when none qualifies.", "type": "number" }, "tailCallouts": { "nullable": true, "description": "Callouts in the window with tail tracking, the denominator of tailBuyers; null when 0.", "type": "number" }, "tailCallouts1h": { "nullable": true, "description": "Callouts in the window whose 1 h tailing-cohort PnL is served; null when 0.", "type": "number" }, "tailCohort1h": { "nullable": true, "description": "Users tailPnl1hUsd covers (tailers whose first attributed buy landed before +1 h and whose window priced); null when no callout is served.", "type": "number" }, "tailPnl1hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +1 h], summed over served callouts; null when none.", "type": "number" }, "tailCallouts4h": { "nullable": true, "description": "Callouts in the window whose 4 h tailing-cohort PnL is served; null when 0.", "type": "number" }, "tailCohort4h": { "nullable": true, "description": "Users tailPnl4hUsd covers (tailers whose first attributed buy landed before +4 h and whose window priced); null when no callout is served.", "type": "number" }, "tailPnl4hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +4 h], summed over served callouts; null when none.", "type": "number" }, "tailCallouts24h": { "nullable": true, "description": "Callouts in the window whose 24 h tailing-cohort PnL is served; null when 0.", "type": "number" }, "tailCohort24h": { "nullable": true, "description": "Users tailPnl24hUsd covers (tailers whose first attributed buy landed before +24 h and whose window priced); null when no callout is served.", "type": "number" }, "tailPnl24hUsd": { "nullable": true, "description": "USD, whole-position PnL change of the tailing cohort over [callout, +24 h], summed over served callouts; null when none.", "type": "number" }, "tailUniqueBuyers": { "nullable": true, "description": "Distinct wallets that tailed at least one of the window's callouts (one wallet tailing five callouts counts once); always <= tailBuyers; null when unknown.", "type": "number" }, "tailVolumeUsd": { "nullable": true, "description": "USD of the tailers' attributed buys through the window's callouts (SOL at the current SOL price plus USDC), author and reply-author self-buys excluded; null when unknown or unpriced.", "type": "number" }, "tailPnlHist1h": { "nullable": true, "description": "Per-tailer 1 h PnL histogram summed over served callouts (server-defined buckets); null when no callout is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailPnlHist4h": { "nullable": true, "description": "Per-tailer 4 h PnL histogram summed over served callouts (server-defined buckets); null when no callout is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailPnlHist24h": { "nullable": true, "description": "Per-tailer 24 h PnL histogram summed over served callouts (server-defined buckets); null when no callout is served, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAth1hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 1 h tailing cohort summed over the window's callouts whose 1 h ATH arm is served (per tailer max(0, in-window bought amount x highest outlier-screened 1 m candle high - in-window buy spend) over its own window [first in-window buy, +1 h]); >= 0; null when no callout in the window is served or unavailable.", "type": "number" }, "tailAth4hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 4 h tailing cohort summed over the window's callouts whose 4 h ATH arm is served (per tailer max(0, in-window bought amount x highest outlier-screened 1 m candle high - in-window buy spend) over its own window [first in-window buy, +4 h]); >= 0; null when no callout in the window is served or unavailable.", "type": "number" }, "tailAth24hUsd": { "nullable": true, "description": "USD, best-case-exit PnL of the 24 h tailing cohort summed over the window's callouts whose 24 h ATH arm is served (per tailer max(0, in-window bought amount x highest outlier-screened 5 m candle high - in-window buy spend) over its own window [first in-window buy, +24 h]); >= 0; null when no callout in the window is served or unavailable.", "type": "number" }, "tailAthHist1h": { "nullable": true, "description": "Per-tailer 1 h best-case-exit PnL histogram (tailer-anchored window, 1 m candle highs) summed elementwise over served callouts; five buckets from 0 up (first min 0, last max null), callouts = how many contributed; null when no callout carries one, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAthHist4h": { "nullable": true, "description": "Per-tailer 4 h best-case-exit PnL histogram (tailer-anchored window, 1 m candle highs) summed elementwise over served callouts; five buckets from 0 up (first min 0, last max null), callouts = how many contributed; null when no callout carries one, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "tailAthHist24h": { "nullable": true, "description": "Per-tailer 24 h best-case-exit PnL histogram (tailer-anchored window, 5 m candle highs) summed elementwise over served callouts; five buckets from 0 up (first min 0, last max null), callouts = how many contributed; null when no callout carries one, never all-zero buckets.", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "min": { "nullable": true, "description": "USD, inclusive lower bound of the bucket's per-tailer PnL range; null for the open-ended bottom bucket.", "type": "number" }, "max": { "nullable": true, "description": "USD, exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "tailers": { "type": "number", "description": "Tailers whose horizon PnL fell in this bucket." }, "pnlUsd": { "type": "number", "description": "USD, summed horizon PnL of this bucket's tailers." } }, "required": [ "min", "max", "tailers", "pnlUsd" ], "additionalProperties": false }, "description": "Server-defined buckets in ascending order; tailers sum to this histogram's cohort and pnlUsd to the matching horizon total." }, "callouts": { "type": "number", "description": "Served callouts whose buckets contributed (1 on a single callout row)." } }, "required": [ "buckets", "callouts" ], "additionalProperties": false }, "distribution": { "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number", "description": "Inclusive lower bound of the bucket's multiple range." }, "max": { "nullable": true, "description": "Exclusive upper bound; null for the open-ended top bucket.", "type": "number" }, "count": { "type": "number" } }, "required": [ "min", "max", "count" ], "additionalProperties": false }, "description": "Server-defined buckets; [] for a user with no callouts." }, "ranks": { "description": "Percentile ranks of this window's tail stats against every author in the same window.", "nullable": true, "type": "object", "properties": { "tailBuyers": { "description": "Raw percentile 0..100 of tailBuyers among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailVolumeUsd": { "description": "Raw percentile 0..100 of tailVolumeUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailCohort1h": { "description": "Raw percentile 0..100 of tailCohort1h among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailCohort4h": { "description": "Raw percentile 0..100 of tailCohort4h among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailCohort24h": { "description": "Raw percentile 0..100 of tailCohort24h among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailPnl1hUsd": { "description": "Raw percentile 0..100 of tailPnl1hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailPnl4hUsd": { "description": "Raw percentile 0..100 of tailPnl4hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailPnl24hUsd": { "description": "Raw percentile 0..100 of tailPnl24hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailAth1hUsd": { "description": "Raw percentile 0..100 of tailAth1hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailAth4hUsd": { "description": "Raw percentile 0..100 of tailAth4hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "tailAth24hUsd": { "description": "Raw percentile 0..100 of tailAth24hUsd among the window's population (share at or below the user, midrank on ties); top X% = 100 - rank. Null/absent = unranked (stat null, no tailed callout in the window, or the window's ladder is missing or stale), never 0.", "nullable": true, "type": "number" }, "population": { "description": "Authors ranked in this window (the population every rank is against).", "nullable": true, "type": "number" }, "generatedAt": { "description": "Epoch ms at which the window's rank ladder was built.", "nullable": true, "type": "number" } }, "additionalProperties": false } }, "required": [ "totalCallouts", "calloutsWithMultiple", "twoXPercent", "onePointFiveXPercent", "onePointTwoXPercent", "averageMultiple", "medianMultiple", "averageTimeToPeakMs", "tailBuyers", "tailCallouts", "tailCallouts1h", "tailCohort1h", "tailPnl1hUsd", "tailCallouts4h", "tailCohort4h", "tailPnl4hUsd", "tailCallouts24h", "tailCohort24h", "tailPnl24hUsd", "tailUniqueBuyers", "tailVolumeUsd", "tailPnlHist1h", "tailPnlHist4h", "tailPnlHist24h", "tailAth1hUsd", "tailAth4hUsd", "tailAth24hUsd", "tailAthHist1h", "tailAthHist4h", "tailAthHist24h", "distribution" ], "additionalProperties": false }, "computedAt": { "type": "string", "description": "Present on every response, the fail-open {} shape included; clients show it as the \"updated\" time instead of their own fetch time. tail* fields are frozen horizon snapshots, not recomputed per read." } }, "required": [ "computedAt" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "A user's callout performance stats (peak-multiple hit rates, averages, time to peak, distribution), every window (daily/weekly/monthly/allTime, plus lastRound = callouts created between the two newest executed payout round cuts) in one response. Public like the callout list itself — derived from publicly visible callouts." } }, "/users/{id}": { "get": { "operationId": "get_users_by_id", "tags": [ "profiles.read" ], "summary": "Get a user by wallet address or user id", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "profiles.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a user by wallet address or user id", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string" }, "userId": { "type": "string" }, "username": { "nullable": true, "type": "string" }, "profile_image": { "nullable": true, "type": "string" }, "header_image_url": { "nullable": true, "type": "string" }, "avatar_decoration": { "description": "The owner's avatar decoration (border effect) PICK as a decoration key — `legendary`, `epic`, `none` (an explicit no-border), `achievement:` — never a url: the client owns the key -> artwork catalog. For the owner's chooser (which tile is selected); the border to draw is resolved_avatar_decoration. null or absent means no pick. Served on GET /users/{id} and POST /users/batch rows.", "nullable": true, "type": "string" }, "resolved_avatar_decoration": { "description": "The border to draw on this avatar, resolved from the owner's pick and achievements: the pick while still earned, else the rarest tier ring the achievements earn (`legendary`, `epic`); null means no border (an explicit `none` pick, or nothing earned). Same key grammar as avatar_decoration. Served on GET /users/{id} and POST /users/batch rows — never fetch a user's achievements to draw a border. A newly earned tier can take up to an hour to show to other viewers; the owner's own view updates immediately", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "person", "group" ] }, "member_count": { "type": "number" }, "group_badges": { "type": "array", "items": { "type": "object", "properties": { "group_id": { "type": "string" }, "username": { "type": "string" }, "profile_image_url": { "nullable": true, "type": "string" }, "role": { "anyOf": [ { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "UNSPECIFIED" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Known values: OWNER, ADMIN, MEMBER, UNSPECIFIED" } }, "required": [ "group_id", "username", "profile_image_url", "role" ], "additionalProperties": false } }, "bio": { "nullable": true, "type": "string" }, "followers": { "type": "number" }, "following": { "type": "number" }, "last_username_update_timestamp": { "description": "Unix epoch ms of the last username change; null when never renamed. Served by the single-profile read and on labelled-wallet search rows; absent from batch and hydrated search-v2 rows", "nullable": true, "type": "number" }, "x_username": { "nullable": true, "type": "string" }, "wallet_label": { "type": "string" }, "is_pump_user": { "type": "boolean" }, "is_banned": { "type": "boolean" }, "canonical_svm_wallet": { "type": "string" }, "canonical_evm_wallet": { "type": "string" }, "last_active_at": { "description": "ISO time of the account's latest authenticated request (~1 min granularity, kept for one day). Viewer-relative: served on GET /users/{id} and POST /users/batch rows to a signed-in viewer, for accounts the viewer follows and the viewer's own row, null otherwise (not followed, never seen, degraded read) — render null as unknown. Absent for anonymous callers, on the API host, and on every other row-serving read", "nullable": true, "type": "string" } }, "required": [ "address", "username", "profile_image", "bio", "followers", "following", "x_username" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } } } }, "/users/{id}/overview": { "get": { "operationId": "get_users_by_id_overview", "tags": [ "profiles.read" ], "summary": "The profile header in one read", "security": [ { "bearer": [] } ], "x-error-codes": [ "API_CREDENTIAL_NOT_ALLOWED", "API_KEY_INVALID", "API_KEY_RATE_LIMITED", "API_KEY_REQUIRED", "API_KEY_REVOKED", "API_ORG_NOT_APPROVED", "API_ORG_SUSPENDED", "API_SCOPE_FORBIDDEN" ], "x-api-scope": "profiles.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Echoed back as address" } } ], "responses": { "200": { "description": "The profile header in one read: profile row, follow counts, verified and achievement badges, ban state, created-coins count and, for a signed-in viewer, the viewer-relative follow, DM and mutuals state. a wallet with none is served as an external wallet.", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "The id as sent" }, "profile": { "nullable": true, "description": "A user id with none is a 404.", "type": "object", "properties": { "address": { "type": "string" }, "userId": { "type": "string" }, "username": { "nullable": true, "type": "string" }, "profile_image": { "nullable": true, "type": "string" }, "header_image_url": { "nullable": true, "type": "string" }, "avatar_decoration": { "description": "The owner's avatar decoration (border effect) PICK as a decoration key — `legendary`, `epic`, `none` (an explicit no-border), `achievement:` — never a url: the client owns the key -> artwork catalog. For the owner's chooser (which tile is selected); the border to draw is resolved_avatar_decoration. null or absent means no pick. Served on GET /users/{id} and POST /users/batch rows.", "nullable": true, "type": "string" }, "resolved_avatar_decoration": { "description": "The border to draw on this avatar, resolved from the owner's pick and achievements: the pick while still earned, else the rarest tier ring the achievements earn (`legendary`, `epic`); null means no border (an explicit `none` pick, or nothing earned). Same key grammar as avatar_decoration. Served on GET /users/{id} and POST /users/batch rows — never fetch a user's achievements to draw a border. A newly earned tier can take up to an hour to show to other viewers; the owner's own view updates immediately", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "person", "group" ] }, "member_count": { "type": "number" }, "group_badges": { "type": "array", "items": { "type": "object", "properties": { "group_id": { "type": "string" }, "username": { "type": "string" }, "profile_image_url": { "nullable": true, "type": "string" }, "role": { "anyOf": [ { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "UNSPECIFIED" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Known values: OWNER, ADMIN, MEMBER, UNSPECIFIED" } }, "required": [ "group_id", "username", "profile_image_url", "role" ], "additionalProperties": false } }, "bio": { "nullable": true, "type": "string" }, "followers": { "type": "number" }, "following": { "type": "number" }, "last_username_update_timestamp": { "description": "Unix epoch ms of the last username change; null when never renamed. Served by the single-profile read and on labelled-wallet search rows; absent from batch and hydrated search-v2 rows", "nullable": true, "type": "number" }, "x_username": { "nullable": true, "type": "string" }, "wallet_label": { "type": "string" }, "is_pump_user": { "type": "boolean" }, "is_banned": { "type": "boolean" }, "canonical_svm_wallet": { "type": "string" }, "canonical_evm_wallet": { "type": "string" }, "last_active_at": { "description": "ISO time of the account's latest authenticated request (~1 min granularity, kept for one day). Viewer-relative: served on GET /users/{id} and POST /users/batch rows to a signed-in viewer, for accounts the viewer follows and the viewer's own row, null otherwise (not followed, never seen, degraded read) — render null as unknown. Absent for anonymous callers, on the API host, and on every other row-serving read", "nullable": true, "type": "string" } }, "required": [ "address", "username", "profile_image", "bio", "followers", "following", "x_username" ], "additionalProperties": false }, "isPumpUser": { "type": "boolean", "description": "profile !== null" }, "counts": { "type": "object", "properties": { "followers": { "nullable": true, "description": "Follower count. null = this leg degraded on this request (named in degraded).", "type": "number" }, "following": { "nullable": true, "description": "Following count. null = this leg degraded on this request (named in degraded).", "type": "number" } }, "required": [ "followers", "following" ], "additionalProperties": false, "description": "Both null when the counts leg degraded" }, "verified": { "nullable": true, "description": "Verified-profile badge; null = this leg degraded on this request (named in degraded).", "type": "boolean" }, "achievementBadgeIds": { "nullable": true, "description": "Top achievement badge ids for the avatar chip; null = this leg degraded on this request (named in degraded).", "type": "array", "items": { "type": "string" } }, "banned": { "nullable": true, "description": "False when not banned. null = this leg degraded on this request (named in degraded).", "type": "boolean" }, "createdCoinsCount": { "nullable": true, "description": "Coins created by the canonical wallet; 0 for a walletless account. null = this leg degraded on this request (named in degraded).", "type": "number" }, "viewer": { "description": "Absent on anonymous responses", "type": "object", "properties": { "isViewer": { "type": "boolean", "description": "The viewer is the profile owner; every other field is null without degrading" }, "follows": { "nullable": true, "description": "Viewer follows the profile. null = this leg degraded on this request (named in degraded).", "type": "boolean" }, "followsYou": { "nullable": true, "description": "Profile follows the viewer; null = this leg degraded on this request (named in degraded).", "type": "boolean" }, "dmEligible": { "nullable": true, "description": "Null = this leg degraded on this request (named in degraded).", "type": "boolean" }, "mutuals": { "nullable": true, "description": "Accounts the viewer follows that also follow the profile, most-followed first. null = this leg degraded on this request (named in degraded).", "type": "object", "properties": { "totalCount": { "type": "number", "description": "Exact size of the whole mutual set" }, "preview": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "PERSON", "GROUP" ] }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true. The verified state itself is isVerified." }, "resolvedAvatarDecoration": { "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border. Treat absent as null.", "nullable": true, "type": "string" } }, "required": [ "userId", "username", "profileImageUrl", "walletAddress", "kind", "isVerified", "verifiedBadgeVisible" ], "additionalProperties": false, "description": "Embedded profile stub: the identity fields a sibling payload needs to render an account chip. A pick of normalizedProfile." } } }, "required": [ "totalCount", "preview" ], "additionalProperties": false } }, "required": [ "isViewer", "follows", "followsYou", "dmEligible", "mutuals" ], "additionalProperties": false }, "degraded": { "type": "array", "items": { "type": "string", "enum": [ "counts", "verified", "badges", "banned", "created_coins", "follows", "follows_you", "dm_eligible", "mutuals" ] }, "description": "Legs that failed, timed out or could only serve a fail-open blank (verified, badges) on this request. Re-issue exactly those against their dedicated routes instead of retrying the aggregate. An anonymous response with a non-empty list is served no-store; a complete one is edge-cacheable with Vary: Authorization, Cookie." } }, "required": [ "address", "profile", "isPumpUser", "counts", "verified", "achievementBadgeIds", "banned", "createdCoinsCount", "degraded" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } } }, "400": { "$ref": "#/components/responses/BadRequestCredential" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Default" } }, "description": "The profile header in one read: profile row, follow counts, verified and achievement badges, ban state, created-coins count and, for a signed-in viewer, the viewer-relative follow, DM and mutuals state. a wallet with none is served as an external wallet." } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "pf_live_<43 base62><6 base62 CRC32>", "description": "API key issued in the developer console. `Authorization: Bearer pf_live_...`; the header `x-api-key: pf_live_...` is accepted as an alias. Never put the key in a query string." } }, "schemas": { "Error": { "type": "object", "properties": { "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "timestamp": { "type": "string" }, "path": { "type": "string" }, "error": { "description": "A documented error code (`API_*` for the platform, a route code from `x-error-codes`), or an HTTP reason phrase.", "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "requiredScope": { "type": "string", "description": "Only on `API_SCOPE_FORBIDDEN`: the scope the key is missing." }, "retryAfterMs": { "type": "integer", "description": "Only on `API_KEY_RATE_LIMITED`: milliseconds until the next request is accepted." }, "limit": { "type": "integer", "description": "Only on `API_KEY_RATE_LIMITED`: the limit that was hit." }, "window": { "type": "string", "enum": [ "burst", "day", "auth", "lookup" ], "description": "Only on `API_KEY_RATE_LIMITED`: which limit was hit: `burst` (per-key per-second budget with a 60 s bucket), `day` (per-key UTC daily limit), `auth` (per-IP failed authentications), `lookup` (per-IP unknown-key lookups)." }, "retryAfterSeconds": { "type": "integer", "description": "Only on the 503: seconds before retrying, the same value as `Retry-After`. That body carries `message` and no `error` code." } }, "required": [ "statusCode" ], "description": "The envelope every refused request carries. Only `statusCode` is always present; `error` is the code to branch on." }, "Shared_35fd92fdd6a3": { "type": "object", "properties": { "coinMint": { "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true; true for user-less callouts" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad callout: userId/userName/profileImage are the squad's while walletAddress is the acting admin's posting wallet; route the author press on userId + accountKind, never the wallet" }, "xUsername": { "nullable": true, "type": "string" }, "xFollowerCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "chain": { "description": "CAIP-2 chain of the called-out ref; absent when the callout carries none", "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "callout": { "type": "object", "properties": { "calloutId": { "type": "string" }, "chain": { "description": "CAIP-2 chain of the called-out ref (hlcore:mainnet for a perp, ton:-239 for a TON callout, near:mainnet for a NEAR callout, starknet:SN_MAIN for a Starknet callout); null when the row carries none", "nullable": true, "type": "string" }, "assetClass": { "description": "Asset class of the called-out position: ASSET_CLASS_PERPETUAL on an hlcore (HyperCore perp) callout, ASSET_CLASS_NFT_LIKE on a card callout (collectible set), ASSET_CLASS_TOKEN on every other row, chainless ones included", "type": "string", "enum": [ "ASSET_CLASS_TOKEN", "ASSET_CLASS_PERPETUAL", "ASSET_CLASS_NFT_LIKE" ] }, "collectible": { "description": "ASSET_CLASS_NFT_LIKE callouts only: the card (identity, grade, mark, insured value, buyback, listing); multiple is then the card mark over calloutPrice. Absent on every token callout", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false }, "perp": { "description": "Set only on a perp callout, whose calledOutAtMcap is 0", "nullable": true, "type": "object", "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "leverageBps": { "type": "number" }, "entryPx": { "nullable": true, "type": "number" }, "closePx": { "nullable": true, "type": "number" }, "closedAt": { "nullable": true, "type": "string" } }, "required": [ "side", "leverageBps", "entryPx", "closePx", "closedAt" ], "additionalProperties": false }, "calledOutAtMcap": { "type": "number", "description": "USD market cap when the callout was made." }, "multiple": { "type": "number", "description": "Current multiplier (live price vs callout price), 1 for an untracked callout; maxMultiplier is the all-time peak" }, "thesis": { "nullable": true, "type": "string" }, "mediaUrl": { "nullable": true, "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "calloutTimestamp": { "nullable": true, "type": "string" }, "likes": { "type": "number" }, "hasLiked": { "nullable": true, "description": "null until a viewer is known", "type": "boolean" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "createdAt": { "nullable": true, "type": "string" }, "likeCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "parentMessageId": { "nullable": true, "type": "string" }, "repostCount": { "type": "number" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" } }, "required": [ "id", "content", "createdAt", "likeCount", "mediaUrl", "parentMessageId", "repostCount" ], "additionalProperties": false }, "description": "Author updates (the author's own replies), newest first; empty when the route does not include them" }, "updateCount": { "type": "number" }, "commentCount": { "type": "number", "description": "Live replies from users OTHER than the callout author" }, "replyCount": { "type": "number", "description": "All live replies, updates included" }, "maxMultiplier": { "nullable": true, "type": "number" }, "maxMultiplierAt": { "nullable": true, "type": "string" }, "calloutPrice": { "type": "number", "description": "Token price when the callout was made; 0 for callouts predating price capture, never null" }, "repostCount": { "type": "number", "description": "Live plain reposts of the callout itself; quotes do not count" }, "quoteCount": { "type": "number" }, "hasReposted": { "nullable": true, "description": "null until a viewer is known", "type": "boolean" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" }, "quotedCalloutId": { "description": "Set with quotedCallout null means \"quote of an unavailable callout\", never \"no quote\"", "nullable": true, "type": "string" }, "actingUserId": { "nullable": true, "description": "Squad callouts: the admin who posted on the squad's behalf; presence is not the squad discriminator, the author's kind is", "type": "string" }, "actingUser": { "nullable": true, "description": "actingUserId set with actingUser null means \"unresolved\", not \"absent\"", "type": "object", "properties": { "userId": { "type": "string" }, "userName": { "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "xUsername": { "nullable": true, "type": "string" } }, "required": [ "userId", "userName", "profileImage", "walletAddress", "isVerified", "verifiedBadgeVisible", "xUsername" ], "additionalProperties": false }, "quotedCallout": { "nullable": true, "description": "The quoted callout one level deep (its own quotedCallout is always null)", "allOf": [ { "$ref": "#/components/schemas/Shared_35fd92fdd6a3" } ] } }, "required": [ "calloutId", "calledOutAtMcap", "multiple", "thesis", "mediaUrl", "calloutTimestamp", "likes", "hasLiked", "updates", "updateCount", "commentCount", "replyCount", "maxMultiplier", "maxMultiplierAt", "calloutPrice", "repostCount", "quoteCount", "hasReposted", "actingUserId", "actingUser", "quotedCallout" ], "additionalProperties": false } }, "required": [ "coinMint", "walletAddress", "userId", "userName", "profileImage", "isVerified", "verifiedBadgeVisible", "accountKind", "xUsername", "xFollowerCount", "mediaUrl", "callout" ], "additionalProperties": false }, "Shared_3ba6ed1d0d06": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "createdAt": { "nullable": true, "type": "string" }, "likeCount": { "type": "number" }, "userId": { "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad reply posted by an acting admin: userId/userName/profileImage are the squad's and walletAddress is null (groups are walletless)" }, "mediaUrl": { "nullable": true, "type": "string" }, "parentMessageId": { "nullable": true, "description": "null when this reply targets the callout itself", "type": "string" }, "rootMessageId": { "nullable": true, "description": "null on thread tops", "type": "string" }, "directReplyCount": { "type": "number" }, "threadReplyCount": { "nullable": true, "description": "Live descendants at every depth; thread tops only", "type": "number" }, "tombstone": { "type": "boolean", "description": "Placeholder for a deleted/hidden reply — only id, linkage and counts are set" }, "hasLiked": { "nullable": true, "description": "null for anonymous requests and on tombstones", "type": "boolean" }, "viewerFollowsAuthor": { "nullable": true, "description": "null for anonymous requests and on tombstones", "type": "boolean" }, "repostCount": { "type": "number" }, "positionAmountHeld": { "nullable": true, "type": "number" }, "positionValueUsd": { "nullable": true, "type": "number" }, "positionPnlUsd": { "nullable": true, "type": "number" }, "positionPnlPercentage": { "nullable": true, "type": "number" }, "positionCostBasisAmount": { "type": "number", "description": "Use the amountBought pair for lifetime entry" }, "positionCostBasisUsd": { "nullable": true, "type": "number" }, "positionAmountBoughtUsd": { "nullable": true, "type": "number" }, "positionAmountBought": { "nullable": true, "type": "number" }, "positionRealizedPnlUsd": { "nullable": true, "type": "number" }, "positionAvgEntryMcapUsd": { "nullable": true, "type": "number" }, "isQuote": { "type": "boolean", "description": "Quote rows root their own thread and never appear in the quoted thread; always false on tombstones" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" }, "previewReplies": { "type": "array", "items": { "$ref": "#/components/schemas/Shared_3ba6ed1d0d06" }, "description": "Newest live direct children, deduped against authorReply; empty without nestedLimit" }, "authorReply": { "nullable": true, "description": "The callout author's earliest live direct child", "allOf": [ { "$ref": "#/components/schemas/Shared_3ba6ed1d0d06" } ] } }, "required": [ "id", "content", "createdAt", "likeCount", "userId", "walletAddress", "userName", "profileImage", "accountKind", "mediaUrl", "parentMessageId", "rootMessageId", "directReplyCount", "threadReplyCount", "tombstone", "hasLiked", "viewerFollowsAuthor", "repostCount", "positionAmountHeld", "positionValueUsd", "positionPnlUsd", "positionPnlPercentage", "positionCostBasisAmount", "positionCostBasisUsd", "positionAmountBoughtUsd", "positionAmountBought", "positionRealizedPnlUsd", "positionAvgEntryMcapUsd", "isQuote", "previewReplies", "authorReply" ], "additionalProperties": false }, "Shared_43ac27dd04b0": { "nullable": true, "description": "The quoted callout one level deep (its own quotedCallout is always null)", "type": "object", "properties": { "coinMint": { "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true; true for user-less callouts" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad callout: userId/userName/profileImage are the squad's while walletAddress is the acting admin's posting wallet; route the author press on userId + accountKind, never the wallet" }, "xUsername": { "nullable": true, "type": "string" }, "xFollowerCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "chain": { "description": "CAIP-2 chain of the called-out ref; absent when the callout carries none", "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "callout": { "type": "object", "properties": { "calloutId": { "type": "string" }, "chain": { "description": "CAIP-2 chain of the called-out ref (hlcore:mainnet for a perp, ton:-239 for a TON callout, near:mainnet for a NEAR callout, starknet:SN_MAIN for a Starknet callout); null when the row carries none", "nullable": true, "type": "string" }, "assetClass": { "description": "Asset class of the called-out position: ASSET_CLASS_PERPETUAL on an hlcore (HyperCore perp) callout, ASSET_CLASS_NFT_LIKE on a card callout (collectible set), ASSET_CLASS_TOKEN on every other row, chainless ones included", "type": "string", "enum": [ "ASSET_CLASS_TOKEN", "ASSET_CLASS_PERPETUAL", "ASSET_CLASS_NFT_LIKE" ] }, "collectible": { "description": "ASSET_CLASS_NFT_LIKE callouts only: the card (identity, grade, mark, insured value, buyback, listing); multiple is then the card mark over calloutPrice. Absent on every token callout", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false }, "perp": { "description": "Set only on a perp callout, whose calledOutAtMcap is 0", "nullable": true, "type": "object", "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "leverageBps": { "type": "number" }, "entryPx": { "nullable": true, "type": "number" }, "closePx": { "nullable": true, "type": "number" }, "closedAt": { "nullable": true, "type": "string" } }, "required": [ "side", "leverageBps", "entryPx", "closePx", "closedAt" ], "additionalProperties": false }, "calledOutAtMcap": { "type": "number", "description": "USD market cap when the callout was made." }, "multiple": { "type": "number", "description": "Current multiplier (live price vs callout price), 1 for an untracked callout; maxMultiplier is the all-time peak" }, "thesis": { "nullable": true, "type": "string" }, "mediaUrl": { "nullable": true, "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "calloutTimestamp": { "nullable": true, "type": "string" }, "likes": { "type": "number" }, "hasLiked": { "nullable": true, "description": "null until a viewer is known", "type": "boolean" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "createdAt": { "nullable": true, "type": "string" }, "likeCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "parentMessageId": { "nullable": true, "type": "string" }, "repostCount": { "type": "number" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" } }, "required": [ "id", "content", "createdAt", "likeCount", "mediaUrl", "parentMessageId", "repostCount" ], "additionalProperties": false }, "description": "Author updates (the author's own replies), newest first; empty when the route does not include them" }, "updateCount": { "type": "number" }, "commentCount": { "type": "number", "description": "Live replies from users OTHER than the callout author" }, "replyCount": { "type": "number", "description": "All live replies, updates included" }, "maxMultiplier": { "nullable": true, "type": "number" }, "maxMultiplierAt": { "nullable": true, "type": "string" }, "calloutPrice": { "type": "number", "description": "Token price when the callout was made; 0 for callouts predating price capture, never null" }, "repostCount": { "type": "number", "description": "Live plain reposts of the callout itself; quotes do not count" }, "quoteCount": { "type": "number" }, "hasReposted": { "nullable": true, "description": "null until a viewer is known", "type": "boolean" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" }, "quotedCalloutId": { "description": "Set with quotedCallout null means \"quote of an unavailable callout\", never \"no quote\"", "nullable": true, "type": "string" }, "actingUserId": { "nullable": true, "description": "Squad callouts: the admin who posted on the squad's behalf; presence is not the squad discriminator, the author's kind is", "type": "string" }, "actingUser": { "nullable": true, "description": "actingUserId set with actingUser null means \"unresolved\", not \"absent\"", "type": "object", "properties": { "userId": { "type": "string" }, "userName": { "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "xUsername": { "nullable": true, "type": "string" } }, "required": [ "userId", "userName", "profileImage", "walletAddress", "isVerified", "verifiedBadgeVisible", "xUsername" ], "additionalProperties": false }, "quotedCallout": { "$ref": "#/components/schemas/Shared_43ac27dd04b0" } }, "required": [ "calloutId", "calledOutAtMcap", "multiple", "thesis", "mediaUrl", "calloutTimestamp", "likes", "hasLiked", "updates", "updateCount", "commentCount", "replyCount", "maxMultiplier", "maxMultiplierAt", "calloutPrice", "repostCount", "quoteCount", "hasReposted", "actingUserId", "actingUser", "quotedCallout" ], "additionalProperties": false } }, "required": [ "coinMint", "walletAddress", "userId", "userName", "profileImage", "isVerified", "verifiedBadgeVisible", "accountKind", "xUsername", "xFollowerCount", "mediaUrl", "callout" ], "additionalProperties": false }, "Shared_47a8d5353d95": { "type": "object", "properties": { "postId": { "type": "string" }, "kind": { "nullable": true, "description": "null only on a tombstone whose underlying row is gone", "type": "string", "enum": [ "root", "reply", "quote", "repost" ] }, "author": { "nullable": true, "description": "null on tombstones", "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "bio": { "type": "string" }, "profileImageUrl": { "type": "string" }, "headerImageUrl": { "type": "string" }, "followerCount": { "type": "number" }, "followingCount": { "type": "number" }, "createdAt": { "nullable": true, "type": "string" }, "updatedAt": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "socials": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "username": { "type": "string" }, "linkedAt": { "nullable": true, "type": "string" } }, "required": [ "provider", "username", "linkedAt" ], "additionalProperties": false } }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true. The verified state itself is isVerified." }, "resolvedAvatarDecoration": { "description": "The border to draw on this avatar as a decoration key (`legendary`, `epic`, `achievement:`), never a url — the owner's pick while still earned, else the rarest tier ring the owner's achievements earn; null = no border. Draw it straight off the row: a client never fetches a user's achievements to draw a border. Treat absent as null.", "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "PERSON", "GROUP" ] }, "memberCount": { "type": "number" }, "membershipPolicy": { "nullable": true, "type": "string", "enum": [ "INVITE" ] }, "groupBadges": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "username": { "type": "string" }, "profileImageUrl": { "nullable": true, "type": "string" }, "role": { "type": "string" } }, "required": [ "groupId", "username", "profileImageUrl", "role" ], "additionalProperties": false } }, "generatedMedia": { "nullable": true, "type": "object", "properties": { "pnlLoop": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" } }, "required": [ "uid", "durationSeconds" ], "additionalProperties": false }, "replayIntro": { "type": "object", "properties": { "uid": { "type": "string" }, "durationSeconds": { "type": "number" }, "fireAt": { "type": "number" } }, "required": [ "uid", "durationSeconds", "fireAt" ], "additionalProperties": false } }, "required": [ "pnlLoop" ], "additionalProperties": false }, "isPumpUser": { "description": "false = unclaimed shell: an identity minted when someone followed an outside wallet that never signed in, served under a generated username. Render it as a wallet (address or the viewer’s wallet label), never as an account. Treat absent as true.", "type": "boolean" } }, "required": [ "userId", "username", "bio", "profileImageUrl", "headerImageUrl", "followerCount", "followingCount", "createdAt", "updatedAt", "walletAddress", "socials", "isVerified", "verifiedBadgeVisible", "kind", "memberCount", "membershipPolicy", "groupBadges", "generatedMedia" ], "additionalProperties": false }, "content": { "nullable": true, "type": "string" }, "mediaUrl": { "nullable": true, "description": "Server-minted CDN URL; null when the post carries no image", "type": "string" }, "createdAt": { "nullable": true, "description": "ISO 8601", "type": "string" }, "parentPostId": { "nullable": true, "description": "Reply rows: the direct parent", "type": "string" }, "rootPostId": { "nullable": true, "description": "Reply rows: the thread root", "type": "string" }, "quotedPostId": { "nullable": true, "description": "Set on quotes even when the target is gone: set with `quoted` null means \"quote of an unavailable post\"", "type": "string" }, "repostedPostId": { "nullable": true, "description": "Repost rows: the reposted post", "type": "string" }, "likeCount": { "type": "number" }, "replyCount": { "type": "number" }, "repostCount": { "type": "number" }, "quoteCount": { "type": "number" }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "walletAddress": { "nullable": true, "description": "Canonical SVM wallet; null when the user has none", "type": "string" } }, "required": [ "userId", "username", "walletAddress" ], "additionalProperties": false } }, "hasLiked": { "nullable": true, "description": "null when the request had no viewer; always false on repost rows (read reposted.hasLiked)", "type": "boolean" }, "hasReposted": { "nullable": true, "description": "null when the request had no viewer; always false on repost rows (read reposted.hasReposted)", "type": "boolean" }, "deleted": { "type": "boolean", "description": "Tombstone marker, only ever true on a `parent` embed: ids, kind, createdAt and counts survive; content, media, author and mentions are cleared" }, "parent": { "nullable": true, "description": "Reply rows: a deleted parent is a tombstone (deleted=true, author null); a moderation-hidden parent is null with parentPostId still set", "allOf": [ { "$ref": "#/components/schemas/Shared_47a8d5353d95" } ] }, "quoted": { "nullable": true, "description": "Quote rows: null when the target is hidden or deleted", "allOf": [ { "$ref": "#/components/schemas/Shared_47a8d5353d95" } ] }, "reposted": { "nullable": true, "description": "Repost rows: always present on a served repost", "allOf": [ { "$ref": "#/components/schemas/Shared_47a8d5353d95" } ] } }, "required": [ "postId", "kind", "author", "content", "mediaUrl", "createdAt", "parentPostId", "rootPostId", "quotedPostId", "repostedPostId", "likeCount", "replyCount", "repostCount", "quoteCount", "mentions", "hasLiked", "hasReposted", "deleted", "parent", "quoted", "reposted" ], "additionalProperties": false }, "Shared_5643735df9ab": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "createdAt": { "nullable": true, "type": "string" }, "likeCount": { "type": "number" }, "userId": { "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad reply posted by an acting admin: userId/userName/profileImage are the squad's and walletAddress is null (groups are walletless)" }, "mediaUrl": { "nullable": true, "type": "string" }, "parentMessageId": { "nullable": true, "description": "null when this reply targets the callout itself", "type": "string" }, "rootMessageId": { "nullable": true, "description": "null on thread tops", "type": "string" }, "directReplyCount": { "type": "number" }, "threadReplyCount": { "nullable": true, "description": "Live descendants at every depth; thread tops only", "type": "number" }, "tombstone": { "type": "boolean", "description": "Placeholder for a deleted/hidden reply — only id, linkage and counts are set" }, "hasLiked": { "nullable": true, "description": "null for anonymous requests and on tombstones", "type": "boolean" }, "viewerFollowsAuthor": { "nullable": true, "description": "null for anonymous requests and on tombstones", "type": "boolean" }, "repostCount": { "type": "number" }, "positionAmountHeld": { "nullable": true, "type": "number" }, "positionValueUsd": { "nullable": true, "type": "number" }, "positionPnlUsd": { "nullable": true, "type": "number" }, "positionPnlPercentage": { "nullable": true, "type": "number" }, "positionCostBasisAmount": { "type": "number", "description": "Use the amountBought pair for lifetime entry" }, "positionCostBasisUsd": { "nullable": true, "type": "number" }, "positionAmountBoughtUsd": { "nullable": true, "type": "number" }, "positionAmountBought": { "nullable": true, "type": "number" }, "positionRealizedPnlUsd": { "nullable": true, "type": "number" }, "positionAvgEntryMcapUsd": { "nullable": true, "type": "number" }, "isQuote": { "type": "boolean", "description": "Quote rows root their own thread and never appear in the quoted thread; always false on tombstones" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" }, "previewReplies": { "type": "array", "items": { "$ref": "#/components/schemas/Shared_5643735df9ab" }, "description": "Newest live direct children, deduped against authorReply; empty without nestedLimit" }, "authorReply": { "nullable": true, "description": "The callout author's earliest live direct child", "allOf": [ { "$ref": "#/components/schemas/Shared_5643735df9ab" } ] } }, "required": [ "id", "content", "createdAt", "likeCount", "userId", "walletAddress", "userName", "profileImage", "accountKind", "mediaUrl", "parentMessageId", "rootMessageId", "directReplyCount", "threadReplyCount", "tombstone", "hasLiked", "viewerFollowsAuthor", "repostCount", "positionAmountHeld", "positionValueUsd", "positionPnlUsd", "positionPnlPercentage", "positionCostBasisAmount", "positionCostBasisUsd", "positionAmountBoughtUsd", "positionAmountBought", "positionRealizedPnlUsd", "positionAvgEntryMcapUsd", "isQuote", "previewReplies", "authorReply" ], "additionalProperties": false }, "Shared_85bd3a13acc3": { "type": "object", "properties": { "coinMint": { "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true; true for user-less callouts" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad callout: userId/userName/profileImage are the squad's while walletAddress is the acting admin's posting wallet; route the author press on userId + accountKind, never the wallet" }, "xUsername": { "nullable": true, "type": "string" }, "xFollowerCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "chain": { "description": "CAIP-2 chain of the called-out ref; absent when the callout carries none", "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "callout": { "type": "object", "properties": { "calloutId": { "type": "string" }, "chain": { "description": "CAIP-2 chain of the called-out ref (hlcore:mainnet for a perp, ton:-239 for a TON callout, near:mainnet for a NEAR callout, starknet:SN_MAIN for a Starknet callout); null when the row carries none", "nullable": true, "type": "string" }, "assetClass": { "description": "Asset class of the called-out position: ASSET_CLASS_PERPETUAL on an hlcore (HyperCore perp) callout, ASSET_CLASS_NFT_LIKE on a card callout (collectible set), ASSET_CLASS_TOKEN on every other row, chainless ones included", "type": "string", "enum": [ "ASSET_CLASS_TOKEN", "ASSET_CLASS_PERPETUAL", "ASSET_CLASS_NFT_LIKE" ] }, "collectible": { "description": "ASSET_CLASS_NFT_LIKE callouts only: the card (identity, grade, mark, insured value, buyback, listing); multiple is then the card mark over calloutPrice. Absent on every token callout", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false }, "perp": { "description": "Set only on a perp callout, whose calledOutAtMcap is 0", "nullable": true, "type": "object", "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "leverageBps": { "type": "number" }, "entryPx": { "nullable": true, "type": "number" }, "closePx": { "nullable": true, "type": "number" }, "closedAt": { "nullable": true, "type": "string" } }, "required": [ "side", "leverageBps", "entryPx", "closePx", "closedAt" ], "additionalProperties": false }, "calledOutAtMcap": { "type": "number", "description": "USD market cap when the callout was made." }, "multiple": { "type": "number", "description": "Current multiplier (live price vs callout price), 1 for an untracked callout; maxMultiplier is the all-time peak" }, "thesis": { "nullable": true, "type": "string" }, "mediaUrl": { "nullable": true, "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "calloutTimestamp": { "nullable": true, "type": "string" }, "likes": { "type": "number" }, "hasLiked": { "nullable": true, "description": "null until a viewer is known", "type": "boolean" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "createdAt": { "nullable": true, "type": "string" }, "likeCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "parentMessageId": { "nullable": true, "type": "string" }, "repostCount": { "type": "number" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" } }, "required": [ "id", "content", "createdAt", "likeCount", "mediaUrl", "parentMessageId", "repostCount" ], "additionalProperties": false }, "description": "Author updates (the author's own replies), newest first; empty when the route does not include them" }, "updateCount": { "type": "number" }, "commentCount": { "type": "number", "description": "Live replies from users OTHER than the callout author" }, "replyCount": { "type": "number", "description": "All live replies, updates included" }, "maxMultiplier": { "nullable": true, "type": "number" }, "maxMultiplierAt": { "nullable": true, "type": "string" }, "calloutPrice": { "type": "number", "description": "Token price when the callout was made; 0 for callouts predating price capture, never null" }, "repostCount": { "type": "number", "description": "Live plain reposts of the callout itself; quotes do not count" }, "quoteCount": { "type": "number" }, "hasReposted": { "nullable": true, "description": "null until a viewer is known", "type": "boolean" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" }, "quotedCalloutId": { "description": "Set with quotedCallout null means \"quote of an unavailable callout\", never \"no quote\"", "nullable": true, "type": "string" }, "actingUserId": { "nullable": true, "description": "Squad callouts: the admin who posted on the squad's behalf; presence is not the squad discriminator, the author's kind is", "type": "string" }, "actingUser": { "nullable": true, "description": "actingUserId set with actingUser null means \"unresolved\", not \"absent\"", "type": "object", "properties": { "userId": { "type": "string" }, "userName": { "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "xUsername": { "nullable": true, "type": "string" } }, "required": [ "userId", "userName", "profileImage", "walletAddress", "isVerified", "verifiedBadgeVisible", "xUsername" ], "additionalProperties": false }, "quotedCallout": { "nullable": true, "description": "The quoted callout one level deep (its own quotedCallout is always null)", "allOf": [ { "$ref": "#/components/schemas/Shared_85bd3a13acc3" } ] } }, "required": [ "calloutId", "calledOutAtMcap", "multiple", "thesis", "mediaUrl", "calloutTimestamp", "likes", "hasLiked", "updates", "updateCount", "commentCount", "replyCount", "maxMultiplier", "maxMultiplierAt", "calloutPrice", "repostCount", "quoteCount", "hasReposted", "actingUserId", "actingUser", "quotedCallout" ], "additionalProperties": false } }, "required": [ "coinMint", "walletAddress", "userId", "userName", "profileImage", "isVerified", "verifiedBadgeVisible", "accountKind", "xUsername", "xFollowerCount", "mediaUrl", "callout" ], "additionalProperties": false }, "Shared_fceda4efe6cd": { "type": "object", "properties": { "calloutId": { "type": "string" }, "chain": { "description": "CAIP-2 chain of the called-out ref (hlcore:mainnet for a perp, ton:-239 for a TON callout, near:mainnet for a NEAR callout, starknet:SN_MAIN for a Starknet callout); null when the row carries none", "nullable": true, "type": "string" }, "assetClass": { "description": "Asset class of the called-out position: ASSET_CLASS_PERPETUAL on an hlcore (HyperCore perp) callout, ASSET_CLASS_NFT_LIKE on a card callout (collectible set), ASSET_CLASS_TOKEN on every other row, chainless ones included", "type": "string", "enum": [ "ASSET_CLASS_TOKEN", "ASSET_CLASS_PERPETUAL", "ASSET_CLASS_NFT_LIKE" ] }, "collectible": { "description": "ASSET_CLASS_NFT_LIKE callouts only: the card (identity, grade, mark, insured value, buyback, listing); multiple is then the card mark over calloutPrice. Absent on every token callout", "type": "object", "properties": { "assetId": { "type": "string", "description": "The card's Metaplex Core asset id or pNFT mint" }, "provider": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Card provider. Known values: collector_crypt, phygitals" }, "status": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "held", "listed", "bought_back", "sold", "redeemed", "seized", "burned", "inventory" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Lifecycle state of the card; listed while a marketplace listing is live. Known values: held, listed, bought_back, sold, redeemed, seized, burned, inventory" }, "name": { "nullable": true, "description": "Card name", "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "grade": { "nullable": true, "description": "Grading company and grade as one label (PSA 10); null ungraded", "type": "string" }, "setName": { "nullable": true, "type": "string" }, "markUsd": { "nullable": true, "description": "The PnL mark the row's tokenPriceUsd and valueUsd rest on; null = unpriced", "type": "number" }, "markSource": { "nullable": true, "description": "Price source the mark was picked from (buyback, standing_bid, fmv, listing,...); null when unpriced", "type": "string" }, "markAsOf": { "nullable": true, "description": "ISO instant the mark was observed", "type": "string" }, "insuredValueUsd": { "nullable": true, "description": "Provider insured value; display only, never the mark", "type": "number" }, "insuredAsOf": { "nullable": true, "type": "string" }, "buybackValueUsd": { "nullable": true, "description": "The provider's current buyback quote; null when none stands", "type": "number" }, "buybackExpiresAt": { "nullable": true, "description": "ISO instant the buyback quote lapses; null = no expiry", "type": "string" }, "listing": { "nullable": true, "description": "Live marketplace listing; null when not listed", "type": "object", "properties": { "priceUsd": { "nullable": true, "type": "number" }, "marketplace": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "collector_crypt", "magic_eden", "tensor", "phygitals" ] }, { "type": "string" } ], "x-open-enum": true, "description": "Marketplace the card is listed on. Known values: collector_crypt, magic_eden, tensor, phygitals" }, "listedAt": { "nullable": true, "description": "ISO instant the listing opened", "type": "string" } }, "required": [ "priceUsd", "marketplace", "listedAt" ], "additionalProperties": false } }, "required": [ "assetId", "provider", "status", "name", "imageUrl", "grade", "setName", "markUsd", "markSource", "markAsOf", "insuredValueUsd", "insuredAsOf", "buybackValueUsd", "buybackExpiresAt", "listing" ], "additionalProperties": false }, "perp": { "description": "Set only on a perp callout, whose calledOutAtMcap is 0", "nullable": true, "type": "object", "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "leverageBps": { "type": "number" }, "entryPx": { "nullable": true, "type": "number" }, "closePx": { "nullable": true, "type": "number" }, "closedAt": { "nullable": true, "type": "string" } }, "required": [ "side", "leverageBps", "entryPx", "closePx", "closedAt" ], "additionalProperties": false }, "calledOutAtMcap": { "type": "number", "description": "USD market cap when the callout was made." }, "multiple": { "type": "number", "description": "Current multiplier (live price vs callout price), 1 for an untracked callout; maxMultiplier is the all-time peak" }, "thesis": { "nullable": true, "type": "string" }, "mediaUrl": { "nullable": true, "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "calloutTimestamp": { "nullable": true, "type": "string" }, "likes": { "type": "number" }, "hasLiked": { "nullable": true, "description": "null until a viewer is known", "type": "boolean" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "createdAt": { "nullable": true, "type": "string" }, "likeCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "parentMessageId": { "nullable": true, "type": "string" }, "repostCount": { "type": "number" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" } }, "required": [ "id", "content", "createdAt", "likeCount", "mediaUrl", "parentMessageId", "repostCount" ], "additionalProperties": false }, "description": "Author updates (the author's own replies), newest first; empty when the route does not include them" }, "updateCount": { "type": "number" }, "commentCount": { "type": "number", "description": "Live replies from users OTHER than the callout author" }, "replyCount": { "type": "number", "description": "All live replies, updates included" }, "maxMultiplier": { "nullable": true, "type": "number" }, "maxMultiplierAt": { "nullable": true, "type": "string" }, "calloutPrice": { "type": "number", "description": "Token price when the callout was made; 0 for callouts predating price capture, never null" }, "repostCount": { "type": "number", "description": "Live plain reposts of the callout itself; quotes do not count" }, "quoteCount": { "type": "number" }, "hasReposted": { "nullable": true, "description": "null until a viewer is known", "type": "boolean" }, "viewCount": { "description": "Session-deduped views; absent means unknown (no counter row yet), never a real zero", "type": "number" }, "quotedCalloutId": { "description": "Set with quotedCallout null means \"quote of an unavailable callout\", never \"no quote\"", "nullable": true, "type": "string" }, "actingUserId": { "nullable": true, "description": "Squad callouts: the admin who posted on the squad's behalf; presence is not the squad discriminator, the author's kind is", "type": "string" }, "actingUser": { "nullable": true, "description": "actingUserId set with actingUser null means \"unresolved\", not \"absent\"", "type": "object", "properties": { "userId": { "type": "string" }, "userName": { "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true" }, "xUsername": { "nullable": true, "type": "string" } }, "required": [ "userId", "userName", "profileImage", "walletAddress", "isVerified", "verifiedBadgeVisible", "xUsername" ], "additionalProperties": false }, "quotedCallout": { "nullable": true, "description": "The quoted callout one level deep (its own quotedCallout is always null)", "type": "object", "properties": { "coinMint": { "type": "string" }, "walletAddress": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "profileImage": { "nullable": true, "type": "string" }, "isVerified": { "type": "boolean" }, "verifiedBadgeVisible": { "type": "boolean", "description": "Badge rendering hint beside isVerified: show the checkmark only when both are true; true for user-less callouts" }, "accountKind": { "type": "string", "enum": [ "person", "group" ], "description": "'group' = a squad callout: userId/userName/profileImage are the squad's while walletAddress is the acting admin's posting wallet; route the author press on userId + accountKind, never the wallet" }, "xUsername": { "nullable": true, "type": "string" }, "xFollowerCount": { "type": "number" }, "mediaUrl": { "nullable": true, "type": "string" }, "chain": { "description": "CAIP-2 chain of the called-out ref; absent when the callout carries none", "type": "string" }, "mediaTranscript": { "description": "Speech-to-text transcript of an attached voice note; absent on every other callout", "type": "string" }, "callout": { "$ref": "#/components/schemas/Shared_fceda4efe6cd" } }, "required": [ "coinMint", "walletAddress", "userId", "userName", "profileImage", "isVerified", "verifiedBadgeVisible", "accountKind", "xUsername", "xFollowerCount", "mediaUrl", "callout" ], "additionalProperties": false } }, "required": [ "calloutId", "calledOutAtMcap", "multiple", "thesis", "mediaUrl", "calloutTimestamp", "likes", "hasLiked", "updates", "updateCount", "commentCount", "replyCount", "maxMultiplier", "maxMultiplierAt", "calloutPrice", "repostCount", "quoteCount", "hasReposted", "actingUserId", "actingUser", "quotedCallout" ], "additionalProperties": false } }, "headers": { "X-RateLimit-Limit": { "description": "Requests allowed in the current 60 second bucket (60 x the key's per-second rate).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current bucket.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time in seconds when the bucket refills.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying. Present on 429 and 503.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Origin-generated request id; quote it in support requests.", "schema": { "type": "string" } }, "x-pump-api-key-id": { "description": "Opaque id of the key that made the request, for support tickets. Never the key itself.", "schema": { "type": "string" } }, "Deprecation": { "description": "Present on a deprecated route: `@` of the day the deprecation was announced (RFC 9745).", "schema": { "type": "string" } }, "Sunset": { "description": "Present on a deprecated route: the HTTP-date after which it is no longer served (RFC 8594). At least 90 days after the Deprecation date.", "schema": { "type": "string" } }, "Link": { "description": "Present on a deprecated route that has a replacement: `; rel=\"successor-version\"`, the successor being its `/v1` path with this request's path parameters filled in, or an absolute URL. Resolve it against the request URL (RFC 8288).", "schema": { "type": "string" } } }, "responses": { "BadRequestCredential": { "description": "A credential of the wrong kind was sent to this host.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_CREDENTIAL_NOT_ALLOWED": { "summary": "A session credential was sent to the API host, or an API key was sent to the pump.fun web host. Keys work only on api.pump.fun.", "value": { "statusCode": 400, "timestamp": "2026-01-01T00:00:00.000Z", "path": "/v1/users/123", "error": "API_CREDENTIAL_NOT_ALLOWED", "message": "A session credential was sent to the API host, or an API key was sent to the pump.fun web host. Keys work only on api.pump.fun." } } } } } }, "Unauthorized": { "description": "Missing, malformed or unknown API key.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" }, "WWW-Authenticate": { "description": "Not set by the API itself. May appear on a 401 answered in front of the API; such a reply does not carry the envelope above.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_REQUIRED": { "summary": "No API key was sent. Send `Authorization: Bearer `.", "value": { "statusCode": 401, "timestamp": "2026-01-01T00:00:00.000Z", "path": "/v1/users/123", "error": "API_KEY_REQUIRED", "message": "No API key was sent. Send `Authorization: Bearer `." } }, "API_KEY_INVALID": { "summary": "The key is malformed (wrong prefix, length or checksum) or unknown.", "value": { "statusCode": 401, "timestamp": "2026-01-01T00:00:00.000Z", "path": "/v1/users/123", "error": "API_KEY_INVALID", "message": "The key is malformed (wrong prefix, length or checksum) or unknown." } } } } } }, "Forbidden": { "description": "The key or its organisation may not call this route.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_REVOKED": { "summary": "The key was revoked. Create a new key in the developer console.", "value": { "statusCode": 403, "timestamp": "2026-01-01T00:00:00.000Z", "path": "/v1/users/123", "error": "API_KEY_REVOKED", "message": "The key was revoked. Create a new key in the developer console." } }, "API_ORG_SUSPENDED": { "summary": "The organisation that owns the key is suspended or closed.", "value": { "statusCode": 403, "timestamp": "2026-01-01T00:00:00.000Z", "path": "/v1/users/123", "error": "API_ORG_SUSPENDED", "message": "The organisation that owns the key is suspended or closed." } }, "API_ORG_NOT_APPROVED": { "summary": "The organisation has applied but is not approved yet.", "value": { "statusCode": 403, "timestamp": "2026-01-01T00:00:00.000Z", "path": "/v1/users/123", "error": "API_ORG_NOT_APPROVED", "message": "The organisation has applied but is not approved yet." } }, "API_SCOPE_FORBIDDEN": { "summary": "The key lacks the scope this route needs; `requiredScope` names it.", "value": { "statusCode": 403, "timestamp": "2026-01-01T00:00:00.000Z", "path": "/v1/users/123", "error": "API_SCOPE_FORBIDDEN", "message": "The key lacks the scope this route needs; `requiredScope` names it.", "requiredScope": "profiles.read" } } } } } }, "TooManyRequests": { "description": "A rate limit was hit; wait for `Retry-After`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "x-pump-api-key-id": { "$ref": "#/components/headers/x-pump-api-key-id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_RATE_LIMITED": { "summary": "A limit was hit; `window` names the ceiling (the `Error` schema lists the values) and `limit` its size. Wait `retryAfterMs` or `Retry-After`.", "value": { "statusCode": 429, "timestamp": "2026-01-01T00:00:00.000Z", "path": "/v1/users/123", "error": "API_KEY_RATE_LIMITED", "message": "A limit was hit; `window` names the ceiling (the `Error` schema lists the values) and `limit` its size. Wait `retryAfterMs` or `Retry-After`.", "retryAfterMs": 1000, "limit": 60, "window": "burst" } } } } } }, "ServiceUnavailable": { "description": "The API could not check the key or its limits because a backing store is unavailable. Keyed calls fail closed; retry after `Retry-After` (`retryAfterSeconds` in the body says the same). The body carries no `error` code: branch on the status.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "statusCode": 503, "timestamp": "2026-01-01T00:00:00.000Z", "path": "/v1/users/123", "message": "API platform temporarily unavailable; retry after 5s", "retryAfterSeconds": 5 } } } }, "Default": { "description": "Any other error: the shared envelope. `error` is a route code from `x-error-codes`, a platform code or an HTTP reason phrase.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-error-registry": { "API_CREDENTIAL_NOT_ALLOWED": { "status": 400, "summary": "Each host accepts only its own credential kind", "actionable": true, "retryable": "never" }, "API_KEY_INVALID": { "status": 401, "summary": "The credential is not a well-formed pf_live_ key (prefix, length, charset or checksum) or no key record exists for it", "actionable": true, "retryable": "never" }, "API_KEY_RATE_LIMITED": { "status": 429, "summary": "A key ceiling refused: the per-key burst bucket, the UTC daily limit (a limit of 0 means the key is paused), the per-IP failed-auth throttle, or the per-IP lookup budget; retry after `retryAfterMs`", "actionable": false, "retryable": "after", "data": { "type": "object", "properties": { "retryAfterMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Milliseconds until the bucket admits a request again" }, "limit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The ceiling that refused: the 60-second bucket (60 x the key's per-second rate), the daily limit, the per-IP failed-auth budget, or the per-IP lookup budget" }, "window": { "type": "string", "enum": [ "burst", "day", "auth", "lookup" ], "description": "Which ceiling refused: burst (the per-key 60-second bucket), day (the per-key UTC daily limit), auth (per-IP failed authentications, charged on failed outcomes only), lookup (per-IP budget of uncached key lookups)" } }, "required": [ "retryAfterMs", "limit", "window" ] } }, "API_KEY_REQUIRED": { "status": 401, "summary": "The keyed API host got no credential: send Authorization: Bearer or x-api-key: ", "actionable": true, "retryable": "never" }, "API_KEY_REVOKED": { "status": 403, "summary": "The key was revoked (by its owner or by the pump.fun team); issue a new key in the developer console", "actionable": true, "retryable": "never" }, "API_ORG_NOT_APPROVED": { "status": 403, "summary": "The key's org application has not been approved yet (or a key is requested before approval)", "actionable": false, "retryable": "after" }, "API_ORG_SUSPENDED": { "status": 403, "summary": "The key's org is suspended or closed, so none of its keys is served", "actionable": false, "retryable": "never" }, "API_SCOPE_FORBIDDEN": { "status": 403, "summary": "The key does not hold the API scope this route needs; `requiredScope` names it", "actionable": true, "retryable": "never", "data": { "type": "object", "properties": { "requiredScope": { "type": "string", "description": "The API scope the route needs and the key does not hold" } }, "required": [ "requiredScope" ] } }, "API_USER_REQUIRED": { "status": 400, "summary": "The route serves the signed-in user when `user` is omitted, but an API key is never a session: send `user=` when calling with an API key", "actionable": true, "retryable": "never" }, "CALLOUT_NOT_FOUND": { "status": 404, "summary": "No callout with that id: deleted, hidden, or never existed", "actionable": false, "retryable": "never" }, "PARENT_REPLY_NOT_FOUND": { "status": 404, "summary": "The reply being nested under does not exist: deleted, or posted too recently to have flushed", "actionable": false, "retryable": "never" }, "PORTFOLIO_BUILDING": { "status": 409, "summary": "The wallet's portfolio is still being built and could not be served within the request's time budget; the build keeps running and a poll in a few seconds serves it", "actionable": false, "retryable": "after" }, "REPLY_NOT_FOUND": { "status": 404, "summary": "No reply with that id: deleted, hidden, or never existed", "actionable": false, "retryable": "never" } } } }