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>",
      "positionAmount": 123,
      "positionStats": {
        "boughtUSD": 123,
        "soldUSD": 123,
        "realizedGainsUSD": 123,
        "holdingsCostBasisUSD": 123
      },
      "trades": [
        {
          "tokenAmount": 123,
          "usdCost": 123,
          "marketCap": 123,
          "timestamp": 123,
          "transactionHash": "<string>",
          "direction": "buy",
          "perpPositionType": "long",
          "perpLeverage": 123,
          "comments": [
            {
              "uid": "<string>",
              "transactionHash": "<string>",
              "chain": "ethereum",
              "tokenAddress": "<string>",
              "commentText": "<string>",
              "timestamp": 123,
              "isAppUserComment": true,
              "metrics": {
                "copyCount": 123,
                "copyVolume": "<string>"
              },
              "signerAddress": "<string>"
            }
          ]
        }
      ]
    },
    "insights": [
      {
        "text": "<string>"
      }
    ],
    "metrics": {
      "copyCount": 123,
      "copyVolume": "<string>",
      "replyCount": 123,
      "commentCount": 123
    },
    "itemId": "<string>",
    "transactionHash": "<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>",
          "pumpName": "<string>",
          "commentCount30d": 123,
          "pnl30d": 123,
          "winRate30d": 123,
          "tradeCount30d": 123,
          "roiPercent30d": 123
        }
      }
    },
    "imageUrl": "<string>",
    "forYouTrade": {
      "tokenAmount": 123,
      "usdCost": 123,
      "marketCap": 123,
      "timestamp": 123,
      "transactionHash": "<string>",
      "direction": "buy",
      "perpPositionType": "long",
      "perpLeverage": 123,
      "comments": [
        {
          "uid": "<string>",
          "transactionHash": "<string>",
          "chain": "ethereum",
          "tokenAddress": "<string>",
          "commentText": "<string>",
          "timestamp": 123,
          "isAppUserComment": true,
          "metrics": {
            "copyCount": 123,
            "copyVolume": "<string>"
          },
          "signerAddress": "<string>"
        }
      ],
      "alphaTags": {
        "big_entry": 198371.27
      },
      "maxAlphaScore": 123
    }
  }
]

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:0xa4e221aa5a7ba51b5d5c7d5c923bfb9bcebcb252
required

The address / public key.

​
status
enum<string>
required

Position status filter. Use "closed" to get fully exited positions.

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
​
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 feed card (typically profile name)

​
callToActions
object[]
required

Action buttons/links for this card

​
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: likes, reposts, bookmarks, reply count, comment count

​
itemId
string
required

Unique identifier for this feed card (position)

​
transactionHash
string
required

Transaction hash of the first trade in this position

​
timestamp
number
required

Unix timestamp of the first 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

​
forYouTrade
object

Present only in For You feed. Highlights the specific trade with alpha tags that triggered recommendation.