# Table of Contents

- [Introduction | Nansen API](#introduction-nansen-api)
- [Rate Limits | Nansen API](#rate-limits-nansen-api)
- [Credits & Pricing Guide | Nansen API](#credits-pricing-guide-nansen-api)
- [Use case Templates | Nansen API](#use-case-templates-nansen-api)
- [Endpoints Overview | Nansen API](#endpoints-overview-nansen-api)
- [Complex Use cases | Nansen API](#complex-use-cases-nansen-api)
- [Make Your First API Call | Nansen API](#make-your-first-api-call-nansen-api)
- [Simple Use cases | Nansen API](#simple-use-cases-nansen-api)
- [Use case 1: Automated Token Tracking & Smart Money Analysis | Nansen API](#use-case-1-automated-token-tracking-smart-money-analysis-nansen-api)
- [API Structure & Base URL | Nansen API](#api-structure-base-url-nansen-api)
- [Use case 3:  Identifying Related Wallets at Scale | Nansen API](#use-case-3-identifying-related-wallets-at-scale-nansen-api)
- [Authentication | Nansen API](#authentication-nansen-api)
- [Understanding Responses and Handling Errors | Nansen API](#understanding-responses-and-handling-errors-nansen-api)
- [Use Case 2: Find & Copytrade Wallets on Hyperliquid | Nansen API](#use-case-2-find-copytrade-wallets-on-hyperliquid-nansen-api)
- [Use case 4: Copytrading Top Performing Wallets | Nansen API](#use-case-4-copytrading-top-performing-wallets-nansen-api)
- [API Changelog | Nansen API](#api-changelog-nansen-api)
- [Use case 5: Monitoring CEX Health | Nansen API](#use-case-5-monitoring-cex-health-nansen-api)
- [Chain Coverage | Nansen API](#chain-coverage-nansen-api)
- [Smart Money | Nansen API](#smart-money-nansen-api)
- [Historical Holdings | Nansen API](#historical-holdings-nansen-api)
- [Profiler | Nansen API](#profiler-nansen-api)
- [Jupiter DCAs | Nansen API](#jupiter-dcas-nansen-api)
- [Perp Trades | Nansen API](#perp-trades-nansen-api)
- [Holdings | Nansen API](#holdings-nansen-api)
- [Netflows | Nansen API](#netflows-nansen-api)
- [2025-08-29 - Major API Restructuring | Nansen API](#2025-08-29-major-api-restructuring-nansen-api)
- [DEX Trades | Nansen API](#dex-trades-nansen-api)
- [Address Related Wallets | Nansen API](#address-related-wallets-nansen-api)
- [Address Perp Trades | Nansen API](#address-perp-trades-nansen-api)
- [Token God Mode | Nansen API](#token-god-mode-nansen-api)
- [Address Counterparties | Nansen API](#address-counterparties-nansen-api)
- [Useful Links | Nansen API](#useful-links-nansen-api)
- [Address Current Balances | Nansen API](#address-current-balances-nansen-api)
- [Portfolio | Nansen API](#portfolio-nansen-api)
- [Address Historical Balances | Nansen API](#address-historical-balances-nansen-api)
- [Flow Intelligence | Nansen API](#flow-intelligence-nansen-api)
- [Entity Name Search | Nansen API](#entity-name-search-nansen-api)
- [Address Labels | Nansen API](#address-labels-nansen-api)
- [Hyperliquid APIs | Nansen API](#hyperliquid-apis-nansen-api)
- [Hyperliquid Address Leaderboard | Nansen API](#hyperliquid-address-leaderboard-nansen-api)
- [Connecting to Nansen MCP | Nansen API](#connecting-to-nansen-mcp-nansen-api)
- [Perp Trades | Nansen API](#perp-trades-nansen-api)
- [PnL Leaderboard | Nansen API](#pnl-leaderboard-nansen-api)
- [Common MCP clients | Nansen API](#common-mcp-clients-nansen-api)
- [Token Information | Nansen API](#token-information-nansen-api)
- [Flows | Nansen API](#flows-nansen-api)
- [Address Perp Positions | Nansen API](#address-perp-positions-nansen-api)
- [Points | Nansen API](#points-nansen-api)
- [Address Transactions | Nansen API](#address-transactions-nansen-api)
- [Overview | Nansen API](#overview-nansen-api)
- [Perp PnL Leaderboard | Nansen API](#perp-pnl-leaderboard-nansen-api)
- [DEX Trades | Nansen API](#dex-trades-nansen-api)
- [Token Transfers | Nansen API](#token-transfers-nansen-api)
- [Who Bought/Sold | Nansen API](#who-bought-sold-nansen-api)
- [Address Perp Positions | Nansen API](#address-perp-positions-nansen-api)
- [Jupiter DCAs | Nansen API](#jupiter-dcas-nansen-api)
- [Perp PnL Leaderboard | Nansen API](#perp-pnl-leaderboard-nansen-api)
- [Holders | Nansen API](#holders-nansen-api)
- [Perp Screener | Nansen API](#perp-screener-nansen-api)
- [Perp Positions | Nansen API](#perp-positions-nansen-api)
- [Token Screener | Nansen API](#token-screener-nansen-api)
- [Token Perp Positions | Nansen API](#token-perp-positions-nansen-api)
- [Address PnL & Trade Performance | Nansen API](#address-pnl-trade-performance-nansen-api)
- [Smart Money Perp Trades | Nansen API](#smart-money-perp-trades-nansen-api)
- [Frequently Asked Questions | Nansen API](#frequently-asked-questions-nansen-api)
- [Hyperliquid Leaderboard | Nansen API](#hyperliquid-leaderboard-nansen-api)
- [Tools supported by Nansen MCP | Nansen API](#tools-supported-by-nansen-mcp-nansen-api)
- [Perp Screener | Nansen API](#perp-screener-nansen-api)
- [Address Perp Trades | Nansen API](#address-perp-trades-nansen-api)
- [Token Perp Trades | Nansen API](#token-perp-trades-nansen-api)
- [Data Redistribution Guidelines | Nansen API](#data-redistribution-guidelines-nansen-api)
- [MCP Data Redistribution Guidelines | Nansen API](#mcp-data-redistribution-guidelines-nansen-api)

---

# Introduction | Nansen API

Nansen API offers programmatic access to high-quality onchain data and advanced blockchain analytics across numerous networks. The API aims to equip users with the necessary data to gain a competitive edge, identify opportunities, perform due diligence, and make informed decisions within the dynamic crypto market. It effectively translates the complexity of raw blockchain data into actionable intelligence, accessible through a structured API interface.

### 

[](https://docs.nansen.ai/#key-capabilities)

Key Capabilities

*   **Proprietary Data Labeling:** Nansen applies unique, human-readable labels to hundreds of millions of blockchain addresses. These labels identify specific entities such as exchanges, funds, market makers, notable individual investors that allows users to understand who is behind onchain activities, providing crucial context that raw, pseudonymous data lacks. Accessing this labelled data via the API is a core component of Nansen's offering.
    
*   **Unique Datasets and Insights:** The API provides access to data points and analytics not readily available elsewhere, such as Smart Money analytics.
    
*   **Comprehensive Multi-Chain Coverage:** The API consolidates data from multiple blockchain networks, allowing users to track assets and activities across different ecosystems through a single integration point.
    

These features collectively enable the API to deliver not just data, but contextualized intelligence, transforming raw onchain events into a clearer picture of market dynamics and participant behavior.

### 

[](https://docs.nansen.ai/#jump-right-in)

Jump right in

[](https://docs.nansen.ai/getting-started/authentication)

Authentication

[](https://docs.nansen.ai/about/endpoints-overview)

Endpoints Overview

[](https://docs.nansen.ai/api/smart-money)

Smart Money API

[](https://docs.nansen.ai/api/profiler)

Profiler API

[](https://docs.nansen.ai/api/token-god-mode)

Token God Mode

[NextEndpoints Overview](https://docs.nansen.ai/about/endpoints-overview)

Was this helpful?

---

# Rate Limits | Nansen API

Due to an ongoing incident, we've brought down the rate limits to 300 requests/min.

The Nansen API employs rate limits and usage quotas to ensure fair usage and maintain performance for all users.

**Rate Limits:**

The current rate limits are 20 **requests per second** and **500 requests per minute**.

**Exceeding Rate Limits:**

If you exceed the defined rate limits, the API will return an error response. You should expect a **429 Too Many Requests** HTTP status code.

[PreviousEndpoints Overview](https://docs.nansen.ai/about/endpoints-overview)
[NextCredits & Pricing Guide](https://docs.nansen.ai/about/credits-and-pricing-guide)

Last updated 12 days ago

Was this helpful?

---

# Credits & Pricing Guide | Nansen API

Welcome to our updated API pricing and credit system. We’ve made it easier to get started, scale up, and pay only for what you need.

[](https://docs.nansen.ai/about/credits-and-pricing-guide#available-api-plans)

Available API Plans


-------------------------------------------------------------------------------------------------------

We offer two main API plans to fit your needs:

Plan

Credits Included

Top Ups

Intended Use

Pro

1,000 Starter Credits (one time grant)

Buy credits as you need

Professional, production, and high volume integrations

Free

100 Trial Credits (one time grant)

No Topups

Brief experimentation and testing

For more information on plan features, visit [our pricing page](https://app.nansen.ai/account/switch-plans)
.

### 

[](https://docs.nansen.ai/about/credits-and-pricing-guide#pro-plan-details)

Pro Plan Details

*   Subscription: $49/month (annual) or $69/month (monthly)
    
*   Starter Credits: Get 1,000 credits to start building before making your first purchase
    
*   Flexi-Credits: Purchase as many credits as you want. (Here's a [purchase guide](https://docs.nansen.ai/about/credits-and-pricing-guide#endpoint-credit-cost)
    )
    
*   Expiry: Credits expire 1 year from purchase
    

### 

[](https://docs.nansen.ai/about/credits-and-pricing-guide#free-plan-details)

Free Plan Details

*   100 one-time credits to try the API
    
*   No ability to purchase credits
    
*   Limited endpoint and feature access (no Smart Money API, limited TGM and Profiler, no premium labels)
    

List of Available Endpoints in Free Tier[](https://docs.nansen.ai/about/credits-and-pricing-guide#list-of-available-endpoints-in-free-tier)

Free plan users have access to the following endpoints:

*   `/v1/profiler/address/transactions`
    
*   `/v1/profiler/address/current-balance`
    
*   `/v1/profiler/address/historical-balances`
    
*   `/v1/profiler/address/counterparties`
    
*   `/v1/profiler/address/related-wallets`
    
*   `/v1/tgm/flows`
    
*   `/v1/tgm/who-bought-sold`
    
*   `/v1/tgm/dex-trades`
    
*   `/v1/tgm/transfers`
    
*   `/v1/tgm/holders`
    
*   `/v1/portfolio/defi-holdings`
    
*   `/v1/transaction-with-token-transfer-lookup`
    
*   `/v1/token-screener`
    

[](https://docs.nansen.ai/about/credits-and-pricing-guide#what-your-budget-gets-you)

What Your Budget Gets You?


--------------------------------------------------------------------------------------------------------------------

You can also use [this Credit Purchase Calculator](https://docs.google.com/spreadsheets/d/15P3HFSZUq_XnSKRalqe26-N9MT59wIdH0N8STxZuRos/edit?usp=sharing)
 to easily plan your API budget.

Quickly compare what each credit package unlocks across our main API features.

Budget

Credits

What it gets you

$100

100K

100K balance/pnl/txn checks or 20K Smart Money calls or 200 label lookups

$500

500K

500K balance/pnl/txn checks or 100K Smart Money calls or 1000 label lookups

$1000

1M

1M balance/pnl/txn checks or 200K Smart Money calls or 2000 label lookups

[](https://docs.nansen.ai/about/credits-and-pricing-guide#endpoint-credit-cost)

Endpoint Credit Cost


---------------------------------------------------------------------------------------------------------

Credit costs are structured to reflect the value of the data you’re accessing. Foundational data is inexpensive to encourage frequent use, while our proprietary, alpha-generating data costs more.

profiler/address/current-balances

1

profiler/address/historical-balances

1

profiler/perp-positions

1

profiler/address/transactions

1

profiler/perp-trades

1

profiler/address/related-wallets

1

profiler/pnl-summary

1

profiler/pnl

1

tgm/token-screener

1

tgm/perp-screener

1

tgm/transfers

1

tgm/dcas

1

tgm/flow-intel

1

tgm/who-bought-sold

1

tgm/dex-trades

1

portfolio/defi-holdings

1

tgm/flows

1

All Smart Money endpoints (/inflows, /holdings, /dex-trades, etc.)

5

profiler/perp-leaderboard

5

tgm/perp-pnl-leaderboard

5

profiler/address/counterparties

5

tgm/holders

5

tgm/pnl-leaderboard

5

All Label endpoints

500

[](https://docs.nansen.ai/about/credits-and-pricing-guide#faqs)

FAQs


-------------------------------------------------------------------------

**What happens if I run out of credits?**

You can purchase additional credit blocks at any time to ensure your service is not interrupted.

**Which is the preferred payment method for credit purchase?**

Credit card payments via Stripe are our preferred method for purchasing credits. We’ll use the same card you used for your subscription to process credit purchases.

**Are there higher tiers or enterprise plans?**

No, the Pro plan is designed to meet most needs. However, if you are making a bulk credit purchase over $10,000, please reach out to our sales team to discuss a custom solution.

**How do I track my credit usage?**

You can track your credit usage by visiting this link: [https://app.nansen.ai/api?tab=usage-analytics](https://app.nansen.ai/api?tab=usage-analytics)

[PreviousRate Limits](https://docs.nansen.ai/about/rate-limits)
[NextMake Your First API Call](https://docs.nansen.ai/getting-started/make-your-first-api-call)

Last updated 26 days ago

Was this helpful?

---

# Use case Templates | Nansen API

This section provides comprehensive use case templates for the Nansen API V1, organized by both difficulty level and specific use case. Templates are grouped into "Simple" and "Complex" categories to help developers quickly find relevant examples based on their experience and needs. Each template is designed to guide you through integrating with the API and building meaningful applications.

[Simple Use cases](https://docs.nansen.ai/getting-started/use-case-templates/simple-use-cases)
[Complex Use cases](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases)

[PreviousMake Your First API Call](https://docs.nansen.ai/getting-started/make-your-first-api-call)
[NextSimple Use cases](https://docs.nansen.ai/getting-started/use-case-templates/simple-use-cases)

Last updated 2 months ago

Was this helpful?

---

# Endpoints Overview | Nansen API

Deprecation Notice: The ‎`/beta` API endpoints will be deprecated on 01 October 2025. Please migrate your integrations to the ‎`/v1` endpoints before this date to ensure uninterrupted service.

Below is the list of APIs currently available as part of the Nansen API. V1 delivers a stable, scalable foundation for developers, with advanced filtering, standardized endpoints, and comprehensive documentation. This ensures efficient integration, reliable performance, and easier maintenance as you build onchain analytics solutions.

### 

[](https://docs.nansen.ai/about/endpoints-overview#smart-money)

Smart Money

A curated list of the top 5 000 highest-performing wallets ranked by realised profit, winrate, and strong performance across market cycles.

Endpoint

Credit

Description

[smart-money/netflows](https://docs.nansen.ai/api/smart-money/netflows)

5

Provides net flow of tokens bought/sold by Smart Money addresses

[smart-money/holdings](https://docs.nansen.ai/api/smart-money/holdings)

5

Holdings of tokens by Smart Money addresses.

[smart-money/historical-holdings](https://docs.nansen.ai/api/smart-money/historical-holdings)

5

All Historical Holdings of Smart Money Wallets

[smart-money/dex-trades](https://docs.nansen.ai/api/smart-money/dex-trades)

5

All dex trades of smart money traders in the last 24h

[smart-money/dcas](https://docs.nansen.ai/api/smart-money/jupiter-dcas)

5

All Jupiter DCAs started by Smart Money Wallets on Solana

[smart-money/perp-trades](https://docs.nansen.ai/api/smart-money/perp-trades)

5

Track what smart money wallets are trading on Hyperliquid

### 

[](https://docs.nansen.ai/about/endpoints-overview#profiler)

Profiler

A toolkit for diving deep into address relationships and behaviour, letting you analyse any wallet or entity cluster to uncover flows, counterparties, and behavioural patterns.

Endpoint

Credit

Description

[address/current-balance](https://docs.nansen.ai/api/profiler/address-current-balances)

1

Current Token balances of an address

[profiler/address/historical-balances](https://docs.nansen.ai/api/profiler/address-historical-balances)

1

Historical holdings of a wallet address

[profiler/perp-positions](https://docs.nansen.ai/api/profiler/address-perp-positions)

1

Fetch current positions, PnL and account health of a wallet

[profiler/address/transactions](https://docs.nansen.ai/api/profiler/address-transactions)

1

List of transactions made by an address

[profiler/perp-trades](https://docs.nansen.ai/api/profiler/address-perp-trades)

1

Get all Hyperliquid trades of a wallet

[profiler/address/related-wallets](https://docs.nansen.ai/api/profiler/address-related-wallets)

1

List of related wallets and its first degree relation

[profiler/address/pnl-summary](https://docs.nansen.ai/api/profiler/address-pnl-and-trade-performance)

1

Trade summary including top 5 trades

[profiler/address/pnl](https://docs.nansen.ai/api/profiler/address-pnl-and-trade-performance)

1

List of Past Trades and their performance made by the address

[profiler/address/counterparties](https://docs.nansen.ai/api/profiler/address-counterparties)

5

Top Counterparties a wallet has interacted with

[perp-leaderboard](https://docs.nansen.ai/api/profiler/hyperliquid-address-leaderboard)

5

Get a list of most profitable Hyperliquid addresses

[/profiler/address/labels](https://docs.nansen.ai/api/profiler/address-labels)

500

Address and list of all its labels

### 

[](https://docs.nansen.ai/about/endpoints-overview#token-god-mode)

Token God Mode

A comprehensive lens on a token’s on-chain activity, combining Smart Money movements, holder-base analysis, and exchange-flow tracking in one view.

Endpoint

Credits

Description

[tgm/token-screener](https://docs.nansen.ai/api/token-god-mode/token-screener)

1

A token screening endpoint that provides real-time analytics and insights across multiple blockchain networks.

[tgm/perp-screener](https://docs.nansen.ai/api/token-god-mode/perp-screener)

1

Discover and screen tokens on Hyperliquid with the highest volume and smart money activity.

[tgm/flow-intelligence](https://docs.nansen.ai/api/token-god-mode/flow-intelligence)

1

Summary of token flows across Smart Money, exchanges, Top PnL Traders, Public Figures, Whales, Fresh Wallets

[tgm/holders](https://docs.nansen.ai/api/token-god-mode/holders)

5

Balance of top addresses, smart money, exchanges, public figures and whales that can be queried by address or by entity

[tgm/perp-positions](https://docs.nansen.ai/api/token-god-mode/perp-positions)

5

See all open positions for a specific perp token including leverage, PnL, and liquidation prices

[tgm/flows](https://docs.nansen.ai/api/token-god-mode/flows)

1

Total Inflow and outflow of a token from smart money, exchanges, public figures or whales.

[tgm/who-bought-sold](https://docs.nansen.ai/api/token-god-mode/who-bought-sold)

1

Recent buyers and sellers of a token summarised

[tgm/perp-trades](https://docs.nansen.ai/api/token-god-mode/perp-trades)

1

View trading history for a specific perp token over a time period

[tgm/dex-trades](https://docs.nansen.ai/api/token-god-mode/dex-trades)

1

All DEX Trades of a Token

[tgm/transfers](https://docs.nansen.ai/api/token-god-mode/token-transfers)

1

Top Token Transfers of a token

[tgm/jup-dca](https://docs.nansen.ai/api/token-god-mode/jupiter-dcas)

1

List of all Jupiter DCA orders of a token on Solana

[tgm/pnl-leaderboard](https://docs.nansen.ai/api/token-god-mode/pnl-leaderboard)

5

List of addresses and their total realised and unrealised PnL

[tgm/perp-pnl-leaderboard](https://docs.nansen.ai/api/token-god-mode/perp-pnl-leaderboard)

5

List of addresses and their PnL for a specific token on Hyperliquid

### 

[](https://docs.nansen.ai/about/endpoints-overview#portfolio-api)

Portfolio API

Endpoint

Credits

Description

[portfolio/defi-holdings](https://docs.nansen.ai/api/portfolio)

1

Track DeFi positions of all addresses

[PreviousIntroduction](https://docs.nansen.ai/)
[NextRate Limits](https://docs.nansen.ai/about/rate-limits)

Last updated 17 days ago

Was this helpful?

---

# Complex Use cases | Nansen API

Explore advanced workflows you can create with the Nansen API. This section showcases complex use cases designed to help you unlock deeper insights and automate sophisticated tasks, empowering your team to get the most from Nansen’s API.

[Use case 1: Automated Token Tracking & Smart Money Analysis](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-1-automated-token-tracking-and-smart-money-analysis)
[Use Case 2: Find & Copytrade Wallets on Hyperliquid](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-2-find-and-copytrade-wallets-on-hyperliquid)
[Use case 3: Identifying Related Wallets at Scale](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale)
[Use case 4: Copytrading Top Performing Wallets](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets)
[Use case 5: Monitoring CEX Health](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-5-monitoring-cex-health)

[PreviousSimple Use cases](https://docs.nansen.ai/getting-started/use-case-templates/simple-use-cases)
[NextUse case 1: Automated Token Tracking & Smart Money Analysis](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-1-automated-token-tracking-and-smart-money-analysis)

Last updated 23 days ago

Was this helpful?

---

# Make Your First API Call | Nansen API

### 

[](https://docs.nansen.ai/getting-started/make-your-first-api-call#step-1-get-your-api-key)

**Step 1: Get your API key**

*   Log in at Nansen [(Click here)](https://app.nansen.ai/api)
    
*   Navigate to the API tab in the left sidebar.
    
*   Click **Create API Key** (See screenshot below for where to find this button)
    
*   Copy your API Key
    

![](https://docs.nansen.ai/~gitbook/image?url=https%3A%2F%2F3666025612-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FHE8GKwbmDRKKCMC7hnip%252Fuploads%252Fa7DeQxuL5FjtUGP7qiCw%252FScreenshot%25202025-09-30%2520at%252011.25.48%25E2%2580%25AFAM.png%3Falt%3Dmedia%26token%3D18696406-d9d4-4893-94b2-06f0d115f831&width=768&dpr=4&quality=100&sign=5ba2823f&sv=2)

### 

[](https://docs.nansen.ai/getting-started/make-your-first-api-call#step-2-run-this-curl-command)

**Step 2: Run this cURL Command**

Copy

    curl -L \
      --request POST \
      --url 'https://api.nansen.ai/api/v1/token-screener' \
      --header 'apiKey: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "chains": [\
          "ethereum",\
          "solana",\
          "base"\
        ],
        "date": {
          "from": "2025-01-01T00:00:00Z",
          "to": "2025-01-31T23:59:59Z"
        },
        "pagination": {
          "page": 1,
          "per_page": 10
        },
        "filters": {
          "only_smart_money": true,
          "token_age_days": {
            "max": 365,
            "min": 1
          }
        },
        "order_by": [\
          {\
            "field": "chain",\
            "direction": "ASC"\
          }\
        ]
      }'

### 

[](https://docs.nansen.ai/getting-started/make-your-first-api-call#step-3-now-try-this-in-api-explorer)

Step 3: Now try this in API Explorer

*   Click on Test It button on the API codeblock below
    
*   Paste your API Key under the value section (As shown in the screenshot)
    
    ![](https://docs.nansen.ai/~gitbook/image?url=https%3A%2F%2F3666025612-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FHE8GKwbmDRKKCMC7hnip%252Fuploads%252FCYSQCQuGlzG3Ly3NuZYO%252FScreenshot%25202025-10-15%2520at%252014.48.48.png%3Falt%3Dmedia%26token%3Deeb92ec3-0bc6-4396-9a2f-794aa5415507&width=768&dpr=4&quality=100&sign=e927a992&sv=2)
    
*   Click on "Send" or press CMD + Enter.
    

### 

[](https://docs.nansen.ai/getting-started/make-your-first-api-call#post-api-v1-token-screener)

Get Token Screening Data

post

https://api.nansen.ai/api/v1/token-screener

Discover and screen tokens across multiple blockchains with advanced filtering capabilities. This endpoint helps identify trending tokens, new launches, and smart money movements by combining metrics like volume, liquidity, market cap, and trading activity.

**What it helps to answer:**

1.  **Which tokens are experiencing significant smart money activity across different chains?**
    
2.  **How do market metrics (price, volume, liquidity) correlate with holder behavior and smart money movements?**
    
3.  **What tokens show strong fundamentals in terms of holder distribution and trading patterns?**
    
4.  **Which emerging tokens are attracting fresh wallet inflows while maintaining healthy smart money participation?**
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for Token Screener endpoint.

chainsstring · enum\[\] · min: 1 · max: 5Required

List of blockchain chains to filter by

Example: `["ethereum","solana","base"]`

Show properties

dateobject · DateRangeRequired

Date range for the token screener

Example: `{"from":"2025-01-01T00:00:00Z","to":"2025-01-31T23:59:59Z"}`

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply

Example: `{"only_smart_money":true,"token_age_days":{"max":365,"min":1}}`

object · TokenScreenerFiltersOptional

Filters for token screener endpoints.

These filters control which tokens are included in the screening results based on various criteria.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "buy\_volume", "direction": "DESC"}\] - Sort by buy volume descending
*   \[{"field": "price\_change", "direction": "DESC"}\] - Sort by price change descending

object · SortOrder\[TokenScreenerSortField\]\[\]Optional

Show properties

Responses

200

Token screening data

application/json

Responseobject · TokenScreenerResponse

Response model for token screener endpoint.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/token-screener

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/token-screener HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 266
    
    {
      "chains": [\
        "ethereum",\
        "solana",\
        "base"\
      ],
      "date": {
        "from": "2025-01-01T00:00:00Z",
        "to": "2025-01-31T23:59:59Z"
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "only_smart_money": true,
        "token_age_days": {
          "max": 365,
          "min": 1
        }
      },
      "order_by": [\
        {\
          "field": "chain",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

Token screening data

Copy

    {
      "data": [\
        {\
          "chain": "text",\
          "token_address": "text",\
          "token_symbol": "text",\
          "token_age_days": 1,\
          "market_cap_usd": 1,\
          "liquidity": 1,\
          "price_usd": 1,\
          "price_change": 1,\
          "fdv": 1,\
          "fdv_mc_ratio": 1,\
          "buy_volume": 1,\
          "inflow_fdv_ratio": 1,\
          "outflow_fdv_ratio": 1,\
          "sell_volume": 1,\
          "volume": 1,\
          "netflow": 1\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

### 

[](https://docs.nansen.ai/getting-started/make-your-first-api-call#next-steps)

Next Steps

1.  **Checkout these Usecase Templates**
    

[📜Use case Templates](https://docs.nansen.ai/getting-started/use-case-templates)

1.  **Checkout all the available endpoints**
    

[Smart Money](https://docs.nansen.ai/api/smart-money)
[Token God Mode](https://docs.nansen.ai/api/token-god-mode)
[Profiler](https://docs.nansen.ai/api/profiler)
[Portfolio](https://docs.nansen.ai/api/portfolio)

[PreviousCredits & Pricing Guide](https://docs.nansen.ai/about/credits-and-pricing-guide)
[NextUse case Templates](https://docs.nansen.ai/getting-started/use-case-templates)

Last updated 1 month ago

Was this helpful?

---

# Simple Use cases | Nansen API

Use the sample requests and responses to accelerate development and gain actionable insights from blockchain data.

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/simple-use-cases#id-1.-viewing-defi-positions)

1\. Viewing DeFi Positions

**Description**: Get comprehensive information about a wallet's DeFi positions including balances, values, and token details.

**Use Case**: Analyze DeFi portfolio performance, track position changes, and understand asset allocation.

**Endpoint Documentation:** [Click Here](https://docs.nansen.ai/beta-nansen-api/api/portfolio#post-api-beta-portfolio-defi-holdings)

**cURL Command (Replace your API Key and run this in your terminal)**:

Copy

    curl -L \
      --request POST \
      --url 'https://api.nansen.ai/api/v1/portfolio/defi-holdings' \
      --header 'apiKey: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "wallet_address": "0x4062b997279de7213731dbe00485722a26718892"
      }'

**Key Benefits**:

*   Complete portfolio overview across multiple chains
    
*   Real-time balance and value calculations
    

**Common Use Cases**:

*   Portfolio tracking applications
    
*   DeFi protocol analytics
    
*   Risk management systems
    

* * *

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/simple-use-cases#id-2.-viewing-smart-money-holdings)

2\. Viewing Smart Money Holdings

**Description**: Discover which tokens top traders and funds are holding.

**Use Case**: Follow smart money movements, identify trending tokens, and make informed investment decisions.

**Endpoint Documentation:** [Click Here](https://docs.nansen.ai/api/smart-money/holdings#post-api-v1-smart-money-holdings)

**cURL Command (Replace your API Key and run this in your terminal)**:

Copy

    curl -L \
      --request POST \
      --url 'https://api.nansen.ai/api/v1/smart-money/holdings' \
      --header 'apiKey: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
      "chains": [\
        "ethereum",\
        "solana",\
        "base"\
      ],
      "pagination": {
        "page": 1,
        "per_page": 50
      },
      "order_by": [\
        {\
          "field": "value_usd",\
          "direction": "DESC"\
        }\
      ]
    }'

**Key Benefits**:

*   Identify institutional investment trends
    
*   Track smart money portfolio changes
    
*   Filter by smart money categories
    

**Common Use Cases**:

*   Investment research and analysis
    
*   Token discovery and trending analysis
    
*   Market sentiment analysis
    

* * *

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/simple-use-cases#id-3.-finding-top-holders-of-a-token)

3\. Finding Top Holders of a Token

**Description**: Discover the largest holders of a specific token, including their balances and wallet types.

**Use Case**: Analyze token distribution, identify major stakeholders, and understand market concentration.

**Endpoint Documentation**: [Click Here](https://docs.nansen.ai/api/token-god-mode/holders)

**cURL Command (Replace your API Key and run this in your terminal)**:

Copy

    curl -L \
      --request POST \
      --url 'https://api.nansen.ai/api/v1/tgm/holders' \
      --header 'apiKey: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "chain": "solana",
        "token_address": "2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv",
        "aggregate_by_entity": false,
        "label_type": "all_holders",
        "pagination": {
          "page": 1,
          "per_page": 10
        },
        "order_by": [\
          {\
            "field": "value_usd",\
            "direction": "DESC"\
          }\
        ]
      }'

**Key Benefits**:

*   Identify major token holders and their types
    
*   Includes individual addresses and aggregated by entity views
    
*   Track balance changes over time
    
*   Understand token distribution patterns
    

**Common Use Cases**:

*   Token governance analysis
    
*   Market concentration studies
    
*   Risk assessment for token holders
    

* * *

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/simple-use-cases#id-4.-using-token-screener-to-find-new-tokens)

4\. Using Token Screener to Find New Tokens

**Description**: Discover new and trending tokens based on various metrics like market cap, token age, volume, and smart money activity.

**Use Case**: Find emerging opportunities, track new token launches, and identify trending assets.

**Endpoint Documentation**: [Click Here](https://docs.nansen.ai/api/token-god-mode/token-screener)

**cURL Command**:

Copy

    curl -L \
      --request POST \
      --url 'https://api.nansen.ai/api/v1/token-screener' \
      --header 'apiKey: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "chains": [\
          "ethereum",\
          "solana",\
          "base"\
        ],
        "date": {
          "from": "2025-08-27T00:00:00Z",
          "to": "2025-09-03T23:59:59Z"
        },
        "pagination": {
          "page": 1,
          "per_page": 10
        },
        "filters": {
          "token_age_days": {
            "max": 7
          }
        },
        "order_by": [\
          {\
            "field": "market_cap_usd",\
            "direction": "DESC"\
          }\
        ]
      }'
    

**Key Benefits**:

*   Discover new token opportunities
    
*   Filter by market cap, volume, sectors and age
    
*   Track trending metrics and holder growth
    

**Common Use Cases**:

*   Token discovery using different metrics
    

* * *

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/simple-use-cases#next-steps)

Next Steps

Once you're comfortable with these easy-level use cases, explore:

*   **Medium Level**: Advanced filtering, historical data analysis, and multi-chain operations
    
*   **Hard Level**: Complex analytics, data aggregation, and real-time monitoring systems
    

For more information, refer to the complete API documentation and examples in the repository.

[PreviousUse case Templates](https://docs.nansen.ai/getting-started/use-case-templates)
[NextComplex Use cases](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases)

Last updated 2 months ago

Was this helpful?

---

# Use case 1: Automated Token Tracking & Smart Money Analysis | Nansen API

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-1-automated-token-tracking-and-smart-money-analysis#scenario)

Scenario

A DeFi trading team automated their token discovery and smart money analysis using Nansen's API. They built custom tools that combine multiple data sources to identify promising trading opportunities in real-time.

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-1-automated-token-tracking-and-smart-money-analysis#problem)

Problem

*   Manual Process: Hours spent cross-referencing multiple dashboards
    
*   Fragmented Data: Token analysis scattered across different platforms
    
*   Slow Decisions: Opportunities missed due to manual analysis delays
    
*   Poor Scalability: Process couldn't handle growing portfolio needs
    

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-1-automated-token-tracking-and-smart-money-analysis#solution)

Solution

The team built an automated system using three core Nansen API endpoints:

1.  **Token Screener** **(**[**Link Here**](https://docs.nansen.ai/api/token-god-mode/token-screener)
    **)** - Find trending tokens
    
2.  **Smart Money Netflow** **(**[**Link Here**](https://docs.nansen.ai/api/smart-money/netflows)
    **)** - Track institutional buying
    
3.  **TGM PnL Leaderboard** **(**[**Link Here**](https://docs.nansen.ai/api/token-god-mode/pnl-leaderboard)
    **)** - Score trader credibility
    

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-1-automated-token-tracking-and-smart-money-analysis#step-by-step-guide)

Step-by-Step Guide

**Step 1: Configure Your Token Screener Filters**

Start by selecting the chains you want to analyze (e.g., Ethereum, Solana). Apply filters to narrow down your search:

*   Set market cap range (`min` and `max`) to target tokens with desired liquidity.
    
*   Specify minimum liquidity and number of traders to focus on active, tradable tokens.
    
*   Limit token age to capture new and trending assets.
    
*   Enable “only\_smart\_money” to prioritize tokens held by sophisticated traders.
    
*   Order results by volume (descending) for immediate visibility on high-activity tokens.
    

**Step 2: Analyze Smart Money Netflow**

Use the Smart Money Netflow endpoint to track institutional and expert activity:

*   Select your chains.
    
*   Include smart money labels such as “Fund”, “Smart Trader”, and “30D Smart Trader” for targeted analysis.
    
*   Set a minimum market cap and trader count to filter out low-activity tokens.
    
*   Order by net flow over the past 7 days to surface tokens with significant smart money movement.
    

**Step 3: Validate Trader Credibility with TGM PnL Leaderboard**

For any token of interest, use the TGM PnL Leaderboard:

*   Specify the chain and token address.
    
*   Set your date range for analysis.
    
*   Filter for holders with significant USD value and realized profit.
    
*   Use pagination to manage large datasets.
    
*   This step helps you confirm which traders are consistently profitable, adding confidence to your token selection.
    

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-1-automated-token-tracking-and-smart-money-analysis#code-blocks)

Code Blocks

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-1-automated-token-tracking-and-smart-money-analysis#token-screener-api-call)

Token Screener API Call

Copy

    curl -X POST "https://api.nansen.ai/api/v1/token-screener" \
      -H "apiKey: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "chains": ["ethereum", "solana"],
        "date": {
          "from": "2025-01-20T00:00:00Z",
          "to": "2025-01-21T23:59:59Z"
        },
        "pagination": {
          "page": 1,
          "per_page": 50
        },
        "filters": {
          "market_cap_usd": {
            "min": 1000000,
            "max": 100000000
          },
          "liquidity": {
            "min": 500000
          },
          "nof_traders": {
            "min": 100
          },
          "only_smart_money": true,
          "token_age_days": {
            "min": 1,
            "max": 30
          }
        },
        "order_by": [\
          {\
            "field": "volume",\
            "direction": "DESC"\
          }\
        ]
      }'

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-1-automated-token-tracking-and-smart-money-analysis#smart-money-netflow-api-call)

Smart Money Netflow API Call

Copy

    curl -L \
      --request POST \
      --url 'https://api.nansen.ai/api/v1/smart-money/netflow' \
      --header 'apiKey: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "chains": [\
          "ethereum",\
          "solana"\
        ],
        "filters": {
          "include_smart_money_labels": [\
            "Fund",\
            "Smart Trader",\
            "30D Smart Trader"\
          ],
          "market_cap_usd": {
            "min": 1000000
          },
          "trader_count": {
            "min": 5
          }
        },
        "pagination": {
          "page": 1,
          "per_page": 10
        },
        "order_by": [\
          {\
            "field": "net_flow_7d_usd",\
            "direction": "DESC"\
          }\
        ]
      }'
    

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-1-automated-token-tracking-and-smart-money-analysis#tgm-pnl-leaderboard-api-call)

TGM PnL Leaderboard API Call

Copy

    curl -L \
      --request POST \
      --url 'https://api.nansen.ai/api/v1/tgm/pnl-leaderboard' \
      --header 'apiKey: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "chain": "ethereum",
        "token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "date": {
          "from": "2024-10-23",
          "to": "2025-01-21"
        },
        "pagination": {
          "page": 1,
          "per_page": 100
        },
        "filters": {
          "holding_usd": {
            "min": 1000
          },
          "pnl_usd_realised": {
            "min": 1000
          }
        }
      }'
    

[PreviousComplex Use cases](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases)
[NextUse Case 2: Find & Copytrade Wallets on Hyperliquid](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-2-find-and-copytrade-wallets-on-hyperliquid)

Last updated 2 months ago

Was this helpful?

---

# API Structure & Base URL | Nansen API

All interactions with the Nansen API V1 occur via HTTPS requests to specific endpoints. The general structure of an API call is:

Copy

    HTTP Method + Base URL + Endpoint Path

*   HTTP Method: Primarily ‎\`POST\` for retrieving data.
    
*   Base URL: The root URL for all V1 API requests is:
    

Copy

    https://api.nansen.ai/api/v1

*   Endpoint Path: The specific path identifying the resource and desired data, appended directly to the Base URL (e.g., ‎\`/smart-money/netflows\`). Endpoint paths for V1 resources are detailed within their respective sections of this documentation.
    
*   Request Body: Parameters are typically passed in JSON format within the request body for POST requests.
    

[PreviousUse case 5: Monitoring CEX Health](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-5-monitoring-cex-health)
[NextAuthentication](https://docs.nansen.ai/getting-started/authentication)

Last updated 2 months ago

Was this helpful?

---

# Use case 3:  Identifying Related Wallets at Scale | Nansen API

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale#scenario)

Scenario

An address clustering workflow that uses the Nansen API to systematically identify related wallet addresses and analyze their relationships. This enables researchers to uncover wallet connections through funding patterns, shared interactions, and behavioral analysis across multiple blockchains.

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale#core-components)

Core Components

*   **Labels:** Find labels of the initial address
    
*   **Related Wallets**: Detection of special connections (funding, signing, contract deployment)
    
*   **Counterparties Analysis**: Identification of high-interaction addresses and shared patterns
    

This integration enables systematic discovery of wallet clusters through multiple relationship types and confidence levels.

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale#workflow-implementation)

Workflow Implementation

**Step 1: Tarket Address Label Lookup**

*   Query labels of the target address
    

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale#step-2-initial-relationship-discovery)

Step 2: Initial Relationship Discovery

*   Query Related Wallets endpoint with target address
    
*   Identify direct relationships: `relation: "First Funder"`, `"Signer"`, `"Deployed via"`
    
*   Build initial cluster with high-confidence connections
    

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale#step-3-counterparty-analysis)

Step 3: Counterparty Analysis

*   Analyze counterparties with `group_by: "entity"` for entity-level grouping
    
*   Filter for `volume_in_usd > 50000` to find significant addresses
    
*   Identify shared CEX deposit addresses across potential cluster members
    

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale#step-4-pattern-recognition)

Step 4: Pattern Recognition

*   Compare transaction timing using `block_timestamp` fields
    
*   Look for addresses with similar `method: "0x"` patterns
    
*   Check for coordinated movements with matching `transaction_type` values
    

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale#step-5-multi-level-clustering)

Step 5: Multi-Level Clustering

*   For each high-confidence related address, repeat steps 1-3
    
*   Cross-reference addresses that deposit to same CEX addresses
    
*   Build network graph of relationships with confidence scores
    

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale#step-6-confidence-assessment)

Step 6: Confidence Assessment

*   **High confidence** (>90%): First funder, shared signers, same CEX deposits
    
*   **Medium confidence** (60-90%): High interaction volume, coordinated timing
    
*   **Low confidence** (<60%): Indirect relationships, behavioral similarities
    

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale#step-7-validation-and-refinement)

Step 7: Validation and Refinement

*   Check balance patterns for coordinated movements
    
*   Filter out false positives from common protocol interactions
    

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale#code-examples)

Code Examples

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale#id-1.-find-target-address-labels)

1\. Find Target Address Labels

Identify all the labels associated with the target address

Copy

    curl -L \
      --request POST \
      --url 'https://api.nansen.ai/api/beta/profiler/address/labels' \
      --header 'apiKey: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "parameters": {
          "chain": "ethereum",
          "address": "0xbdfa4f4492dd7b7cf211209c4791af8d52bf5c50"
        },
        "pagination": {
          "page": 1,
          "recordsPerPage": 100
        }
      }'

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale#id-2.-find-related-wallets-direct-relationships)

2\. Find Related Wallets (Direct Relationships)

Identify wallets with special connections to a target address:

Copy

    curl -X POST "https://api.nansen.ai/api/v1/profiler/address/related-wallets" \
      -H "apiKey: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "address": "0x28c6c06298d514db089934071355e5743bf21d60",
        "chain": "ethereum",
        "pagination": {
          "page": 1,
          "per_page": 20
        }
      }'

This reveals first funder relationships, signer connections, multisig relationships, and contract deployment patterns.

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale#id-3.-analyze-address-counterparties)

3\. Analyze Address Counterparties

Find addresses with the highest interaction volume:

Copy

    curl -X POST "https://api.nansen.ai/api/v1/profiler/address/counterparties" \
      -H "apiKey: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "address": "0x28c6c06298d514db089934071355e5743bf21d60",
        "chain": "ethereum",
        "date": {
          "from": "2024-07-01",
          "to": "2025-01-21"
        },
        "group_by": "wallet",
        "source_input": "Combined",
        "filters": {
          "total_volume_usd": {
            "min": 10000
          }
        },
        "order_by": [\
          {\
            "field": "total_volume_usd",\
            "direction": "DESC"\
          }\
        ]
      }'

This identifies CEX deposit addresses and high-frequency interaction patterns crucial for clustering.

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale#id-4.-track-historical-balance-patterns)

4\. Track Historical Balance Patterns

Analyze coordinated balance movements across potential cluster members:

Copy

    curl -X POST "https://api.nansen.ai/api/v1/profiler/address/historical-balances" \
      -H "apiKey: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "address": "0x28c6c06298d514db089934071355e5743bf21d60",
        "chain": "ethereum",
        "date": {
          "from": "2024-10-01",
          "to": "2025-01-21"
        },
        "filters": {
          "token_symbol": "USDC",
          "value_usd": {
            "min": 1000
          }
        }
      }'

Coordinated balance changes across addresses indicate potential cluster membership.

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale#id-5.-examine-transaction-patterns)

5\. Examine Transaction Patterns

Review transaction history for behavioral similarities:

Copy

    curl -X POST "https://api.nansen.ai/api/v1/profiler/address/transactions" \
      -H "apiKey: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "address": "0x28c6c06298d514db089934071355e5743bf21d60",
        "chain": "ethereum",
        "date": {
          "from": "2025-01-01",
          "to": "2025-01-21"
        },
        "filters": {
          "volume_usd": {
            "min": 5000
          },
          "source_type": "transfer"
        }
      }'

Similar transaction timing and patterns across addresses suggest coordinated activity.

[PreviousUse Case 2: Find & Copytrade Wallets on Hyperliquid](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-2-find-and-copytrade-wallets-on-hyperliquid)
[NextUse case 4: Copytrading Top Performing Wallets](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets)

Last updated 2 months ago

Was this helpful?

---

# Authentication | Nansen API

The Nansen API uses API key-based authentication. All requests must include an API key provided in the request header for successful authentication.

### 

[](https://docs.nansen.ai/getting-started/authentication#obtaining-api-keys)

Obtaining API Keys

You can access the API Keys from [this link](https://app.nansen.ai/api)
 in Nansen App

![](https://docs.nansen.ai/~gitbook/image?url=https%3A%2F%2F3666025612-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FHE8GKwbmDRKKCMC7hnip%252Fuploads%252FkpBOZWD2bwbdTytY7QMt%252FScreenshot%25202025-10-30%2520at%252010.36.16%25E2%2580%25AFAM.png%3Falt%3Dmedia%26token%3Da0a813c1-5417-4731-9b91-92eda05ca2c8&width=768&dpr=4&quality=100&sign=f82f83f8&sv=2)

### 

[](https://docs.nansen.ai/getting-started/authentication#including-your-api-key-in-requests)

Including Your API Key in Requests

Add the following header to all API requests:

Header Name

Header Value

`apiKey`

`YOUR_API_KEY`

Replace `YOUR_API_KEY` with your actual API key.

[PreviousAPI Structure & Base URL](https://docs.nansen.ai/getting-started/api-structure-and-base-url)
[NextUnderstanding Responses and Handling Errors](https://docs.nansen.ai/getting-started/understanding-responses-and-handling-errors)

Last updated 24 days ago

Was this helpful?

---

# Understanding Responses and Handling Errors | Nansen API

API responses are delivered in JSON format. The client applications must parse this JSON to extract the required data. Equally important is handling the HTTP status code returned with each response to determine success or failure.

**Common HTTP Status Codes:**

400

Bad Request: Malformed request, invalid parameters or format

Check your request syntax and parameters

401

Unauthorized: Authentication failed (missing, invalid, or expired token)

Obtain or refresh your API Key

403

Forbidden: Auth succeeded, but no permission for resource

Ensure your account has access rights

404

Not Found: Resource or endpoint does not exist

Verify the endpoint path and resource identifiers

422

Unprocessable Content

Please verify your parameters

429

Too Many Requests: Rate limit exceeded

Slow down requests; respect rate limits

500

Internal Server Error: Unexpected server issue

Try again later; contact support if persistent

504

Gateway Timeout: Backend server did not respond in time

Retry after a short wait; check for heavy queries

[PreviousAuthentication](https://docs.nansen.ai/getting-started/authentication)
[NextChain Coverage](https://docs.nansen.ai/getting-started/chain-coverage)

Last updated 8 days ago

Was this helpful?

---

# Use Case 2: Find & Copytrade Wallets on Hyperliquid | Nansen API

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-2-find-and-copytrade-wallets-on-hyperliquid#id-1.-scenario)

1\. Scenario

Identify and replicate trades from successful perpetual traders on Hyperliquid by monitoring their positions and trade activity in real-time.

**Goal:** Build an automated copytrading system that:

1.  **Discovers** profitable traders using the Hyperliquid leaderboard
    
2.  **Monitors** their perpetual positions and recent trades
    
3.  **Replicates** their trading activity in your own account
    

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-2-find-and-copytrade-wallets-on-hyperliquid#id-2.-solution)

2\. Solution

Use three Nansen API endpoints:

1.  **Perp Leaderboard** [**(Link Here)**](https://docs.nansen.ai/api/hyperliquid-apis/hyperliquid-leaderboard)
     - Discover top performing traders by PnL and ROI
    
2.  **Perp Positions** [**(Link Here)**](https://docs.nansen.ai/api/hyperliquid-apis/address-perp-positions)
     - Monitor current open positions for selected wallets
    
3.  **Perp Trades** [**(Link Here)**](https://docs.nansen.ai/api/hyperliquid-apis/address-perp-trades)
     - Track all trades executed by profitable wallets
    

**Optional:** Filter the leaderboard to smart money wallets only for higher quality signals.

**Example workflow:**

1.  Discover top Smart Money traders from Step 1
    
2.  Every 30 minutes to an hour:
    
    1.  Fetch recent trades (last 1 hour) for all traders
        
    2.  Identify new "Open" or "Add" Actions
        
    3.  Execute matching trades on your account
        
    
3.  **Every couple of hours**
    
    1.  **Check current positions vs tracked wallets**
        
    2.  **Close any positions where traders have exited**
        
    3.  **Rebalance position sizes if needed**
        
    

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-2-find-and-copytrade-wallets-on-hyperliquid#id-3.-step-by-step-guide)

3\. Step-by-Step Guide

**Step 1: Find Profitable Traders on Hyperliquid**

Use the Perp Leaderboard endpoint to discover the most profitable perpetual traders over a specific timeframe.

**Call the perp leaderboard endpoint:**

Copy

    curl -X POST "https://api.nansen.ai/api/v1/perp-leaderboard" \
      -H "apiKey: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "date": {
          "from": "2025-10-01",
          "to": "2025-10-31"
        },
        "filters": {
          "total_pnl": { "min": 10000 },
          "roi": { "min": 20 },
          "account_value": { "min": 50000 },
          "include_smart_money_labels": ["Fund", "Smart Trader"]
        },
        "pagination": { "page": 1, "per_page": 20 },
        "order_by": [{ "field": "total_pnl", "direction": "DESC" }]
      }'

**Process the response:**

*   Extract `trader_address` from top performers
    
*   Note their `total_pnl`, `roi`, and `account_value` for ranking
    
*   Filter by `trader_address_label` to identify known smart money wallets
    
*   Store addresses for monitoring in the next steps
    

**Example response:**

Copy

    {
      "data": [\
        {\
          "trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",\
          "trader_address_label": "Smart Money Trader [0x28c6c0]",\
          "total_pnl": 45230.50,\
          "roi": 35.2,\
          "account_value": 150000.0\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 20,
        "total": 150
      }
    }

**Step 2: Monitor Current Positions**

For each profitable trader identified, check their current open positions to understand what they're actively trading.

**Call the perp positions endpoint:**

Copy

    curl -X POST "https://api.nansen.ai/api/v1/profiler/perp-positions" \
      -H "apiKey: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "address": "0x28c6c06298d514db089934071355e5743bf21d60",
        "order_by": [{ "field": "position_value_usd", "direction": "DESC" }]
      }'

**Process the response:**

*   Identify active positions by `token_symbol` (e.g., BTC, ETH, SOL)
    
*   Note position direction from `size` (positive = long, negative = short)
    
*   Review `unrealized_pnl_usd` to gauge current profitability
    
*   Check `leverage_value` to understand risk levels
    
*   Use `entry_price_usd` and `liquidation_price_usd` for position context
    

**Key fields to monitor:**

*   `token_symbol`: The perpetual contract being traded
    
*   `size`: Position size (negative for short, positive for long)
    
*   `position_value_usd`: Total position value
    
*   `unrealized_pnl_usd`: Current unrealized profit/loss
    
*   `leverage_value`: Leverage multiplier used
    
*   `entry_price_usd`: Average entry price
    
*   `mark_price_usd`: Current market price
    

**Step 3: Track Trading Activity**

Monitor recent trades to identify entry and exit signals you can replicate.

**Call the perp trades endpoint:**

Copy

    curl -X POST "https://api.nansen.ai/api/v1/profiler/perp-trades" \
      -H "apiKey: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "address": "0x28c6c06298d514db089934071355e5743bf21d60",
        "date": {
          "from": "2025-10-30T00:00:00Z",
          "to": "2025-10-31T23:59:59Z"
        },
        "filters": {
          "value_usd": { "min": 5000 }
        },
        "pagination": { "page": 1, "per_page": 100 },
        "order_by": [{ "field": "timestamp", "direction": "DESC" }]
      }'

**Process the response:**

*   Identify new positions from trades where `action` = "Open"
    
*   Detect position increases where `action` = "Add"
    
*   Track exits where `action` = "Close" or "Reduce"
    
*   Note the `side` (Long/Short) and `token_symbol` for each trade
    
*   Monitor `price`, `size`, and `value_usd` to replicate sizing
    
*   Check `closed_pnl` to understand profitability of closed trades
    

**Key fields for copytrading:**

*   `timestamp`: When the trade occurred
    
*   `token_symbol`: What contract was traded (e.g., BTC, ETH)
    
*   `side`: Position direction (Long or Short)
    
*   `action`: Trade action (Open, Add, Close, Reduce)
    
*   `price`: Execution price
    
*   `size`: Trade size in token units
    
*   `value_usd`: USD value of the trade
    
*   `start_position`: Position size before this trade
    
*   `closed_pnl`: Realized profit/loss (for closing trades)
    

[PreviousUse case 1: Automated Token Tracking & Smart Money Analysis](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-1-automated-token-tracking-and-smart-money-analysis)
[NextUse case 3: Identifying Related Wallets at Scale](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale)

Last updated 23 days ago

Was this helpful?

---

# Use case 4: Copytrading Top Performing Wallets | Nansen API

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets#scenario)

Scenario

A copy trading workflow that uses the Nansen API to deliver structured, real-time onchain token insights. This enables traders to understand token flows, track smart money activity, and evaluate token performance across multiple chains.

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets#core-components)

Core Components

*   **Flow Intelligence (**[**Link Here**](https://docs.nansen.ai/api/token-god-mode/flow-intelligence)
    **)**: Real-time tracking of wallet inflows and outflows for each token
    
*   **PnL Leaderboard (**[**Link Here**](https://docs.nansen.ai/api/token-god-mode/pnl-leaderboard)
    **)**: Identification of top-performing wallets by token
    
*   **PnL Summary (**[**Link Here**](https://docs.nansen.ai/api/profiler/address-pnl-and-trade-performance#post-api-v1-profiler-address-pnl-summary)
    **)**: Cross-chain wallet performance analysis
    
*   **TGM Holders (**[**Link Here**](https://docs.nansen.ai/api/token-god-mode/holders)
    **)**: Identify top holders of any token
    

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets#step-by-step-guide)

Step-by-Step Guide

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets#step-1-track-token-flow-intelligence)

Step 1: Track Token Flow Intelligence

*   Select your target blockchain (`chain: "ethereum"`) and token address (`token_address: "0x6982508145454ce325ddbe47a25d4ec3d2311933"`).
    
*   Call the Flow Intelligence endpoint with `timeframe: "7d"` to monitor weekly inflows and outflows.
    
*   Review net flows by wallet type - check `smart_trader_net_flow_usd`, `whale_net_flow_usd`, and `public_figure_net_flow_usd` fields to spot accumulation (positive values) or distribution (negative values) trends.
    

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets#step-2-find-top-performing-wallets-for-a-token)

Step 2: Find Top-Performing Wallets For a Token

*   Use the PnL Leaderboard endpoint with `chain: "ethereum"` and your token address.
    
*   Set date range with `date: { "from": "2024-10-01", "to": "2025-01-21" }` for 3-month analysis.
    
*   Apply filter `pnl_usd_realised: { "min": 1000 }` to find wallets with over $1,000 realized profits.
    
*   Review the `roi_percent_realised` and `nof_trades` fields to identify consistent performers.
    

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets#step-3-assess-cross-chain-wallet-performance)

Step 3: Assess Cross-Chain Wallet Performance

*   For any wallet, use PnL Summary with `address: "0x39d52da6beec991f075eebe577474fd105c5caec"` and `chain: "ethereum"`.
    
*   Set `date: { "from": "2024-07-01", "to": "2025-01-21" }` for 6-month performance history.
    
*   Check `win_rate` (target > 0.5), `realized_pnl_usd`, and `top5_tokens` array to judge trader reliability.
    

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets#step-4-monitor-smart-money-dex-trades)

Step 4: Monitor Smart Money DEX Trades

*   Call Smart Money DEX Trades with `chains: ["ethereum", "base", "arbitrum"]` for multi-chain coverage.
    
*   Apply filters: `token_bought_address: "0x6982508145454ce325ddbe47a25d4ec3d2311933"` and `trade_value_usd: { "min": 10000 }`.
    
*   Include `include_smart_money_labels: ["Smart Trader", "Fund"]` to focus on sophisticated traders.
    
*   Monitor `token_bought_amount` and `estimated_swap_price_usd` for entry points.
    

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets#step-5-analyze-token-holder-distribution)

Step 5: Analyze Token Holder Distribution

*   Access Token Holders endpoint with `chain: "ethereum"` and your token address.
    
*   Set `label_type: "smart_money"` and filter with `include_smart_money_labels: ["Smart Trader", "Fund", "30D Smart Trader"]`.
    
*   Apply `filters: { "ownership_percentage": { "min": 0.1 }, "value_usd": { "min": 50000 } }` to find significant holders.
    
*   Check `balance_change_7d` and `balance_change_30d` fields to see if smart money is accumulating (positive) or exiting (negative).
    

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets#step-6-implement-and-refine-copy-trading)

Step 6: Implement and Refine Copy Trading

*   Select wallets with `roi_percent_realised > 50` and `win_rate > 0.6` from your PnL analysis.
    
*   Set up monitoring with `pagination: { "page": 1, "per_page": 20 }` to track the top 20 performers.
    
*   Use `order_by: [{ "field": "pnl_usd_realised", "direction": "DESC" }]` to prioritize highest profit wallets.
    
*   Refresh Flow Intelligence data with `timeframe: "1h"` for intraday monitoring during volatile periods.
    

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets#code-examples)

Code Examples

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets#id-1.-get-token-flow-intelligence)

1\. Get Token Flow Intelligence

Track real-time capital flows to identify accumulation or distribution patterns:

Copy

    curl -X POST "https://api.nansen.ai/api/v1/tgm/flow-intelligence" \
      -H "apiKey: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "chain": "solana",
        "token_address": "token_address_here",
        "timeframe": "7d"
      }'

This endpoint reveals net flows across different wallet segments (smart traders, whales, public figures) helping identify whether sophisticated players are accumulating or distributing.

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets#id-2.-get-pnl-leaderboard-find-highest-performing-wallets)

2\. Get PnL Leaderboard (Find Highest Performing Wallets)

Identify the most profitable traders for any token:

Copy

    curl -X POST "https://api.nansen.ai/api/v1/tgm/pnl-leaderboard" \
      -H "apiKey: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "chain": "solana",
        "token_address": "token_address_here",
        "date": {
          "from": "2024-10-23",
          "to": "2025-01-21"
        },
        "filters": {
          "pnl_usd_realised": {
            "min": 1000
          }
        }
      }'

This leaderboard shows which wallets have the highest realized profits, enabling copy traders to identify successful trading patterns.

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets#id-3.-get-wallet-pnl-summary-cross-chain-performance)

3\. Get Wallet PnL Summary (Cross-Chain Performance)

Analyze a trader's overall performance and success rate:

Copy

    curl -X POST "https://api.nansen.ai/api/v1/profiler/address/pnl-summary" \
      -H "apiKey: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "address": "wallet_address_here",
        "chain": "solana",
        "date": {
          "from": "2024-10-23",
          "to": "2025-01-21"
        }
      }'

This provides win-rate, realized PnL, and top profitable tokens for any wallet, helping assess trader quality before copying their strategies.

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets#id-4.-track-smart-money-dex-trades)

4\. Track Smart Money DEX Trades

Monitor real-time trading activity from sophisticated traders:

Copy

    curl -X POST "https://api.nansen.ai/api/v1/smart-money/dex-trades" \
      -H "apiKey: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "chains": ["solana"],
        "filters": {
          "token_bought_address": "token_address_here",
          "trade_value_usd": {
            "min": 10000
          }
        }
      }'

Real-time smart money trades provide copy trading signals by showing what experienced traders are buying or selling right now.

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets#id-5.-analyze-token-holder-distribution)

5\. Analyze Token Holder Distribution

Understand token concentration and holder quality:

Copy

    curl -X POST "https://api.nansen.ai/api/v1/tgm/holders" \
      -H "apiKey: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "chain": "solana",
        "token_address": "token_address_here",
        "label_type": "smart_money",
        "filters": {
          "include_smart_money_labels": ["Smart Trader", "Fund"]
        }
      }'

This shows smart money concentration in any token, helping traders assess whether sophisticated investors are holding or have exited.

[PreviousUse case 3: Identifying Related Wallets at Scale](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-3-identifying-related-wallets-at-scale)
[NextUse case 5: Monitoring CEX Health](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-5-monitoring-cex-health)

Last updated 2 months ago

Was this helpful?

---

# API Changelog | Nansen API

[2025-08-29 - Major API Restructuring](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring)

[PreviousChain Coverage](https://docs.nansen.ai/getting-started/chain-coverage)
[Next2025-08-29 - Major API Restructuring](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring)

Last updated 2 months ago

Was this helpful?

---

# Use case 5: Monitoring CEX Health | Nansen API

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-5-monitoring-cex-health#id-1.-scenario)

1\. Scenario

Monitor centralized exchange (CEX) health by tracking onchain asset balances and daily net flows.

**Goal:** Generate daily reports showing:

Name

Assets on Exchange

24hr Net Flows

Coinbase, Inc.

$30bn

$1.2bn

OKX

$129bn

$34m

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-5-monitoring-cex-health#id-2.-solution)

2\. Solution

Use two Nansen API endpoints:

1.  **Address Balances** [**(Link Here)**](https://docs.nansen.ai/api/profiler/address-current-balances)
     - Get total token holdings across all chains
    
2.  **Counterparties** [**(Link Here)**](https://docs.nansen.ai/api/profiler/address-counterparties)
     - Calculate 24hr net flows (inflows minus outflows)
    

**Alternative:** Compare today's balance vs yesterday's balance for a simpler net flow calculation.

### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-5-monitoring-cex-health#id-3.-step-by-step-guide)

3\. Step-by-Step Guide

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-5-monitoring-cex-health#step-1-get-current-assets-on-exchange)

Step 1: Get Current Assets on Exchange

Fetch token balances across all chains covered by Nansen.

**Call the address balances endpoint:**

Copy

    curl -X POST "https://api.nansen.ai/api/v1/profiler/address/current-balance" \
      -H "apiKey: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "entity_name": "Coinbase",
        "chain": "all",
        "hide_spam_token": true,
        "pagination": { "page": 1, "per_page": 1000 }
      }'

**Process the response:**

*   Sum all `usd_value` fields to get total assets on exchange
    
*   Store this value for comparison
    

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-5-monitoring-cex-health#step-2-calculate-24hr-net-flow)

Step 2: Calculate 24hr Net Flow

**Method A: Simple (Balance Difference)**

1.  Get today's total balance (from Step 1)
    
2.  Get yesterday's total balance (same call, run 24 hours earlier)
    
3.  Calculate: `Net Flow = Today's Balance - Yesterday's Balance`
    

**Method B: Detailed (Counterparties Breakdown)**

Fetch all inflows and outflows for the past 24 hours:

Copy

    curl -X POST "https://api.nansen.ai/api/v1/profiler/address/counterparties" \
      -H "apiKey: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "entity_name": "Coinbase",
        "chain": "base",
        "date": {
          "from": "2025-10-22T18:43:00Z",
          "to": "2025-10-23T18:43:00Z"
        },
        "group_by": "entity",
        "source_input": "Combined",
        "pagination": { "page": 1, "per_page": 1000 }
      }'

**Process the response:**

1.  Sum all `inflow_usd` values = Total Inflows
    
2.  Sum all `outflow_usd` values = Total Outflows
    
3.  Calculate: `Net Flow = Total Inflows - Total Outflows`
    

#### 

[](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-5-monitoring-cex-health#step-3-format-results)

Step 3: Format Results

Combine data into your target format:

Copy

    Name: [entity_name]
    Assets on Exchange: [Sum of usd_value from current-balance]
    24hr Net Flows: [Net Flow calculation from Step 2\
\
[PreviousUse case 4: Copytrading Top Performing Wallets](https://docs.nansen.ai/getting-started/use-case-templates/complex-use-cases/use-case-4-copytrading-top-performing-wallets)\
[NextAPI Structure & Base URL](https://docs.nansen.ai/getting-started/api-structure-and-base-url)\
\
Last updated 29 days ago\
\
Was this helpful?

---

# Chain Coverage | Nansen API

Not all endpoints are available across all chains. Below is the list of chains that are supported across different endpoints.

Chain Name

Use in Parameter as

Profiler

Token God Mode

Smart Money

Arbitrum

arbitrum

✅

✅

✅

Avalanche

avalanche

✅

✅

✅

Base

base

✅

✅

✅

Bitcoin

bitcoin

✅

✅

BNB

bnb

✅

✅

✅

Ethereum

ethereum

✅

✅

✅

HyperEVM

hyperevm

✅

✅

✅

Hyperliquid

Unique Endpoints

✅

✅

✅

IOTA

iotaevm

✅

✅

✅

Linea

linea

✅

✅

✅

Mantle

mantle

✅

✅

✅

Optimism

optimism

✅

✅

✅

Plasma

plasma

✅

✅

✅

Polygon

polygon

✅

✅

✅

Ronin

ronin

✅

✅

✅

Scroll

scroll

✅

✅

✅

Sei

sei

✅

✅

✅

Solana

solana

✅

✅

✅

Sonic

sonic

✅

✅

✅

Starknet

starknet

✅

✅

TON

ton

✅

✅

TRON

tron

✅

✅

Unichain

unichain

✅

✅

✅

zkSync

zksync

✅

✅

✅

Please note we're always expanding the chain support at Nansen. If the chain you are interested in is missing, please reach out to us.

[PreviousUnderstanding Responses and Handling Errors](https://docs.nansen.ai/getting-started/understanding-responses-and-handling-errors)
[NextAPI Changelog](https://docs.nansen.ai/api/api-changelog)

Last updated 2 days ago

Was this helpful?

---

# Smart Money | Nansen API

A curated list of the top 5 000 highest-performing wallets ranked by realised profit, winrate, and strong performance across market cycles. Available Smart Money labels:

*   30D Smart Trader
    
*   90D Smart Trader
    
*   180D Smart Trader
    
*   Fund
    
*   Smart Trader
    

### 

[](https://docs.nansen.ai/api/smart-money#available-api-endpoints)

Available API Endpoints:

[Netflows](https://docs.nansen.ai/api/smart-money/netflows)
[Holdings](https://docs.nansen.ai/api/smart-money/holdings)
[Historical Holdings](https://docs.nansen.ai/api/smart-money/historical-holdings)
[DEX Trades](https://docs.nansen.ai/api/smart-money/dex-trades)
[🆕Perp Trades](https://docs.nansen.ai/api/smart-money/perp-trades)
[Jupiter DCAs](https://docs.nansen.ai/api/smart-money/jupiter-dcas)

[Previous2025-08-29 - Major API Restructuring](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring)
[NextNetflows](https://docs.nansen.ai/api/smart-money/netflows)

Last updated 9 days ago

Was this helpful?

---

# Historical Holdings | Nansen API

**Note:** This is a beta endpoint. The data provided may be subject to changes, corrections, or improvements as we continue to refine our Smart Money analytics.

### 

[](https://docs.nansen.ai/api/smart-money/historical-holdings#post-api-v1-smart-money-historical-holdings)

Get Smart Money Historical Holdings Data

post

https://api.nansen.ai/api/v1/smart-money/historical-holdings

Retrieve historical snapshots of aggregated token balances held by smart traders and funds. This endpoint provides time-series data for trend analysis, backtesting, and performance attribution.

Key Features:

*   Daily snapshots of smart money holdings
    
*   Date range filtering (MVP: Ethereum only, 6-12 months lookback)
    
*   Point-in-time pricing and market cap data
    
*   Balance change tracking between snapshots
    
*   Same filtering options as current holdings endpoint
    

Use Cases:

*   Trend Analysis: Track how smart money rotates between assets over time
    
*   Performance Attribution: Combine with price data to estimate ROI
    
*   Backtesting: Validate trading strategies based on historical smart money behavior
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for smart money historical holdings endpoint.

date\_rangeobject · DateRangeRequired

Date range for historical data (YYYY-MM-DD format). If 'to' is omitted, defaults to today. Maximum lookback is 4 years.

Example: `{"from":"2025-10-01","to":"2025-10-31"}`

Show properties

chainsstring · enum\[\]Required

Chains to include in the analysis. Currently supports ethereum, base, and bnb.

Example: `["ethereum"]`

Show properties

filtersany ofOptional

Additional filters to apply

Example: `{"balance_24h_percent_change":{"max":0.1,"min":-0.1},"exclude_smart_money_labels":["30D Smart Trader"],"include_native_tokens":false,"include_smart_money_labels":["Fund","Smart Trader"],"include_stablecoins":false,"token_age_days":{"max":30},"value_usd":{"max":100000,"min":1000}}`

object · SmartMoneyHistoricalHoldingsFiltersOptional

Filters for smart money historical holdings endpoint.

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

order\_byany ofOptional

Custom sort order. Defaults to sorting by date DESC, value\_usd DESC, token\_address ASC, chain ASC for stable pagination.

object · SortOrder\[SmartMoneyHistoricalHoldingsSortField\]\[\]Optional

Show properties

Responses

200

Smart money historical holdings data

application/json

Responseobject · SmartMoneyHistoricalHoldingsResponse

Response model for smart money historical holdings endpoint.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/smart-money/historical-holdings

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/smart-money/historical-holdings HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 453
    
    {
      "date_range": {
        "from": "2025-10-01",
        "to": "2025-10-31"
      },
      "chains": [\
        "ethereum"\
      ],
      "filters": {
        "balance_24h_percent_change": {
          "max": 0.1,
          "min": -0.1
        },
        "exclude_smart_money_labels": [\
          "30D Smart Trader"\
        ],
        "include_native_tokens": false,
        "include_smart_money_labels": [\
          "Fund",\
          "Smart Trader"\
        ],
        "include_stablecoins": false,
        "token_age_days": {
          "max": 30
        },
        "value_usd": {
          "max": 100000,
          "min": 1000
        }
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "order_by": [\
        {\
          "field": "date",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

Smart money historical holdings data

Copy

    {
      "data": [\
        {\
          "date": "text",\
          "chain": "base",\
          "token_address": "text",\
          "token_symbol": "text",\
          "token_sectors": [\
            "text"\
          ],\
          "smart_money_labels": [\
            "text"\
          ],\
          "balance": 1,\
          "value_usd": 1,\
          "balance_24h_percent_change": 1,\
          "holders_count": 1,\
          "share_of_holdings_percent": 1,\
          "token_age_days": 1,\
          "market_cap_usd": 1\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousHoldings](https://docs.nansen.ai/api/smart-money/holdings)
[NextDEX Trades](https://docs.nansen.ai/api/smart-money/dex-trades)

Last updated 22 days ago

Was this helpful?

---

# Profiler | Nansen API

[Address Current Balances](https://docs.nansen.ai/api/profiler/address-current-balances)
[Address Historical Balances](https://docs.nansen.ai/api/profiler/address-historical-balances)
[Address Transactions](https://docs.nansen.ai/api/profiler/address-transactions)
[Address Counterparties](https://docs.nansen.ai/api/profiler/address-counterparties)
[Address Related Wallets](https://docs.nansen.ai/api/profiler/address-related-wallets)
[Address PnL & Trade Performance](https://docs.nansen.ai/api/profiler/address-pnl-and-trade-performance)
[Address Labels](https://docs.nansen.ai/api/profiler/address-labels)
[🆕Entity Name Search](https://docs.nansen.ai/api/profiler/entity-name-search)
[🆕Address Perp Positions](https://docs.nansen.ai/api/profiler/address-perp-positions)
[🆕Address Perp Trades](https://docs.nansen.ai/api/profiler/address-perp-trades)
[🆕Hyperliquid Address Leaderboard](https://docs.nansen.ai/api/profiler/hyperliquid-address-leaderboard)

[PreviousJupiter DCAs](https://docs.nansen.ai/api/smart-money/jupiter-dcas)
[NextAddress Current Balances](https://docs.nansen.ai/api/profiler/address-current-balances)

Was this helpful?

---

# Jupiter DCAs | Nansen API

### 

[](https://docs.nansen.ai/api/smart-money/jupiter-dcas#post-api-v1-smart-money-dcas)

Get Smart Money DCAs Data

post

https://api.nansen.ai/api/v1/smart-money/dcas

Monitor DCA strategies employed by smart money on Solana through Jupiter DCA. This endpoint reveals systematic accumulation strategies used by smart money.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

filtersany ofOptional

Additional filters to apply. Only filters for columns that are being selected will be applied.

Example: `{"exclude_smart_money_labels":["30D Smart Trader"],"include_smart_money_labels":["Fund","Smart Trader"]}`

object · SmartMoneyDcasFiltersOptional

Filters for smart money DCAs endpoint.

These filters control which DCA orders, tokens, and traders are included in the DCA analysis.

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "dca\_created\_at", "direction": "DESC"}\] - Sort by DCA created timestamp descending
*   \[{"field": "dca\_updated\_at", "direction": "ASC"}\] - Sort by DCA updated timestamp ascending
*   \[{"field": "deposit\_token\_amount", "direction": "DESC"}, {"field": "token\_spent\_amount", "direction": "ASC"}\] - Sort by deposit token amount descending, then token spent amount ascending

object · SortOrder\[SmartMoneyDcasSortField\]\[\]Optional

Show properties

Responses

200

Smart money DCAs data

application/json

Responseobject · SmartMoneyDcasResponse

Response model for smart money DCAs endpoint.

Contains the filtered smart money DCAs data with metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/smart-money/dcas

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/smart-money/dcas HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 212
    
    {
      "filters": {
        "exclude_smart_money_labels": [\
          "30D Smart Trader"\
        ],
        "include_smart_money_labels": [\
          "Fund",\
          "Smart Trader"\
        ]
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "order_by": [\
        {\
          "field": "dca_created_at",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

Smart money DCAs data

Copy

    {
      "data": [\
        {\
          "dca_created_at": "text",\
          "dca_updated_at": "text",\
          "trader_address": "text",\
          "transaction_hash": "text",\
          "trader_address_label": "text",\
          "dca_vault_address": "text",\
          "input_token_address": "text",\
          "output_token_address": "text",\
          "deposit_token_amount": 1,\
          "token_spent_amount": 1,\
          "output_token_redeemed_amount": 1,\
          "dca_status": "text",\
          "input_token_symbol": "text",\
          "output_token_symbol": "text",\
          "deposit_value_usd": 1\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousPerp Trades](https://docs.nansen.ai/api/smart-money/perp-trades)
[NextProfiler](https://docs.nansen.ai/api/profiler)

Last updated 2 months ago

Was this helpful?

---

# Perp Trades | Nansen API

### 

[](https://docs.nansen.ai/api/smart-money/perp-trades#post-api-v1-smart-money-perp-trades)

Get Smart Money Perpetual Trades Data

post

https://api.nansen.ai/api/v1/smart-money/perp-trades

Access real-time perpetual trading activity from smart traders and funds on Hyperliquid. This endpoint provides granular transaction-level data showing exactly what sophisticated traders are trading on perpetual contracts.

Key Features:

*   Hyperliquid perpetual contracts only (no chain field needed)
    
*   Real-time trading data from smart money wallets
    
*   Detailed trade information including coin, amount, price, action, and type
    
*   Smart money filtering capabilities
    
*   Type filtering (Market/Limit)
    
*   Only new positions filter to show only position opening trades (defaults to false - shows all trades)
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

filtersany ofOptional

Additional filters to apply. Only filters for columns that are being selected will be applied.

Example: `{"action":"Buy - Add Long","side":"Long","token_symbol":"BTC","type":"Limit","value_usd":{"max":10000,"min":1000}}`

object · SmartMoneyPerpTradesFiltersOptional

Filters for smart money perpetual trades endpoint.

These filters control which perpetual trades and traders are included in the trades analysis.

Show properties

only\_new\_positionsany ofOptional

When True, includes 'Open' position actions (Open Long, Open Short). Can be combined with other action filters using OR logic (union). When False (default), returns all trades.

Default: `false`Example: `true`

booleanOptional

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "value\_usd", "direction": "DESC"}\] - Sort by trade value descending
*   \[{"field": "block\_timestamp", "direction": "ASC"}\] - Sort by timestamp ascending
*   \[{"field": "token\_amount", "direction": "DESC"}, {"field": "block\_timestamp", "direction": "ASC"}\] - Sort by token amount descending, then timestamp ascending

object · SortOrder\[SmartMoneyPerpTradesSortField\]\[\]Optional

Show properties

Responses

200

Smart money perpetual trades data

application/json

Responseobject · SmartMoneyPerpTradesResponse

Response model for smart money perpetual trades endpoint.

Contains the filtered smart money perpetual trades data with metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/smart-money/perp-trades

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/smart-money/perp-trades HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 249
    
    {
      "filters": {
        "action": "Buy - Add Long",
        "side": "Long",
        "token_symbol": "BTC",
        "type": "Limit",
        "value_usd": {
          "max": 10000,
          "min": 1000
        }
      },
      "only_new_positions": true,
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "order_by": [\
        {\
          "field": "block_timestamp",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

Smart money perpetual trades data

Copy

    {
      "data": [\
        {\
          "trader_address_label": "text",\
          "trader_address": "text",\
          "token_symbol": "text",\
          "side": "Long",\
          "action": "Add",\
          "token_amount": 1,\
          "price_usd": 1,\
          "value_usd": 1,\
          "type": "Market",\
          "block_timestamp": "text",\
          "transaction_hash": "text"\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousDEX Trades](https://docs.nansen.ai/api/smart-money/dex-trades)
[NextJupiter DCAs](https://docs.nansen.ai/api/smart-money/jupiter-dcas)

Last updated 17 days ago

Was this helpful?

---

# Holdings | Nansen API

### 

[](https://docs.nansen.ai/api/smart-money/holdings#common-scenarios)

Common Scenarios

Usecase

Required Parameters

Filters

Sorting Logic

Expected Output

View smart trader token holdings across chains

chains = \["ethereum", "solana"\]

N/A

order\_by = \[{field: "value\_usd", direction: "DESC"}\]

Aggregated list of tokens held by smart traders on specified chains

Monitor top accumulating tokens this week

chains = "all",

filters = {balance\_24h\_percent\_change: {min: 10}},

order\_by = \[{field: "balance\_24h\_percent\_change", direction: "DESC"}\]

Tokens showing largest recent increases in smart trader holdings

Screen for newly held tokens with threshold value

chains = "all",

filters = {token\_age\_days: {max: 30}, value\_usd: {min: 10000}}

order\_by = \[{field: "token\_age\_days", direction: "ASC"}\]

Newly acquired tokens by smart money, filtered by age and min USD value

### 

[](https://docs.nansen.ai/api/smart-money/holdings#post-api-v1-smart-money-holdings)

Get Smart Money Holdings Data

post

https://api.nansen.ai/api/v1/smart-money/holdings

Retrieve aggregated token balances held by smart traders and funds across multiple blockchains. This endpoint provides insights into what tokens are being accumulated by sophisticated market participants, excluding whales, large holders, and influencers to focus specifically on trading expertise.

Key Features:

*   Aggregated balances (not per-wallet breakdowns)
    
*   24-hour balance change tracking updated in realtime
    
*   Sector categorization for tokens
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

chainsstring · enum\[\]Required

Chains to include in the analysis (only smart money supported chains). Use 'all' to include all available chains.

Example: `["ethereum","solana"]`

Show properties

filtersany ofOptional

Additional filters to apply. Only filters for columns that are being selected will be applied.

Example: `{"balance_24h_percent_change":{"max":0.1,"min":-0.1},"exclude_smart_money_labels":["30D Smart Trader"],"include_native_tokens":false,"include_smart_money_labels":["Fund","Smart Trader"],"include_stablecoins":false,"token_age_days":{"max":30},"value_usd":{"max":100000,"min":1000}}`

object · SmartMoneyHoldingsFiltersOptional

Filters for smart money holdings endpoint.

These filters control which token holdings, smart money categories, and data are included in the holdings analysis.

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "value\_usd", "direction": "DESC"}\] - Sort by value USD descending
*   \[{"field": "holders\_count", "direction": "ASC"}\] - Sort by number of holders ascending
*   \[{"field": "value\_usd", "direction": "DESC"}, {"field": "holders\_count", "direction": "ASC"}\] - Sort by value USD descending, then number of holders ascending

object · SortOrder\[SmartMoneyHoldingsSortField\]\[\]Optional

Show properties

Responses

200

Smart money holdings data

application/json

Responseobject · SmartMoneyHoldingsResponse

Response model for smart money holdings endpoint.

Contains the filtered smart money holdings data with metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/smart-money/holdings

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/smart-money/holdings HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 410
    
    {
      "chains": [\
        "ethereum",\
        "solana"\
      ],
      "filters": {
        "balance_24h_percent_change": {
          "max": 0.1,
          "min": -0.1
        },
        "exclude_smart_money_labels": [\
          "30D Smart Trader"\
        ],
        "include_native_tokens": false,
        "include_smart_money_labels": [\
          "Fund",\
          "Smart Trader"\
        ],
        "include_stablecoins": false,
        "token_age_days": {
          "max": 30
        },
        "value_usd": {
          "max": 100000,
          "min": 1000
        }
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "order_by": [\
        {\
          "field": "chain",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

Smart money holdings data

Copy

    {
      "data": [\
        {\
          "chain": "all",\
          "token_address": "text",\
          "token_symbol": "text",\
          "token_sectors": [\
            "text"\
          ],\
          "value_usd": 1,\
          "balance_24h_percent_change": 1,\
          "holders_count": 1,\
          "share_of_holdings_percent": 1,\
          "token_age_days": 1,\
          "market_cap_usd": 1\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousNetflows](https://docs.nansen.ai/api/smart-money/netflows)
[NextHistorical Holdings](https://docs.nansen.ai/api/smart-money/historical-holdings)

Last updated 1 month ago

Was this helpful?

---

# Netflows | Nansen API

### 

[](https://docs.nansen.ai/api/smart-money/netflows#common-scenarios)

Common Scenarios

Usecase

Required Parameters

Optional Filters

Sorting Logic

Expected Output

Find what funds are buying on Solana

chains: \["Solana"\]

include\_smart\_money\_labels: \["Fund"\]

\[{"field":"net\_flow\_7d\_usd", "direction":"DESC"}\]

Returns top tokens by funds, sorted by 7D inflow

Top DeFi tokens that Smart Money are selling

chains: \["ethereum"\]

token\_sectors: \["DeFi"\]

\[{"field":"net\_flow\_7d\_usd", "direction":"ASC"}\]

Returns tokens with highest net outflow in DeFi sector

### 

[](https://docs.nansen.ai/api/smart-money/netflows#post-api-v1-smart-money-netflow)

Get Smart Money Netflow Data

post

https://api.nansen.ai/api/v1/smart-money/netflow

Analyze net capital flows (inflows vs outflows) from smart traders and funds across different time periods. This endpoint helps identify which tokens are experiencing net accumulation or distribution by smart money.

What are Net Flows? Net flows represent the difference between smart money inflows and outflows for a token. This includes:

*   DEX Trading Activity: Tokens bought vs sold on decentralized exchanges
    
*   CEX Transfers: Tokens sent to or received from centralized exchanges
    
*   Positive Net Flow: Smart money is accumulating (buying more than selling, or withdrawing from CEXs)
    
*   Negative Net Flow: Smart money is distributing (selling more than buying, or depositing to CEXs)
    

Key Features:

*   Aggregated net flow calculations across all smart money activity
    
*   Multiple time period analysis (24h, 7d, 30d)
    
*   Sortable results by volume metrics
    
*   Includes both DEX trades and CEX transfers
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

chainsstring · enum\[\]Required

Chains to include in the analysis (only smart money supported chains). Use 'all' to include all available chains.

Example: `["ethereum","solana"]`

Show properties

filtersany ofOptional

Additional filters to apply. Only filters for columns that are being selected will be applied.

Example: `{"exclude_smart_money_labels":["30D Smart Trader"],"include_native_tokens":false,"include_smart_money_labels":["Fund","Smart Trader"],"include_stablecoins":false}`

object · SmartMoneyNetflowFiltersOptional

Filters for smart money netflow endpoint.

These filters control which smart money categories, tokens, and data are included in the netflow analysis.

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "market\_cap\_usd", "direction": "DESC"}\] - Sort by market cap descending
*   \[{"field": "net\_flow\_24h\_usd", "direction": "ASC"}\] - Sort by 24h flow ascending
*   \[{"field": "market\_cap\_usd", "direction": "DESC"}, {"field": "net\_flow\_24h\_usd", "direction": "ASC"}\] - Sort by market cap descending, then 24h flow ascending

object · SortOrder\[SmartMoneyNetflowSortField\]\[\]Optional

Show properties

Responses

200

Smart money netflow data

application/json

Responseobject · SmartMoneyNetflowResponse

Response model for smart money netflow endpoint.

Contains the filtered smart money netflow data with metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/smart-money/netflow

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/smart-money/netflow HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 292
    
    {
      "chains": [\
        "ethereum",\
        "solana"\
      ],
      "filters": {
        "exclude_smart_money_labels": [\
          "30D Smart Trader"\
        ],
        "include_native_tokens": false,
        "include_smart_money_labels": [\
          "Fund",\
          "Smart Trader"\
        ],
        "include_stablecoins": false
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "order_by": [\
        {\
          "field": "chain",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

Smart money netflow data

Copy

    {
      "data": [\
        {\
          "token_address": "text",\
          "token_symbol": "text",\
          "net_flow_24h_usd": 1,\
          "net_flow_7d_usd": 1,\
          "net_flow_30d_usd": 1,\
          "chain": "text",\
          "token_sectors": [\
            "text"\
          ],\
          "trader_count": 1,\
          "token_age_days": 1,\
          "market_cap_usd": 1\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousSmart Money](https://docs.nansen.ai/api/smart-money)
[NextHoldings](https://docs.nansen.ai/api/smart-money/holdings)

Last updated 1 month ago

Was this helpful?

---

# 2025-08-29 - Major API Restructuring | Nansen API

This changelog highlights the key architectural and structural differences between the beta endpoints and v1 endpoints, focusing on breaking changes that developers need to be aware of when migrating.

#### 

[](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring#version-update)

🔄 Version Update

*   **From**: Beta endpoints (`/api/beta/*`)
    
*   **To**: v1 endpoints (`/api/v1/*`)
    

#### 

[](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring#major-structural-changes)

🏗️ **Major Structural Changes**

#### 

[](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring#id-1.-parameter-structure-overhaul)

1\. **Parameter Structure Overhaul**

**Before (Beta): Nested Parameters Object**

Copy

    {
      "parameters": {
        "tokenAddress": "2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv",
        "smFilter": ["180D Smart Trader"],
        "chain": "solana"
      },
      "pagination": {
        "page": 1,
        "recordsPerPage": 100
      }
    }

**After (v1): Structured Request with Nested Filters**

Copy

    {
      "chain": "solana",
      "token_address": "2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv",
      "filters": {
        "smart_money": {
          "include": ["180D Smart Trader"]
        },
        "include_stablecoins": true,
        "include_native_tokens": true
      },
      "pagination": {
        "page": 1,
        "per_page": 100
      }
    }

**Impact**: All existing client code must be restructured to remove the nested `parameters` wrapper.

#### 

[](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring#id-2.-naming-convention-changes)

2\. **Naming Convention Changes**

**Before (Beta): camelCase**

*   `tokenAddress`
    
*   `includeStablecoin`
    

**After (v1): snake\_case**

*   `tokenAddress →` token\_address\`
    
*   `smFilter` → `filters.smart_money.include` (nested structure)
    
*   `includeStablecoin` → `filters.include_stablecoins`
    

**Impact**: Significant impact - all fields are changed to snake\_case

#### 

[](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring#id-3.-response-structure-standardization)

3\. **Response Structure Standardization**

**Before (Beta): camelCase Response Fields**

Copy

    {
      "tokenAddress": "...",
      "symbol": "...",
      "marketCap": 1000000
    }

**After (v1): snake\_case Response Fields**

Copy

    {
      "token_address": "...",
      "symbol": "...",
      "market_cap": 1000000
    }

**Note**: Not all v1 endpoints return pagination fields - some return data only while others include pagination metadata. When pagination is present, it now includes an `is_last_page` boolean for easier pagination handling.

**Impact**: All client code must be updated to handle snake\_case field names in responses.

#### 

[](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring#renamed-endpoint)

📋 **Renamed Endpoint**

#### 

[](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring#smart-money-endpoints)

**Smart Money Endpoints**

`**/beta/smart-money/inflows**` **→** `**/api/v1/smart-money/netflow**`

#### 

[](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring#profiler-endpoints)

**Profiler Endpoints**

`**/beta/profiler/address/balances**` **→** `**/api/v1/profiler/address/current-balance**`

#### 

[](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring#breaking-changes-summary)

🚨 **Breaking Changes Summary**

#### 

[](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring#must-update)

**Must Update**:

1.  **Remove nested** `**parameters**` **wrapper** from all requests
    
2.  **Handle new response structure** with `data` and `pagination` fields
    
3.  **Check parameter naming** for snake\_case vs camelCase changes
    

### 

[](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring#endpoint-migration-map)

Endpoint Migration Map

#### 

[](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring#smart-money-endpoints-1)

Smart Money Endpoints

`**/api/beta/smart-money/inflows**` **→** `**/api/v1/smart-money/netflow**`

**Changes:**

*   Renamed from "inflows" to "netflow" for clarity
    
*   Request structure simplified (no `parameters` wrapper)
    
*   Enhanced filtering capabilities
    
*   Added comprehensive sorting options
    
*   Response includes pagination metadata
    

**New Features in V1:**

*   `remove_scam_tokens` filter
    
*   `hide_spam_tokens` filter
    
*   `token_sector` filter
    
*   Custom sort ordering support
    

`**/api/beta/smart-money/holdings**` **→** `**/api/v1/smart-money/holdings**`

**Changes:**

*   Direct request body structure
    
*   Enhanced response with pagination
    
*   Improved filtering system
    
*   Added sort customization
    

`**/api/beta/smart-money/dex-trades**` **→** `**/api/v1/smart-money/dex-trades**`

**Changes:**

*   Simplified request structure
    
*   Added comprehensive trade filters
    
*   Enhanced label filtering
    
*   Improved response metadata
    

`**/api/beta/smart-money/dcas**` **→** `**/api/v1/smart-money/dcas**`

**Changes:**

*   Standardized request/response format
    
*   Enhanced filtering for DCA parameters
    
*   Added sort capabilities
    

#### 

[](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring#wallet-profiler-endpoints)

Wallet Profiler Endpoints

`**/api/beta/profiler/address/transactions**` **→** `**/api/v1/profiler/address/transactions**`

**Changes:**

*   Reduced max pagination from 100 to 20 records per page (performance optimization)
    
*   Enhanced filtering for transaction types
    
*   Added method and source type filters
    
*   Improved token info structure
    

`**/api/beta/profiler/address/balances**` **→** `**/api/v1/profiler/address/current-balance**`

**Changes:**

*   Renamed for clarity (balances → current-balance)
    
*   Enhanced filtering capabilities
    
*   Added value range filters
    
*   Improved chain support
    

`**/api/beta/profiler/address/pnl**` **→** `**/api/v1/profiler/address/pnl**`

**Changes:**

*   Simplified request structure
    
*   Enhanced PnL calculation fields
    
*   Added comprehensive filtering
    
*   Improved sort options
    

`**/api/beta/profiler/address/pnl-summary**` **→** `**/api/v1/profiler/address/pnl-summary**`

**Changes:**

*   Standardized response format
    
*   Enhanced top token structure
    
*   Improved metadata
    

`**/api/beta/profiler/address/counterparties**` **→** `**/api/v1/profiler/address/counterparties**`

**Changes:**

*   Enhanced label filtering
    
*   Added interaction count filters
    
*   Improved volume filtering
    
*   Better token info structure
    

`**/api/beta/profiler/address/historical-balances**` **→** `**/api/v1/profiler/address/historical-balances**`

**Changes:**

*   Standardized date range handling
    
*   Enhanced spam token filtering
    
*   Improved response structure
    

`**/api/beta/profiler/address/related-wallets**` **→** `**/api/v1/profiler/address/related-wallets**`

**Changes:**

*   Enhanced relationship metadata
    
*   Added sort capabilities
    
*   Improved response structure
    

#### 

[](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring#token-god-mode-tgm-endpoints)

Token God Mode (TGM) Endpoints

`**/api/beta/tgm/dex-trades**` **→** `**/api/v1/tgm/dex-trades**`

**Changes:**

*   Enhanced filtering system
    
*   Added action filters (buy/sell)
    
*   Improved trader label filtering
    
*   Better value range filters
    

`**/api/beta/tgm/transfers**` **→** `**/api/v1/tgm/transfers**`

**Changes:**

*   Enhanced transfer type filtering
    
*   Added CEX/DEX inclusion controls
    
*   Improved smart money filtering
    
*   Better address label filtering
    

`**/api/beta/tgm/holders**` **→** `**/api/v1/tgm/holders**`

**Changes:**

*   Simplified label type handling
    
*   Enhanced balance change tracking
    
*   Added ownership percentage filters
    
*   Improved sort capabilities
    

`**/api/beta/tgm/flows**` **→** `**/api/v1/tgm/flows**`

**Changes:**

*   Enhanced flow tracking
    
*   Added holder statistics
    
*   Improved time-based analysis
    
*   Better sort options
    

`**/api/beta/tgm/pnl-leaderboard**` **→** `**/api/v1/tgm/pnl-leaderboard**`

**Changes:**

*   Enhanced PnL metrics
    
*   Added ROI calculations
    
*   Improved trader filtering
    
*   Better sort capabilities
    

`**/api/beta/tgm/who-bought-sold**` **→** `**/api/v1/tgm/who-bought-sold**`

**Changes:**

*   Enhanced volume tracking
    
*   Added trade direction analysis
    
*   Improved label filtering
    

`**/api/beta/tgm/jup-dca**` **→** `**/api/v1/tgm/jup-dca**`

**Changes:**

*   Standardized DCA vault tracking
    
*   Enhanced status filtering
    
*   Improved deposit tracking
    

`**/api/beta/tgm/flow-intelligence**` **→** `**/api/v1/tgm/flow-intelligence**`

**Changes:**

*   Enhanced category tracking
    
*   Added wallet count metrics
    
*   Improved flow analysis
    

#### 

[](https://docs.nansen.ai/api/api-changelog/2025-08-29-major-api-restructuring#new-v1-only-endpoints)

New V1-Only Endpoints

`**/api/v1/portfolio/defi-holdings**`

*   Production-ready DeFi portfolio tracking
    
*   Comprehensive protocol breakdown
    
*   Asset/debt/reward categorization
    

`**/api/v1/transaction-with-token-transfer-lookup**`

*   Enhanced transaction lookup
    
*   NFT transfer support
    
*   Comprehensive token transfer tracking
    

`**/api/v1/token-screener**`

*   Advanced token discovery
    
*   Multi-chain screening
    
*   Comprehensive filtering system
    
*   Smart money integration
    

[PreviousAPI Changelog](https://docs.nansen.ai/api/api-changelog)
[NextSmart Money](https://docs.nansen.ai/api/smart-money)

Last updated 2 months ago

Was this helpful?

---

# DEX Trades | Nansen API

### 

[](https://docs.nansen.ai/api/smart-money/dex-trades#post-api-v1-smart-money-dex-trades)

Get Smart Money DEX Trades Data

post

https://api.nansen.ai/api/v1/smart-money/dex-trades

Access real-time DEX trading activity from smart traders and funds over the last 24 hours. This endpoint provides granular transaction-level data showing exactly what sophisticated traders are buying and selling on decentralized exchanges.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

chainsstring · enum\[\]Required

Chains to include in the analysis (only smart money supported chains). Use 'all' to include all available chains.

Example: `["ethereum","solana"]`

Show properties

filtersany ofOptional

Additional filters to apply. Only filters for columns that are being selected will be applied.

Example: `{"exclude_smart_money_labels":["30D Smart Trader"],"include_smart_money_labels":["Fund","Smart Trader"],"token_bought_age_days":{"max":30,"min":1},"trade_value_usd":{"max":10000,"min":1000}}`

object · SmartMoneyDexTradesFiltersOptional

Filters for smart money DEX trades endpoint.

These filters control which DEX trades, tokens, and traders are included in the trades analysis.

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "trade\_value\_in\_usd", "direction": "DESC"}\] - Sort by trade value descending
*   \[{"field": "block\_timestamp", "direction": "ASC"}\] - Sort by timestamp ascending
*   \[{"field": "token\_bought\_amount", "direction": "DESC"}, {"field": "block\_timestamp", "direction": "ASC"}\] - Sort by bought amount descending, then timestamp ascending

object · SortOrder\[SmartMoneyDexTradesSortField\]\[\]Optional

Show properties

Responses

200

Smart money DEX trades data

application/json

Responseobject · SmartMoneyDexTradesResponse

Response model for smart money dex trades endpoint.

Contains the filtered smart money dex trades data with metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/smart-money/dex-trades

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/smart-money/dex-trades HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 320
    
    {
      "chains": [\
        "ethereum",\
        "solana"\
      ],
      "filters": {
        "exclude_smart_money_labels": [\
          "30D Smart Trader"\
        ],
        "include_smart_money_labels": [\
          "Fund",\
          "Smart Trader"\
        ],
        "token_bought_age_days": {
          "max": 30,
          "min": 1
        },
        "trade_value_usd": {
          "max": 10000,
          "min": 1000
        }
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "order_by": [\
        {\
          "field": "chain",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

Smart money DEX trades data

Copy

    {
      "data": [\
        {\
          "chain": "text",\
          "block_timestamp": "text",\
          "transaction_hash": "text",\
          "trader_address": "text",\
          "trader_address_label": "text",\
          "token_bought_address": "text",\
          "token_sold_address": "text",\
          "token_bought_amount": 1,\
          "token_sold_amount": 1,\
          "token_bought_symbol": "text",\
          "token_sold_symbol": "text",\
          "token_bought_age_days": 1,\
          "token_sold_age_days": 1,\
          "token_bought_market_cap": 1,\
          "token_sold_market_cap": 1,\
          "trade_value_usd": 1\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousHistorical Holdings](https://docs.nansen.ai/api/smart-money/historical-holdings)
[NextPerp Trades](https://docs.nansen.ai/api/smart-money/perp-trades)

Last updated 2 months ago

Was this helpful?

---

# Address Related Wallets | Nansen API

### 

[](https://docs.nansen.ai/api/profiler/address-related-wallets#post-api-v1-profiler-address-related-wallets)

Get Address Related Wallets Data

post

https://api.nansen.ai/api/v1/profiler/address/related-wallets

Get wallets that are related to the input address through various types of blockchain interactions and relationships. Returns detailed information about each related wallet including the relationship type, transaction details, and timing information.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

addressstringRequired

Address to get related wallets for

Example: `0x28c6c06298d514db089934071355e5743bf21d60`

chainstring · enumRequired

Blockchain chain for the related wallets data

Example: `ethereum`Possible values: `all``arbitrum``avalanche``base``bitcoin``bnb``ethereum``iotaevm``linea``mantle``monad``optimism``plasma``polygon``ronin``scroll``sei``solana``sonic``starknet``ton``tron``unichain``zksync`

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering

object · SortOrder\[ProfilerAddressRelatedWalletsSortField\]\[\]Optional

Show properties

Responses

200

Address related wallets data

application/json

Responseobject · ProfilerAddressRelatedWalletsResponse

Response model for profiler address related wallets endpoint.

Contains the related wallets data with metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/profiler/address/related-wallets

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/profiler/address/related-wallets HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 162
    
    {
      "address": "0x28c6c06298d514db089934071355e5743bf21d60",
      "chain": "ethereum",
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "order_by": [\
        {\
          "field": "order",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

Address related wallets data

Copy

    {
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      },
      "data": [\
        {\
          "address": "text",\
          "address_label": "text",\
          "relation": "text",\
          "transaction_hash": "text",\
          "block_timestamp": "text",\
          "order": 1,\
          "chain": "text"\
        }\
      ]
    }

[PreviousAddress Counterparties](https://docs.nansen.ai/api/profiler/address-counterparties)
[NextAddress PnL & Trade Performance](https://docs.nansen.ai/api/profiler/address-pnl-and-trade-performance)

Last updated 2 months ago

Was this helpful?

---

# Address Perp Trades | Nansen API

### 

[](https://docs.nansen.ai/api/profiler/address-perp-trades#post-api-v1-profiler-perp-trades)

Get Perpetual Trade Data

post

https://api.nansen.ai/api/v1/profiler/perp-trades

Get perpetual trade data for a user. This endpoint provides trade information including trade price, size, side, fees, and other trade details.

**What it helps to answer:**

1.  **What are the perpetual trades for a specific user address within a date range?**
    
2.  **What are the trade prices, sizes, and directions for each trade?**
    
3.  **What are the trading fees and closed PnL for each trade?**
    
4.  **What are the order IDs and transaction hashes for trade tracking?**
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for Perp Trades endpoint.

addressstring · min: 42 · max: 42Required

User's Hyperliquid address in 42-character hexadecimal format

Example: `0x45d26f28196d226497130c4bac709d808fed4029`

dateobject · DateRangeRequired

Date range for the trades

Example: `{"from":"2025-10-01","to":"2025-10-10"}`

Show properties

filtersany ofOptional

Additional filters for the trades

Example: `{"size":{"max":1000,"min":0.001}}`

object · PerpTradeFiltersOptional

Filters for perp trades endpoint.

These filters control which perpetual trades are included in the results based on various trade criteria.

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

order\_byany ofOptional

Sort order for the trades

Example: `[{"direction":"DESC","field":"timestamp"}]`

object · SortOrder\[PerpTradeSortField\]\[\]Optional

Show properties

Responses

200

Perpetual trade data for the user

application/json

Responseobject · PerpTradeResponse

Response model for perp trades endpoint.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/profiler/perp-trades

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/profiler/perp-trades HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 239
    
    {
      "address": "0x45d26f28196d226497130c4bac709d808fed4029",
      "date": {
        "from": "2025-10-01",
        "to": "2025-10-10"
      },
      "filters": {
        "size": {
          "max": 1000,
          "min": 0.001
        }
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "order_by": [\
        {\
          "direction": "DESC",\
          "field": "timestamp"\
        }\
      ]
    }

Test it

200

Perpetual trade data for the user

Copy

    {
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      },
      "data": [\
        {\
          "action": "Add",\
          "block_number": 756553592,\
          "closed_pnl": 0,\
          "crossed": true,\
          "fee_token_symbol": "USDC",\
          "fee_usd": 0.434851,\
          "oid": 191284609448,\
          "price": 0.25884,\
          "side": "Short",\
          "size": 6000,\
          "start_position": -7788000,\
          "timestamp": "2025-10-08T18:46:11.452000",\
          "token_symbol": "DOGE",\
          "transaction_hash": "0x50cea34e7464d3055248042d1817780203b600340f67f1d7f4974ea13368acef",\
          "user": "0x45d26f28196d226497130c4bac709d808fed4029",\
          "value_usd": 1553.04\
        },\
        {\
          "action": "Open",\
          "block_number": 756553593,\
          "closed_pnl": 0,\
          "crossed": false,\
          "fee_token_symbol": "USDC",\
          "fee_usd": 2.25,\
          "oid": 191284609449,\
          "price": 45000,\
          "side": "Long",\
          "size": 0.1,\
          "start_position": 0,\
          "timestamp": "2025-10-08T15:30:22.123000",\
          "token_symbol": "BTC",\
          "transaction_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",\
          "user": "0x45d26f28196d226497130c4bac709d808fed4029",\
          "value_usd": 4500\
        },\
        {\
          "action": "Close",\
          "block_number": 756553594,\
          "closed_pnl": 150,\
          "crossed": true,\
          "fee_token_symbol": "USDC",\
          "fee_usd": 2.25,\
          "oid": 191284609450,\
          "price": 3000,\
          "side": "Long",\
          "size": 1.5,\
          "start_position": 1000,\
          "timestamp": "2025-10-08T12:15:33.789000",\
          "token_symbol": "ETH",\
          "transaction_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",\
          "user": "0x45d26f28196d226497130c4bac709d808fed4029",\
          "value_usd": 4500\
        }\
      ]
    }

[PreviousAddress Perp Positions](https://docs.nansen.ai/api/profiler/address-perp-positions)
[NextHyperliquid Address Leaderboard](https://docs.nansen.ai/api/profiler/hyperliquid-address-leaderboard)

Last updated 26 days ago

Was this helpful?

---

# Token God Mode | Nansen API

[Token Information](https://docs.nansen.ai/api/token-god-mode/token-information)
[Token Screener](https://docs.nansen.ai/api/token-god-mode/token-screener)
[Flow Intelligence](https://docs.nansen.ai/api/token-god-mode/flow-intelligence)
[Holders](https://docs.nansen.ai/api/token-god-mode/holders)
[Flows](https://docs.nansen.ai/api/token-god-mode/flows)
[Who Bought/Sold](https://docs.nansen.ai/api/token-god-mode/who-bought-sold)
[DEX Trades](https://docs.nansen.ai/api/token-god-mode/dex-trades)
[Token Transfers](https://docs.nansen.ai/api/token-god-mode/token-transfers)
[Jupiter DCAs](https://docs.nansen.ai/api/token-god-mode/jupiter-dcas)
[PnL Leaderboard](https://docs.nansen.ai/api/token-god-mode/pnl-leaderboard)
[🆕Perp Screener](https://docs.nansen.ai/api/token-god-mode/perp-screener)
[🆕Perp PnL Leaderboard](https://docs.nansen.ai/api/token-god-mode/perp-pnl-leaderboard)
[🆕Perp Positions](https://docs.nansen.ai/api/token-god-mode/perp-positions)
[🆕Perp Trades](https://docs.nansen.ai/api/token-god-mode/perp-trades)

[PreviousHyperliquid Address Leaderboard](https://docs.nansen.ai/api/profiler/hyperliquid-address-leaderboard)
[NextToken Information](https://docs.nansen.ai/api/token-god-mode/token-information)

Was this helpful?

---

# Address Counterparties | Nansen API

### 

[](https://docs.nansen.ai/api/profiler/address-counterparties#common-scenarios)

Common Scenarios

You can use this endpoint to find correct entity name format to use in this Profiler Endpoint: [**Click Here**](https://docs.nansen.ai/api/profiler/entity-name-search)

Usecase

Required Parameters

Expected Output

Get counterparties for a single address

address = "0x28c6c06298d514db089934071355e5743bf21d60", chain = "ethereum", group\_by: "address"

List of counterparties with interaction stats (volume, frequency, timing)

Get counterparties for an entity (e.g., Coinbase)

entity\_name = "Coinbase", chain = "all", group\_by: "entity"

Aggregated counterparties across all entity wallets with interaction stats

### 

[](https://docs.nansen.ai/api/profiler/address-counterparties#post-api-v1-profiler-address-counterparties)

Get Address Counterparties Data

post

https://api.nansen.ai/api/v1/profiler/address/counterparties

Get top counterparties that wallet addresses have interacted with, supporting different grouping options (wallet or entity) and source filtering (Combined, Tokens, ETH). Returns interaction statistics including volume, frequency, and timing data.

What it helps to answer:

*   Most frequent transaction partners by count and volume
    
*   Net value flows between addresses (inflows vs outflows)
    
*   Exchange and protocol interaction patterns
    
*   DeFi protocol usage and DEX trading counterparties
    
*   High-value transfer relationships and funding sources
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

addressany ofOptional

Address to get counterparties for

Example: `0x28c6c06298d514db089934071355e5743bf21d60`

stringOptional

entity\_nameany ofOptional

Entity name to get counterparties for

Example: `Vitalik Buterin`

stringOptional

chainstring · enumRequired

Blockchain chain for the counterparties data

Example: `ethereum`Possible values: `all``arbitrum``avalanche``base``bitcoin``bnb``ethereum``hyperevm``iotaevm``linea``mantle``monad``optimism``plasma``polygon``ronin``scroll``sei``solana``sonic``starknet``ton``tron``unichain``zksync`

dateobject · DateRangeRequired

Date range for the counterparties data

Example: `{"from":"2025-05-01T00:00:00Z","to":"2025-05-03T23:59:59Z"}`

Show properties

source\_inputstring · enumOptional

Type of interactions to include

Default: `Combined`Possible values: `Combined``Tokens``ETH`

group\_bystring · enumOptional

Group counterparties by wallet or entity

Default: `wallet`Possible values: `wallet``entity`

filtersany ofOptional

Additional filters to apply. Only filters for columns that are being selected will be applied.

Example: `{"include_smart_money_labels":["Exchange"],"interaction_count":{"min":5},"total_volume_usd":{"min":1000}}`

object · ProfilerAddressCounterpartiesFiltersOptional

Filters for profiler address counterparties endpoint.

These filters control which counterparties and interactions are included.

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "total\_volume\_usd", "direction": "DESC"}\] - Sort by total volume descending
*   \[{"field": "interaction\_count", "direction": "ASC"}\] - Sort by interaction count ascending
*   \[{"field": "last\_interaction\_date", "direction": "DESC"}\] - Sort by last interaction date descending
*   \[{"field": "volume\_in\_usd", "direction": "DESC"}\] - Sort by incoming volume descending

object · SortOrder\[ProfilerAddressCounterpartiesSortField\]\[\]Optional

Show properties

Responses

200

Address counterparties data

application/json

Responseobject · ProfilerAddressCounterpartiesResponse

Response model for profiler address counterparties endpoint.

Contains the filtered counterparties data with metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/profiler/address/counterparties

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/profiler/address/counterparties HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 226
    
    {
      "address": "0x28c6c06298d514db089934071355e5743bf21d60",
      "chain": "ethereum",
      "date": {
        "from": "2025-05-01T00:00:00Z",
        "to": "2025-05-03T23:59:59Z"
      },
      "group_by": "wallet",
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "source_input": "Combined"
    }

Test it

200

Address counterparties data

Copy

    {
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      },
      "data": [\
        {\
          "counterparty_address": "text",\
          "counterparty_address_label": [\
            "text"\
          ],\
          "interaction_count": 1,\
          "total_volume_usd": 1,\
          "volume_in_usd": 1,\
          "volume_out_usd": 1,\
          "tokens_info": [\
            {\
              "token_address": "text",\
              "token_symbol": "text",\
              "token_name": "text",\
              "num_transfer": "text"\
            }\
          ]\
        }\
      ]
    }

[PreviousAddress Transactions](https://docs.nansen.ai/api/profiler/address-transactions)
[NextAddress Related Wallets](https://docs.nansen.ai/api/profiler/address-related-wallets)

Last updated 22 days ago

Was this helpful?

---

# Useful Links | Nansen API

Name

Link

Website Link

[https://www.nansen.ai](https://www.nansen.ai/)

Plans and Pricing

[https://app.nansen.ai/account/switch-plans](https://app.nansen.ai/account/switch-plans)

Web-App

[https://app.nansen.ai](https://app.nansen.ai/)

[PreviousFrequently Asked Questions](https://docs.nansen.ai/guides/frequently-asked-questions)

Was this helpful?

---

# Address Current Balances | Nansen API

### 

[](https://docs.nansen.ai/api/profiler/address-current-balances#common-scenarios)

Common Scenarios

You can use this endpoint to find correct entity name format to use in this Profiler Endpoint: [**Click Here**](https://docs.nansen.ai/api/profiler/entity-name-search)

Usecase

Required Parameters

Optional Filters

Expected Output

Check current holdings for a single address

address = "0x28c6c06298d514db089934071355e5743bf21d60", chain = "ethereum"

hide\_spam\_token = true,

List of tokens with amounts, USD values, and chain info for the address

View entity-wide portfolio (e.g., Vitalik Buterin)

entity\_name = "Vitalik Buterin", chain = "all"

hide\_spam\_token = true

Aggregated balances for entity across all wallets, showing holdings per chain

### 

[](https://docs.nansen.ai/api/profiler/address-current-balances#post-api-v1-profiler-address-current-balance)

Get Address Current Balance Data

post

https://api.nansen.ai/api/v1/profiler/address/current-balance

Retrieve current token holdings for addresses or entities. Returns detailed balance information across specified chains.

What it helps to answer:

*   Current token holdings with quantities and USD valuations
    
*   Asset distribution across different blockchain networks
    
*   Native token versus token balances
    
*   Stablecoin holdings and percentages
    
*   Cross-chain portfolio composition
    

Note: The address field in the response will be empty if entity\_name is provided.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

addressany ofOptional

Address to get balances for

Example: `0x28c6c06298d514db089934071355e5743bf21d60`

stringOptional

entity\_nameany ofOptional

Entity name to get balances for

Example: `Vitalik Buterin`

stringOptional

chainstring · enumRequired

Blockchain chain for the balances

Example: `ethereum`Possible values: `all``arbitrum``avalanche``base``bitcoin``bnb``ethereum``hyperevm``iotaevm``linea``mantle``monad``optimism``plasma``polygon``ronin``scroll``sei``solana``sonic``starknet``ton``tron``unichain``zksync`

hide\_spam\_tokenbooleanOptional

Removes suspicious tokens from the balance list

Default: `true`Example: `true`

filtersany ofOptional

Additional filters to apply. Only filters for columns that are being selected will be applied.

Example: `{"token_symbol":"USDC","value_usd":{"min":10}}`

object · ProfilerAddressBalancesFiltersOptional

Filters for profiler address current balance endpoint.

These filters control which token balances are included.

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering

object · SortOrder\[ProfilerAddressBalancesSortField\]\[\]Optional

Show properties

Responses

200

Address current balance data

application/json

Responseobject · ProfilerAddressBalancesResponse

Response model for profiler address current-balance endpoint.

Contains the filtered balance data with metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/profiler/address/current-balance

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/profiler/address/current-balance HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 136
    
    {
      "address": "0x28c6c06298d514db089934071355e5743bf21d60",
      "chain": "ethereum",
      "hide_spam_token": true,
      "pagination": {
        "page": 1,
        "per_page": 10
      }
    }

Test it

200

Address current balance data

Copy

    {
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      },
      "data": [\
        {\
          "chain": "text",\
          "address": "text",\
          "token_address": "text",\
          "token_symbol": "text",\
          "token_name": "text",\
          "token_amount": 1,\
          "price_usd": 1,\
          "value_usd": 1\
        }\
      ]
    }

[PreviousProfiler](https://docs.nansen.ai/api/profiler)
[NextAddress Historical Balances](https://docs.nansen.ai/api/profiler/address-historical-balances)

Last updated 22 days ago

Was this helpful?

---

# Portfolio | Nansen API

### 

[](https://docs.nansen.ai/api/portfolio#post-api-v1-portfolio-defi-holdings)

Get Portfolio DeFi Holdings Data

post

https://api.nansen.ai/api/v1/portfolio/defi-holdings

Get simplified DeFi holdings for a wallet address with aggregated tokens and protocol summaries in a user-friendly format.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for portfolio DeFi holdings endpoint.

wallet\_addressstringRequired

Wallet address to get DeFi holdings for

Example: `0x4062b997279de7213731dbe00485722a26718892`

Responses

200

Portfolio DeFi holdings data

application/json

Responseobject · PortfolioDefiHoldingsResponse

Response model for portfolio DeFi holdings endpoint.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/portfolio/defi-holdings

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/portfolio/defi-holdings HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 63
    
    {
      "wallet_address": "0x4062b997279de7213731dbe00485722a26718892"
    }

Test it

200

Portfolio DeFi holdings data

Copy

    {
      "summary": {
        "total_value_usd": 1,
        "total_assets_usd": 1,
        "total_debts_usd": 1,
        "total_rewards_usd": 1,
        "token_count": 1,
        "protocol_count": 1
      },
      "protocols": [\
        {\
          "protocol_name": "text",\
          "chain": "text",\
          "total_value_usd": 1,\
          "total_assets_usd": 1,\
          "total_debts_usd": 1,\
          "total_rewards_usd": 1,\
          "tokens": [\
            {\
              "address": "text",\
              "symbol": "text",\
              "amount": 1,\
              "value_usd": 1,\
              "position_type": "text"\
            }\
          ]\
        }\
      ]
    }

### 

[](https://docs.nansen.ai/api/portfolio#output-field-meanings)

Output Field Meanings

#### 

[](https://docs.nansen.ai/api/portfolio#top-level-fields)

Top-Level Fields

Field

Description

`protocolsUsed`

Array of protocol names the wallet actively uses (e.g., "aave-v3-ethereum")

`holdingsByProtocol`

Detailed breakdown of positions per protocol

`success`

Boolean indicating API call success

`totalProtocols`

Count of protocols with detected activity

#### 

[](https://docs.nansen.ai/api/portfolio#position-types-within-holdingsbyprotocol)

Position Types within `holdingsByProtocol`

Type

Description

`deposits`/`lendings`

Assets supplied to lending protocols (Aave, Compound), including amounts, value, and rewards

`borrows`

Borrowed assets with debt ratios and health factors

`stakings`

Tokens staked for rewards (liquid staking, governance tokens)

`positions`

Complex positions like LP tokens, derivatives, or structured products

`locked`

Time-locked or vested tokens (e.g., vote-escrowed tokens)

`rewards`

Claimable but unclaimed protocol rewards

`farms`

Yield farming positions with staked LP tokens

#### 

[](https://docs.nansen.ai/api/portfolio#position-detail-structure)

Position Detail Structure

Field

Description

`type`

Position category (e.g., "lending", "common", "locked")

`summary`

High-level metrics (asset value, rewards, debt)

`detail`

Granular breakdown including individual token balances, prices, and price changes

[](https://docs.nansen.ai/api/portfolio#supported-protocols)

Supported Protocols


-------------------------------------------------------------------------------------

You can find the list of supported protocols on each supported chain by [clicking here](https://app.nansen.ai/portfolio/protocols)
.

[](https://docs.nansen.ai/api/portfolio#usage-guide-creating-complete-portfolio-overview)

Usage Guide: Creating Complete Portfolio Overview


------------------------------------------------------------------------------------------------------------------------------------------------

Use the following steps to create a complete Portfolio Overview:

**Step 1: Fetch DeFi Positions** Get active protocol positions, staking rewards, and lending activities. This shows how assets are being used in DeFi.

**Step 2: Fetch Wallet Balances** [**(Link Here)**](https://docs.nansen.ai/api/profiler/balances#post-beta-profiler-address-balances)
 Retrieve all token holdings across chains, including idle tokens not actively deployed in protocols.

**Step 3: Combine & Analyze**

*   Total Portfolio Value = DeFi positions + wallet balances
    
*   Strategy Analysis: Compare liquid vs. staked vs. lending positions
    
*   Chain Distribution: Identify multi-chain allocation patterns
    
*   Risk Assessment: Analyze borrowing ratios, protocol concentration
    

[PreviousPerp Trades](https://docs.nansen.ai/api/token-god-mode/perp-trades)
[NextPoints](https://docs.nansen.ai/api/points)

Last updated 2 months ago

Was this helpful?

---

# Address Historical Balances | Nansen API

### 

[](https://docs.nansen.ai/api/profiler/address-historical-balances#common-scenarios)

Common Scenarios

You can use this endpoint to find correct entity name format to use in this Profiler Endpoint: [**Click Here**](https://docs.nansen.ai/api/profiler/entity-name-search)

Usecase

Required Parameters

Optional Filters

Expected Output

Check current holdings for a single address

address = "0x28c6c06298d514db089934071355e5743bf21d60", chain = "ethereum"

hide\_spam\_token = true,

List of tokens with amounts, USD values, and chain info for the address

View entity-wide portfolio (e.g., Coinbase)

entity\_name = "Coinbase", chain = "all"

hide\_spam\_token = true

Aggregated balances for entity across all wallets, showing holdings per chain

### 

[](https://docs.nansen.ai/api/profiler/address-historical-balances#post-api-v1-profiler-address-historical-balances)

Get Address Historical Balances Data

post

https://api.nansen.ai/api/v1/profiler/address/historical-balances

Track token and native coin balance changes over time for addresses or entities. Provides snapshots at configurable intervals to analyze holding patterns, transaction activity, and portfolio evolution across multiple blockchains.

What it helps to answer:

*   Portfolio value changes across different time periods
    
*   Token accumulation and distribution patterns over selected timeframes
    
*   New positions entered and exited during specific periods
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

addressany ofOptional

Address to get historical balances for

Example: `0x28c6c06298d514db089934071355e5743bf21d60`

stringOptional

entity\_nameany ofOptional

Entity name to get historical balances for

Example: `Vitalik Buterin`

stringOptional

chainstring · enumRequired

Blockchain chain for the historical balances

Example: `ethereum`Possible values: `all``arbitrum``avalanche``base``bitcoin``bnb``ethereum``hyperevm``iotaevm``linea``mantle``monad``optimism``plasma``polygon``ronin``scroll``sei``solana``sonic``starknet``ton``tron``unichain``zksync`

dateobject · DateRangeRequired

Date range for historical data

Example: `{"from":"2025-05-01T00:00:00Z","to":"2025-05-03T23:59:59Z"}`

Show properties

filtersany ofOptional

Additional filters to apply. Only filters for columns that are being selected will be applied.

Example: `{"hide_spam_tokens":true,"token_symbol":"USDC","value_usd":{"min":10}}`

object · ProfilerAddressHistoricalBalancesFiltersOptional

Filters for profiler address historical balances endpoint.

These filters control which historical balance data is included.

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering

object · SortOrder\[ProfilerAddressHistoricalBalancesSortField\]\[\]Optional

Show properties

Responses

200

Address historical balances data

application/json

Responseobject · ProfilerAddressHistoricalBalancesResponse

Response model for profiler address historical-balances endpoint.

Contains the filtered historical balance data with metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/profiler/address/historical-balances

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/profiler/address/historical-balances HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 180
    
    {
      "address": "0x28c6c06298d514db089934071355e5743bf21d60",
      "chain": "ethereum",
      "date": {
        "from": "2025-05-01T00:00:00Z",
        "to": "2025-05-03T23:59:59Z"
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      }
    }

Test it

200

Address historical balances data

Copy

    {
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      },
      "data": [\
        {\
          "block_timestamp": "text",\
          "token_address": "text",\
          "chain": "text",\
          "token_amount": 1,\
          "value_usd": 1,\
          "token_symbol": "text"\
        }\
      ]
    }

[PreviousAddress Current Balances](https://docs.nansen.ai/api/profiler/address-current-balances)
[NextAddress Transactions](https://docs.nansen.ai/api/profiler/address-transactions)

Last updated 22 days ago

Was this helpful?

---

# Flow Intelligence | Nansen API

### 

[](https://docs.nansen.ai/api/token-god-mode/flow-intelligence#post-api-v1-tgm-flow-intelligence)

Get TGM Flow Intelligence Data

post

https://api.nansen.ai/api/v1/tgm/flow-intelligence

This endpoint provides comprehensive flow intelligence analytics, including inflows, outflows, and net flows for a specific token, broken down by various holder segments (Exchanges, Smart Money, Public Figures, Whales) with time-based statistics and trends. It can be used for identifying accumulation/distribution patterns across different holder segments.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for TGM flow-intelligence endpoint.

This endpoint provides detailed token flow intelligence for analyzing token movements across different chains. It helps track and categorize token transfers, identifying patterns such as exchange deposits, withdrawals, and transfers between different types of wallets.

chainstring · enumRequired

Blockchain chain

Example: `ethereum`Possible values: `arbitrum``avalanche``base``bnb``ethereum``hyperevm``iotaevm``linea``mantle``monad``optimism``plasma``polygon``ronin``scroll``sei``solana``sonic``starknet``ton``tron``unichain``zksync`

token\_addressstringRequired

Token address

Example: `0x6982508145454ce325ddbe47a25d4ec3d2311933`

timeframestring · enumOptional

Time window for the flow intelligence data

Default: `1d`Possible values: `5m``1h``6h``12h``1d``7d`

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"whale_wallet_count":{"min":1}}`

object · TGMFlowIntelligenceFiltersOptional

Filters for TGM flow intelligence endpoint.

These filters control the flow intelligence analysis data.

Show properties

Responses

200

TGM flow intelligence data

application/json

Responseobject · TGMFlowIntelligenceResponse

Response model for TGM flow-intelligence endpoint.

Contains flow intelligence data with pagination and metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/flow-intelligence

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/tgm/flow-intelligence HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 141
    
    {
      "chain": "ethereum",
      "token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
      "timeframe": "1d",
      "filters": {
        "whale_wallet_count": {
          "min": 1
        }
      }
    }

Test it

200

TGM flow intelligence data

Copy

    {
      "data": [\
        {\
          "public_figure_net_flow_usd": 1000000.5,\
          "public_figure_avg_flow_usd": 50000.25,\
          "public_figure_wallet_count": 10,\
          "top_pnl_net_flow_usd": 2000000.75,\
          "top_pnl_avg_flow_usd": 100000.5,\
          "top_pnl_wallet_count": 15,\
          "whale_net_flow_usd": 5000000.25,\
          "whale_avg_flow_usd": 250000.75,\
          "whale_wallet_count": 25,\
          "smart_trader_net_flow_usd": 1500000.5,\
          "smart_trader_avg_flow_usd": 75000.25,\
          "smart_trader_wallet_count": 20,\
          "exchange_net_flow_usd": 3000000.75,\
          "exchange_avg_flow_usd": 150000.5,\
          "exchange_wallet_count": 5,\
          "fresh_wallets_net_flow_usd": 500000.25,\
          "fresh_wallets_avg_flow_usd": 25000.75,\
          "fresh_wallets_wallet_count": 100\
        }\
      ]
    }

[PreviousToken Screener](https://docs.nansen.ai/api/token-god-mode/token-screener)
[NextHolders](https://docs.nansen.ai/api/token-god-mode/holders)

Last updated 2 months ago

Was this helpful?

---

# Entity Name Search | Nansen API

### 

[](https://docs.nansen.ai/api/profiler/entity-name-search#post-api-v1-search-entity-name)

Search for Entity Names

post

https://api.nansen.ai/api/v1/search/entity-name

Search for entity names to use in other v1 endpoints that support `entity_name` parameters.

This endpoint helps users find the correct entity name format when they want to query by entity instead of address. Many endpoints accept either `address` or `entity_name` as parameters, but entity names must match exactly. This search endpoint makes it easy to find the right entity name.

**Key Features:**

*   Case-insensitive search that matches anywhere in the entity name
    
*   Returns up to 100 results ordered alphabetically
    
*   Minimum 2 character search query required
    
*   Free endpoint (0 credits)
    

**Use Cases:**

1.  **Find entity names for profiler endpoints**: Search "vitalik" to find "Vitalik Buterin" for use in address balance or transaction queries
    
2.  **Discover exchange entities**: Search "binance" to find all Binance-related entities
    
3.  **Locate fund entities**: Search "jump" to find "Jump Trading" and related entities
    

**Example Usage:**

Copy

    {
      "search_query": "vitalik"
    }

**Response:**

Copy

    {
      "data": [\
        {"entity_name": "Vitalik Buterin"},\
        {"entity_name": "Vitalik Buterin: Charity"}\
      ]
    }

**Note:** This endpoint does not support pagination as results are capped at 100 items.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for entity name search endpoint.

This endpoint helps users find the correct entity\_name to use in other v1 endpoints that accept entity\_name as a parameter.

search\_querystring · min: 2Required

Search query for entity names (minimum 2 characters). Search is case-insensitive and matches anywhere in the entity name.

Example: `vitalik`

Responses

200

List of matching entity names

application/json

Responseobject · EntityNameSearchResponse

Response model for entity name search endpoint.

Returns up to 100 entity names ordered alphabetically. No pagination is provided as results are limited to 100 items.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/search/entity-name

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/search/entity-name HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 26
    
    {
      "search_query": "vitalik"
    }

Test it

200

List of matching entity names

Copy

    {
      "data": [\
        {\
          "entity_name": "text"\
        }\
      ]
    }

[PreviousAddress Labels](https://docs.nansen.ai/api/profiler/address-labels)
[NextAddress Perp Positions](https://docs.nansen.ai/api/profiler/address-perp-positions)

Last updated 22 days ago

Was this helpful?

---

# Address Labels | Nansen API

### 

[](https://docs.nansen.ai/api/profiler/address-labels#post-api-beta-profiler-address-labels)

profiler/address/labels

post

https://api.nansen.ai/api/beta/profiler/address/labels

Address and its labels

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

parametersobjectRequired

Object containing all parameters for the endpoint

Show properties

paginationobjectOptional

Pagination options

Default: `{"page":1,"recordsPerPage":100}`

Show properties

Responses

200

Successful response

application/json

Responseobject\[\]

Address and its labels

Show properties

400

Bad request

application/json

401

Authentication error

application/json

403

Forbidden - Subscription tier required

application/json

500

Internal server error

application/json

post

/api/beta/profiler/address/labels

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/beta/profiler/address/labels HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 128
    
    {
      "parameters": {
        "chain": "ethereum",
        "address": "text",
        "entity": "text",
        "label": "text"
      },
      "pagination": {
        "page": 1,
        "recordsPerPage": 100
      }
    }

Test it

200

Successful response

Copy

    [\
      {\
        "label": "Deployer",\
        "category": "others",\
        "definition": "Person or smart contract who deploys a smart contract.",\
        "smEarnedDate": "01/01/20",\
        "fullname": "Alex Svanevik"\
      }\
    ]

### 

[](https://docs.nansen.ai/api/profiler/address-labels#required-parameters)

Required Parameters

Field

Type

Description

chain

string

Blockchain network. Select all to query all EVM chains

address

string

The blockchain address to query for labels

### 

[](https://docs.nansen.ai/api/profiler/address-labels#response-structure)

Response Structure

The API returns an array of label objects with the following fields:

Field

Type

Description

`label`

string

The specific label name assigned to the address

`category`

string

The category of the label (see categories below)

`definition`

string

Detailed description of what the label represents

`smEarnedDate`

string/null

Date when the address earned Smart Money status (ISO format)

`fullname`

string

Full descriptive name or entity name associated with the label

#### 

[](https://docs.nansen.ai/api/profiler/address-labels#label-categories)

Label Categories

*   `**behavioral**` - Labels based on trading patterns and on-chain behavior
    
*   `**defi**` - DeFi protocol interactions and usage
    
*   `**social**` - Social identifiers and public profiles
    
*   `**smart_money**` - Smart money and profitable trader classifications
    
*   `**others**` - Miscellaneous labels including airdrops, platform usage, etc.
    

### 

[](https://docs.nansen.ai/api/profiler/address-labels#example-request)

Example Request

json

Copy

    {
      "parameters": {
        "chain": "solana",
        "address": "H1gJR25VXi5Ape1gAU7fTWzZFWaCpuP3rzRtKun8Dwo2"
      },
      "pagination": {
        "page": 1,
        "recordsPerPage": 100
      }
    }

### 

[](https://docs.nansen.ai/api/profiler/address-labels#example-response)

Example Response

json

Copy

    [\
      {\
        "label": "hornybeliever.sol",\
        "category": "social",\
        "definition": "Shows an address owns a particular Solana Name Service domain name (ex. user.sol).",\
        "smEarnedDate": null,\
        "fullname": "🤓 👤 pow"\
      },\
      {\
        "label": "Top 100 on PENGU Leaderboard",\
        "category": "behavioral",\
        "definition": "Address is on the Top 100 Addresses by Realized PnL for the token.",\
        "smEarnedDate": null,\
        "fullname": "🤓 👤 pow"\
      },\
      {\
        "label": "30D Smart Trader",\
        "category": "smart_money",\
        "definition": "Top addresses based on their realized and unrealized profit in the last 30 days.",\
        "smEarnedDate": null,\
        "fullname": "🤓 👤 pow"\
      }\
    ]

[PreviousAddress PnL & Trade Performance](https://docs.nansen.ai/api/profiler/address-pnl-and-trade-performance)
[NextEntity Name Search](https://docs.nansen.ai/api/profiler/entity-name-search)

Last updated 2 months ago

Was this helpful?

---

# Hyperliquid APIs | Nansen API

Nansen's Hyperliquid API endpoints provide comprehensive access to perp trading data on Hyperliquid. Track positions, analyze trades, screen tokens, and follow smart money activity across the fastest-growing perps platform.

[](https://docs.nansen.ai/api/hyperliquid-apis#what-can-you-do)

What can you do?


-------------------------------------------------------------------------------------

With Hyperliquid endpoints, you can:

*   **Track wallet positions:** Monitor real-time perpetual positions, PnL, and account health
    
*   **Analyze trading activity:** View detailed trade history and execution data of any address
    
*   **Screen perp trading activity:** Find high-volume tokens and smart money flows on Hyperliquid
    
*   **Find top performers:** Discover the most profitable traders on specific tokens.
    

[](https://docs.nansen.ai/api/hyperliquid-apis#which-endpoints-can-i-use)

Which endpoints can I use?


---------------------------------------------------------------------------------------------------------

I want to...

Use this endpoint

Best for

See all open positions for a wallet including leverage, PnL, and liquidation prices

[Address Perp Positions](https://docs.nansen.ai/api/hyperliquid-apis/address-perp-positions)

Snapshot of current positions

View a wallet's trading history with entry/exit prices, fees, and PnL

[Address Perp Trades](https://docs.nansen.ai/api/hyperliquid-apis/address-perp-trades)

Trade by trade breakdown of address activity

See top profitable wallets on Hyperliquid over a given period

[Hyperliquid Leaderboard](https://docs.nansen.ai/api/hyperliquid-apis/hyperliquid-leaderboard)

Find profitable wallets and copy trading

Find high-volume perp tokens or see where smart money is trading

[Perp Screener](https://docs.nansen.ai/api/hyperliquid-apis/perp-screener)

Market discovery & trends

Find the most profitable traders on a specific perp token

[Perp PnL Leaderboard](https://docs.nansen.ai/api/hyperliquid-apis/perp-pnl-leaderboard)

Performance rankings

Track what smart money wallets are trading on Hyperliquid

[Smart Money Perp Trades](https://docs.nansen.ai/api/hyperliquid-apis/smart-money-perp-trades)

Real-time smart money

See all open positions for a specific perp token including leverage, PnL, and liquidation prices

[Token Perp Positions](https://docs.nansen.ai/api/hyperliquid-apis/token-perp-positions)

Snapshot of current positions for a token

View trading history for a specific perp token over a time period

[Token Perp Trades](https://docs.nansen.ai/api/hyperliquid-apis/token-perp-trades)

All trading activity for a specific token

[](https://docs.nansen.ai/api/hyperliquid-apis#key-differences-hyperliquid-vs.-other-chains)

Key Differences: Hyperliquid vs. Other Chains


-----------------------------------------------------------------------------------------------------------------------------------------------

#### 

[](https://docs.nansen.ai/api/hyperliquid-apis#token-identification)

Token Identification

**Important**: Hyperliquid perp endpoints use **token symbols** instead of token addresses in Token God Mode Inputs

Other Chains

Hyperliquid

`token_address: "0x1234..."`

`token_symbol: "BTC"`

Use contract addresses

Use ticker symbols (BTC, ETH, SOL, etc.)

**Example**:

Copy

    // Other chains
    {"token_address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"}
    
    // Hyperliquid
    {"token_symbol": "BTC"}  // For leaderboard endpoint

#### 

[](https://docs.nansen.ai/api/hyperliquid-apis#positive-and-negative-positions)

Positive and Negative Positions

Some endpoints (Eg. Token Perp Positions) have negative Position value. This usually represents a short and a positive value represents a long.

[](https://docs.nansen.ai/api/hyperliquid-apis#quick-start-checklist)

Quick Start Checklist


------------------------------------------------------------------------------------------------

1.  **Get your API key** from Nansen
    
2.  **Choose your use case**:
    
    *   Wallet monitoring → Use `/perp-positions` + `/perp-trades`
        
    *   Market discovery → Use `/perp-screener`
        
    *   Copy trading → Use `/perp-leaderboard` + `/tgm/perp-pnl-leaderboard`
        
    
3.  **Remember**: Use token symbols (BTC, ETH) not addresses
    
4.  **Add filters**: Refine results with volume, PnL, or time filters
    

[PreviousPoints](https://docs.nansen.ai/api/points)
[NextAddress Perp Positions](https://docs.nansen.ai/api/hyperliquid-apis/address-perp-positions)

Last updated 17 days ago

Was this helpful?

---

# Hyperliquid Address Leaderboard | Nansen API

### 

[](https://docs.nansen.ai/api/profiler/hyperliquid-address-leaderboard#post-api-v1-perp-leaderboard)

Get Perpetual Trading Leaderboard Data

post

https://api.nansen.ai/api/v1/perp-leaderboard

Get perpetual trading leaderboard data showing the most profitable traders within a given date range. This endpoint provides trader performance metrics including total PnL, ROI, and account values.

**What it helps to answer:**

1.  **Who are the most profitable perpetual traders in a given timeframe?**
    
2.  **What are the ROI percentages for top performing traders?**
    
3.  **What are the account values of successful perpetual traders?**
    
4.  **How do trader addresses and labels correlate with performance?**
    

**Key Features:**

*   Trader address and label information
    
*   Total PnL tracking in USD
    
*   ROI calculations as percentages
    
*   Account value tracking
    
*   Flexible filtering and sorting options
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for Perp Leaderboard endpoint. This endpoint provides a perpetual trading leaderboard showing the most profitable traders within a given date range.

dateobject · DateOnlyRangeRequired

Date range object with optional from and to fields in YYYY-MM-DD format

Example: `{"from":"2025-10-14","to":"2025-10-15"}`

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"account_value":{"min":10000},"total_pnl":{"min":1000}}`

object · PerpLeaderboardFiltersOptional

Filters for Perp Leaderboard endpoint.

These filters control which traders are included in the leaderboard.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering

object · SortOrder\[PerpLeaderboardSortField\]\[\]Optional

Show properties

Responses

200

Perpetual trading leaderboard data

application/json

Responseobject · PerpLeaderboardResponse

Response model for Perp Leaderboard endpoint. Contains a list of leaderboard records with pagination and metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/perp-leaderboard

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/perp-leaderboard HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 206
    
    {
      "date": {
        "from": "2025-10-14",
        "to": "2025-10-15"
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "account_value": {
          "min": 10000
        },
        "total_pnl": {
          "min": 1000
        }
      },
      "order_by": [\
        {\
          "field": "total_pnl",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

Perpetual trading leaderboard data

Copy

    {
      "data": [\
        {\
          "trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",\
          "trader_address_label": "🏦 Binance 14 [0x28c6c0]",\
          "total_pnl": 1250.5,\
          "roi": 15.5,\
          "account_value": 10000\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousAddress Perp Trades](https://docs.nansen.ai/api/profiler/address-perp-trades)
[NextToken God Mode](https://docs.nansen.ai/api/token-god-mode)

Last updated 26 days ago

Was this helpful?

---

# Connecting to Nansen MCP | Nansen API

The Nansen MCP server provides AI assistants with access to comprehensive blockchain analytics through a secure API. This guide covers how to connect to Nansen MCP.

### 

[](https://docs.nansen.ai/nansen-mcp/overview/connecting-to-nansen-mcp#prerequisites)

Prerequisites

Before connecting, you'll need:

1.  **Nansen API Key**: Get yours at [https://app.nansen.ai/api?tab=api](https://app.nansen.ai/api?tab=api)
    
2.  **npx**: Required for remote connections (`npm install -g npx`)
    

### 

[](https://docs.nansen.ai/nansen-mcp/overview/connecting-to-nansen-mcp#installation-guide)

Installation Guide

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/connecting-to-nansen-mcp#id-1.-claude-desktop-one-click-install-claude-desktop-required)

1\. Claude Desktop (One-Click Install; Claude Desktop Required)

The easiest way to get started with Nansen MCP. Double-click the downloaded .dxt file to configure automatically.

[**Quick Install Link**](https://github.com/nansen-ai/nansen-mcp-dxt/raw/refs/heads/main/nansen.dxt)

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/connecting-to-nansen-mcp#id-2.-claude-code-terminal-integration)

2\. Claude Code (Terminal Integration)

Connect Nansen MCP through your terminal:

Copy

    claude mcp add --transport http nansen https://mcp.nansen.ai/ra/mcp --header "NANSEN-API-KEY: YOUR_API_KEY_HERE"

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/connecting-to-nansen-mcp#id-3.-cursor-ide)

3\. Cursor IDE

**One-click install via Cursor deep link:**

1.  Copy the deep link below (right-click > copy)
    
2.  Paste into any Cursor text/chat field
    
3.  Ctrl+Click (or Cmd+Click on Mac) inside Cursor to install
    

Copy

    cursor://anysphere.cursor-deeplink/mcp/install?name=nansen-mcp&config=eyJlbnYiOnsiTkFOU0VOX0FQSV9LRVkiOiJSRVBMQUNFX1RISVMifSwiY29tbWFuZCI6Im5weCIsImFyZ3MiOlsiLXkiLCJtY3AtcmVtb3RlIiwiaHR0cHM6Ly9tY3AubmFuc2VuLmFpL3JhL21jcC8iLCItLWhlYWRlciIsIk5BTlNFTi1BUEktS0VZOiR7TkFOU0VOX0FQSV9LRVl9IiwiLS1hbGxvdy1odHRwIl19Cg==

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/connecting-to-nansen-mcp#id-4.-other-mcp-clients)

4\. Other MCP Clients

Integration example for various other tools supporting MCPs

**Server configuration:**

*   Server: `https://mcp.nansen.ai/ra/mcp`
    
*   Header: `NANSEN-API-KEY: your_api_key`
    
*   Transport: `mcp-remote --allow-http`
    

Copy

    {
      "mcpServers": {
        "nansen-mcp": {
          "command": "npx",
          "args": [\
            "-y",\
            "mcp-remote",\
            "https://mcp.nansen.ai/ra/mcp",\
            "--header",\
            "NANSEN-API-KEY: ",\
            "--allow-http"\
          ]
        }
      }
    }

**NPX example:**

Copy

    npx -y mcp-remote https://mcp.nansen.ai/ra/mcp \\
      --header "NANSEN-API-KEY:YOUR_API_KEY_HERE" \\
      --allow-http
    

### 

[](https://docs.nansen.ai/nansen-mcp/overview/connecting-to-nansen-mcp#authentication)

Authentication

⚠️ Nansen MCP uses the same API as your regular API keys. Ensure you have sufficient credits for your usage.

[PreviousOverview](https://docs.nansen.ai/nansen-mcp/overview)
[NextTools supported by Nansen MCP](https://docs.nansen.ai/nansen-mcp/overview/tools-supported-by-nansen-mcp)

Last updated 25 days ago

Was this helpful?

---

# Perp Trades | Nansen API

### 

[](https://docs.nansen.ai/api/token-god-mode/perp-trades#post-api-v1-tgm-perp-trades)

Get TGM Perp Trades Data

post

https://api.nansen.ai/api/v1/tgm/perp-trades

Retrieve perpetual trade data for a specific token on Hyperliquid. Shows individual trades with detailed information including trader address, trade side (Long/Short), action type (Add/Reduce/Open/Close), order type (Market/Limit), and trade metrics.

**Key Features:**

*   Hyperliquid perpetual contracts only
    
*   Smart money filtering capabilities
    
*   Detailed trade breakdown with parsed action fields
    
*   Support for both Long and Short position trading
    
*   Market and Limit order types
    

**Request Parameters:**

*   `token_symbol`: Token symbol to fetch trades for (e.g., "BTC", "ETH")
    
*   `date`: Date range for the trades
    
*   `filters`: Additional filters for side, action, order\_type, etc.
    
*   `pagination`: Page and per\_page parameters
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for TGM perp trades endpoint.

This endpoint provides perp trades data for a specific token.

token\_symbolstringRequired

Token symbol

Example: `BTC`

dateobject · DateRangeRequired

ISO 8601 date range object with optional from and to fields

Example: `{"from":"2025-07-07","to":"2025-07-14"}`

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"order_type":["MARKET"],"side":["Long"]}`

object · TGMPerpTradesFiltersOptional

Filters for TGM perp trades endpoint.

These filters control which perp trades are included in the results.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "block\_timestamp", "direction": "DESC"}\] - Sort by timestamp descending
*   \[{"field": "value\_usd", "direction": "DESC"}\] - Sort by trade value descending

object · SortOrder\[TGMPerpTradesSortField\]\[\]Optional

Show properties

Responses

200

TGM perp trades data

application/json

Responseobject · TGMPerpTradesResponse

Response model for TGM perp trades endpoint.

Contains a list of perp trade records with pagination and metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/perp-trades

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/tgm/perp-trades HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 218
    
    {
      "token_symbol": "BTC",
      "date": {
        "from": "2025-07-07",
        "to": "2025-07-14"
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "order_type": [\
          "MARKET"\
        ],
        "side": [\
          "Long"\
        ]
      },
      "order_by": [\
        {\
          "field": "block_timestamp",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

TGM perp trades data

Copy

    {
      "data": [\
        {\
          "trader_address_label": "Smart Money",\
          "trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",\
          "token_symbol": "BTC",\
          "side": "Long",\
          "action": "Add",\
          "token_amount": 1.5,\
          "price_usd": 60000,\
          "value_usd": 90000,\
          "type": "MARKET",\
          "block_timestamp": "2025-10-01T12:40:00Z",\
          "transaction_hash": "0x61adb6da30853c5988f0204dd9f6e4abbc878e02c34030a4f707cf4ec3124bcb"\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousPerp Positions](https://docs.nansen.ai/api/token-god-mode/perp-positions)
[NextPortfolio](https://docs.nansen.ai/api/portfolio)

Last updated 17 days ago

Was this helpful?

---

# PnL Leaderboard | Nansen API

### 

[](https://docs.nansen.ai/api/token-god-mode/pnl-leaderboard#post-api-v1-tgm-pnl-leaderboard)

Get TGM PnL Leaderboard Data

post

https://api.nansen.ai/api/v1/tgm/pnl-leaderboard

Rank traders by their profit/loss performance for a specific token. Shows both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages and trading patterns. This endpoint can be used to analyze the realized and unrealized profit for each trader who traded the input token.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for TGM PnL leaderboard endpoint. This endpoint provides a token PnL leaderboard showing the most profitable traders for a specific token within a given date range.

chainstring · enumRequired

Blockchain chain

Example: `ethereum`Possible values: `arbitrum``avalanche``base``bnb``ethereum``hyperevm``iotaevm``linea``mantle``monad``optimism``plasma``polygon``ronin``scroll``sei``solana``sonic``starknet``ton``tron``unichain``zksync`

token\_addressstringRequired

Token address

Example: `0x6982508145454ce325ddbe47a25d4ec3d2311933`

dateobject · DateRangeRequired

ISO 8601 date range object with optional from and to fields

Example: `{"from":"2025-07-14","to":"2025-07-15"}`

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"holding_usd":{"min":1000},"pnl_usd_realised":{"min":1000}}`

object · TGMPnlLeaderboardFiltersOptional

Filters for TGM PnL leaderboard endpoint.

These filters control which traders are included in the leaderboard.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering

object · SortOrder\[TGMPnlLeaderboardSortField\]\[\]Optional

Show properties

Responses

200

TGM PnL leaderboard data

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/pnl-leaderboard

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/tgm/pnl-leaderboard HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 297
    
    {
      "chain": "ethereum",
      "token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
      "date": {
        "from": "2025-07-14",
        "to": "2025-07-15"
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "holding_usd": {
          "min": 1000
        },
        "pnl_usd_realised": {
          "min": 1000
        }
      },
      "order_by": [\
        {\
          "field": "pnl_usd_realised",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

TGM PnL leaderboard data

Copy

    {
      "data": [\
        {\
          "trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",\
          "trader_address_label": "🏦 Binance 14 [0x28c6c0]",\
          "price_usd": 1.23,\
          "pnl_usd_realised": 1250.5,\
          "pnl_usd_unrealised": 100.25,\
          "holding_amount": 5000,\
          "holding_usd": 6000,\
          "max_balance_held": 10000,\
          "max_balance_held_usd": 12000,\
          "still_holding_balance_ratio": 0.5,\
          "netflow_amount_usd": 2500.75,\
          "netflow_amount": 1500,\
          "roi_percent_total": 15.5,\
          "roi_percent_realised": 12.3,\
          "roi_percent_unrealised": 3.2,\
          "pnl_usd_total": 1350.75,\
          "nof_trades": 25\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousJupiter DCAs](https://docs.nansen.ai/api/token-god-mode/jupiter-dcas)
[NextPerp Screener](https://docs.nansen.ai/api/token-god-mode/perp-screener)

Last updated 2 months ago

Was this helpful?

---

# Common MCP clients | Nansen API

Below are some popular MCP clients for running remote Nansen MCP servers:

*   Claude
    
*   Cursor
    
*   VS Code
    
*   N8N
    

[PreviousTools supported by Nansen MCP](https://docs.nansen.ai/nansen-mcp/overview/tools-supported-by-nansen-mcp)
[NextMCP Data Redistribution Guidelines](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines)

Was this helpful?

---

# Token Information | Nansen API

### 

[](https://docs.nansen.ai/api/token-god-mode/token-information#post-api-v1-tgm-token-information)

Get TGM Token Information Data

post

https://api.nansen.ai/api/v1/tgm/token-information

Get comprehensive token information including basic details (name, symbol, contract address, logo), token details (deployment date, social links, market metrics like market cap and FDV), and spot trading metrics (volume, buys/sells, unique traders, liquidity, holders).

This endpoint provides a complete overview of a token's metadata, market position, and trading activity for a specific date range.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for TGM token information endpoint. This endpoint provides comprehensive token information including basic details, token details (deployment, social links, market metrics), and spot trading metrics.

chainstring · enumRequired

Blockchain chain

Example: `ethereum`Possible values: `arbitrum``avalanche``base``bnb``ethereum``hyperevm``iotaevm``linea``mantle``monad``optimism``plasma``polygon``ronin``scroll``sei``solana``sonic``starknet``ton``tron``unichain``zksync`

token\_addressstringRequired

Token address

Example: `0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9`

timeframestring · enumRequired

Timeframe for the token information query

Example: `1d`Possible values: `5m``1h``6h``12h``1d``7d`

Responses

200

TGM token information data

application/json

Responseobject · TGMTokenInformationResponse

Response model for TGM token information endpoint. Contains comprehensive token information including basic details, token details, and spot metrics.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/token-information

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/tgm/token-information HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 98
    
    {
      "chain": "ethereum",
      "token_address": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
      "timeframe": "1d"
    }

Test it

200

TGM token information data

Copy

    {
      "data": {
        "name": "Aave",
        "symbol": "AAVE",
        "contract_address": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
        "logo": "https://assets.coingecko.com/coins/images/12645/large/AAVE.png",
        "token_details": {
          "token_deployment_date": "2020-11-05T00:00:00Z",
          "website": "https://aave.com",
          "x": "https://x.com/aave",
          "telegram": "https://t.me/Aavesome",
          "market_cap_usd": 4690000000,
          "fdv_usd": 4930000000,
          "circulating_supply": 15230000,
          "total_supply": 16000000
        },
        "spot_metrics": {
          "volume_total_usd": 8850000,
          "buy_volume_usd": 4520000,
          "sell_volume_usd": 4330000,
          "total_buys": 666,
          "total_sells": 499,
          "unique_buyers": 106,
          "unique_sellers": 132,
          "liquidity_usd": 153420000,
          "total_holders": 165299
        }
      }
    }

[PreviousToken God Mode](https://docs.nansen.ai/api/token-god-mode)
[NextToken Screener](https://docs.nansen.ai/api/token-god-mode/token-screener)

Last updated 2 days ago

Was this helpful?

---

# Flows | Nansen API

### 

[](https://docs.nansen.ai/api/token-god-mode/flows#post-api-v1-tgm-flows)

Get TGM Flows Data

post

https://api.nansen.ai/api/v1/tgm/flows

Analyze aggregated token flows by holder category over time. Shows hourly snapshots of balances, inflows, and outflows for specific holder groups: smart money, public figures, whales, and exchanges.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for TGM flows endpoint.

This endpoint provides comprehensive token flow analytics showing inflow and outflow patterns from various holder segments including Exchanges, Smart Money addresses, Public Figures, and Whales with time-based statistics and trends.

chainstring · enumRequired

Blockchain chain

Example: `solana`Possible values: `arbitrum``avalanche``base``bnb``ethereum``hyperevm``iotaevm``linea``mantle``monad``optimism``plasma``polygon``ronin``scroll``sei``solana``sonic``starknet``ton``tron``unichain``zksync`

token\_addressstringRequired

Token address

Example: `2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv`

dateobject · DateRangeRequired

ISO 8601 date range object with optional from and to fields

Example: `{"from":"2025-05-01","to":"2025-05-03"}`

Show properties

labelstring · enumOptional

Label type for filtering flows

Default: `top_100_holders`Example: `smart_money`Possible values: `whale``public_figure``smart_money``top_100_holders``exchange`

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"price_usd":{"max":1000,"min":0.01},"value_usd":{"min":10000}}`

object · TGMFlowsFiltersOptional

Filters for TGM flows endpoint.

These filters control which data points are included in the flows analysis.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "date", "direction": "DESC"}\] - Sort by date descending (most recent first)
*   \[{"field": "total\_inflows\_usd", "direction": "ASC"}\] - Sort by total inflows ascending
*   \[{"field": "total\_outflows\_usd", "direction": "DESC"}\] - Sort by total outflows descending

object · SortOrder\[TGMFlowsSortField\]\[\]Optional

Show properties

Responses

200

TGM flows data

application/json

Responseobject · TGMFlowsResponse

Response model for TGM flows endpoint.

Contains a list of flow records with pagination and metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/flows

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/tgm/flows HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 310
    
    {
      "chain": "solana",
      "token_address": "2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv",
      "date": {
        "from": "2025-05-01",
        "to": "2025-05-03"
      },
      "label": "smart_money",
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "price_usd": {
          "max": 1000,
          "min": 0.01
        },
        "value_usd": {
          "min": 10000
        }
      },
      "order_by": [\
        {\
          "field": "date",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

TGM flows data

Copy

    {
      "data": [\
        {\
          "date": "text",\
          "price_usd": 1,\
          "token_amount": 1,\
          "value_usd": 1,\
          "holders_count": 1,\
          "total_inflows_count": 1,\
          "total_outflows_count": 1\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

### 

[](https://docs.nansen.ai/api/token-god-mode/flows#using-flows-endpoint)

Using /flows Endpoint

The /flows endpoint allows you to analyze historical inflows and outflows of token holdings across specific wallet labels (e.g., Smart Money, Whales, Public Figures, etc.) on supported blockchains. This enables powerful workflows to investigate token accumulation or distribution trends by high-signal wallet groups over time.

This guide walks through how to use the endpoint in a workflow to explore Smart Money behavior for a given token on a given chain.

#### 

[](https://docs.nansen.ai/api/token-god-mode/flows#usecase-1-track-smart-money-accumulation-trends)

Usecase 1: Track Smart Money Accumulation Trends

This workflow helps you:

*   Identify what tokens Smart Money is holding (e.g., via /holdings or /inflows)
    
*   Investigate how inflows/outflows of Smart Money have evolved over time
    
*   Combine historical activity with price trends for better decision-making
    

**Step by Step Guide:**

1.  Start with /holdings endpoint to identify what tokens Smart Money is holding.
    
2.  Pick a token of interest based on value and activity patterns.
    
3.  Use the /flows endpoint with the token address and smart\_money label to view inflow/outflow trends.
    
4.  Specify timeframe (e.g., last 30 days) and examine how Smart Money behavior is evolving.
    

#### 

[](https://docs.nansen.ai/api/token-god-mode/flows#usecase-2-monitor-exchange-flows)

Usecase 2: Monitor Exchange Flows

This workflow helps you:

*   Track how much of a token is being sent to or from exchange wallets
    
*   Spot accumulation or distribution trends by observing net exchange flow
    
*   Correlate token price movement with CEX behavior patterns
    

**Step by Step Guide:**

1.  Identify the token of interest (e.g., USDC, ETH, SOL).
    
2.  Choose the chain where it is active.
    
3.  Use label: "exchange" to track exchange wallets.
    
4.  Analyze net flows:
    
    *   High inflow = Possible sell pressure
        
    *   High outflow = Possible accumulation
        
    
5.  Correlate flow data with price action or events (e.g., listings, unlocks, news).
    

[PreviousHolders](https://docs.nansen.ai/api/token-god-mode/holders)
[NextWho Bought/Sold](https://docs.nansen.ai/api/token-god-mode/who-bought-sold)

Last updated 2 months ago

Was this helpful?

---

# Address Perp Positions | Nansen API

### 

[](https://docs.nansen.ai/api/profiler/address-perp-positions#post-api-v1-profiler-perp-positions)

Get Perpetual Positions Data

post

https://api.nansen.ai/api/v1/profiler/perp-positions

Get perpetual positions data for a user by calling the Hyperliquid API directly. This endpoint provides real-time position information including entry price, mark price, PnL, leverage, and other position details.

**What it helps to answer:**

1.  **What are the current perpetual positions for a specific user address?**
    
2.  **What is the unrealized PnL and performance of each position?**
    
3.  **What are the leverage levels and margin requirements for each position?**
    
4.  **What are the liquidation prices and risk levels for each position?**
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for Perp Positions endpoint.

addressstring · min: 42 · max: 42Required

User's Hyperliquid address in 42-character hexadecimal format

Example: `0xa312114b5795dff9b8db50474dd57701aa78ad1e`

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"position_value_usd":{"min":1000},"unrealized_pnl_usd":{"max":0}}`

object · PerpPositionsFiltersOptional

Filters for perp positions endpoint.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "position\_value\_usd", "direction": "DESC"}\] - Sort by position value descending
*   \[{"field": "unrealized\_pnl\_usd", "direction": "ASC"}\] - Sort by unrealized PnL ascending

If not provided, positions are sorted by position value descending.

Example: `[{"direction":"DESC","field":"position_value_usd"}]`

object · SortOrder\[PerpPositionsSortField\]\[\]Optional

Show properties

Responses

200

Perpetual positions data for the user

application/json

Responseobject · PerpPositionsResponse

Response model for perp positions endpoint.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/profiler/perp-positions

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/profiler/perp-positions HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 196
    
    {
      "address": "0xa312114b5795dff9b8db50474dd57701aa78ad1e",
      "filters": {
        "position_value_usd": {
          "min": 1000
        },
        "unrealized_pnl_usd": {
          "max": 0
        }
      },
      "order_by": [\
        {\
          "direction": "DESC",\
          "field": "position_value_usd"\
        }\
      ]
    }

Test it

200

Perpetual positions data for the user

Copy

    {
      "data": {
        "asset_positions": [\
          {\
            "position": {\
              "cumulative_funding_all_time_usd": "-623.219722",\
              "cumulative_funding_since_change_usd": "-618.925976",\
              "cumulative_funding_since_open_usd": "-623.219722",\
              "entry_price_usd": "0.43499",\
              "leverage_type": "cross",\
              "leverage_value": 3,\
              "liquidation_price_usd": "66.817537196",\
              "margin_used_usd": "1743.87343",\
              "max_leverage_value": 3,\
              "position_value_usd": "5231.62029",\
              "return_on_equity": "2.2836393396",\
              "size": "-50367.0",\
              "token_symbol": "STBL",\
              "unrealized_pnl_usd": "16677.54047"\
            },\
            "position_type": "oneWay"\
          },\
          {\
            "position": {\
              "cumulative_funding_all_time_usd": "200.361581",\
              "cumulative_funding_since_change_usd": "201.157877",\
              "cumulative_funding_since_open_usd": "200.361581",\
              "entry_price_usd": "0.311285",\
              "leverage_type": "cross",\
              "leverage_value": 5,\
              "liquidation_price_usd": "39.6872752647",\
              "margin_used_usd": "2020.946984",\
              "max_leverage_value": 5,\
              "position_value_usd": "10104.73492",\
              "return_on_equity": "3.1976362269",\
              "size": "-90052.0",\
              "token_symbol": "MOODENG",\
              "unrealized_pnl_usd": "17927.1615"\
            },\
            "position_type": "oneWay"\
          }\
        ],
        "cross_maintenance_margin_used_usd": "722948.2832910001",
        "cross_margin_summary_account_value_usd": "4643143.4382309997",
        "cross_margin_summary_total_margin_used_usd": "1456365.231985",
        "cross_margin_summary_total_net_liquidation_position_on_usd": "13339928.690684",
        "cross_margin_summary_total_raw_usd": "13987445.0243870001",
        "margin_summary_account_value_usd": "4643143.4382309997",
        "margin_summary_total_margin_used_usd": "1456365.231985",
        "margin_summary_total_net_liquidation_position_usd": "13339928.690684",
        "margin_summary_total_raw_usd": "13987445.0243870001",
        "timestamp": 1761283435707,
        "withdrawable_usd": "2933647.2403759998"
      }
    }

[PreviousEntity Name Search](https://docs.nansen.ai/api/profiler/entity-name-search)
[NextAddress Perp Trades](https://docs.nansen.ai/api/profiler/address-perp-trades)

Last updated 26 days ago

Was this helpful?

---

# Points | Nansen API

> **📈 Season 02 Updates (Updated: Oct 7, 2025)** **What's New:** The `is_eligible` field now reflects the new reward redemption requirements.

### 

[](https://docs.nansen.ai/api/points#permissionless-rewards-concepts)

Permissionless Rewards: Concepts

Before integrating the Nansen Points Leaderboard endpoint, it helps to understand **Permissionless Rewards** at a high level—see [Nansen Academy: On Permissionless Rewards](https://academy.nansen.ai/articles/2154465-on-permissionless-rewards)
 for full details.

*   **What they are**: An open registry that maps Nansen Points balances to onchain wallets (EVM and Solana), without requiring an API key or explicit permission from Nansen.
    
*   **Why it matters**: Protocols can seamlessly discover eligible wallets and distribute tokens, NFTs, or other perks—fully public and opt-in.
    
*   **Privacy model**: Only six data points are exposed (rank, EVM wallet address, Solana wallet address, tier, points balance, eligibility status); no personal data is shared.
    
*   **User control**: Holders can add or remove their wallet mapping at any time, revoking future distributions.
    

> **📈 Quick Access for Non-Technical users:** See all leaderboard data in Nansen Points Hub! 🌐 **See it here:** [**https://app.nansen.ai/points**](https://app.nansen.ai/points)

### 

[](https://docs.nansen.ai/api/points#points-leaderboard)

Points Leaderboard

`GET` [https://app.nansen.ai/api/points-leaderboard](https://app.nansen.ai/api/points-leaderboard)

Fetch a complete snapshot of eligible Nansen Points users via the public endpoint. _**No API key or authentication required.**_

#### 

[](https://docs.nansen.ai/api/points#query-parameters)

Query Parameters

Name

Type

Required

Default

Description

`tier`

string

No

―

Filter by tier name. Valid values: `green`, `ice`, `north`, `star`

`isEligible`

boolean

No

true

Filter by reward eligibility status. Valid values: `"true"` , `"false"` (ineligible users)

#### 

[](https://docs.nansen.ai/api/points#example-request)

**Example Request**

**Recommended – Browser Access:** Open these URLs directly in your browser:

*   Eligible users: [https://app.nansen.ai/api/points-leaderboard](https://app.nansen.ai/api/points-leaderboard)
    

### 

[](https://docs.nansen.ai/api/points#response)

Response

Code

Description

200

Successful response

400

Bad request (invalid parameters)

500

Internal server error

#### 

[](https://docs.nansen.ai/api/points#response-structure)

Response Structure

Copy

    [\
        {\
          "rank": 1,\
          "evm_address": "0x6E93Ebc8302890fF1D1BeFd779D1DB131eF30D4d",\
          "solana_address": "EhWT1SJXSCF6YTmUpTgH1xa8xZiGqEPSED3CWfR4cicM",\
          "points": 1138320,\
          "tier": "star",\
          "is_eligible": true\
        }\
        // … all eligible users …\
      ]
    
    

#### 

[](https://docs.nansen.ai/api/points#record-fields-within-data-array)

Record Fields (within data array):

Field

Type

Description

`rank`

integer

Position on the leaderboard.

`evm_address`

string | null

Ethereum-compatible wallet address, or `null` if none.

`solana_address`

string | null

Solana wallet address, or `null` if none.

`points`

integer

Total accumulated points.

`tier`

string

Tier name determined by points thresholds. Valid values: "green", "ice", "north", "star".

`is_eligible`

boolean

`true` if the user currently meets reward eligibility criteria.

### 

[](https://docs.nansen.ai/api/points#usage-notes)

Usage Notes

#### 

[](https://docs.nansen.ai/api/points#api-behavior)

**API Behavior:**

*   **Complete Dataset**: Returns all qualifying users in one response
    
*   **Minimum Qualification**: Only users with 1000+ points (Green tier threshold) are included
    
*   **No Server Pagination**: Single request gets full leaderboard data
    
*   **Tier Restrictions**: Users below the Green tier threshold are excluded
    
*   **Data Filtering:** Users must have at least one wallet address to appear.
    

#### 

[](https://docs.nansen.ai/api/points#guidelines)

Guidelines

*   **Browser Access**: Most reliable method - open URLs directly in any web browser
    
*   **Public & Permissionless** No authentication header or API key required
    
*   **Single Request**: Get complete leaderboard data in one API call
    
*   **Response Format:** The API returns a raw JSON array. Access the data directly via response.json() (no wrapper object).
    
*   **Rank Handling**: Users with identical `points` will share the same rank. The next distinct score will receive the immediately following rank (e.g. if two users tie for rank 5, the following user is rank 6).
    
*   **Cache-Friendly** Leaderboard data refreshes once a day (11am UTC). Implement local caching to reduce redundant calls.
    

[PreviousPortfolio](https://docs.nansen.ai/api/portfolio)
[NextHyperliquid APIs](https://docs.nansen.ai/api/hyperliquid-apis)

Last updated 1 month ago

Was this helpful?

---

# Address Transactions | Nansen API

### 

[](https://docs.nansen.ai/api/profiler/address-transactions#post-api-v1-profiler-address-transactions)

Get Address Transactions Data

post

https://api.nansen.ai/api/v1/profiler/address/transactions

Retrieve recent blockchain transactions for an address including token transfers, native currency movements, and contract interactions.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

addressstringRequired

Address to get transactions for

Example: `0x28c6c06298d514db089934071355e5743bf21d60`

chainstring · enumRequired

Blockchain chain for the transactions

Example: `ethereum`Possible values: `arbitrum``avalanche``base``bitcoin``bnb``ethereum``iotaevm``linea``mantle``monad``optimism``plasma``polygon``ronin``scroll``sei``solana``sonic``starknet``ton``tron``unichain``zksync`

dateobject · DateRangeRequired

Date range for the transactions

Example: `{"from":"2025-08-01T00:00:00Z","to":"2025-08-10T23:59:59Z"}`

Show properties

hide\_spam\_tokenbooleanOptional

Removes suspicious tokens from the transaction list

Default: `true`Example: `true`

filtersany ofOptional

Additional filters to apply. Only filters for columns that are being selected will be applied.

Example: `{"volume_usd":{"min":100}}`

object · ProfilerAddressTransactionsFiltersOptional

Filters for profiler address transactions endpoint.

These filters control which transactions are included in the wallet transaction history.

Show properties

paginationobject · ProfilerPaginationRequestOptional

Pagination parameters (max 100 records per page for performance)

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering

object · SortOrder\[ProfilerAddressTransactionsSortField\]\[\]Optional

Show properties

Responses

200

Address transaction data

application/json

Responseobject · ProfilerAddressTransactionsResponse

Response model for profiler address transactions endpoint.

Contains the filtered transaction data with metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/profiler/address/transactions

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/profiler/address/transactions HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 299
    
    {
      "address": "0x28c6c06298d514db089934071355e5743bf21d60",
      "chain": "ethereum",
      "date": {
        "from": "2025-08-01T00:00:00Z",
        "to": "2025-08-10T23:59:59Z"
      },
      "hide_spam_token": true,
      "filters": {
        "volume_usd": {
          "min": 100
        }
      },
      "pagination": {
        "page": 1,
        "per_page": 20
      },
      "order_by": [\
        {\
          "field": "block_timestamp",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

Address transaction data

Copy

    {
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      },
      "data": [\
        {\
          "chain": "text",\
          "method": "text",\
          "tokens_sent": [\
            {\
              "token_symbol": "text",\
              "token_amount": 1,\
              "price_usd": 1,\
              "value_usd": 1,\
              "token_address": "text",\
              "chain": "text",\
              "from_address": "text",\
              "to_address": "text",\
              "from_address_label": "text",\
              "to_address_label": "text"\
            }\
          ],\
          "tokens_received": [\
            {\
              "token_symbol": "text",\
              "token_amount": 1,\
              "price_usd": 1,\
              "value_usd": 1,\
              "token_address": "text",\
              "chain": "text",\
              "from_address": "text",\
              "to_address": "text",\
              "from_address_label": "text",\
              "to_address_label": "text"\
            }\
          ],\
          "volume_usd": 1,\
          "block_timestamp": "text",\
          "transaction_hash": "text",\
          "source_type": "text"\
        }\
      ]
    }

### 

[](https://docs.nansen.ai/api/profiler/address-transactions#post-api-v1-transaction-with-token-transfer-lookup)

Get Transaction with Token Transfer Lookup Data

post

https://api.nansen.ai/api/v1/transaction-with-token-transfer-lookup

Get comprehensive transaction information including token transfers and NFT transfers. This endpoint provides detailed information about a specific transaction including native cryptocurrency movements, token transfers, and NFT transfers with USD values.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

chainstring · enumRequired

Blockchain chain for the transaction lookup

Example: `ethereum`Possible values: `arbitrum``avalanche``base``bitcoin``bnb``ethereum``hyperevm``iotaevm``linea``mantle``monad``optimism``plasma``ronin``scroll``sei``sonic``starknet``ton``tron``unichain``zksync`

transaction\_hashstringRequired

Transaction hash to lookup

Example: `0xf16f93cb53f4f977d45b1b08af7b66e1939d0fe69d669012458239b23797e492`

block\_timestampstringRequired

Timestamp of the transaction

Example: `2025-08-06 01:47:11`

Responses

200

Transaction lookup data with token and NFT transfer information

application/json

Responseobject · TransactionLookupListResponse

Response model for transaction lookup endpoint returning a list of transactions.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/transaction-with-token-transfer-lookup

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/transaction-with-token-transfer-lookup HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 148
    
    {
      "chain": "ethereum",
      "transaction_hash": "0xf16f93cb53f4f977d45b1b08af7b66e1939d0fe69d669012458239b23797e492",
      "block_timestamp": "2025-08-06 01:47:11"
    }

Test it

200

Transaction lookup data with token and NFT transfer information

Copy

    {
      "data": [\
        {\
          "chain": "text",\
          "transaction_hash": "text",\
          "from_address": "text",\
          "from_address_label": "text",\
          "to_address": "text",\
          "to_address_label": "text",\
          "native_value": 1,\
          "dated_native_price": 1,\
          "dated_native_value_usd": 1,\
          "current_native_price": 1,\
          "current_native_value_usd": 1,\
          "receipt_status": 1,\
          "block_timestamp": "text",\
          "token_transfer_array": [\
            {\
              "from_address": "text",\
              "from_address_label": "text",\
              "to_address": "text",\
              "to_address_label": "text",\
              "token_address": "text",\
              "token_symbol": "text",\
              "token_amount": 1,\
              "dated_price_usd": 1,\
              "dated_value_usd": 1,\
              "current_price_usd": 1,\
              "current_value_usd": 1,\
              "transfer_id": "text"\
            }\
          ],\
          "nft_transfer_array": [\
            {\
              "from_address": "text",\
              "from_address_label": "text",\
              "to_address": "text",\
              "to_address_label": "text",\
              "project_id": "text",\
              "collection_name": "text",\
              "nft_id": "text"\
            }\
          ]\
        }\
      ]
    }

[PreviousAddress Historical Balances](https://docs.nansen.ai/api/profiler/address-historical-balances)
[NextAddress Counterparties](https://docs.nansen.ai/api/profiler/address-counterparties)

Last updated 2 months ago

Was this helpful?

---

# Overview | Nansen API

Connect your AI tools (Eg. Claude, Cursor) using Anthropic's Model Context Protocol, a standard that lets AI tools interact with Nansen data.

### 

[](https://docs.nansen.ai/nansen-mcp/overview#what-is-nansen-mcp)

What is Nansen MCP?

**Nansen MCP** is a Model Context Protocol (MCP) server that provides access to Nansen's institutional-grade blockchain intelligence platform. It transforms Nansen's onchain intelligence into an accessible interface that AI agents, developers, and researchers can use to analyze crypto markets and blockchain activity.

#### 

[](https://docs.nansen.ai/nansen-mcp/overview#core-offering)

Core Offering

*   **MCP Protocol**: Built on the standardized Model Context Protocol, ensuring compatibility with AI tools like Claude, Cursor, and other MCP-compatible clients
    
*   **Multi-Chain Coverage**: Supports 25+ major blockchains including Ethereum, Solana, Bitcoin, Arbitrum, Base, Polygon, and more
    
*   **Real-Time Data**: Provides access to live blockchain data including transactions, token movements, wallet activities, dex trades and PnL
    

### 

[](https://docs.nansen.ai/nansen-mcp/overview#undefined)

### 

[](https://docs.nansen.ai/nansen-mcp/overview#why-use-nansen-mcp)

Why Use Nansen MCP?

AI tools currently have no visibility into what's happening onchain. Even answering simple blockchain queries is extremely difficult without proper data access and context. Nansen MCP gives AI tools the ability to see and understand onchain activities, transforming them into powerful blockchain research assistants.

#### 

[](https://docs.nansen.ai/nansen-mcp/overview#id-1.-real-time-access-to-nansens-rich-data)

**1\. Real-Time Access to Nansen's Rich Data**

*   Access to Nansen's proprietary wallet labeling system with millions of identified addresses including smart money labels
    
*   Institutional-grade data accuracy and reliability
    
*   Real-time processing of onchain activities across multiple blockchains
    

#### 

[](https://docs.nansen.ai/nansen-mcp/overview#id-2.-ai-native-integration)

**2\. AI-Native Integration**

*   One-click installation with Claude Desktop
    
*   No need to struggle with complex APIs or documentation - everything works out of the box
    
*   Build custom AI agents and LLMs with blockchain intelligence
    

#### 

[](https://docs.nansen.ai/nansen-mcp/overview#id-3.-streamlined-research-workflows)

**3\. Streamlined Research Workflows**

*   Saves time by wrapping complex workflows into simpler tasks
    
*   Automate onchain research that would take hours manually
    
*   Generate insights from multiple data sources simultaneously
    

### 

[](https://docs.nansen.ai/nansen-mcp/overview#what-can-you-do-with-nansen-mcp)

What Can You Do with Nansen MCP?

#### 

[](https://docs.nansen.ai/nansen-mcp/overview#smart-money-tracking)

**Smart Money Tracking**

Track DEX trades, token holdings, and portfolio changes of profitable traders and funds. Discover tokens gaining traction among smart money before broader market adoption.

#### 

[](https://docs.nansen.ai/nansen-mcp/overview#token-intelligence-and-discovery)

**Token Intelligence & Discovery**

Screen thousands of tokens across multiple chains using advanced filters. Analyze real-time trading data, holder distributions, and exchange flows to identify opportunities.

#### 

[](https://docs.nansen.ai/nansen-mcp/overview#address-and-entity-profiling)

**Address & Entity Profiling**

Deep dive into wallet activities, trading patterns, and PnL analysis. Map relationships between wallets and identify connected addresses across all supported blockchains.

#### 

[](https://docs.nansen.ai/nansen-mcp/overview#example-prompts)

**Example Prompts**

*   "Show me all tokens that funds bought in the last 24 hours"
    
*   "What DCA strategies are profitable traders using on Jupiter?"
    
*   "Find new tokens with high smart money inflows and growing trading volume"
    
*   "Show me trending tokens with liquidity above $100k"
    
*   "Analyze the trading performance of this whale address"
    
*   "Find wallets connected to this successful trader"
    
*   "Track how this fund's portfolio allocation has changed over time"
    
*   "Do a deep dive into this wallet to find whom does it belong to"
    

[PreviousToken Perp Trades](https://docs.nansen.ai/api/hyperliquid-apis/token-perp-trades)
[NextConnecting to Nansen MCP](https://docs.nansen.ai/nansen-mcp/overview/connecting-to-nansen-mcp)

Was this helpful?

---

# Perp PnL Leaderboard | Nansen API

### 

[](https://docs.nansen.ai/api/hyperliquid-apis/perp-pnl-leaderboard#common-scenarios)

Common Scenarios

Usecase

Required Parameters

Optional Filters

Expected Output

Filter for high-profit and high-balance addresses

token\_symbol ="ETH" date ={ "from": "2025-10-14", "to": "2025-10-15" }

filters ={ "pnl\_usd\_realised": { "min": 100000 }, "position\_value\_usd": { "min": 100000 } }

Only addresses with at least $100k realized PnL and $100k+ in position value are shown

Surface only smart money traders for a specific contract

token\_symbol ="SOL" date ={ "from": "2025-10-14", "to": "2025-10-15" }

filters ={ "trader\_address\_label": "Smart Money" }

Leaderboard limited to traders labeled as Smart Money

### 

[](https://docs.nansen.ai/api/hyperliquid-apis/perp-pnl-leaderboard#post-api-v1-tgm-perp-pnl-leaderboard)

Get TGM Perp PnL Leaderboard Data

post

https://api.nansen.ai/api/v1/tgm/perp-pnl-leaderboard

Rank traders by their profit/loss performance for a specific perpetual contract on Hyperliquid. Shows both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages and trading patterns. This endpoint can be used to analyze the realized and unrealized profit for each trader who traded the input perpetual contract.

**Key Features:**

*   Hyperliquid perpetual contracts only (no chain field needed)
    
*   Realized and unrealized PnL tracking
    
*   ROI calculations and trading patterns
    
*   Position size and balance tracking
    

**Request Format:**

*   `token_symbol`: Perpetual contract symbol (e.g., "BTC", "ETH", "SOL")
    
*   `date`: Date range for analysis
    
*   `filters`: Optional filters for trader addresses, PnL ranges, etc.
    
*   `pagination`: Page and per\_page parameters
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for TGM Perp PnL leaderboard endpoint. Simplified version that only supports Hyperliquid perpetual contracts.

token\_symbolstringRequired

Perpetual contract symbol (e.g., BTC, ETH, SOL)

Example: `BTC`

dateobject · DateRangeRequired

ISO 8601 date range object with optional from and to fields

Example: `{"from":"2025-10-14","to":"2025-10-15"}`

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"pnl_usd_realised":{"min":1000},"position_value_usd":{"min":1000}}`

object · TGMPerpPnlLeaderboardFiltersOptional

Filters for TGM Perp PnL leaderboard endpoint.

These filters control which traders are included in the leaderboard.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering

object · SortOrder\[TGMPerpPnlLeaderboardSortField\]\[\]Optional

Show properties

Responses

200

TGM Perp PnL leaderboard data

application/json

Responseobject · TGMPerpPnlLeaderboardResponse

Response model for TGM Perp PnL leaderboard endpoint. Contains a list of PnL leaderboard records with pagination and metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/perp-pnl-leaderboard

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/tgm/perp-pnl-leaderboard HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 245
    
    {
      "token_symbol": "BTC",
      "date": {
        "from": "2025-10-14",
        "to": "2025-10-15"
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "pnl_usd_realised": {
          "min": 1000
        },
        "position_value_usd": {
          "min": 1000
        }
      },
      "order_by": [\
        {\
          "field": "pnl_usd_realised",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

TGM Perp PnL leaderboard data

Copy

    {
      "data": [\
        {\
          "trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",\
          "trader_address_label": "🏦 Binance 14 [0x28c6c0]",\
          "price_usd": 1.23,\
          "pnl_usd_realised": 1250.5,\
          "pnl_usd_unrealised": 100.25,\
          "holding_amount": 5000,\
          "position_value_usd": 6000,\
          "max_balance_held": 10000,\
          "max_balance_held_usd": 12000,\
          "still_holding_balance_ratio": 0.5,\
          "netflow_amount_usd": 2500.75,\
          "netflow_amount": 1500,\
          "roi_percent_total": 15.5,\
          "roi_percent_realised": 12.3,\
          "roi_percent_unrealised": 3.2,\
          "pnl_usd_total": 1350.75,\
          "nof_trades": 25\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousPerp Screener](https://docs.nansen.ai/api/hyperliquid-apis/perp-screener)
[NextSmart Money Perp Trades](https://docs.nansen.ai/api/hyperliquid-apis/smart-money-perp-trades)

Last updated 23 days ago

Was this helpful?

---

# DEX Trades | Nansen API

### 

[](https://docs.nansen.ai/api/token-god-mode/dex-trades#post-api-v1-tgm-dex-trades)

Get TGM DEX Trades Data

post

https://api.nansen.ai/api/v1/tgm/dex-trades

Access individual DEX trading transactions for a specific token. Shows detailed trade-by-trade data including trader labels, amounts, and prices.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for TGM dex-trades endpoint.

This endpoint provides all DEX trades for a specific token with optional filtering for smart money wallets only.

chainstring · enumRequired

Blockchain chain

Example: `solana`Possible values: `arbitrum``avalanche``base``bnb``ethereum``hyperevm``iotaevm``linea``mantle``monad``optimism``plasma``polygon``ronin``scroll``sei``solana``sonic``starknet``ton``tron``unichain``zksync`

token\_addressstringRequired

Token address

Example: `2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv`

only\_smart\_moneybooleanOptional

Returns only the DEX Trades made by Smart Money wallets

Default: `false`

dateobject · DateRangeRequired

ISO 8601 date range object with optional from and to fields

Example: `{"from":"2025-07-07","to":"2025-07-14"}`

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"action":"BUY","estimated_value_usd":{"min":1000},"include_smart_money_labels":["Whale","Smart Trader"],"token_amount":{"min":100}}`

object · TGMDexTradesFiltersOptional

Filters for TGM DEX trades endpoint.

These filters control which DEX trades are included in the analysis.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "block\_timestamp", "direction": "DESC"}\] - Sort by timestamp descending
*   \[{"field": "estimated\_value\_usd", "direction": "ASC"}\] - Sort by estimated value ascending
*   \[{"field": "token\_amount", "direction": "DESC"}\] - Sort by token amount descending

object · SortOrder\[TGMDexTradesSortField\]\[\]Optional

Show properties

Responses

200

TGM DEX trades data

application/json

Responseobject · TGMDexTradesResponse

Response model for TGM dex-trades endpoint.

Contains a list of DEX trade records with pagination and metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/dex-trades

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/tgm/dex-trades HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 393
    
    {
      "chain": "solana",
      "token_address": "2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv",
      "only_smart_money": false,
      "date": {
        "from": "2025-07-07",
        "to": "2025-07-14"
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "action": "BUY",
        "estimated_value_usd": {
          "min": 1000
        },
        "include_smart_money_labels": [\
          "Whale",\
          "Smart Trader"\
        ],
        "token_amount": {
          "min": 100
        }
      },
      "order_by": [\
        {\
          "field": "block_timestamp",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

TGM DEX trades data

Copy

    {
      "data": [\
        {\
          "block_timestamp": "2025-05-01T12:00:00Z",\
          "transaction_hash": "0x61adb6da30853c5988f0204dd9f6e4abbc878e02c34030a4f707cf4ec3124bcb",\
          "trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",\
          "trader_address_label": "High Gas Consumer",\
          "action": "BUY",\
          "token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",\
          "token_name": "USDC",\
          "token_amount": 1000,\
          "traded_token_address": "0x6b175474e89094c44da98b954eedeac495271d0f",\
          "traded_token_name": "DAI",\
          "traded_token_amount": 500,\
          "estimated_swap_price_usd": 1,\
          "estimated_value_usd": 1500.5\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousWho Bought/Sold](https://docs.nansen.ai/api/token-god-mode/who-bought-sold)
[NextToken Transfers](https://docs.nansen.ai/api/token-god-mode/token-transfers)

Last updated 2 months ago

Was this helpful?

---

# Token Transfers | Nansen API

### 

[](https://docs.nansen.ai/api/token-god-mode/token-transfers#post-api-v1-tgm-transfers)

Get TGM Transfers Data

post

https://api.nansen.ai/api/v1/tgm/transfers

Track all token transfer activity including direct transfers, DEX trades, and CEX movements. This endpoint is particularly useful for monitoring exchange flows - both centralized (CEX) and decentralized (DEX) - to identify accumulation or distribution patterns.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for TGM transfers endpoint.

This endpoint provides top token transfers for a specific token, with support for both native tokens (ETH, SOL, etc.) and ERC-20 tokens. The model selection is dynamic based on the token address.

chainstring · enumRequired

Blockchain chain

Example: `ethereum`Possible values: `arbitrum``avalanche``base``bnb``ethereum``hyperevm``iotaevm``linea``mantle``monad``optimism``plasma``polygon``ronin``scroll``sei``solana``sonic``starknet``ton``tron``unichain``zksync`

token\_addressstringRequired

Token address (supports both native and ERC-20 tokens)

Example: `0x6982508145454ce325ddbe47a25d4ec3d2311933`

dateobject · DateRangeRequired

ISO 8601 date range object with from and to fields. Restriction: The date range must be at most 1 year.

Example: `{"from":"2025-05-01","to":"2025-05-03"}`

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"include_cex":true,"include_dex":true,"non_exchange_transfers":true,"only_smart_money":true}`

object · TGMTransfersFiltersOptional

Filters for TGM transfers endpoint.

These filters control which transfers are included in the analysis.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "transfer\_value\_usd", "direction": "ASC"}\] - Sort by transfer value ascending
*   \[{"field": "transfer\_amount", "direction": "DESC"}\] - Sort by transfer amount descending

object · SortOrder\[TGMTransfersSortField\]\[\]Optional

Show properties

Responses

200

TGM transfers data

application/json

Responseobject · TGMTransfersResponse

Response model for TGM transfers endpoint.

Contains a list of transfer records with pagination and metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/transfers

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/tgm/transfers HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 329
    
    {
      "chain": "ethereum",
      "token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
      "date": {
        "from": "2025-05-01",
        "to": "2025-05-03"
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "include_cex": true,
        "include_dex": true,
        "non_exchange_transfers": true,
        "only_smart_money": true
      },
      "order_by": [\
        {\
          "field": "block_timestamp",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

TGM transfers data

Copy

    {
      "data": [\
        {\
          "block_timestamp": "2025-05-01T12:00:00Z",\
          "transaction_hash": "0x1234567890abcdef...",\
          "from_address": "0x28c6c06298d514db089934071355e5743bf21d60",\
          "to_address": "0x742d35cc6634c0532925a3b8d4c9db96c4b4d8b6",\
          "from_address_label": "🏦 Binance 14 [0x28c6c0]",\
          "to_address_label": "High Balance",\
          "transaction_type": "DEX",\
          "transfer_amount": 1000,\
          "transfer_value_usd": 2500\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousDEX Trades](https://docs.nansen.ai/api/token-god-mode/dex-trades)
[NextJupiter DCAs](https://docs.nansen.ai/api/token-god-mode/jupiter-dcas)

Last updated 2 months ago

Was this helpful?

---

# Who Bought/Sold | Nansen API

### 

[](https://docs.nansen.ai/api/token-god-mode/who-bought-sold#post-api-v1-tgm-who-bought-sold)

Get TGM Who Bought/Sold Data

post

https://api.nansen.ai/api/v1/tgm/who-bought-sold

This endpoint provides an aggregated summary of trade volumes in USD for addresses. It can be used to identify addresses that are net buyers or sellers of a token within a time period.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for TGM who bought/sold endpoint.

This endpoint provides an aggregated summary of trade volumes in USD for addresses involved in DEX (Decentralized Exchange) trades for a specific token.

chainstring · enumRequired

Blockchain chain

Example: `solana`Possible values: `arbitrum``avalanche``base``bnb``ethereum``hyperevm``iotaevm``linea``mantle``monad``optimism``plasma``polygon``ronin``scroll``sei``solana``sonic``starknet``ton``tron``unichain``zksync`

token\_addressstringRequired

Address of token

Example: `2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv`

buy\_or\_sellstring · enumOptional

Are we checking buys or sells

Default: `BUY`Possible values: `BUY``SELL`

dateobject · DateRangeRequired

ISO 8601 date range object with from and to fields

Example: `{"from":"2025-05-01","to":"2025-05-03"}`

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"include_smart_money_labels":["Whale","Smart Trader"],"trade_volume_usd":{"min":1}}`

object · TGMWhoBoughtSoldFiltersOptional

Filters for TGM who bought/sold endpoint.

These filters control which traders and trade data are included.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "bought\_volume\_usd", "direction": "DESC"}\] - Sort by bought volume descending
*   \[{"field": "sold\_volume\_usd", "direction": "ASC"}\] - Sort by sold volume ascending

object · SortOrder\[TGMWhoBoughtSoldSortField\]\[\]Optional

Show properties

Responses

200

TGM who bought/sold data

application/json

Responseobject · TGMWhoBoughtSoldResponse

Response model for TGM who bought/sold endpoint.

Contains a list of address records with pagination and metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/who-bought-sold

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/tgm/who-bought-sold HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 342
    
    {
      "chain": "solana",
      "token_address": "2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv",
      "buy_or_sell": "BUY",
      "date": {
        "from": "2025-05-01",
        "to": "2025-05-03"
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "include_smart_money_labels": [\
          "Whale",\
          "Smart Trader"\
        ],
        "trade_volume_usd": {
          "min": 1
        }
      },
      "order_by": [\
        {\
          "field": "bought_volume_usd",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

TGM who bought/sold data

Copy

    {
      "data": [\
        {\
          "address": "0x1234567890123456789012345678901234567890",\
          "address_label": "High Gas Consumer",\
          "bought_token_volume": 1000.5,\
          "sold_token_volume": 500.25,\
          "token_trade_volume": 500.25,\
          "bought_volume_usd": 25000,\
          "sold_volume_usd": 12500,\
          "trade_volume_usd": 12500\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousFlows](https://docs.nansen.ai/api/token-god-mode/flows)
[NextDEX Trades](https://docs.nansen.ai/api/token-god-mode/dex-trades)

Last updated 2 months ago

Was this helpful?

---

# Address Perp Positions | Nansen API

### 

[](https://docs.nansen.ai/api/hyperliquid-apis/address-perp-positions#common-scenarios)

Common Scenarios

Usecase

Required Parameters

Optional Filters

Expected Output

Check current perp positions for a single address

address ="0xa312114b5795dff9b8db50474dd57701aa78ad1e"

filters ={"position\_value\_usd": {"min": 1000}}

List of open perpetual positions with entry price, mark price, leverage, PnL, and margin info for the address

Get all perp positions with negative PnL for an address

address ="0xa312114b5795dff9b8db50474dd57701aa78ad1e"

filters ={"unrealized\_pnl\_usd": {"max": 0}}

List of positions with negative unrealized PnL

### 

[](https://docs.nansen.ai/api/hyperliquid-apis/address-perp-positions#post-api-v1-profiler-perp-positions)

Get Perpetual Positions Data

post

https://api.nansen.ai/api/v1/profiler/perp-positions

Get perpetual positions data for a user by calling the Hyperliquid API directly. This endpoint provides real-time position information including entry price, mark price, PnL, leverage, and other position details.

**What it helps to answer:**

1.  **What are the current perpetual positions for a specific user address?**
    
2.  **What is the unrealized PnL and performance of each position?**
    
3.  **What are the leverage levels and margin requirements for each position?**
    
4.  **What are the liquidation prices and risk levels for each position?**
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for Perp Positions endpoint.

addressstring · min: 42 · max: 42Required

User's Hyperliquid address in 42-character hexadecimal format

Example: `0xa312114b5795dff9b8db50474dd57701aa78ad1e`

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"position_value_usd":{"min":1000},"unrealized_pnl_usd":{"max":0}}`

object · PerpPositionsFiltersOptional

Filters for perp positions endpoint.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "position\_value\_usd", "direction": "DESC"}\] - Sort by position value descending
*   \[{"field": "unrealized\_pnl\_usd", "direction": "ASC"}\] - Sort by unrealized PnL ascending

If not provided, positions are sorted by position value descending.

Example: `[{"direction":"DESC","field":"position_value_usd"}]`

object · SortOrder\[PerpPositionsSortField\]\[\]Optional

Show properties

Responses

200

Perpetual positions data for the user

application/json

Responseobject · PerpPositionsResponse

Response model for perp positions endpoint.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/profiler/perp-positions

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/profiler/perp-positions HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 196
    
    {
      "address": "0xa312114b5795dff9b8db50474dd57701aa78ad1e",
      "filters": {
        "position_value_usd": {
          "min": 1000
        },
        "unrealized_pnl_usd": {
          "max": 0
        }
      },
      "order_by": [\
        {\
          "direction": "DESC",\
          "field": "position_value_usd"\
        }\
      ]
    }

Test it

200

Perpetual positions data for the user

Copy

    {
      "data": {
        "asset_positions": [\
          {\
            "position": {\
              "cumulative_funding_all_time_usd": "-623.219722",\
              "cumulative_funding_since_change_usd": "-618.925976",\
              "cumulative_funding_since_open_usd": "-623.219722",\
              "entry_price_usd": "0.43499",\
              "leverage_type": "cross",\
              "leverage_value": 3,\
              "liquidation_price_usd": "66.817537196",\
              "margin_used_usd": "1743.87343",\
              "max_leverage_value": 3,\
              "position_value_usd": "5231.62029",\
              "return_on_equity": "2.2836393396",\
              "size": "-50367.0",\
              "token_symbol": "STBL",\
              "unrealized_pnl_usd": "16677.54047"\
            },\
            "position_type": "oneWay"\
          },\
          {\
            "position": {\
              "cumulative_funding_all_time_usd": "200.361581",\
              "cumulative_funding_since_change_usd": "201.157877",\
              "cumulative_funding_since_open_usd": "200.361581",\
              "entry_price_usd": "0.311285",\
              "leverage_type": "cross",\
              "leverage_value": 5,\
              "liquidation_price_usd": "39.6872752647",\
              "margin_used_usd": "2020.946984",\
              "max_leverage_value": 5,\
              "position_value_usd": "10104.73492",\
              "return_on_equity": "3.1976362269",\
              "size": "-90052.0",\
              "token_symbol": "MOODENG",\
              "unrealized_pnl_usd": "17927.1615"\
            },\
            "position_type": "oneWay"\
          }\
        ],
        "cross_maintenance_margin_used_usd": "722948.2832910001",
        "cross_margin_summary_account_value_usd": "4643143.4382309997",
        "cross_margin_summary_total_margin_used_usd": "1456365.231985",
        "cross_margin_summary_total_net_liquidation_position_on_usd": "13339928.690684",
        "cross_margin_summary_total_raw_usd": "13987445.0243870001",
        "margin_summary_account_value_usd": "4643143.4382309997",
        "margin_summary_total_margin_used_usd": "1456365.231985",
        "margin_summary_total_net_liquidation_position_usd": "13339928.690684",
        "margin_summary_total_raw_usd": "13987445.0243870001",
        "timestamp": 1761283435707,
        "withdrawable_usd": "2933647.2403759998"
      }
    }

[PreviousHyperliquid APIs](https://docs.nansen.ai/api/hyperliquid-apis)
[NextAddress Perp Trades](https://docs.nansen.ai/api/hyperliquid-apis/address-perp-trades)

Last updated 23 days ago

Was this helpful?

---

# Jupiter DCAs | Nansen API

### 

[](https://docs.nansen.ai/api/token-god-mode/jupiter-dcas#post-api-v1-tgm-jup-dca)

Get TGM Jupiter DCA Data

post

https://api.nansen.ai/api/v1/tgm/jup-dca

This endpoint provides Jupiter DCA orders with stats per vault for a specific token. Jupiter DCA (Dollar Cost Averaging) is only available on Solana and allows users to automate token purchases over time. Returns comprehensive data about DCA vaults including deposit amounts, redemption status, and trader information.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for TGM Jupiter DCA endpoint.

This endpoint provides Jupiter DCA orders with stats per vault for a specific token. Only supports Solana chain as Jupiter DCA is exclusive to Solana.

token\_addressstringRequired

Token address on Solana

Example: `2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv`

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"deposit_amount":{"min":100},"deposit_usd_value":{"min":1000},"status":"Closed"}`

object · TGMJupDcaFiltersOptional

Filters for TGM Jupiter DCA endpoint.

These filters control which Jupiter DCA orders are included in the analysis.

Show properties

Responses

200

TGM Jupiter DCA data

application/json

Responseobject · TGMJupDcaResponse

Response model for TGM Jupiter DCA endpoint.

Contains a list of Jupiter DCA records with pagination and metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/jup-dca

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/tgm/jup-dca HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 194
    
    {
      "token_address": "2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv",
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "deposit_amount": {
          "min": 100
        },
        "deposit_usd_value": {
          "min": 1000
        },
        "status": "Closed"
      }
    }

Test it

200

TGM Jupiter DCA data

Copy

    {
      "data": [\
        {\
          "since_timestamp": "2024-01-15T10:30:00Z",\
          "last_timestamp": "2024-01-20T15:45:00Z",\
          "trader_address": "7BgBvyjrZX8YKHKbbh3FbXzqKFKWJNJRVdVkgLkFUGG1",\
          "creation_hash": "3k2j9h4k5l6m7n8o9p0q1r2s3t4u5v6w7x8y9z0a1b2c3d4e5f6g7h8i9j0k1l2m",\
          "trader_label": "High Gas Consumer",\
          "dca_vault_address": "8CvgjhGJeKM9xkRBKkwRGF2VchUxJKNDLvSfXBmZ4Pqr",\
          "input_mint_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",\
          "output_mint_address": "2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv",\
          "deposit_amount": 1000,\
          "deposit_spent": 250.5,\
          "other_token_redeemed": 50.25,\
          "status": "Active",\
          "token_input": "USDC",\
          "token_output": "PEPE",\
          "deposit_usd_value": 1000\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousToken Transfers](https://docs.nansen.ai/api/token-god-mode/token-transfers)
[NextPnL Leaderboard](https://docs.nansen.ai/api/token-god-mode/pnl-leaderboard)

Last updated 2 months ago

Was this helpful?

---

# Perp PnL Leaderboard | Nansen API

### 

[](https://docs.nansen.ai/api/token-god-mode/perp-pnl-leaderboard#post-api-v1-tgm-perp-pnl-leaderboard)

Get TGM Perp PnL Leaderboard Data

post

https://api.nansen.ai/api/v1/tgm/perp-pnl-leaderboard

Rank traders by their profit/loss performance for a specific perpetual contract on Hyperliquid. Shows both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages and trading patterns. This endpoint can be used to analyze the realized and unrealized profit for each trader who traded the input perpetual contract.

**Key Features:**

*   Hyperliquid perpetual contracts only (no chain field needed)
    
*   Realized and unrealized PnL tracking
    
*   ROI calculations and trading patterns
    
*   Position size and balance tracking
    

**Request Format:**

*   `token_symbol`: Perpetual contract symbol (e.g., "BTC", "ETH", "SOL")
    
*   `date`: Date range for analysis
    
*   `filters`: Optional filters for trader addresses, PnL ranges, etc.
    
*   `pagination`: Page and per\_page parameters
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for TGM Perp PnL leaderboard endpoint. Simplified version that only supports Hyperliquid perpetual contracts.

token\_symbolstringRequired

Perpetual contract symbol (e.g., BTC, ETH, SOL)

Example: `BTC`

dateobject · DateRangeRequired

ISO 8601 date range object with optional from and to fields

Example: `{"from":"2025-10-14","to":"2025-10-15"}`

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"pnl_usd_realised":{"min":1000},"position_value_usd":{"min":1000}}`

object · TGMPerpPnlLeaderboardFiltersOptional

Filters for TGM Perp PnL leaderboard endpoint.

These filters control which traders are included in the leaderboard.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering

object · SortOrder\[TGMPerpPnlLeaderboardSortField\]\[\]Optional

Show properties

Responses

200

TGM Perp PnL leaderboard data

application/json

Responseobject · TGMPerpPnlLeaderboardResponse

Response model for TGM Perp PnL leaderboard endpoint. Contains a list of PnL leaderboard records with pagination and metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/perp-pnl-leaderboard

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/tgm/perp-pnl-leaderboard HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 245
    
    {
      "token_symbol": "BTC",
      "date": {
        "from": "2025-10-14",
        "to": "2025-10-15"
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "pnl_usd_realised": {
          "min": 1000
        },
        "position_value_usd": {
          "min": 1000
        }
      },
      "order_by": [\
        {\
          "field": "pnl_usd_realised",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

TGM Perp PnL leaderboard data

Copy

    {
      "data": [\
        {\
          "trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",\
          "trader_address_label": "🏦 Binance 14 [0x28c6c0]",\
          "price_usd": 1.23,\
          "pnl_usd_realised": 1250.5,\
          "pnl_usd_unrealised": 100.25,\
          "holding_amount": 5000,\
          "position_value_usd": 6000,\
          "max_balance_held": 10000,\
          "max_balance_held_usd": 12000,\
          "still_holding_balance_ratio": 0.5,\
          "netflow_amount_usd": 2500.75,\
          "netflow_amount": 1500,\
          "roi_percent_total": 15.5,\
          "roi_percent_realised": 12.3,\
          "roi_percent_unrealised": 3.2,\
          "pnl_usd_total": 1350.75,\
          "nof_trades": 25\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousPerp Screener](https://docs.nansen.ai/api/token-god-mode/perp-screener)
[NextPerp Positions](https://docs.nansen.ai/api/token-god-mode/perp-positions)

Last updated 26 days ago

Was this helpful?

---

# Holders | Nansen API

### 

[](https://docs.nansen.ai/api/token-god-mode/holders#post-api-v1-tgm-holders)

Get TGM Holders Data

post

https://api.nansen.ai/api/v1/tgm/holders

Retrieve the top token holders with their current balances, historical activity, and recent balance changes. Shows up to 100 holders per page, providing insights into token distribution, smart money and fund holdings.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for TGM holders endpoint.

This endpoint provides comprehensive data on token holders and their balances. Retrieve holders by various criteria including smart money, exchanges, public figures, whales, and top holders with detailed balance information and filtering options.

chainstring · enumRequired

Blockchain chain

Example: `solana`Possible values: `arbitrum``avalanche``base``bitcoin``bnb``ethereum``hyperevm``iotaevm``linea``mantle``monad``optimism``plasma``polygon``ronin``scroll``sei``solana``sonic``starknet``ton``tron``unichain``zksync`

token\_addressstringRequired

Token address

Example: `2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv`

aggregate\_by\_entitybooleanOptional

Whether to return entity data

Default: `false`

label\_typestring · enumOptional

Label type. You must also include the labels filter to match the label type. For example, for label type 'smart\_money', you must include '30D Smart Trader', '90D Smart Trader', '180D Smart Trader', 'Fund' or 'Smart Trader' in the filters.labels.include parameter.

Default: `all_holders`Example: `all_holders`Possible values: `whale``public_figure``smart_money``all_holders``exchange`

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"include_smart_money_labels":["30D Smart Trader","Fund"],"ownership_percentage":{"min":0.01},"token_amount":{"min":1000},"value_usd":{"min":10000}}`

object · TGMHoldersFiltersOptional

Filters for TGM holders endpoint.

These filters control which holders are included in the analysis.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "value\_usd", "direction": "DESC"}\] - Sort by value USD descending
*   \[{"field": "token\_amount", "direction": "ASC"}\] - Sort by token amount ascending
*   \[{"field": "ownership\_percentage", "direction": "DESC"}\] - Sort by ownership percentage descending

object · SortOrder\[TGMHoldersSortField\]\[\]Optional

Show properties

Responses

200

TGM holders data

application/json

Responseobject · TGMHoldersResponse

Response model for TGM holders endpoint.

Contains a list of holder records with pagination and metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/holders

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/tgm/holders HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 384
    
    {
      "chain": "solana",
      "token_address": "2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv",
      "aggregate_by_entity": false,
      "label_type": "all_holders",
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "include_smart_money_labels": [\
          "30D Smart Trader",\
          "Fund"\
        ],
        "ownership_percentage": {
          "min": 0.01
        },
        "token_amount": {
          "min": 1000
        },
        "value_usd": {
          "min": 10000
        }
      },
      "order_by": [\
        {\
          "field": "address",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

TGM holders data

Copy

    {
      "data": [\
        {\
          "address": "0x1234567890123456789012345678901234567890",\
          "address_label": "Smart Money",\
          "token_amount": 1000000,\
          "total_outflow": 50000,\
          "total_inflow": 1050000,\
          "balance_change_24h": 1000,\
          "balance_change_7d": 5000,\
          "balance_change_30d": 15000,\
          "ownership_percentage": 2.5,\
          "value_usd": 50000\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

### 

[](https://docs.nansen.ai/api/token-god-mode/holders#how-to-use-the-holders-endpoint)

How to use the Holders Endpoint

The Holders Endpoint returns holder data for a given token on a specific chain over a defined date range. You can use this to analyze who is holding a particular token—whether it’s Smart Money wallets, exchanges, or all holders.

#### 

[](https://docs.nansen.ai/api/token-god-mode/holders#usecase-1-get-list-of-smart-money-holders)

Usecase 1: Get list of Smart Money Holders

1.  Set "label" to "smart\_money" in the parameters object.
    
2.  Add "includeLabels" as an array with the specific Smart Money segments you want (e.g., "Fund", "30D Smart Trader").
    
3.  Other parameters (like chain, tokenAddress, date range, etc.) stay the same.
    

**Example Configuration:**

Copy

    "label": "smart_money",
    "includeLabels": ["Fund", "30D Smart Trader"]
    "isEntity": true, -- To aggregate by Entity

#### 

[](https://docs.nansen.ai/api/token-god-mode/holders#usecase-2-list-of-exchanges-holding-a-token)

Usecase 2: List of Exchanges Holding a Token

1.  Set "label" to "exchange" in the parameters object.
    
2.  Add "includeLabels" with "Exchange"
    
3.  Other parameters remain unchanged.
    

**Example Configuration:**

Copy

    "label": "exchange",
    "includeLabels": ["Exchange"]
    "isEntity": true, -- To aggregate by Entity

[PreviousFlow Intelligence](https://docs.nansen.ai/api/token-god-mode/flow-intelligence)
[NextFlows](https://docs.nansen.ai/api/token-god-mode/flows)

Last updated 2 months ago

Was this helpful?

---

# Perp Screener | Nansen API

### 

[](https://docs.nansen.ai/api/token-god-mode/perp-screener#post-api-v1-perp-screener)

Get Perpetual Contract Screening Data

post

https://api.nansen.ai/api/v1/perp-screener

Discover and screen perpetual contracts on Hyperliquid with advanced filtering capabilities. This endpoint helps identify trending perpetual contracts, trading activity, funding rates, and smart money movements by combining metrics like volume, open interest, funding rates, and position data.

**What it helps to answer:**

1.  **Which perpetual contracts are experiencing significant trading volume and activity?**
    
2.  **How do funding rates correlate with trading patterns and smart money positions?**
    
3.  **What perpetual contracts show strong fundamentals in terms of open interest and trading patterns?**
    
4.  **Which perpetual contracts are attracting smart money participation with long/short positions?**
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for Perp Screener endpoint.

dateobject · DateRangeRequired

Date range for the perp screener

Example: `{"from":"2025-10-01T00:00:00Z","to":"2025-10-06T23:59:59Z"}`

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply

Example: `{"token_symbol":"BTC","volume":{"min":10000}}`

object · PerpScreenerFiltersOptional

Filters for perp screener endpoints.

These filters control which perpetual contracts are included in the screening results based on various criteria.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "volume", "direction": "DESC"}\] - Sort by volume descending
*   \[{"field": "net\_positionz\_change", "direction": "DESC"}\] - Sort by net\_position\_change descending
*   \[{"field": "buy\_sell\_pressure", "direction": "DESC"}\] - Sort by buy/sell pressure descending (smart money)

Default behavior:

*   When only\_smart\_money is False: sorts by buy\_sell\_pressure DESC
*   When only\_smart\_money is True: sorts by net\_position\_change DESC

Example: `[{"direction":"DESC","field":"buy_sell_pressure"}]`

object · SortOrder\[Union\[PerpScreenerSortFieldDefault,PerpScreenerSortFieldSmartMoney\]\]\[\]Optional

Show properties

Responses

200

Perpetual contract screening data

application/json

Responseobject · PerpScreenerResponse

Response model for perp screener endpoint.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/perp-screener

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/perp-screener HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 224
    
    {
      "date": {
        "from": "2025-10-01T00:00:00Z",
        "to": "2025-10-06T23:59:59Z"
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "token_symbol": "BTC",
        "volume": {
          "min": 10000
        }
      },
      "order_by": [\
        {\
          "direction": "DESC",\
          "field": "buy_sell_pressure"\
        }\
      ]
    }

Test it

200

Perpetual contract screening data

Copy

    {
      "data": [\
        {\
          "buy_sell_pressure": 5518.4408,\
          "buy_volume": 216502.59923,\
          "funding": 0.0000125,\
          "mark_price": 0.3301,\
          "open_interest": 261310.461,\
          "previous_price_usd": 0.4155,\
          "sell_volume": 210984.15843,\
          "token_symbol": "ARK",\
          "trader_count": 109,\
          "volume": 427486.75766\
        },\
        {\
          "buy_sell_pressure": 25000,\
          "buy_volume": 1250000,\
          "funding": 0.0001,\
          "mark_price": 45000,\
          "open_interest": 5000000,\
          "previous_price_usd": 44000,\
          "sell_volume": 1250000,\
          "token_symbol": "BTC",\
          "trader_count": 500,\
          "volume": 2500000\
        },\
        {\
          "current_smart_money_position_longs_usd": 500000,\
          "current_smart_money_position_shorts_usd": -500000,\
          "funding": -0.0001,\
          "mark_price": 3000,\
          "net_position_change": 25000,\
          "open_interest": 2000000,\
          "previous_price_usd": 2900,\
          "smart_money_buy_volume": 75000,\
          "smart_money_longs_count": 5,\
          "smart_money_sell_volume": 75000,\
          "smart_money_shorts_count": 5,\
          "smart_money_volume": 150000,\
          "token_symbol": "ETH",\
          "trader_count": 15\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousPnL Leaderboard](https://docs.nansen.ai/api/token-god-mode/pnl-leaderboard)
[NextPerp PnL Leaderboard](https://docs.nansen.ai/api/token-god-mode/perp-pnl-leaderboard)

Last updated 26 days ago

Was this helpful?

---

# Perp Positions | Nansen API

### 

[](https://docs.nansen.ai/api/token-god-mode/perp-positions#post-api-v1-tgm-perp-positions)

Get TGM Perp Positions Data

post

https://api.nansen.ai/api/v1/tgm/perp-positions

Retrieve current perpetual positions for a specific token on Hyperliquid. Shows active positions with detailed metrics including entry price, mark price, leverage, PnL, and liquidation price.

**Key Features:**

*   Hyperliquid perpetual contracts only (no chain field needed)
    
*   Real-time position tracking with live PnL calculations
    
*   Leverage and margin information
    
*   Smart money filtering capabilities
    
*   Support for both Long and Short positions
    

**What it helps to answer:**

1.  **What are the current perp positions for a specific token?**
    
2.  **Which addresses have the largest positions by value?**
    
3.  **What are the unrealized gains/losses on current positions?**
    
4.  **What leverage levels are traders using?**
    
5.  **Which smart money wallets are holding positions?**
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for TGM perp positions endpoint.

This endpoint provides perp positions data for a specific token.

token\_symbolstringRequired

Token symbol

Example: `BTC`

label\_typestring · enumOptional

Label type filter

Default: `all_traders`Example: `all_traders`Possible values: `smart_money``all_traders``whale``public_figure``exchange`

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"include_smart_money_labels":["Smart HL Perps Trader","Fund"],"position_value_usd":{"min":10000},"side":["Long"],"upnl_usd":{"min":0}}`

object · TGMPerpPositionsFiltersOptional

Filters for TGM perp positions endpoint.

These filters control which perp positions are included in the analysis.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "position\_value\_usd", "direction": "DESC"}\] - Sort by position value USD descending
*   \[{"field": "upnl\_usd", "direction": "ASC"}\] - Sort by unrealized PnL ascending
*   \[{"field": "leverage", "direction": "DESC"}\] - Sort by leverage descending

object · SortOrder\[TGMPerpPositionsSortField\]\[\]Optional

Show properties

Responses

200

TGM perp positions data

application/json

Responseobject · TGMPerpPositionsResponse

Response model for TGM perp positions endpoint.

Contains a list of perp position records with pagination and metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/perp-positions

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/tgm/perp-positions HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 284
    
    {
      "token_symbol": "BTC",
      "label_type": "all_traders",
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "include_smart_money_labels": [\
          "Smart HL Perps Trader",\
          "Fund"\
        ],
        "position_value_usd": {
          "min": 10000
        },
        "side": [\
          "Long"\
        ],
        "upnl_usd": {
          "min": 0
        }
      },
      "order_by": [\
        {\
          "field": "address",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

TGM perp positions data

Copy

    {
      "data": [\
        {\
          "address": "0x1234567890123456789012345678901234567890",\
          "address_label": "Smart Money",\
          "side": "Long",\
          "position_value_usd": 50000,\
          "position_size": 1.5,\
          "leverage": "5X",\
          "leverage_type": "cross",\
          "entry_price": 50000,\
          "mark_price": 50500,\
          "liquidation_price": 45000,\
          "funding_usd": 10.5,\
          "upnl_usd": 500\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousPerp PnL Leaderboard](https://docs.nansen.ai/api/token-god-mode/perp-pnl-leaderboard)
[NextPerp Trades](https://docs.nansen.ai/api/token-god-mode/perp-trades)

Last updated 17 days ago

Was this helpful?

---

# Token Screener | Nansen API

**Data Retention Limits**

This endpoint only supports recent data:

*   Minute Granularity: Last 130 minutes
    
*   Hourly Granularity: Last 50 hours
    
*   Daily Granularity: Last 50 days
    

**Historical Analysis Not Supported:**

*   `to_date` must be within 5 minutes of current time
    
*   Historical snapshots (e.g., "show me January 2024") are not available
    

### 

[](https://docs.nansen.ai/api/token-god-mode/token-screener#post-api-v1-token-screener)

Get Token Screening Data

post

https://api.nansen.ai/api/v1/token-screener

Discover and screen tokens across multiple blockchains with advanced filtering capabilities. This endpoint helps identify trending tokens, new launches, and smart money movements by combining metrics like volume, liquidity, market cap, and trading activity.

**What it helps to answer:**

1.  **Which tokens are experiencing significant smart money activity across different chains?**
    
2.  **How do market metrics (price, volume, liquidity) correlate with holder behavior and smart money movements?**
    
3.  **What tokens show strong fundamentals in terms of holder distribution and trading patterns?**
    
4.  **Which emerging tokens are attracting fresh wallet inflows while maintaining healthy smart money participation?**
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for Token Screener endpoint.

chainsstring · enum\[\] · min: 1 · max: 5Required

List of blockchain chains to filter by

Example: `["ethereum","solana","base"]`

Show properties

dateobject · DateRangeRequired

Date range for the token screener

Example: `{"from":"2025-01-01T00:00:00Z","to":"2025-01-31T23:59:59Z"}`

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply

Example: `{"only_smart_money":true,"token_age_days":{"max":365,"min":1}}`

object · TokenScreenerFiltersOptional

Filters for token screener endpoints.

These filters control which tokens are included in the screening results based on various criteria.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "buy\_volume", "direction": "DESC"}\] - Sort by buy volume descending
*   \[{"field": "price\_change", "direction": "DESC"}\] - Sort by price change descending

object · SortOrder\[TokenScreenerSortField\]\[\]Optional

Show properties

Responses

200

Token screening data

application/json

Responseobject · TokenScreenerResponse

Response model for token screener endpoint.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/token-screener

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/token-screener HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 266
    
    {
      "chains": [\
        "ethereum",\
        "solana",\
        "base"\
      ],
      "date": {
        "from": "2025-01-01T00:00:00Z",
        "to": "2025-01-31T23:59:59Z"
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "only_smart_money": true,
        "token_age_days": {
          "max": 365,
          "min": 1
        }
      },
      "order_by": [\
        {\
          "field": "chain",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

Token screening data

Copy

    {
      "data": [\
        {\
          "chain": "text",\
          "token_address": "text",\
          "token_symbol": "text",\
          "token_age_days": 1,\
          "market_cap_usd": 1,\
          "liquidity": 1,\
          "price_usd": 1,\
          "price_change": 1,\
          "fdv": 1,\
          "fdv_mc_ratio": 1,\
          "buy_volume": 1,\
          "inflow_fdv_ratio": 1,\
          "outflow_fdv_ratio": 1,\
          "sell_volume": 1,\
          "volume": 1,\
          "netflow": 1\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousToken Information](https://docs.nansen.ai/api/token-god-mode/token-information)
[NextFlow Intelligence](https://docs.nansen.ai/api/token-god-mode/flow-intelligence)

Last updated 1 day ago

Was this helpful?

---

# Token Perp Positions | Nansen API

### 

[](https://docs.nansen.ai/api/hyperliquid-apis/token-perp-positions#post-api-v1-tgm-perp-positions)

Get TGM Perp Positions Data

post

https://api.nansen.ai/api/v1/tgm/perp-positions

Retrieve current perpetual positions for a specific token on Hyperliquid. Shows active positions with detailed metrics including entry price, mark price, leverage, PnL, and liquidation price.

**Key Features:**

*   Hyperliquid perpetual contracts only (no chain field needed)
    
*   Real-time position tracking with live PnL calculations
    
*   Leverage and margin information
    
*   Smart money filtering capabilities
    
*   Support for both Long and Short positions
    

**What it helps to answer:**

1.  **What are the current perp positions for a specific token?**
    
2.  **Which addresses have the largest positions by value?**
    
3.  **What are the unrealized gains/losses on current positions?**
    
4.  **What leverage levels are traders using?**
    
5.  **Which smart money wallets are holding positions?**
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for TGM perp positions endpoint.

This endpoint provides perp positions data for a specific token.

token\_symbolstringRequired

Token symbol

Example: `BTC`

label\_typestring · enumOptional

Label type filter

Default: `all_traders`Example: `all_traders`Possible values: `smart_money``all_traders``whale``public_figure``exchange`

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"include_smart_money_labels":["Smart HL Perps Trader","Fund"],"position_value_usd":{"min":10000},"side":["Long"],"upnl_usd":{"min":0}}`

object · TGMPerpPositionsFiltersOptional

Filters for TGM perp positions endpoint.

These filters control which perp positions are included in the analysis.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "position\_value\_usd", "direction": "DESC"}\] - Sort by position value USD descending
*   \[{"field": "upnl\_usd", "direction": "ASC"}\] - Sort by unrealized PnL ascending
*   \[{"field": "leverage", "direction": "DESC"}\] - Sort by leverage descending

object · SortOrder\[TGMPerpPositionsSortField\]\[\]Optional

Show properties

Responses

200

TGM perp positions data

application/json

Responseobject · TGMPerpPositionsResponse

Response model for TGM perp positions endpoint.

Contains a list of perp position records with pagination and metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/perp-positions

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/tgm/perp-positions HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 284
    
    {
      "token_symbol": "BTC",
      "label_type": "all_traders",
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "include_smart_money_labels": [\
          "Smart HL Perps Trader",\
          "Fund"\
        ],
        "position_value_usd": {
          "min": 10000
        },
        "side": [\
          "Long"\
        ],
        "upnl_usd": {
          "min": 0
        }
      },
      "order_by": [\
        {\
          "field": "address",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

TGM perp positions data

Copy

    {
      "data": [\
        {\
          "address": "0x1234567890123456789012345678901234567890",\
          "address_label": "Smart Money",\
          "side": "Long",\
          "position_value_usd": 50000,\
          "position_size": 1.5,\
          "leverage": "5X",\
          "leverage_type": "cross",\
          "entry_price": 50000,\
          "mark_price": 50500,\
          "liquidation_price": 45000,\
          "funding_usd": 10.5,\
          "upnl_usd": 500\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousSmart Money Perp Trades](https://docs.nansen.ai/api/hyperliquid-apis/smart-money-perp-trades)
[NextToken Perp Trades](https://docs.nansen.ai/api/hyperliquid-apis/token-perp-trades)

Last updated 17 days ago

Was this helpful?

---

# Address PnL & Trade Performance | Nansen API

You can use this endpoint to find correct entity name format to use in this Profiler Endpoint: [**Click Here**](https://docs.nansen.ai/api/profiler/entity-name-search)

### 

[](https://docs.nansen.ai/api/profiler/address-pnl-and-trade-performance#post-api-v1-profiler-address-pnl-summary)

Get Address PnL Summary Data

post

https://api.nansen.ai/api/v1/profiler/address/pnl-summary

Get aggregate PnL statistics and top profitable tokens for a specific wallet address. This endpoint provides comprehensive profit and loss analysis including realized PnL, win rate, and top performing tokens.

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

addressany ofOptional

Address to get PnL summary for

Example: `0x39d52da6beec991f075eebe577474fd105c5caec`

stringOptional

entity\_nameany ofOptional

Entity name to get PnL summary for

Example: `Vitalik Buterin`

stringOptional

chainstring · enumRequired

Blockchain chain for the PnL data

Example: `ethereum`Possible values: `all``arbitrum``avalanche``base``bitcoin``bnb``ethereum``hyperevm``iotaevm``linea``mantle``monad``optimism``plasma``polygon``ronin``scroll``sei``solana``sonic``starknet``ton``tron``unichain``zksync`

dateobject · DateRangeRequired

Date range for the PnL data

Example: `{"from":"2025-05-01T00:00:00Z","to":"2025-05-03T23:59:59Z"}`

Show properties

Responses

200

Address PnL summary data

application/json

Responseobject · ProfilerAddressPnlSummaryResponse

Response model for profiler address pnl-summary endpoint.

Contains aggregate PnL statistics and top profitable tokens.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/profiler/address/pnl-summary

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/profiler/address/pnl-summary HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 142
    
    {
      "address": "0x39d52da6beec991f075eebe577474fd105c5caec",
      "chain": "ethereum",
      "date": {
        "from": "2025-05-01T00:00:00Z",
        "to": "2025-05-03T23:59:59Z"
      }
    }

Test it

200

Address PnL summary data

Copy

    {
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      },
      "top5_tokens": [\
        {\
          "realized_pnl": 1,\
          "realized_roi": 1,\
          "token_address": "text",\
          "token_symbol": "text",\
          "chain": "text"\
        }\
      ],
      "traded_token_count": 1,
      "traded_times": 1,
      "realized_pnl_usd": 1,
      "realized_pnl_percent": 1,
      "win_rate": 1
    }

### 

[](https://docs.nansen.ai/api/profiler/address-pnl-and-trade-performance#post-api-v1-profiler-address-pnl)

Get Address PnL Data

post

https://api.nansen.ai/api/v1/profiler/address/pnl

Calculate profit and loss metrics for a specific address and token. Provides detailed trading performance including realized gains from sales and unrealized gains from current holdings.

What it helps to answer:

*   Realized profits or losses from completed token sales
    
*   Unrealized gains or losses on current token holdings
    
*   Average purchase and sale prices for the token
    
*   Total return on investment
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

addressany ofOptional

Wallet address to get PnL for

Example: `0x39d52da6beec991f075eebe577474fd105c5caec`

stringOptional

entity\_nameany ofOptional

Entity name to get PnL for

Example: `Vitalik Buterin`

stringOptional

chainstring · enumRequired

Blockchain chain for the PnL data

Example: `ethereum`Possible values: `all``arbitrum``avalanche``base``bitcoin``bnb``ethereum``hyperevm``iotaevm``linea``mantle``monad``optimism``plasma``polygon``ronin``scroll``sei``solana``sonic``starknet``ton``tron``unichain``zksync`

dateany ofOptional

Date range for PnL analysis

Example: `{"from":"2025-05-01","to":"2025-05-03"}`

object · DateRangeOptional

Date range model matching the API schema.

Show properties

filtersany ofOptional

Additional filters to apply.

Example: `{"show_realized":false}`

object · ProfilerAddressPnlFiltersOptional

Filters for profiler address PnL endpoint.

These filters control token filtering and realized PnL options for analysis.

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering (default: pnl\_usd\_realised DESC).

If the parameter show\_realized is false, the default sort order is pnl\_usd\_unrealised DESC.

object · SortOrder\[ProfilerAddressPnlSortField\]\[\]Optional

Show properties

Responses

200

Address PnL data

application/json

Responseobject · ProfilerAddressPnlResponse

Response model for profiler address pnl endpoint.

Contains the filtered PnL data with metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/profiler/address/pnl

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/profiler/address/pnl HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 160
    
    {
      "address": "0x39d52da6beec991f075eebe577474fd105c5caec",
      "chain": "ethereum",
      "date": {
        "from": "2025-05-01",
        "to": "2025-05-03"
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      }
    }

Test it

200

Address PnL data

Copy

    {
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      },
      "data": [\
        {\
          "token_address": "text",\
          "token_symbol": "text",\
          "token_price": 1,\
          "roi_percent_realised": 1,\
          "pnl_usd_realised": 1,\
          "pnl_usd_unrealised": 1,\
          "roi_percent_unrealised": 1,\
          "bought_amount": 1,\
          "bought_usd": 1,\
          "cost_basis_usd": 1,\
          "sold_amount": 1,\
          "sold_usd": 1,\
          "avg_sold_price_usd": 1,\
          "holding_amount": 1,\
          "holding_usd": 1,\
          "nof_buys": "text",\
          "nof_sells": "text",\
          "max_balance_held": 1,\
          "max_balance_held_usd": 1\
        }\
      ]
    }

[PreviousAddress Related Wallets](https://docs.nansen.ai/api/profiler/address-related-wallets)
[NextAddress Labels](https://docs.nansen.ai/api/profiler/address-labels)

Last updated 22 days ago

Was this helpful?

---

# Smart Money Perp Trades | Nansen API

### 

[](https://docs.nansen.ai/api/hyperliquid-apis/smart-money-perp-trades#post-api-v1-smart-money-perp-trades)

Get Smart Money Perpetual Trades Data

post

https://api.nansen.ai/api/v1/smart-money/perp-trades

Access real-time perpetual trading activity from smart traders and funds on Hyperliquid. This endpoint provides granular transaction-level data showing exactly what sophisticated traders are trading on perpetual contracts.

Key Features:

*   Hyperliquid perpetual contracts only (no chain field needed)
    
*   Real-time trading data from smart money wallets
    
*   Detailed trade information including coin, amount, price, action, and type
    
*   Smart money filtering capabilities
    
*   Type filtering (Market/Limit)
    
*   Only new positions filter to show only position opening trades (defaults to false - shows all trades)
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

filtersany ofOptional

Additional filters to apply. Only filters for columns that are being selected will be applied.

Example: `{"action":"Buy - Add Long","side":"Long","token_symbol":"BTC","type":"Limit","value_usd":{"max":10000,"min":1000}}`

object · SmartMoneyPerpTradesFiltersOptional

Filters for smart money perpetual trades endpoint.

These filters control which perpetual trades and traders are included in the trades analysis.

Show properties

only\_new\_positionsany ofOptional

When True, includes 'Open' position actions (Open Long, Open Short). Can be combined with other action filters using OR logic (union). When False (default), returns all trades.

Default: `false`Example: `true`

booleanOptional

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "value\_usd", "direction": "DESC"}\] - Sort by trade value descending
*   \[{"field": "block\_timestamp", "direction": "ASC"}\] - Sort by timestamp ascending
*   \[{"field": "token\_amount", "direction": "DESC"}, {"field": "block\_timestamp", "direction": "ASC"}\] - Sort by token amount descending, then timestamp ascending

object · SortOrder\[SmartMoneyPerpTradesSortField\]\[\]Optional

Show properties

Responses

200

Smart money perpetual trades data

application/json

Responseobject · SmartMoneyPerpTradesResponse

Response model for smart money perpetual trades endpoint.

Contains the filtered smart money perpetual trades data with metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/smart-money/perp-trades

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/smart-money/perp-trades HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 249
    
    {
      "filters": {
        "action": "Buy - Add Long",
        "side": "Long",
        "token_symbol": "BTC",
        "type": "Limit",
        "value_usd": {
          "max": 10000,
          "min": 1000
        }
      },
      "only_new_positions": true,
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "order_by": [\
        {\
          "field": "block_timestamp",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

Smart money perpetual trades data

Copy

    {
      "data": [\
        {\
          "trader_address_label": "text",\
          "trader_address": "text",\
          "token_symbol": "text",\
          "side": "Long",\
          "action": "Add",\
          "token_amount": 1,\
          "price_usd": 1,\
          "value_usd": 1,\
          "type": "Market",\
          "block_timestamp": "text",\
          "transaction_hash": "text"\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousPerp PnL Leaderboard](https://docs.nansen.ai/api/hyperliquid-apis/perp-pnl-leaderboard)
[NextToken Perp Positions](https://docs.nansen.ai/api/hyperliquid-apis/token-perp-positions)

Last updated 17 days ago

Was this helpful?

---

# Frequently Asked Questions | Nansen API

### 

[](https://docs.nansen.ai/guides/frequently-asked-questions#authentication)

Authentication

How can developers obtain API keys and access Nansen’s API endpoints?[](https://docs.nansen.ai/guides/frequently-asked-questions#how-can-developers-obtain-api-keys-and-access-nansens-api-endpoints)

You can request an API key by signing up on Nansen. You can find the detailed steps [here](https://docs.nansen.ai/getting-started/authentication#obtaining-api-keys)
.

#### 

[](https://docs.nansen.ai/guides/frequently-asked-questions#available-endpoints)

Available Endpoints

What types of data are available through Nansen’s API (e.g., wallet balances, token prices, labeled transactions)?[](https://docs.nansen.ai/guides/frequently-asked-questions#what-types-of-data-are-available-through-nansens-api-e.g.-wallet-balances-token-prices-labeled-trans)

The API provides access to wallet balances, transaction data, exchange flows, smart money tracking and other on-chain analytics across multiple chains. You can find the full list of endpoints [here](https://docs.nansen.ai/endpoints-overview)
.

#### 

[](https://docs.nansen.ai/guides/frequently-asked-questions#api-rate-limits-and-quotas)

API Rate Limits & Quotas

What are the usage limits for Nansen’s API?[](https://docs.nansen.ai/guides/frequently-asked-questions#what-are-the-usage-limits-for-nansens-api)

Nansen API comes with a flexi-credit plan. You purchase as many credits you need.

#### 

[](https://docs.nansen.ai/guides/frequently-asked-questions#data-coverage)

**Data Coverage**

Can I access labeled transaction data across multiple chains via the API?[](https://docs.nansen.ai/guides/frequently-asked-questions#can-i-access-labeled-transaction-data-across-multiple-chains-via-the-api)

Yes, you can use /transactions to access transaction data and /labels endpoint to fetch labels across multiple chains.

What on-chain metrics are available via Nansen’s API?[](https://docs.nansen.ai/guides/frequently-asked-questions#what-on-chain-metrics-are-available-via-nansens-api)

Metrics include wallet balances, token flows, smart money movements, portfolio distributions, and other derived analytics from raw blockchain data. You can find the full list of endpoints [here.](https://docs.nansen.ai/endpoints-overview)

Does the API provide access to smart money wallet activities and behaviors?[](https://docs.nansen.ai/guides/frequently-asked-questions#does-the-api-provide-access-to-smart-money-wallet-activities-and-behaviors)

Yes, API allows users to monitor smart money inflows, portfolio holdings and DEX Trades. You can find the full list of Smart Money endpoints [here](https://docs.nansen.ai/api/smart-money)
.

How does Nansen handle and provide data for non-EVM chains such as Solana or Sui?[](https://docs.nansen.ai/guides/frequently-asked-questions#how-does-nansen-handle-and-provide-data-for-non-evm-chains-such-as-solana-or-sui)

Nansen processes data from non-EVM chains by building native integrations that extract and structure on-chain information similar to EVM-based chains, while adjusting for each chain’s unique architecture. You can find the full list of supported chains [here](https://docs.nansen.ai/getting-started/chain-coverage)
.

#### 

[](https://docs.nansen.ai/guides/frequently-asked-questions#data-freshness-and-performance)

Data Freshness and Performance

How frequently is the data updated in the API?[](https://docs.nansen.ai/guides/frequently-asked-questions#how-frequently-is-the-data-updated-in-the-api)

Data is refreshed at varying intervals, with many endpoints updating in real-time depending on the data type.

What is the typical latency for data delivery through Nansen’s API?[](https://docs.nansen.ai/guides/frequently-asked-questions#what-is-the-typical-latency-for-data-delivery-through-nansens-api)

Typical data latency is low, often within seconds, depending on the chain being queried

#### 

[](https://docs.nansen.ai/guides/frequently-asked-questions#developer-tools-and-integration)

Developer Tools and Integration

Does Nansen support AI Integration Capabilities?[](https://docs.nansen.ai/guides/frequently-asked-questions#does-nansen-support-ai-integration-capabilities)

Nansen offers MCP support that allows you to connect your AI tools to Nansen's Onchain Data. You can read more and follow steps for access [here](https://docs.nansen.ai/nansen-mcp/overview)
.

Does Nansen offer SDKs, libraries, or tools for integrating analytics into third-party applications like DEXs or wallets?[](https://docs.nansen.ai/guides/frequently-asked-questions#does-nansen-offer-sdks-libraries-or-tools-for-integrating-analytics-into-third-party-applications-li)

No

Can I programmatically perform bulk analysis on wallet data using Nansen’s tools?[](https://docs.nansen.ai/guides/frequently-asked-questions#can-i-programmatically-perform-bulk-analysis-on-wallet-data-using-nansens-tools)

Yes, Nansen’s API endpoints are designed for scalable, programmatic analysis across large datasets of wallets and transactions.

[PreviousData Redistribution Guidelines](https://docs.nansen.ai/guides/data-redistribution-guidelines)
[NextUseful Links](https://docs.nansen.ai/useful-links)

Last updated 1 month ago

Was this helpful?

---

# Hyperliquid Leaderboard | Nansen API

### 

[](https://docs.nansen.ai/api/hyperliquid-apis/hyperliquid-leaderboard#common-scenarios)

Common Scenarios

Usecase

Required Parameters

Optional Filters

Expected Output

Find top perpetual traders in a specific date range

date ={ "from": "2025-10-14", "to": "2025-10-15" }

pagination ={ "page": 1, "per\_page": 10 }

List of the most profitable perpetual traders (addresses and labels) with their total PnL, ROI (%), and account values in the date range

Filter leaderboard for high-value profitable accounts

date ={ "from": "2025-10-14", "to": "2025-10-15" }

filters ={ "account\_value": { "min": 10000 }, "total\_pnl": { "min": 1000 } }

Leaderboard limited to traders with $10k+ account value and $1k+ profit, for easier benchmarking

Show only smart money leaders (filtered by trader address label)

date ={ "from": "2025-10-14", "to": "2025-10-15" }

filters ={ "trader\_address\_label": "Smart Money" }

Leaderboard showing only traders identified as Smart Money, with PnL, ROI, and account value for each

### 

[](https://docs.nansen.ai/api/hyperliquid-apis/hyperliquid-leaderboard#post-api-v1-perp-leaderboard)

Get Perpetual Trading Leaderboard Data

post

https://api.nansen.ai/api/v1/perp-leaderboard

Get perpetual trading leaderboard data showing the most profitable traders within a given date range. This endpoint provides trader performance metrics including total PnL, ROI, and account values.

**What it helps to answer:**

1.  **Who are the most profitable perpetual traders in a given timeframe?**
    
2.  **What are the ROI percentages for top performing traders?**
    
3.  **What are the account values of successful perpetual traders?**
    
4.  **How do trader addresses and labels correlate with performance?**
    

**Key Features:**

*   Trader address and label information
    
*   Total PnL tracking in USD
    
*   ROI calculations as percentages
    
*   Account value tracking
    
*   Flexible filtering and sorting options
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for Perp Leaderboard endpoint. This endpoint provides a perpetual trading leaderboard showing the most profitable traders within a given date range.

dateobject · DateOnlyRangeRequired

Date range object with optional from and to fields in YYYY-MM-DD format

Example: `{"from":"2025-10-14","to":"2025-10-15"}`

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"account_value":{"min":10000},"total_pnl":{"min":1000}}`

object · PerpLeaderboardFiltersOptional

Filters for Perp Leaderboard endpoint.

These filters control which traders are included in the leaderboard.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering

object · SortOrder\[PerpLeaderboardSortField\]\[\]Optional

Show properties

Responses

200

Perpetual trading leaderboard data

application/json

Responseobject · PerpLeaderboardResponse

Response model for Perp Leaderboard endpoint. Contains a list of leaderboard records with pagination and metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/perp-leaderboard

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/perp-leaderboard HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 206
    
    {
      "date": {
        "from": "2025-10-14",
        "to": "2025-10-15"
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "account_value": {
          "min": 10000
        },
        "total_pnl": {
          "min": 1000
        }
      },
      "order_by": [\
        {\
          "field": "total_pnl",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

Perpetual trading leaderboard data

Copy

    {
      "data": [\
        {\
          "trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",\
          "trader_address_label": "🏦 Binance 14 [0x28c6c0]",\
          "total_pnl": 1250.5,\
          "roi": 15.5,\
          "account_value": 10000\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousAddress Perp Trades](https://docs.nansen.ai/api/hyperliquid-apis/address-perp-trades)
[NextPerp Screener](https://docs.nansen.ai/api/hyperliquid-apis/perp-screener)

Last updated 23 days ago

Was this helpful?

---

# Tools supported by Nansen MCP | Nansen API

Explore the suite of tools available through Nansen MCP. Each tool is purpose-built to deliver actionable blockchain insights, from tracking smart money movements to analyzing token flows and wallet activities.

Tool Name

Corresponding API

Credits

Description/Purpose

**Smart Money**

smart\_traders\_and\_funds\_token\_balances

Smart Money Holdings

5

Get aggregated smart trader and fund token balances and 24h change per chain (excludes whales, influencers)

smart\_traders\_and\_funds\_netflows

Smart Money Netflows

5

Get aggregated smart trader and fund net flows for the last 1, 7, and 30 days

smart\_traders\_and\_funds\_dcas\_solana

Smart Money DCAs

5

Get Jupiter DCA orders created by smart traders and funds on Solana

**Token God Mode**

token\_current\_top\_holders

TGM Holders

5

Get up to 25 (per page) top holders information for a specific token, sorted by current balance

token\_dex\_trades

TGM DEX Trades

1

Get DEX trading activity for a specific token with optional smart money filtering

token\_transfers

TGM Transfers

1

Get 25 token transfers (per page) for a specific token based on sort order

token\_flows

TGM Flows

1

Get hourly aggregated token flows for specific segments of holders (Top 100, Whale, Public Figure, Smart Money, Exchange) over a date range

token\_pnl\_leaderboard

TGM PnL Leaderboard

5

Get up to 25 results (per page) of trader PnL for a token with sorting and filtering options

token\_who\_bought\_sold

TGM Who Bought/Sold

1

Get TOTAL amount of tokens bought/sold by address for a token on DEX only

token\_jup\_dca

TGM Jupiter DCA

1

Get Jupiter DCA orders for a specific token (Solana only)

token\_recent\_flows\_summary

TGM Flow Intelligence

1

Get TOTAL token flows per segment (Public Figures, Smart Money, Whales, Exchanges)

token\_discovery\_screener

Token Screener

1

Get comprehensive token screening data across multiple blockchains with advanced filtering

token\_ohlcv

MCP Tool Only

1

Get OHLCV (Open, High, Low, Close, Volume) price data for a token with automatic interval resolution

**Wallet Profiler**

address\_historical\_balances

WP Historical Balances

1

Get historical native coin & token balances for addresses or entities

address\_related\_addresses

WP Related Addresses

1

Get information about related addresses (first funders, signers, deployed contracts)

address\_counterparties

WP Counterparties

5

Get 25 (per page) addresses/entities with most common interactions with input addresses

address\_transactions

WP Transactions

1

Get list of 20 most recent transactions made by an address (per page)

wallet\_pnl\_for\_token

WP PnL for Token

1

Get PnL stats for a specific token traded by an address during a date range

wallet\_pnl\_summary

WP PnL Summary

1

Get aggregate stats of overall realized PnL for an address (excludes unrealized PnL)

address\_transactions\_for\_token

WP Token Transactions

1

Get up to 20 (per page) most recent token transfers for a specific address and token

address\_portfolio

DeFi Positions

1

Get comprehensive portfolio overview for a wallet address or entity

**Miscellaneous**

general\_search

MCP Tool Only

0 (Free)

General search tool for looking up tokens, entities, and addresses. First entry point for queries (does not support NFTs)

growth\_chain\_rank

MCP Tool Only

1

Get chain growth rankings by active addresses, transactions, gas fees, and DEX volume

transaction\_lookup

MCP Tool Only

1

Get comprehensive transaction details including token transfers (EVM only)

[PreviousConnecting to Nansen MCP](https://docs.nansen.ai/nansen-mcp/overview/connecting-to-nansen-mcp)
[NextCommon MCP clients](https://docs.nansen.ai/nansen-mcp/overview/common-mcp-clients)

Last updated 10 days ago

Was this helpful?

---

# Perp Screener | Nansen API

### 

[](https://docs.nansen.ai/api/hyperliquid-apis/perp-screener#common-scenarios)

Common Scenarios

Usecase

Required Parameters

Optional Filters

Expected Output

Screen for perps with net buy/sell pressure and strong fundamentals

date ={ "from": "2025-10-01T00:00:00Z", "to": "2025-10-06T23:59:59Z" }

filters ={ "buy\_sell\_pressure": { "min": 100000 }, "open\_interest": { "min": 500000 } }

Perps showing high buy/sell pressure and strong open interest, returned with mark price, volume, and trader details

Discover perps favored by smart money

date ={ "from": "2025-10-01T00:00:00Z", "to": "2025-10-06T23:59:59Z" }

only\_smart\_money =true filters ={ "smart\_money\_volume": { "min": 100000 } }

Perps with the highest smart money volume, including smart money long/short counts, USD position sizes, and assets

### 

[](https://docs.nansen.ai/api/hyperliquid-apis/perp-screener#post-api-v1-perp-screener)

Get Perpetual Contract Screening Data

post

https://api.nansen.ai/api/v1/perp-screener

Discover and screen perpetual contracts on Hyperliquid with advanced filtering capabilities. This endpoint helps identify trending perpetual contracts, trading activity, funding rates, and smart money movements by combining metrics like volume, open interest, funding rates, and position data.

**What it helps to answer:**

1.  **Which perpetual contracts are experiencing significant trading volume and activity?**
    
2.  **How do funding rates correlate with trading patterns and smart money positions?**
    
3.  **What perpetual contracts show strong fundamentals in terms of open interest and trading patterns?**
    
4.  **Which perpetual contracts are attracting smart money participation with long/short positions?**
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for Perp Screener endpoint.

dateobject · DateRangeRequired

Date range for the perp screener

Example: `{"from":"2025-10-01T00:00:00Z","to":"2025-10-06T23:59:59Z"}`

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply

Example: `{"token_symbol":"BTC","volume":{"min":10000}}`

object · PerpScreenerFiltersOptional

Filters for perp screener endpoints.

These filters control which perpetual contracts are included in the screening results based on various criteria.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "volume", "direction": "DESC"}\] - Sort by volume descending
*   \[{"field": "net\_positionz\_change", "direction": "DESC"}\] - Sort by net\_position\_change descending
*   \[{"field": "buy\_sell\_pressure", "direction": "DESC"}\] - Sort by buy/sell pressure descending (smart money)

Default behavior:

*   When only\_smart\_money is False: sorts by buy\_sell\_pressure DESC
*   When only\_smart\_money is True: sorts by net\_position\_change DESC

Example: `[{"direction":"DESC","field":"buy_sell_pressure"}]`

object · SortOrder\[Union\[PerpScreenerSortFieldDefault,PerpScreenerSortFieldSmartMoney\]\]\[\]Optional

Show properties

Responses

200

Perpetual contract screening data

application/json

Responseobject · PerpScreenerResponse

Response model for perp screener endpoint.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/perp-screener

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/perp-screener HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 224
    
    {
      "date": {
        "from": "2025-10-01T00:00:00Z",
        "to": "2025-10-06T23:59:59Z"
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "token_symbol": "BTC",
        "volume": {
          "min": 10000
        }
      },
      "order_by": [\
        {\
          "direction": "DESC",\
          "field": "buy_sell_pressure"\
        }\
      ]
    }

Test it

200

Perpetual contract screening data

Copy

    {
      "data": [\
        {\
          "buy_sell_pressure": 5518.4408,\
          "buy_volume": 216502.59923,\
          "funding": 0.0000125,\
          "mark_price": 0.3301,\
          "open_interest": 261310.461,\
          "previous_price_usd": 0.4155,\
          "sell_volume": 210984.15843,\
          "token_symbol": "ARK",\
          "trader_count": 109,\
          "volume": 427486.75766\
        },\
        {\
          "buy_sell_pressure": 25000,\
          "buy_volume": 1250000,\
          "funding": 0.0001,\
          "mark_price": 45000,\
          "open_interest": 5000000,\
          "previous_price_usd": 44000,\
          "sell_volume": 1250000,\
          "token_symbol": "BTC",\
          "trader_count": 500,\
          "volume": 2500000\
        },\
        {\
          "current_smart_money_position_longs_usd": 500000,\
          "current_smart_money_position_shorts_usd": -500000,\
          "funding": -0.0001,\
          "mark_price": 3000,\
          "net_position_change": 25000,\
          "open_interest": 2000000,\
          "previous_price_usd": 2900,\
          "smart_money_buy_volume": 75000,\
          "smart_money_longs_count": 5,\
          "smart_money_sell_volume": 75000,\
          "smart_money_shorts_count": 5,\
          "smart_money_volume": 150000,\
          "token_symbol": "ETH",\
          "trader_count": 15\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousHyperliquid Leaderboard](https://docs.nansen.ai/api/hyperliquid-apis/hyperliquid-leaderboard)
[NextPerp PnL Leaderboard](https://docs.nansen.ai/api/hyperliquid-apis/perp-pnl-leaderboard)

Last updated 23 days ago

Was this helpful?

---

# Address Perp Trades | Nansen API

### 

[](https://docs.nansen.ai/api/hyperliquid-apis/address-perp-trades#common-scenarios)

Common Scenarios

Usecase

Required Parameters

Optional Filters

Expected Output

Fetch all perp trades for an address within a specific date range

address ="0x45d26f28196d226497130c4bac709d808fed4029" date ={ "from": "2025-10-01", "to": "2025-10-10" }

(none needed for basic usage)

List of trades with timestamps, price, size, token, direction (Long/Short), action (Open/Close), and fees for the address

Analyze high-value trades with closed PnL details

address ="0x45d26f28196d226497130c4bac709d808fed4029" date ={ "from": "2025-10-01", "to": "2025-10-10" }

filters ={"value\_usd": {"min": 1000}}

List of trades above $1,000 with closed PnL, fees paid, order IDs, and asset symbols

Track all short trades and compare performance by token

address ="0x45d26f28196d226497130c4bac709d808fed4029" date ={ "from": "2025-10-01", "to": "2025-10-10" }

filters ={"type": "Short"} order\_by =\[{"direction": "DESC", "field": "closed\_pnl"}\]

All short trades, sorted by closed profit, allowing analysis of which tokens and trades delivered the best results

### 

[](https://docs.nansen.ai/api/hyperliquid-apis/address-perp-trades#post-api-v1-profiler-perp-trades)

Get Perpetual Trade Data

post

https://api.nansen.ai/api/v1/profiler/perp-trades

Get perpetual trade data for a user. This endpoint provides trade information including trade price, size, side, fees, and other trade details.

**What it helps to answer:**

1.  **What are the perpetual trades for a specific user address within a date range?**
    
2.  **What are the trade prices, sizes, and directions for each trade?**
    
3.  **What are the trading fees and closed PnL for each trade?**
    
4.  **What are the order IDs and transaction hashes for trade tracking?**
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for Perp Trades endpoint.

addressstring · min: 42 · max: 42Required

User's Hyperliquid address in 42-character hexadecimal format

Example: `0x45d26f28196d226497130c4bac709d808fed4029`

dateobject · DateRangeRequired

Date range for the trades

Example: `{"from":"2025-10-01","to":"2025-10-10"}`

Show properties

filtersany ofOptional

Additional filters for the trades

Example: `{"size":{"max":1000,"min":0.001}}`

object · PerpTradeFiltersOptional

Filters for perp trades endpoint.

These filters control which perpetual trades are included in the results based on various trade criteria.

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

order\_byany ofOptional

Sort order for the trades

Example: `[{"direction":"DESC","field":"timestamp"}]`

object · SortOrder\[PerpTradeSortField\]\[\]Optional

Show properties

Responses

200

Perpetual trade data for the user

application/json

Responseobject · PerpTradeResponse

Response model for perp trades endpoint.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/profiler/perp-trades

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/profiler/perp-trades HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 239
    
    {
      "address": "0x45d26f28196d226497130c4bac709d808fed4029",
      "date": {
        "from": "2025-10-01",
        "to": "2025-10-10"
      },
      "filters": {
        "size": {
          "max": 1000,
          "min": 0.001
        }
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "order_by": [\
        {\
          "direction": "DESC",\
          "field": "timestamp"\
        }\
      ]
    }

Test it

200

Perpetual trade data for the user

Copy

    {
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      },
      "data": [\
        {\
          "action": "Add",\
          "block_number": 756553592,\
          "closed_pnl": 0,\
          "crossed": true,\
          "fee_token_symbol": "USDC",\
          "fee_usd": 0.434851,\
          "oid": 191284609448,\
          "price": 0.25884,\
          "side": "Short",\
          "size": 6000,\
          "start_position": -7788000,\
          "timestamp": "2025-10-08T18:46:11.452000",\
          "token_symbol": "DOGE",\
          "transaction_hash": "0x50cea34e7464d3055248042d1817780203b600340f67f1d7f4974ea13368acef",\
          "user": "0x45d26f28196d226497130c4bac709d808fed4029",\
          "value_usd": 1553.04\
        },\
        {\
          "action": "Open",\
          "block_number": 756553593,\
          "closed_pnl": 0,\
          "crossed": false,\
          "fee_token_symbol": "USDC",\
          "fee_usd": 2.25,\
          "oid": 191284609449,\
          "price": 45000,\
          "side": "Long",\
          "size": 0.1,\
          "start_position": 0,\
          "timestamp": "2025-10-08T15:30:22.123000",\
          "token_symbol": "BTC",\
          "transaction_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",\
          "user": "0x45d26f28196d226497130c4bac709d808fed4029",\
          "value_usd": 4500\
        },\
        {\
          "action": "Close",\
          "block_number": 756553594,\
          "closed_pnl": 150,\
          "crossed": true,\
          "fee_token_symbol": "USDC",\
          "fee_usd": 2.25,\
          "oid": 191284609450,\
          "price": 3000,\
          "side": "Long",\
          "size": 1.5,\
          "start_position": 1000,\
          "timestamp": "2025-10-08T12:15:33.789000",\
          "token_symbol": "ETH",\
          "transaction_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",\
          "user": "0x45d26f28196d226497130c4bac709d808fed4029",\
          "value_usd": 4500\
        }\
      ]
    }

[PreviousAddress Perp Positions](https://docs.nansen.ai/api/hyperliquid-apis/address-perp-positions)
[NextHyperliquid Leaderboard](https://docs.nansen.ai/api/hyperliquid-apis/hyperliquid-leaderboard)

Last updated 23 days ago

Was this helpful?

---

# Token Perp Trades | Nansen API

### 

[](https://docs.nansen.ai/api/hyperliquid-apis/token-perp-trades#post-api-v1-tgm-perp-trades)

Get TGM Perp Trades Data

post

https://api.nansen.ai/api/v1/tgm/perp-trades

Retrieve perpetual trade data for a specific token on Hyperliquid. Shows individual trades with detailed information including trader address, trade side (Long/Short), action type (Add/Reduce/Open/Close), order type (Market/Limit), and trade metrics.

**Key Features:**

*   Hyperliquid perpetual contracts only
    
*   Smart money filtering capabilities
    
*   Detailed trade breakdown with parsed action fields
    
*   Support for both Long and Short position trading
    
*   Market and Limit order types
    

**Request Parameters:**

*   `token_symbol`: Token symbol to fetch trades for (e.g., "BTC", "ETH")
    
*   `date`: Date range for the trades
    
*   `filters`: Additional filters for side, action, order\_type, etc.
    
*   `pagination`: Page and per\_page parameters
    

Authorizations

ApiKeyAuth

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

application/json

Request model for TGM perp trades endpoint.

This endpoint provides perp trades data for a specific token.

token\_symbolstringRequired

Token symbol

Example: `BTC`

dateobject · DateRangeRequired

ISO 8601 date range object with optional from and to fields

Example: `{"from":"2025-07-07","to":"2025-07-14"}`

Show properties

paginationobject · PaginationRequestOptional

Pagination parameters

Show properties

filtersany ofOptional

Additional filters to apply to the query.

Example: `{"order_type":["MARKET"],"side":["Long"]}`

object · TGMPerpTradesFiltersOptional

Filters for TGM perp trades endpoint.

These filters control which perp trades are included in the results.

Show properties

order\_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

*   \[{"field": "block\_timestamp", "direction": "DESC"}\] - Sort by timestamp descending
*   \[{"field": "value\_usd", "direction": "DESC"}\] - Sort by trade value descending

object · SortOrder\[TGMPerpTradesSortField\]\[\]Optional

Show properties

Responses

200

TGM perp trades data

application/json

Responseobject · TGMPerpTradesResponse

Response model for TGM perp trades endpoint.

Contains a list of perp trade records with pagination and metadata.

Show properties

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Entity

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/perp-trades

HTTP

HTTPcURLJavaScriptPython

Copy

    POST /api/v1/tgm/perp-trades HTTP/1.1
    Host: api.nansen.ai
    apiKey: YOUR_API_KEY
    Content-Type: application/json
    Accept: */*
    Content-Length: 218
    
    {
      "token_symbol": "BTC",
      "date": {
        "from": "2025-07-07",
        "to": "2025-07-14"
      },
      "pagination": {
        "page": 1,
        "per_page": 10
      },
      "filters": {
        "order_type": [\
          "MARKET"\
        ],
        "side": [\
          "Long"\
        ]
      },
      "order_by": [\
        {\
          "field": "block_timestamp",\
          "direction": "ASC"\
        }\
      ]
    }

Test it

200

TGM perp trades data

Copy

    {
      "data": [\
        {\
          "trader_address_label": "Smart Money",\
          "trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",\
          "token_symbol": "BTC",\
          "side": "Long",\
          "action": "Add",\
          "token_amount": 1.5,\
          "price_usd": 60000,\
          "value_usd": 90000,\
          "type": "MARKET",\
          "block_timestamp": "2025-10-01T12:40:00Z",\
          "transaction_hash": "0x61adb6da30853c5988f0204dd9f6e4abbc878e02c34030a4f707cf4ec3124bcb"\
        }\
      ],
      "pagination": {
        "page": 1,
        "per_page": 10,
        "is_last_page": true
      }
    }

[PreviousToken Perp Positions](https://docs.nansen.ai/api/hyperliquid-apis/token-perp-positions)
[NextOverview](https://docs.nansen.ai/nansen-mcp/overview)

Last updated 17 days ago

Was this helpful?

---

# Data Redistribution Guidelines | Nansen API

### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#purpose)

Purpose

These guidelines help developers understand how to legally and responsibly redistribute data obtained from Nansen API and MCP tools, while protecting Nansen's proprietary insights and competitive advantage.

### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#quick-reference-can-you-redistribute)

Quick Reference: Can You Redistribute?

Endpoint

Status

Requirements

profiler/address/balances

✅ Allowed

None

profiler/perp-positions

✅ Allowed

None

profiler/perp-trades

✅ Allowed

None

profiler/address/pnl & pnl-summary

✅ Allowed

None

profiler/address/historical-balances

✅ Allowed

None

tgm/transfers

✅ Allowed

Attribution required

profiler/address/transactions

✅ Allowed

Attribution required

profiler/address/counterparty

✅ Allowed

Attribution required

profiler/address/related-wallets

✅ Allowed

Attribution required

tgm/token-screener

✅ Allowed

Attribution required

tgm/perp-screener

✅ Allowed

Attribution required

tgm/dex-trades

✅ Allowed

Attribution required

tgm/perp-trades

✅ Allowed

Attribution required

tgm/who-bought-sold

✅ Allowed

Attribution required

tgm/flow-intelligence

✅ Allowed

Attribution required

tgm/flows

✅ Allowed

Attribution required

tgm/holders (with smart money filter)

⚠️ Restricted

Approval + Significant Modification

tgm/perp-positions (with smart money filter)

⚠️ Restricted

Approval + Significant Modification

smart-money/inflows

⚠️ Restricted

Approval + Significant Modification

**Prohibited Endpoints**

/label (smart money labels)

🚫 Prohibited

Not permitted

smart-money/holdings

🚫 Prohibited

Not permitted

tgm/pnl-leaderboard

🚫 Prohibited

Not permitted

perp-leaderboard

🚫 Prohibited

Not permitted

smart-money/dex-trades

🚫 Prohibited

Not permitted

smart-money/dcas

🚫 Prohibited

Not permitted

smart-money/perp-trades

🚫 Prohibited

Not permitted

* * *

### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#understanding-redistribution-statuses)

Understanding Redistribution Statuses

#### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#allowed)

✅ **Allowed**

You may freely redistribute this data in your products, services, or applications according to Nansen's Terms of Service. No additional permissions needed.

**Example use cases:**

*   Displaying wallet balances in your portfolio tracker
    

* * *

#### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#allowed-with-attribution)

✅ **Allowed (with attribution)**

You may redistribute this data, but you **must** provide clear attribution to Nansen.

**Attribution requirements:**

*   Display "Powered by Nansen API" visibly in your product interface, OR
    
*   Provide a clickable link to [Nansen.ai](https://nansen.ai/)
     near the data display
    

**Note:** Attribution is NOT required for personal or internal-only use.

**Example use cases:**

*   Token screening dashboards that display real-time token metrics and volume data
    
*   Trading analytics platforms showing DEX trade flows and whale activity
    
*   Portfolio management apps displaying counterparties
    
*   Research reports examining flow intelligence patterns across tokens
    

* * *

#### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#restricted-by-default)

⚠️ **Restricted By-Default**

These endpoints contain Nansen's proprietary smart money insights and require **both** approval AND significant data modification.

**You must:**

1.  Submit a request for approval via [this form](https://forms.gle/AoXk9jRdbuiqqG5f9)
    
2.  Demonstrate significant data transformation (see requirements below)
    
3.  Provide clear attribution to Nansen
    

**This data cannot be redistributed without meeting these requirements.**

* * *

#### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#prohibited)

🚫 **Prohibited**

Redistribution is **NOT allowed** under any circumstances. These endpoints contain Nansen's most sensitive proprietary data and competitive advantages.

**Do not:**

*   Display this data in any public or customer-facing interface
    
*   Use this data to build competing products
    
*   Redistribute this data through APIs, exports, or any other means
    

**Internal use only:** You may use this data for your own internal analysis, but not share it externally.

* * *

### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#what-is-significant-modification)

What is "Significant Modification"?

To redistribute smart money data, you must transform it substantially so that:

1.  **Not Directly Traceable**: The output cannot be reverse-engineered to reveal Nansen's underlying smart money classifications, wallet lists, or raw activity data
    
2.  **Meaningfully Combined**: The data must be integrated with at least one other substantial, independent data source (not just cosmetic additions)
    
3.  **Novel Insights**: Your final output must provide unique analysis or value-add beyond what Nansen already offers
    

✅ **ALLOWED Use Cases** (with approval)[](https://docs.nansen.ai/guides/data-redistribution-guidelines#allowed-use-cases-with-approval)

#### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#id-1.-ai-agent-background-analysis)

1\. **AI Agent Background Analysis**

Using smart money data as one input among multiple sources to generate unique analytical responses.

**✓ Good Example:**

> Your AI agent analyzes: Nansen smart money flows (30%) + on-chain volume metrics (30%) + social sentiment analysis (20%) + technical indicators (20%) → generates custom investment thesis that synthesizes all sources

**✗ Bad Example:**

> Your AI agent says: "Smart money wallets bought 5M tokens in the last 24 hours according to Nansen data"

#### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#id-2.-custom-composite-indicators)

2\. **Custom Composite Indicators**

Building proprietary trading signals that incorporate smart money data alongside other metrics.

**✓ Good Example:**

> A "Token Momentum Score" (0-100) that combines:
> 
> *   Smart money net flow (25%)
>     
> *   DEX liquidity depth (25%)
>     
> *   Price action volatility (25%)
>     
> *   Developer activity (25%)
>     

**✗ Bad Example:**

> A "Smart Money Activity Index" that's just a reformatted version of Nansen's smart money inflow data

#### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#id-3.-research-reports-and-analysis)

3\. **Research Reports & Analysis**

Periodic research that synthesizes smart money trends with broader market context.

**✓ Good Example:**

> Weekly market report: "DeFi sector analysis combining smart trader positioning (via Nansen), protocol TVL trends (via DeFiLlama), and governance activity (via on-chain data) suggests..."

**✗ Bad Example:**

> Daily newsletter that lists: "Top 10 tokens smart money bought yesterday" with minimal additional context

🚫 **PROHIBITED Use Cases**[](https://docs.nansen.ai/guides/data-redistribution-guidelines#prohibited-use-cases)

#### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#id-1.-direct-display-dashboards)

1\. **Direct Display Dashboards**

Any interface where Nansen's smart money data is shown without substantial transformation.

**Examples of what NOT to do:**

*   Dashboards showing "Smart Money bought these tokens in last 24h"
    
*   Charts displaying raw smart money wallet balances over time
    
*   Tables listing smart money trades with timestamps and amounts
    
*   Real-time feeds of smart money wallet activity
    

#### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#id-2.-competing-smart-money-products)

2\. **Competing Smart Money Products**

Products that directly compete with or replicate Nansen's core offerings.

**Examples of what NOT to do:**

*   "Smart Money Tracker" features
    
*   "Profitable Wallet Scanner" tools
    
*   "Smart Trader Leaderboards"
    
*   "Elite Wallet Following" services
    

#### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#id-3.-public-leaderboards-and-rankings)

3\. **Public Leaderboards & Rankings**

Displaying smart money wallet performance, rankings, or PnL data.

**Examples of what NOT to do:**

*   "Top 50 Smart Money Wallets This Month"
    
*   "Highest PnL Smart Traders" rankings
    
*   Public smart money wallet performance dashboards
    
*   Smart money wallet comparison tools
    

#### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#id-4.-near-real-time-data-redistribution)

4\. **Near Real-Time Data Redistribution**

Redistributing smart money data with minimal time delay or transformation.

**Examples of what NOT to do:**

*   API endpoints serving Nansen smart money data with <7d delay
    
*   Webhook notifications for smart money wallet trades
    
*   Real-time smart money activity alerts
    
*   Automated smart money trade copying services
    

* * *

### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#requesting-approval-for-restricted-endpoints)

Requesting Approval for Restricted Endpoints

**Step 1: Submit Your Request**

Complete the approval form: [https://forms.gle/AoXk9jRdbuiqqG5f9](https://forms.gle/AoXk9jRdbuiqqG5f9)

**Step 2: Provide Required Information**

1.  Describe your product, how you'll use the data, and your target audience
    
2.  Explain modifications, other data sources, and provide mockups
    
3.  Show unique insights and differentiation from Nansen's products
    
4.  Detail how you'll credit Nansen and potential partnership opportunities
    

* * *

### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#attribution-guidelines)

Attribution Guidelines

**When Attribution is Required**

Required for endpoints marked "✅ Allowed (with attribution)" or "⚠️ Restricted".

**How to Attribute**

Choose one:

*   **Text**: "Powered by Nansen API" or similar, displayed near the data
    
*   **Logo**: Nansen logo with link to [nansen.ai](https://nansen.ai/)
    
*   **Footer**: "Blockchain analytics powered by [Nansen](https://nansen.ai/)
    "
    

**When Attribution is NOT Required**

*   Personal or internal use only
    
*   Endpoints marked "✅ Allowed" (no attribution noted)
    

* * *

### 

[](https://docs.nansen.ai/guides/data-redistribution-guidelines#general-rules-and-compliance)

General Rules & Compliance

**1\. Terms of Service**

*   Must comply with Nansen's [Terms of Service](https://www.nansen.ai/legal/terms-of-services)
    

**2\. Stay Updated**

*   Check latest guidelines before launching products, changing data usage, or entering new markets
    

**3\. API & MCP Coverage**

*   Rules apply to API responses, MCP tools, and derived data
    

**4\. Volume & Rate Limits**

*   Redistribution doesn't exempt you from rate limits
    

**5\. Data Accuracy**

*   Don't misrepresent data
    
*   Include appropriate disclaimers
    
*   Don't make unwarranted guarantees
    

**6\. Competitive Use**

*   Don't build competing products
    
*   Don't use Nansen data as foundation for competitor services
    
*   Don't repackage data to commoditize Nansen's insights
    

[PreviousMCP Data Redistribution Guidelines](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines)
[NextFrequently Asked Questions](https://docs.nansen.ai/guides/frequently-asked-questions)

Last updated 4 days ago

Was this helpful?

---

# MCP Data Redistribution Guidelines | Nansen API

### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#purpose)

Purpose

These guidelines help developers understand how to legally and responsibly redistribute data obtained from Nansen API and MCP tools, while protecting Nansen's proprietary insights and competitive advantage.

### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#quick-reference-can-you-redistribute)

Quick Reference: Can You Redistribute?

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#wallet-profiler)

Wallet Profiler

Tool Name

Redistribution Status

Requirements

`address_portfolio`

✅ Allowed

None

`address_historical_balances`

✅ Allowed

None

`wallet_pnl_for_token`

✅ Allowed

None

`wallet_pnl_summary`

✅ Allowed

None

`address_transactions`

✅ Allowed

Attribution required

`address_related_addresses`

✅ Allowed

Attribution required

`address_counterparties`

✅ Allowed

Attribution required

`address_transactions_for_token`

✅ Allowed

Attribution required

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#token-god-mode)

Token God Mode

Tool Name

Redistribution Status

Notes

`token_ohlcv`

✅ Allowed

None

`token_dex_trades`

✅ Allowed

Attribution required

`token_transfers`

✅ Allowed

Attribution required

`token_who_bought_sold`

✅ Allowed

Attribution required

`token_flows`

✅ Allowed

Attribution required

`token_recent_flows_summary`

✅ Allowed

Attribution required

`token_jup_dca`

✅ Allowed

Attribution required

`token_exchange_transactions`

✅ Allowed

Attribution required

`token_discovery_screener`

✅ Allowed

Attribution required

`token_current_top_holders`

⚠️ Restricted

Approval + Significant Modification

`token_pnl_leaderboard`

🚫 Prohibited

Not permitted

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#smart-money)

Smart Money

Tool Name

Redistribution Status

Notes

`smart_traders_and_funds_netflows`

⚠️ Restricted

Approval + Significant Modification

`smart_traders_and_funds_token_balances`

🚫 Prohibited

Not permitted

* * *

### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#understanding-redistribution-statuses)

Understanding Redistribution Statuses

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#allowed)

✅ **Allowed**

You may freely redistribute this data in your products, services, or applications according to Nansen's Terms of Service. No additional permissions needed.

**Example use cases:**

*   Displaying wallet balances in your portfolio tracker
    

* * *

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#allowed-with-attribution)

✅ **Allowed (with attribution)**

You may redistribute this data, but you **must** provide clear attribution to Nansen.

**Attribution requirements:**

*   Display "Powered by Nansen API" visibly in your product interface, OR
    
*   Provide a clickable link to [Nansen.ai](https://nansen.ai/)
     near the data display
    

**Note:** Attribution is NOT required for personal or internal-only use.

**Example use cases:**

*   Token screening dashboards that display real-time token metrics and volume data
    
*   Trading analytics platforms showing DEX trade flows and whale activity
    
*   Portfolio management apps displaying counterparties
    
*   Research reports examining flow intelligence patterns across tokens
    

* * *

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#restricted-by-default)

⚠️ **Restricted By-Default**

These endpoints contain Nansen's proprietary smart money insights and require **both** approval AND significant data modification.

**You must:**

1.  Submit a request for approval via [this form](https://forms.gle/AoXk9jRdbuiqqG5f9)
    
2.  Demonstrate significant data transformation (see requirements below)
    
3.  Provide clear attribution to Nansen
    

**This data cannot be redistributed without meeting these requirements.**

* * *

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#prohibited)

🚫 **Prohibited**

Redistribution is **NOT allowed** under any circumstances. These endpoints contain Nansen's most sensitive proprietary data and competitive advantages.

**Do not:**

*   Display this data in any public or customer-facing interface
    
*   Use this data to build competing products
    
*   Redistribute this data through APIs, exports, or any other means
    

**Internal use only:** You may use this data for your own internal analysis, but not share it externally.

* * *

### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#what-is-significant-modification)

What is "Significant Modification"?

To redistribute smart money data, you must transform it substantially so that:

1.  **Not Directly Traceable**: The output cannot be reverse-engineered to reveal Nansen's underlying smart money classifications, wallet lists, or raw activity data
    
2.  **Meaningfully Combined**: The data must be integrated with at least one other substantial, independent data source (not just cosmetic additions)
    
3.  **Novel Insights**: Your final output must provide unique analysis or value-add beyond what Nansen already offers
    

✅ **ALLOWED Use Cases** (with approval)[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#allowed-use-cases-with-approval)

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#id-1.-ai-agent-background-analysis)

1\. **AI Agent Background Analysis**

Using smart money data as one input among multiple sources to generate unique analytical responses.

**✓ Good Example:**

> Your AI agent analyzes: Nansen smart money flows (30%) + on-chain volume metrics (30%) + social sentiment analysis (20%) + technical indicators (20%) → generates custom investment thesis that synthesizes all sources

**✗ Bad Example:**

> Your AI agent says: "Smart money wallets bought 5M tokens in the last 24 hours according to Nansen data"

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#id-2.-custom-composite-indicators)

2\. **Custom Composite Indicators**

Building proprietary trading signals that incorporate smart money data alongside other metrics.

**✓ Good Example:**

> A "Token Momentum Score" (0-100) that combines:
> 
> *   Smart money net flow (25%)
>     
> *   DEX liquidity depth (25%)
>     
> *   Price action volatility (25%)
>     
> *   Developer activity (25%)
>     

**✗ Bad Example:**

> A "Smart Money Activity Index" that's just a reformatted version of Nansen's smart money inflow data

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#id-3.-research-reports-and-analysis)

3\. **Research Reports & Analysis**

Periodic research that synthesizes smart money trends with broader market context.

**✓ Good Example:**

> Weekly market report: "DeFi sector analysis combining smart trader positioning (via Nansen), protocol TVL trends (via DeFiLlama), and governance activity (via on-chain data) suggests..."

**✗ Bad Example:**

> Daily newsletter that lists: "Top 10 tokens smart money bought yesterday" with minimal additional context

🚫 **PROHIBITED Use Cases**[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#prohibited-use-cases)

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#id-1.-direct-display-dashboards)

1\. **Direct Display Dashboards**

Any interface where Nansen's smart money data is shown without substantial transformation.

**Examples of what NOT to do:**

*   Dashboards showing "Smart Money bought these tokens in last 24h"
    
*   Charts displaying raw smart money wallet balances over time
    
*   Tables listing smart money trades with timestamps and amounts
    
*   Real-time feeds of smart money wallet activity
    

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#id-2.-competing-smart-money-products)

2\. **Competing Smart Money Products**

Products that directly compete with or replicate Nansen's core offerings.

**Examples of what NOT to do:**

*   "Smart Money Tracker" features
    
*   "Profitable Wallet Scanner" tools
    
*   "Smart Trader Leaderboards"
    
*   "Elite Wallet Following" services
    

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#id-3.-public-leaderboards-and-rankings)

3\. **Public Leaderboards & Rankings**

Displaying smart money wallet performance, rankings, or PnL data.

**Examples of what NOT to do:**

*   "Top 50 Smart Money Wallets This Month"
    
*   "Highest PnL Smart Traders" rankings
    
*   Public smart money wallet performance dashboards
    
*   Smart money wallet comparison tools
    

#### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#id-4.-near-real-time-data-redistribution)

4\. **Near Real-Time Data Redistribution**

Redistributing smart money data with minimal time delay or transformation.

**Examples of what NOT to do:**

*   API endpoints serving Nansen smart money data with <7d delay
    
*   Webhook notifications for smart money wallet trades
    
*   Real-time smart money activity alerts
    
*   Automated smart money trade copying services
    

* * *

### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#requesting-approval-for-restricted-endpoints)

Requesting Approval for Restricted Endpoints

**Step 1: Submit Your Request**

Complete the approval form: [https://forms.gle/AoXk9jRdbuiqqG5f9](https://forms.gle/AoXk9jRdbuiqqG5f9)

**Step 2: Provide Required Information**

1.  Describe your product, how you'll use the data, and your target audience
    
2.  Explain modifications, other data sources, and provide mockups
    
3.  Show unique insights and differentiation from Nansen's products
    
4.  Detail how you'll credit Nansen and potential partnership opportunities
    

* * *

### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#attribution-guidelines)

Attribution Guidelines

**When Attribution is Required**

Required for endpoints marked "✅ Allowed (with attribution)" or "⚠️ Restricted".

**How to Attribute**

Choose one:

*   **Text**: "Powered by Nansen API" or similar, displayed near the data
    
*   **Logo**: Nansen logo with link to [nansen.ai](https://nansen.ai/)
    
*   **Footer**: "Blockchain analytics powered by [Nansen](https://nansen.ai/)
    "
    

**When Attribution is NOT Required**

*   Personal or internal use only
    
*   Endpoints marked "✅ Allowed" (no attribution noted)
    

* * *

### 

[](https://docs.nansen.ai/nansen-mcp/overview/mcp-data-redistribution-guidelines#general-rules-and-compliance)

General Rules & Compliance

**1\. Terms of Service**

*   Must comply with Nansen's [Terms of Service](https://www.nansen.ai/legal/terms-of-services)
    

**2\. Stay Updated**

*   Check latest guidelines before launching products, changing data usage, or entering new markets
    

**3\. API & MCP Coverage**

*   Rules apply to API responses, MCP tools, and derived data
    

**4\. Volume & Rate Limits**

*   Redistribution doesn't exempt you from rate limits
    

**5\. Data Accuracy**

*   Don't misrepresent data
    
*   Include appropriate disclaimers
    
*   Don't make unwarranted guarantees
    

**6\. Competitive Use**

*   Don't build competing products
    
*   Don't use Nansen data as foundation for competitor services
    
*   Don't repackage data to commoditize Nansen's insights
    

[PreviousCommon MCP clients](https://docs.nansen.ai/nansen-mcp/overview/common-mcp-clients)
[NextData Redistribution Guidelines](https://docs.nansen.ai/guides/data-redistribution-guidelines)

Last updated 4 days ago

Was this helpful?

---