API reference · v5

Binance Smart Money API

Every trader on Binance's Smart Money leaderboard: rankings, open positions with entry and mark prices, and closed-trade and order history.

Base URL https://api.kopyon.com/v5/binance-smart-money/ · send your key in the X-API-KEY header · trader id: The number in a trader's Smart Money profile URL.

Get a free API key · Interactive reference with Try it · Authentication, paging and errors

Ranking

GET /v5/binance-smart-money/traders

The current Binance Smart Money ranking for a time range, by PnL or ROI.

Query parameters

Name	Type	Description
`rankingType`required	enum	Rank by profit or by returnPNL, ROI
`order`required	enum	DESC lists the highest first, ASC the lowestDESC, ASC
`onlyShowSharingPosition`required	bool	true lists only traders who share their positions
`period`required	enum	Period the ranking covers1D, 3D, 7D, 30D, 90D, 1Y, ALL
`accountGroup`	enum	Only AI traders, or Binance's featured AI or human tradersAI, FEATURED_TRADERS_AI, FEATURED_TRADERS_HUMAN
`page`	intdefault 1	Page number
`rows`	intdefault 20	Rows per page1 to 20

Response fields, in `data`

Field	Type	Description
`traders[]`always	array
`traders[].traderId`always	string	The trader's id at the source; other operations take it as traderId
`traders[].name`always	string	Display name
`traders[].avatarUrl`	string
`traders[].roi`	number
`traders[].pnl`	number
`traders[].pnlCurrency`	string
`traders[].sourceDetails.accountName`	only Binance
`traders[].sourceDetails.subscribers`	only Binance
`traders[].sourceDetails.assets`	only Binance
`traders[].sourceDetails.positionStatus`	only Binance
`traders[].sourceDetails.chart`	only Binance
`hasMore`always	boolean	true when another page follows
`total`always	number	Traders across all pages

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/binance-smart-money/traders?rankingType=PNL&order=DESC&onlyShowSharingPosition=true&period=1D"

{
  "data": {
    "traders": [
      {
        "traderId": "4555301953191358802",
        "name": "BlockchainUSA1",
        "avatarUrl": "https://public.nftstatic.com/static/nft/res/nft-cex/S3/1695716378565_p7gg128kqzin6mp0ezo3tlwjbbmqblp9.png",
        "roi": 0.541987,
        "pnl": 9754121.92997,
        "pnlCurrency": "USD",
        "sourceDetails": {
          "accountName": "Main",
          "subscribers": 5411,
          "assets": 6.0435405,
          "positionStatus": "NO_POSITION",
          "chart": {
            "metric": "PNL",
            "points": [
              {
                "timestamp": 1792245600000,
                "value": 0
              },
              {
                "timestamp": 1792249200000,
                "value": -0.034746
              },
              {
                "timestamp": 1792252800000,
                "value": -0.044926
              }
            ]
          }
        }
      },
      {
        "traderId": "4555301962251055450",
        "name": "yugoviking",
        "avatarUrl": "https://public.nftstatic.com/static/nft/res/nft-cex/S3/1698378555472_3wjk65lknpdunvgoq8bufjv69kax5c8k.png",
        "roi": 3.947321,
        "pnl": 7361291.091318,
        "pnlCurrency": "USD",
        "sourceDetails": {
          "accountName": "Main",
          "subscribers": 17922,
          "assets": 4.7566469,
          "positionStatus": "NO_POSITION",
          "chart": {
            "metric": "PNL",
            "points": [
              {
                "timestamp": 1792245600000,
                "value": 0
              },
              {
                "timestamp": 1792249200000,
                "value": -0.007267
              },
              {
                "timestamp": 1792252800000,
                "value": -0.010079
              }
            ]
          }
        }
      },
      {
        "traderId": "5009866480849101313",
        "name": "币享人生",
        "avatarUrl": "https://public.bnbstatic.com/image/common_notification/20211230/fe45acbe-4cb8-4d78-b426-07f3402e285c.png",
        "roi": 0.215513,
        "pnl": 5903541.188464,
        "pnlCurrency": "USD",
        "sourceDetails": {
          "accountName": "lp-oooe1ige8wja",
          "subscribers": 31864,
          "assets": 0,
          "positionStatus": "NO_POSITION",
          "chart": {
            "metric": "PNL",
            "points": [
              {
                "timestamp": 1792245600000,
                "value": 0
              },
              {
                "timestamp": 1792249200000,
                "value": 0
              },
              {
                "timestamp": 1792252800000,
                "value": 0
              }
            ]
          }
        }
      }
    ],
    "hasMore": true,
    "total": 100
  }
}

