Skip to main content
GET
/
v1
/
positions
/
{address}
/
{chain}
/
{contract}
/
{timestamp}
Position by Actor / Token / Timestamp
curl --request GET \
  --url https://api.clicker.xyz/v1/positions/{address}/{chain}/{contract}/{timestamp} \
  --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
                    },
                    "externalId": "<string>"
                  }
                },
                "timestamp": 123
              }
            ]
          }
        ]
      }
    ],
    "positionAmountWithLeverage": 123
  },
  "insights": [
    {
      "text": "<string>"
    }
  ],
  "metrics": {
    "copyCount": 123,
    "copyVolume": "<string>",
    "likeCount": 123,
    "isLikedByUser": true,
    "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>",
        "hlName": "<string>",
        "commentCount30d": 123,
        "pnl30d": 123,
        "winRate30d": 123,
        "tradeCount30d": 123,
        "roiPercent30d": 123,
        "pnl7d": 123,
        "winRate7d": 123,
        "tradeCount7d": 123,
        "roiPercent7d": 123,
        "medianHoldingTimeMinutes": 123
      },
      "externalId": "<string>"
    }
  },
  "imageUrl": "<string>"
}

Authorizations

Authorization
string
header
required

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

Path Parameters

address
string
default:0xa4e221aa5a7ba51b5d5c7d5c923bfb9bcebcb252
required

The address / public key.

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

The contract / token address.

timestamp
number | null
required

Unix timestamp, in seconds or (for Hyperliquid) milliseconds

Example:

1700000000

Query Parameters

viewerAddresses
string[]

Optional viewer address(es) to populate isLikedByUser on comments and replies. Accepts a single address or an array of the viewer’s linked wallets (additional addresses beyond 10 are ignored).

Response

200

A group of trades of a single token by a single actor comprising a position. Contains full trade history, position stats, and engagement metrics.

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)

transactionHash
string
required

Transaction hash of the most recent trade in this 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