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",
          "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>"
              },
              "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>",
                        "commentCount30d": 123,
                        "pnl30d": 123,
                        "winRate30d": 123,
                        "tradeCount30d": 123,
                        "roiPercent30d": 123
                      }
                    }
                  },
                  "timestamp": 123
                }
              ]
            }
          ]
        }
      ],
      "positionAmountWithLeverage": 123
    },
    "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>",
          "commentCount30d": 123,
          "pnl30d": 123,
          "winRate30d": 123,
          "tradeCount30d": 123,
          "roiPercent30d": 123
        }
      }
    },
    "imageUrl": "<string>"
  }
]

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>[]

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 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: copytrade count and volume, 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