Search traders

GET /v5/binance-smart-money/traderSearch

Traders whose name matches. Results carry no roi or pnl.

Query parameters

Name	Type	Description
`name`required	string	Part of the trader's name
`page`	intdefault 1	Page number
`rows`	intdefault 20	Rows per page1 to 20

Response fields, in `data`

Field	Type	Description
`traders[]`always	array
`traders[].traderId`always	string	The trader's id at the source; other operations take it as traderId
`traders[].name`always	string	Display name
`traders[].avatarUrl`	string
`traders[].roi`	number
`traders[].pnl`	number
`traders[].pnlCurrency`	string
`traders[].sourceDetails.accountName`	only Binance
`traders[].sourceDetails.subscribers`	only Binance
`traders[].sourceDetails.assets`	only Binance
`traders[].sourceDetails.positionStatus`	only Binance
`traders[].sourceDetails.chart`	only Binance
`hasMore`always	boolean	true when another page follows
`total`always	number	Traders across all pages

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/binance-smart-money/traderSearch?name=Bloc"

{
  "data": {
    "traders": [
      {
        "traderId": "4762253409324263168",
        "name": "BLOCK-D Capitale",
        "avatarUrl": "https://public.bnbstatic.com/image/pgc/202509/860227c95bd60444f0e6b69389537385.png",
        "sourceDetails": {
          "accountName": "BLOCK-D Capitale",
          "subscribers": 0
        }
      },
      {
        "traderId": "4771499983147419393",
        "name": "BlockChainBunny",
        "avatarUrl": "https://public.bnbstatic.com/image/pgc/202410/b2e49b2979ac7dbd88b2ed6784e3ce6a.png",
        "sourceDetails": {
          "accountName": "BlockChainBunny",
          "subscribers": 0
        }
      },
      {
        "traderId": "4776973588770187776",
        "name": "BlockThinker",
        "avatarUrl": "https://public.bnbstatic.com/image/pgc/202511/e091d5eb66fa33785917f4dc329e30e7.jpg",
        "sourceDetails": {
          "accountName": "BlockThinker",
          "subscribers": 0
        }
      }
    ],
    "hasMore": true,
    "total": 418
  }
}

Trader profile

GET /v5/binance-smart-money/traderProfile

A trader's statistics, and whether they share positions and history.

Query parameters

Name	Type	Description
`traderId`required	string	The trader's id, from the ranking or a search

Response fields, in `data`

Field	Type	Description
`traderId`always	string
`name`	string
`avatarUrl`	string
`bio`	string
`roi`	number
`sourceDetails.accountName`	only Binance
`sourceDetails.enabled`	only Binance
`sourceDetails.sharingPositions`	only Binance
`sourceDetails.sharingPositionHistory`	only Binance
`sourceDetails.sharingLatestRecord`	only Binance
`sourceDetails.pnl`	only Binance
`sourceDetails.umMarginBalance`	only Binance
`sourceDetails.cmMarginBalance`	only Binance
`sourceDetails.daysActive`	only Binance
`sourceDetails.maxDrawdown`	only Binance
`sourceDetails.winRate`	only Binance
`sourceDetails.netTransfer`	only Binance
`sourceDetails.subscribers`	only Binance
`sourceDetails.isAi`	only Binance

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/binance-smart-money/traderProfile?traderId=4555301953191358802"

