Skip to main content
GET
/
v1
/
tokens
/
{chain}
/
{contractAddress}
/
positions
/
{status}
Get Token Positions
curl --request GET \
  --url https://api.clicker.xyz/v1/tokens/{chain}/{contractAddress}/positions/{status} \
  --header 'Authorization: Bearer <token>'
[
  {
    "totalCompletions": 123,
    "itemTitle": "<string>",
    "callToActions": [
      {
        "text": "<string>",
        "url": "<string>"
      }
    ],
    "metadata": {
      "tokenChain": "ethereum",
      "tokenSymbol": "<string>",
      "tokenName": "<string>",
      "tokenAddress": "<string>",
      "metadataType": "token",
      "totalSupply": "<string>",
      "perpPositionType": "long",
      "perpLeverage": 123,
      "positionAmount": 123,
      "positionStats": {
        "boughtUSD": 123,
        "soldUSD": 123,
        "realizedGainsUSD": 123,
        "holdingsCostBasisUSD": 123,
        "receivedCostBasisUSD": 123,
        "holdingReceivedCostBasisUSD": 123,
        "isOpen": true,
        "boughtUSDWithLeverage": 123,
        "soldUSDWithLeverage": 123,
        "holdingsCostBasisUSDWithLeverage": 123,
        "unavailable": true
      },
      "trades": [
        {
          "tokenAmount": 123,
          "usdCost": 123,
          "marketCap": 123,
          "timestamp": 123,
          "transactionHash": "<string>",
          "direction": "buy",
          "classification": "spot",
          "intent": "enter",
          "perpPositionType": "long",
          "perpLeverage": 123,
          "comments": [
            {
              "uid": "<string>",
              "transactionHash": "<string>",
              "chain": "ethereum",
              "tokenAddress": "<string>",
              "commentText": "<string>",
              "timestamp": 123,
              "isAppUserComment": true,
              "metrics": {
                "copyCount": 123,
                "copyVolume": "<string>",
                "likeCount": 123,
                "isLikedByUser": true
              },
              "signerAddress": "<string>",
              "replies": [
                {
                  "id": "<string>",
                  "text": "<string>",
                  "author": {
                    "type": "user",
                    "address": "<string>",
                    "name": "<string>",
                    "images": {
                      "raw": "<string>",
                      "xs": "<string>",
                      "sm": "<string>"
                    },
                    "profile": {
                      "id": "<string>",
                      "name": "<string>",
                      "images": {
                        "raw": "<string>",
                        "xs": "<string>",
                        "sm": "<string>"
                      },
                      "addresses": [
                        "<string>"
                      ],
                      "metadata": {
                        "farcasterUsername": "<string>",
                        "farcasterId": 123,
                        "lensHandle": "<string>",
                        "ensName": "<string>",
                        "twitterHandle": "<string>",
                        "debankName": "<string>",
                        "hlName": "<string>",
                        "commentCount30d": 123,
                        "pnl30d": 123,
                        "winRate30d": 123,
                        "tradeCount30d": 123,
                        "roiPercent30d": 123,
                        "pnl7d": 123,
                        "winRate7d": 123,
                        "tradeCount7d": 123,
                        "roiPercent7d": 123,
                        "medianHoldingTimeMinutes": 123
                      },
                      "isNSFW": false,
                      "externalId": "<string>"
                    }
                  },
                  "timestamp": 123,
                  "likeCount": 123,
                  "isLikedByUser": true
                }
              ]
            }
          ]
        }
      ],
      "positionAmountWithLeverage": 123
    },
    "insights": [
      {
        "text": "<string>"
      }
    ],
    "metrics": {
      "copyCount": 123,
      "copyVolume": "<string>",
      "likeCount": 123,
      "isLikedByUser": true,
      "replyCount": 123,
      "commentCount": 123
    },
    "itemId": "<string>",
    "timestamp": 123,
    "cardLatestTradeAt": 123,
    "actor": {
      "type": "user",
      "address": "<string>",
      "name": "<string>",
      "images": {
        "raw": "<string>",
        "xs": "<string>",
        "sm": "<string>"
      },
      "profile": {
        "id": "<string>",
        "name": "<string>",
        "images": {
          "raw": "<string>",
          "xs": "<string>",
          "sm": "<string>"
        },
        "addresses": [
          "<string>"
        ],
        "metadata": {
          "farcasterUsername": "<string>",
          "farcasterId": 123,
          "lensHandle": "<string>",
          "ensName": "<string>",
          "twitterHandle": "<string>",
          "debankName": "<string>",
          "hlName": "<string>",
          "commentCount30d": 123,
          "pnl30d": 123,
          "winRate30d": 123,
          "tradeCount30d": 123,
          "roiPercent30d": 123,
          "pnl7d": 123,
          "winRate7d": 123,
          "tradeCount7d": 123,
          "roiPercent7d": 123,
          "medianHoldingTimeMinutes": 123
        },
        "isNSFW": false,
        "externalId": "<string>"
      }
    },
    "imageUrl": "<string>"
  }
]

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.

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:
ChainDescription
baseBase (Coinbase L2)
solanaSolana
ethereumEthereum mainnet
hyperliquidHyperliquid (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 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.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
chain
enum<string>
required
Available options:
ethereum,
optimism,
polygon,
arbitrum,
zora,
base,
zero,
solana,
hyperliquid
​
contractAddress
string
default:0x5180db8f5c931aae63c74266b211f580155ecac8
required

The contract / token address.

​
status
enum<string>
required

Position status filter. "open" = currently held (>= $1 value), "closed" = fully exited or dust (< $1 value).

Available options:
open,
closed
Example:

"closed"

Query Parameters

​
sort
enum<string>
default:value

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.

Available options:
value,
latest
​
chains
enum<string>[]
read-only

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.

Available options:
ethereum,
optimism,
polygon,
arbitrum,
zora,
base,
zero,
solana,
hyperliquid,
all
​
page
number
default:1

Page number for pagination (1-based)

Required range: x >= 1
​
limit
number
default:20

Number of positions per page (max 100)

Required range: 1 <= x <= 100

Response

200

​
totalCompletions
number
required

Number of unique addresses that purchased this token in the last 24 hours

​
itemTitle
string
required

Display title for the position (typically profile name)

​
callToActions
object[]
required

Action buttons/links for this position

​
metadata
object
required

Token details and position statistics including all trades

​
insights
object[]
required

AI-generated insights and metrics about this position

​
metrics
object
required

Engagement metrics: copytrade count and volume, reply count, comment count

​
itemId
string
required

Unique identifier for this feed card (position)

​
timestamp
number
required

Unix timestamp of the most recent trade in this position

​
cardLatestTradeAt
number
required

Unix timestamp of the most recent trade in this position. Used for "latest" sort ordering.

​
actor
object
required

Profile information of the trader who holds/held this position

​
imageUrl
string

Profile avatar image URL of the actor