Skip to main content
GET
/
v1
/
addresses
/
{identifier}
/
positions
/
{status}
Get Profile Positions
curl --request GET \
  --url https://api.clicker.xyz/v1/addresses/{identifier}/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

identifier
string
required

Profile UUID or wallet address to look up

status
enum<string>
required

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

Available options:
open,
closed
Example:

"closed"

Query Parameters

providedAddressesOnly
boolean

When true, returns positions for only the provided wallet address. When false (default), aggregates positions across all addresses in the profile.

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.