{
  "data": {
    "traderId": "4555301953191358802",
    "name": "BlockchainUSA1",
    "avatarUrl": "https://public.nftstatic.com/static/nft/res/nft-cex/S3/1695716378565_p7gg128kqzin6mp0ezo3tlwjbbmqblp9.png",
    "roi": 170.8454,
    "sourceDetails": {
      "accountName": "Main",
      "enabled": true,
      "sharingPositions": true,
      "sharingPositionHistory": true,
      "sharingLatestRecord": true,
      "pnl": 9754121.82896129,
      "umMarginBalance": 0.11185043,
      "cmMarginBalance": 5.74821022,
      "daysActive": 2526,
      "maxDrawdown": 0.099225,
      "winRate": 0.8017,
      "netTransfer": -9754115.886429,
      "subscribers": 5411,
      "isAi": false
    }
  }
}

Trader chart

GET /v5/binance-smart-money/traderChart

A trader's ROI, PnL or balance over a time range.

Query parameters

Name	Type	Description
`traderId`required	string	The trader's id, from the ranking or a search
`period`required	enum	Period the ranking covers1D, 3D, 7D, 30D, 90D, 1Y, ALL
`chartDataType`required	enum	What the chart measuresROI, PNL, BALANCE

Response fields, in `data`

Field	Type	Description
`metric`always	string	What the points measure: ROI, PNL or BALANCE
`points[]`always	array
`points[].timestamp`always	number	Point time, in Unix milliseconds
`points[].value`always	number

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/binance-smart-money/traderChart?traderId=4555301953191358802&period=1D&chartDataType=ROI"

{
  "data": {
    "metric": "ROI",
    "points": [
      {
        "timestamp": 1792245600000,
        "value": 0
      },
      {
        "timestamp": 1792249200000,
        "value": 0
      },
      {
        "timestamp": 1792252800000,
        "value": 0
      }
    ]
  }
}

Open positions

GET /v5/binance-smart-money/openPositions

A trader's open positions now. To follow them as they change, use the stream or a webhook.

Binance refreshes this Binance updates these positions every 10 s, so reading them more often returns the same data..

Query parameters

Name	Type	Description
`traderId`required	string	The trader's id, from the ranking or a search
`marketType`required	enum	UM for USDⓈ-M futures, CM for COIN-M futuresUM, CM
`page`	intdefault 1	Page number
`rows`	intdefault 20	Rows per page1 to 20

Response fields, in `data`

Field	Type	Description
`positions[]`always	array
`positions[].symbol`always	string
`positions[].side`always	LONG \| SHORT
`positions[].size`	number	Position size, always positive; side gives the direction
`positions[].entryPrice`always	number
`positions[].markPrice`	number	The exchange's mark price
`positions[].leverage`	number
`positions[].marginMode`	ISOLATED \| CROSS
`positions[].unrealizedPnl`	number	In pnlCurrency
`positions[].pnlCurrency`	string
`positions[].liquidationPrice`	number
`positions[].margin`	number	Margin the position uses, in pnlCurrency
`positions[].roi`	number	unrealizedPnl over margin, as a fraction. Where the exchange sends its own (KuCoin; BingX, over the opening margin), it is passed on and can differ from that ratio
`positions[].sourceDetails.marketType`	only Binance
`positions[].sourceDetails.maintenanceMargin`	only Binance
`positions[].sourceDetails.marginRatio`	only Binance
`total`	number
`hidden`always	boolean	true when the trader hides it; the list is then empty

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/binance-smart-money/openPositions?traderId=4555301952033730879&marketType=UM"

{
  "data": {
    "positions": [],
    "total": 0,
    "hidden": false
  }
}

Position history

GET /v5/binance-smart-money/positionHistory

Closed and partially closed positions. USDⓈ-M answers report total.

Query parameters

Name	Type	Description
`traderId`required	string	The trader's id, from the ranking or a search
`marketType`required	enum	UM for USDⓈ-M futures, CM for COIN-M futuresUM, CM
`startTime`	int	Unix time in milliseconds
`endTime`	int	Unix time in milliseconds
`rows`	intdefault 20	Rows per page1 to 20
`symbol`	string	Only this symbol, for example BTCUSDT
`cursor`	string	The nextCursor of the previous answer; leave it out for the first page

