> ## Documentation Index > Fetch the complete documentation index at: https://docs.clicker.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Token Positions > Returns positions for a specific token across all traders. Open positions are those with remaining value >= \$1; closed positions have remaining value < \$1 (fully exited or dust). The metadata.trades array is only populated with trades which were commented on. Returns open or closed positions for a specific token across named traders. Use this to enrich token detail pages with social trading context — showing which traders have conviction in a token and how their positions are performing. ## Path Parameters ### `chain` The blockchain the token is on. Supported chains: | Chain | Description | | ------------- | ------------------- | | `base` | Base (Coinbase L2) | | `solana` | Solana | | `ethereum` | Ethereum mainnet | | `hyperliquid` | Hyperliquid (perps) | ### `contractAddress` The token's contract address on the given chain. ### `status` Either `open` or `closed`. ## Sorting The default sort is `value`, which orders positions by size: * **Open positions** are sorted by **holding amount** (largest current holdings first). * **Closed positions** are sorted by **all-time realized PnL** (highest profit first). You can pass `sort=latest` to sort by most recent trade activity instead. ## Calling This Endpoint for Perps Perps positions on Hyperliquid use the same endpoint — just pass `hyperliquid` as the chain. For example, to get open ETH perps positions: ``` GET /v1/tokens/hyperliquid/0x0000000000000000000000000000000000000000/positions/open ``` Perps positions include additional fields like `perpPositionType`, `perpLeverage`, and `positionAmountWithLeverage`. See the [Perps Positions guide](/guides/perps) for how to handle these fields in your integration. ## Understanding Position Values The response includes several USD value fields that serve different purposes: **`positionAmount`** is the base token quantity held. For perps, this is the margin amount (un-leveraged). **`positionAmountWithLeverage`** (perps only) is the token amount multiplied by leverage — the notional exposure. **`positionStats.holdingsCostBasisUSD`** is the USD cost basis of the current holdings. For spot, this is what the trader paid for tokens they still hold. For perps, this is the margin posted. **`positionStats.realizedGainsUSD`** is the all-time realized PnL for the position. To compute **unrealized PnL**, you need a current price from your own pricing source: ``` // Spot unrealizedPnL = (positionAmount * currentPrice) - holdingsCostBasisUSD // Perps (see the Perps guide for long vs short) unrealizedPnL = (positionAmountWithLeverage * currentPrice) - holdingsCostBasisUSDWithLeverage ``` Clicker provides the position data and cost basis. Your app provides the real-time price. ## OpenAPI ````yaml GET /v1/tokens/{chain}/{contractAddress}/positions/{status} openapi: 3.0.0 info: version: 1.0.0 title: Daylight.xyz API description: >- Welcome to the Daylight API! API endpoints require a Daylight partner API key passed in the HTTP Authorization header. servers: - url: https://api.clicker.xyz security: - {} - bearerAuth: [] paths: /v1/tokens/{chain}/{contractAddress}/positions/{status}: get: tags: - Social - Feed, Profiles and Discovery summary: Get Token Positions description: >- Returns positions for a specific token across all traders. Open positions are those with remaining value >= \$1; closed positions have remaining value < \$1 (fully exited or dust). The metadata.trades array is only populated with trades which were commented on. parameters: - schema: type: string enum: - ethereum - optimism - polygon - arbitrum - zora - base - zero - solana - hyperliquid required: true name: chain in: path - schema: type: string default: '0x5180db8f5c931aae63c74266b211f580155ecac8' description: The contract / token address. required: true name: contractAddress in: path - schema: type: string enum: - open - closed description: >- Position status filter. "open" = currently held (>= \$1 value), "closed" = fully exited or dust (< \$1 value). example: closed required: true name: status in: path - schema: type: string enum: - value - latest default: value description: >- Sorting method. "value" (default): sorts by realized gains for closed positions, 30-day sell cost basis for open. "latest": sorts by close date for closed positions, open date for open. required: false name: sort in: query - schema: type: array description: >- If included, only include transactions with actions on the provided chains. Defaults to `base`, `ethereum`, `solana`. Pass `all` to see transactions on all supported chains. items: enum: - ethereum - optimism - polygon - arbitrum - zora - base - zero - solana - hyperliquid - all readOnly: true required: false name: chains in: query - schema: type: number minimum: 1 default: 1 description: Page number for pagination (1-based) required: false name: page in: query - schema: type: number minimum: 1 maximum: 100 default: 20 description: Number of positions per page (max 100) required: false name: limit in: query responses: '200': description: '200' content: application/json: schema: type: array items: type: object properties: totalCompletions: type: number description: >- Number of unique addresses that purchased this token in the last 24 hours imageUrl: type: string description: Profile avatar image URL of the actor itemTitle: type: string description: Display title for the position (typically profile name) callToActions: type: array items: type: object properties: text: type: string url: type: string required: - text - url description: Action buttons/links for this position metadata: type: object properties: tokenChain: type: string enum: - ethereum - optimism - polygon - arbitrum - zora - base - zero - solana - hyperliquid description: Blockchain network (e.g., ethereum, solana, base) tokenSymbol: type: string description: Token ticker symbol tokenName: type: string description: Human-readable token name tokenAddress: type: string description: Contract address of the token metadataType: type: string enum: - token totalSupply: type: string nullable: true description: Total token supply if known perpPositionType: type: string nullable: true enum: - long - short description: >- For perp positions, whether this is a 'long' or 'short' position. Null for spot positions. perpLeverage: type: number nullable: true description: >- For perp positions, the leverage multiplier (e.g., 5 for 5x leverage). Null for spot positions. positionAmount: type: number description: >- Current token balance held. A value >= 0.0001 indicates an open position; < 0.0001 indicates closed. For perps, this is the un-leveraged amount. positionAmountWithLeverage: type: number description: >- For leveraged perp positions, the position amount multiplied by leverage (capital at risk). Only present for hyperliquid. positionStats: type: object properties: boughtUSD: type: number description: >- Total USD spent buying this token (all-time). For perps, this is the un-leveraged amount. boughtUSDWithLeverage: type: number description: >- For leveraged perp positions, total USD spent multiplied by leverage. Only present for hyperliquid. soldUSD: type: number description: >- Total USD received from selling this token (all-time). For perps, this is the un-leveraged amount. soldUSDWithLeverage: type: number description: >- For leveraged perp positions, total USD received multiplied by leverage. Only present for hyperliquid. realizedGainsUSD: type: number description: >- Realized profit/loss in USD (sold value minus cost basis of sold tokens) holdingsCostBasisUSD: type: number description: >- USD cost basis of tokens currently held (for unrealized P&L calculation). For perps, this is the un-leveraged amount. holdingsCostBasisUSDWithLeverage: type: number description: >- For leveraged perp positions, cost basis of held tokens multiplied by leverage. Only present for hyperliquid. receivedCostBasisUSD: type: number description: >- Total USD value of tokens received via airdrops/transfers (all-time) holdingReceivedCostBasisUSD: type: number description: USD cost basis of currently held received tokens isOpen: type: boolean description: Whether this position is currently open unavailable: type: boolean enum: - true description: True when position metrics could not be computed required: - boughtUSD - soldUSD - realizedGainsUSD - holdingsCostBasisUSD - receivedCostBasisUSD - holdingReceivedCostBasisUSD - isOpen description: Aggregated trading statistics for this position trades: type: array items: type: object properties: tokenAmount: type: number description: >- The amount of tokens traded. Negative for sells. usdCost: type: number description: >- The USD cost traded for all tokens. Negative for sells. marketCap: type: number nullable: true description: >- The market cap of the token at the time of this trade timestamp: type: number transactionHash: type: string direction: type: string enum: - buy - sell classification: type: string nullable: true enum: - spot - perp - send - receive description: >- High-level trade classification: 'spot' for spot trades, 'perp' for perpetual futures, 'send' for outgoing transfers, 'receive' for airdrops/incoming transfers. Null for legacy trades. intent: type: string enum: - enter - exit description: >- Whether this trade is entering or exiting a position. For spot trades, 'enter' = buy and 'exit' = sell. For perps, direction depends on position type (e.g., opening a short is 'enter' even though the trade side is 'sell'). perpPositionType: type: string nullable: true enum: - long - short description: >- For perps positions, whether this is a 'long' or 'short' position. Null for spot trades. perpLeverage: type: number nullable: true description: >- For perps positions, the leverage multiplier (e.g., 5 for 5x leverage). Null for spot trades. comments: type: array items: type: object properties: uid: type: string description: Unique identifier for the comment transactionHash: type: string description: >- The transaction hash associated with the swap chain: type: string enum: - ethereum - optimism - polygon - arbitrum - zora - base - zero - solana - hyperliquid tokenAddress: type: string description: >- The token address associated with the swap commentText: type: string description: The comment text signerAddress: type: string description: >- The Ethereum address of the comment author timestamp: type: number description: >- Unix timestamp of when the comment was created isAppUserComment: type: boolean description: >- Whether the comment was created by a user of this partner's app metrics: type: object properties: copyCount: type: number description: >- The number of times the comment has been copied copyVolume: type: string description: The volume of the comment in USD likeCount: type: number description: The number of likes on this comment isLikedByUser: type: boolean description: >- Whether the requesting user has liked this comment required: - copyCount - copyVolume - likeCount - isLikedByUser replies: type: array items: type: object properties: id: type: string description: Unique identifier for the reply text: type: string description: The reply text author: type: object properties: type: type: string enum: - user address: type: string name: type: string description: >- The name of the feed actor. Use this field for maximum forward compatibility. images: type: object properties: raw: type: string nullable: true description: The full-sized image xs: type: string nullable: true description: 75x75 sm: type: string nullable: true description: 300x300 required: - raw - xs - sm description: >- An image of the feed actor. Use this field for maximum forward compatibility. profile: type: object properties: id: type: string name: type: string images: type: object properties: raw: type: string nullable: true description: The full-sized image xs: type: string nullable: true description: 75x75 sm: type: string nullable: true description: 300x300 required: - raw - xs - sm description: URLs for different size squares. addresses: type: array items: type: string externalId: type: string metadata: type: object properties: farcasterUsername: type: string nullable: true farcasterId: type: number nullable: true lensHandle: type: string nullable: true ensName: type: string nullable: true twitterHandle: type: string nullable: true debankName: type: string nullable: true hlName: type: string nullable: true commentCount30d: type: number nullable: true pnl30d: type: number nullable: true winRate30d: type: number nullable: true tradeCount30d: type: number nullable: true roiPercent30d: type: number nullable: true pnl7d: type: number nullable: true winRate7d: type: number nullable: true tradeCount7d: type: number nullable: true roiPercent7d: type: number nullable: true medianHoldingTimeMinutes: type: number nullable: true required: - farcasterUsername - farcasterId - lensHandle - ensName - twitterHandle - debankName - hlName - commentCount30d - pnl30d - winRate30d - tradeCount30d - roiPercent30d - pnl7d - winRate7d - tradeCount7d - roiPercent7d - medianHoldingTimeMinutes isNSFW: anyOf: - type: boolean enum: - false - type: object properties: nsfwImage: type: boolean nsfwText: type: boolean required: - nsfwImage - nsfwText description: >- `false` when the profile is clean. Otherwise an object with `nsfwImage` and `nsfwText` booleans indicating which axes the scanner flagged. Clients decide whether to render, censor, or hide the underlying content. required: - id - name - images - addresses - metadata - isNSFW description: >- Profile of the user (including additional known addresses and extra metadata). Use this field to tailor your UI specifically. required: - type - address - name - images - profile description: >- The actor that completed an action to create a feed item. timestamp: type: number description: >- Unix timestamp of when the reply was created likeCount: type: number description: The number of likes on this reply isLikedByUser: type: boolean description: >- Whether the requesting user has liked this reply required: - id - text - author - timestamp - likeCount - isLikedByUser description: >- Replies to this comment, only included when fetching a single position required: - uid - transactionHash - chain - tokenAddress - commentText - timestamp - isAppUserComment - metrics required: - tokenAmount - usdCost - marketCap - timestamp - transactionHash - direction - classification - intent - perpPositionType - perpLeverage - comments description: >- Complete list of all buy/sell transactions for this token by this actor, ordered by timestamp descending required: - tokenChain - tokenSymbol - tokenName - tokenAddress - metadataType - totalSupply - perpPositionType - perpLeverage - positionAmount - positionStats - trades description: >- Token details and position statistics including all trades insights: type: array items: type: object properties: text: type: string required: - text description: AI-generated insights and metrics about this position metrics: type: object properties: copyCount: type: number description: The number of times the comment has been copied copyVolume: type: string description: The volume of the comment in USD likeCount: type: number description: The number of likes on this comment isLikedByUser: type: boolean description: Whether the requesting user has liked this comment replyCount: type: number description: Number of replies on this position commentCount: type: number description: The number of author comments on this position required: - copyCount - copyVolume - likeCount - isLikedByUser - replyCount - commentCount description: >- Engagement metrics: copytrade count and volume, reply count, comment count itemId: type: string description: Unique identifier for this feed card (position) timestamp: type: number description: Unix timestamp of the most recent trade in this position cardLatestTradeAt: type: number description: >- Unix timestamp of the most recent trade in this position. Used for "latest" sort ordering. actor: type: object properties: type: type: string enum: - user address: type: string name: type: string description: >- The name of the feed actor. Use this field for maximum forward compatibility. images: type: object properties: raw: type: string nullable: true description: The full-sized image xs: type: string nullable: true description: 75x75 sm: type: string nullable: true description: 300x300 required: - raw - xs - sm description: >- An image of the feed actor. Use this field for maximum forward compatibility. profile: type: object properties: id: type: string name: type: string images: type: object properties: raw: type: string nullable: true description: The full-sized image xs: type: string nullable: true description: 75x75 sm: type: string nullable: true description: 300x300 required: - raw - xs - sm description: URLs for different size squares. addresses: type: array items: type: string externalId: type: string metadata: type: object properties: farcasterUsername: type: string nullable: true farcasterId: type: number nullable: true lensHandle: type: string nullable: true ensName: type: string nullable: true twitterHandle: type: string nullable: true debankName: type: string nullable: true hlName: type: string nullable: true commentCount30d: type: number nullable: true pnl30d: type: number nullable: true winRate30d: type: number nullable: true tradeCount30d: type: number nullable: true roiPercent30d: type: number nullable: true pnl7d: type: number nullable: true winRate7d: type: number nullable: true tradeCount7d: type: number nullable: true roiPercent7d: type: number nullable: true medianHoldingTimeMinutes: type: number nullable: true required: - farcasterUsername - farcasterId - lensHandle - ensName - twitterHandle - debankName - hlName - commentCount30d - pnl30d - winRate30d - tradeCount30d - roiPercent30d - pnl7d - winRate7d - tradeCount7d - roiPercent7d - medianHoldingTimeMinutes isNSFW: anyOf: - type: boolean enum: - false - type: object properties: nsfwImage: type: boolean nsfwText: type: boolean required: - nsfwImage - nsfwText description: >- `false` when the profile is clean. Otherwise an object with `nsfwImage` and `nsfwText` booleans indicating which axes the scanner flagged. Clients decide whether to render, censor, or hide the underlying content. required: - id - name - images - addresses - metadata - isNSFW description: >- Profile of the user (including additional known addresses and extra metadata). Use this field to tailor your UI specifically. required: - type - address - name - images - profile description: >- Profile information of the trader who holds/held this position required: - totalCompletions - itemTitle - callToActions - metadata - insights - metrics - itemId - timestamp - cardLatestTradeAt - actor '400': description: >- The request payload or query string parameter you passed was not valid content: application/json: schema: type: object properties: error: type: string required: - error '404': description: The item you requested could not be found content: application/json: schema: type: object properties: error: type: string required: - error components: securitySchemes: bearerAuth: type: http scheme: bearer ````