Response fields, in `data`

Field	Type	Description
`positions[]`always	array
`positions[].positionId`	string
`positions[].symbol`always	string
`positions[].side`	LONG \| SHORT
`positions[].status`	string
`positions[].marginMode`	ISOLATED \| CROSS
`positions[].leverage`	number
`positions[].roi`	number
`positions[].entryPrice`	number
`positions[].closePrice`	number
`positions[].openedAt`always	number	When the position opened, in Unix milliseconds
`positions[].closedAt`	number	When the position closed, in Unix milliseconds
`positions[].updatedAt`always	number	Last change, in Unix milliseconds
`positions[].openedVolume`	number
`positions[].closedVolume`	number
`positions[].maxOpenInterest`	number
`positions[].grossPnl`	number
`positions[].fundingPnl`	number
`positions[].tradingFee`	number
`positions[].liquidationFee`	number
`positions[].netPnl`	number
`positions[].pnlCurrency`	string
`positions[].sourceDetails.marketType`	only Binance
`positions[].sourceDetails.commissionByAsset`	only Binance
`total`	number	USDⓈ-M only
`hidden`always	boolean	true when the trader hides it; the list is then empty
`nextCursor`	string	Send it back as cursor, with the same query, to read the next page; absent on the last page

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/binance-smart-money/positionHistory?traderId=4555301952033730879&marketType=UM"

{
  "data": {
    "positions": [],
    "hidden": false,
    "total": 0
  }
}

Order history

GET /v5/binance-smart-money/orderHistory

A trader's executed orders.

Query parameters

Name	Type	Description
`traderId`required	string	The trader's id, from the ranking or a search
`marketType`required	enum	UM for USDⓈ-M futures, CM for COIN-M futuresUM, CM
`startTime`	int	Unix time in milliseconds
`endTime`	int	Unix time in milliseconds
`rows`	intdefault 20	Rows per page1 to 20
`cursor`	string	The nextCursor of the previous answer; leave it out for the first page

Response fields, in `data`

Field	Type	Description
`orders[]`always	array
`orders[].symbol`always	string
`orders[].side`always	string
`orders[].positionSide`	string	BOTH in one-way mode; LONG or SHORT in hedge mode
`orders[].price`	number
`orders[].quantity`	number
`orders[].quoteQuantity`	number
`orders[].createdAt`	number	When the order was placed, in Unix milliseconds
`orders[].updatedAt`always	number	Last change, in Unix milliseconds
`orders[].sourceDetails.marketType`	only Binance
`total`	number
`hidden`always	boolean	true when the trader hides it; the list is then empty
`nextCursor`	string	Send it back as cursor, with the same query, to read the next page; absent on the last page

Example

curl -H "X-API-KEY: $KOPYON_KEY" \
  "https://api.kopyon.com/v5/binance-smart-money/orderHistory?traderId=4555301953191358802&marketType=UM"

{
  "data": {
    "orders": [],
    "hidden": false,
    "total": 0
  }
}

Stream and webhooks

Paid plans can follow a trader in real time over wss://api.kopyon.com/v5/streamor through signed webhooks. Topics for this source:

openPositions: Open positions, whenever they change
positionEvents: Opened, increased, decreased, closed
orderHistory: New and updated orders
positionHistory: Newly closed positions

Stream messages and webhook signatures

Binance Smart Money API

Ranking

Query parameters

Response fields, in data

Example

Search traders

Query parameters

Response fields, in data

Example

Trader profile

Query parameters

Response fields, in data

Example

Trader chart

Query parameters

Response fields, in data

Example

Open positions

Query parameters

Response fields, in data

Example

Position history

Query parameters

Response fields, in data

Example

Order history

Query parameters

Response fields, in data

Example

Stream and webhooks

Try the Binance Smart Money API for free.

Response fields, in `data`

Response fields, in `data`

Response fields, in `data`

Response fields, in `data`

Response fields, in `data`

Response fields, in `data`

Response fields, in `data`