Quickstart guide

Base URL (unified gateway at https://api.1inch.com): https://api.1inch.com/portfolio/portfolio/v5.0

The OpenAPI paths for the Portfolio service are /portfolio/v5.0/.... On the unified gateway, use an extra /portfolio segment so requests are routed correctly (the gateway strips the first /portfolio before forwarding). The same applies to the MCP product_api tool: use paths starting with /portfolio/portfolio/v5.0.

Portfolio API provides real-time and historical data about wallet holdings across multiple blockchains. Track token balances, DeFi positions, profit and loss, and portfolio value over time.

This guide covers the most common use cases to get you started quickly. For full API reference, see the Open API specifications.

Response Format

All endpoints return responses wrapped in an envelope:

         
         

           JSON
         
 
         
         

           
           

             
1
2
3
4
           
 
           
           
{
  "result": { ... },
  "meta": { ... }
}
         
       

Your data is always in result. The meta field contains optional metadata (pagination, warnings, etc.).

Multiple Wallets

Pass multiple addresses parameters to aggregate data across wallets:

         
         

           Bash
         
 
         
         

           
           

             
1
           
 
           
           
?addresses=0xabc...&addresses=0xdef...&addresses=0x123...
         
       

The API will return combined results. Individual wallet breakdowns are available in by_address field where supported.

Getting Started

1. Get Total Portfolio Value

Returns USD value of all assets (tokens + DeFi positions) broken down by category, chain, and protocol.

         
         

           Bash
         
 
         
         

           
           

             
1
2
           
 
           
           
curl 'https://api.1inch.com/portfolio/portfolio/v5.0/general/current_value?addresses=0xd470055c6189b921c4d44b3d277ad868f79c0f75' \
  -H 'Authorization: Bearer YOUR_API_KEY'
         
       

Response:

         
         

           JSON
         
 
         
         

           
           

             
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
           
 
           
           
{
  "result": {
    "total": 12543.87,
    "by_category": [
      { "category_id": "tokens", "category_name": "Tokens", "value_usd": 8234.12 },
      { "category_id": "protocols", "category_name": "Protocols", "value_usd": 3106.3 },
      { "category_id": "native", "category_name": "Native", "value_usd": 1203.45 }
    ],
    "by_chain": [
      { "chain_id": 1, "chain_name": "Ethereum", "value_usd": 9500.0 },
      { "chain_id": 137, "chain_name": "Polygon", "value_usd": 3043.87 }
    ],
    "by_protocol_group": [{ "protocol_group_id": "aave", "protocol_group_name": "Aave", "value_usd": 2500.0 }]
  }
}
         
       

Notes:

• tokens = ERC-20 tokens and SPL tokens
• native = ETH, MATIC, BNB, etc.
• protocols = value locked in DeFi (lending, LPs, staking, etc.)

2. Get Profit and Loss

Returns realized + unrealized PnL for a given timerange, grouped by chain.

         
         

           Bash
         
 
         
         

           
           

             
1
2
           
 
           
           
curl 'https://api.1inch.com/portfolio/portfolio/v5.0/general/profit_and_loss?addresses=0xd470055c6189b921c4d44b3d277ad868f79c0f75&timerange=1year' \
  -H 'Authorization: Bearer YOUR_API_KEY'
         
       

Response:

         
         

           JSON
         
 
         
         

           
           

             
1
2
3
4
5
6
7
           
 
           
           
{
  "result": [
    { "chain_id": 1, "abs_profit_usd": 2341.56 },
    { "chain_id": 137, "abs_profit_usd": -128.3 },
    { "chain_id": null, "abs_profit_usd": 2213.26 }
  ]
}
         
       

Notes:

• chain_id: null = aggregated total across all chains
• Negative values indicate a loss

3. Get Token Holdings and DeFi Positions

Token balances:

         
         

           Bash
         
 
         
         

           
           

             
1
2
           
 
           
           
curl 'https://api.1inch.com/portfolio/portfolio/v5.0/tokens/snapshot?addresses=0xd470055c6189b921c4d44b3d277ad868f79c0f75' \
  -H 'Authorization: Bearer YOUR_API_KEY'
         
       

DeFi positions:

         
         

           Bash
         
 
         
         

           
           

             
1
2
           
 
           
           
curl 'https://api.1inch.com/portfolio/portfolio/v5.0/protocols/snapshot?addresses=0xd470055c6189b921c4d44b3d277ad868f79c0f75' \
  -H 'Authorization: Bearer YOUR_API_KEY'
         
       

Notes:

• Add chain_id parameter to filter by specific chain
• Add timestamp (unix seconds) to get historical snapshot

4. Get Token and Protocol Metrics

Returns PnL, ROI, inflows/outflows for each token or protocol position.

Token metrics:

         
         

           Bash
         
 
         
         

           
           

             
1
2
           
 
           
           
curl 'https://api.1inch.com/portfolio/portfolio/v5.0/tokens/metrics?addresses=0xd470055c6189b921c4d44b3d277ad868f79c0f75&timerange=1year' \
  -H 'Authorization: Bearer YOUR_API_KEY'
         
       

Protocol metrics:

         
         

           Bash
         
 
         
         

           
           

             
1
2
           
 
           
           
curl 'https://api.1inch.com/portfolio/portfolio/v5.0/protocols/metrics?addresses=0xd470055c6189b921c4d44b3d277ad868f79c0f75&timerange=1year' \
  -H 'Authorization: Bearer YOUR_API_KEY'
         
       

Notes:

• Returns a list of metrics per token/protocol position
• Each item includes profit_abs_usd, roi, inflow_usd, outflow_usd, etc.

5. Get Single Token Details

Returns detailed analytics for a specific token: average buy price, inflows, outflows, PnL.

         
         

           Bash
         
 
         
         

           
           

             
1
2
           
 
           
           
curl 'https://api.1inch.com/portfolio/portfolio/v5.0/tokens/additional/details?addresses=0xd470055c6189b921c4d44b3d277ad868f79c0f75&chain_id=1&contract_address=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&timerange=1year' \
  -H 'Authorization: Bearer YOUR_API_KEY'
         
       

Response:

         
         

           JSON
         
 
         
         

           
           

             
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
           
 
           
           
{
  "result": {
    "chain": 1,
    "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "symbol": "USDC",
    "name": "USD Coin",
    "amount": 5000.0,
    "price_to_usd": 1.0,
    "value_usd": 5000.0,
    "abs_profit_usd": 127.45,
    "roi": 0.026,
    "average_price_usd": 0.998,
    "average_price_usd_period": 0.999,
    "value_inflow_usd": 4800.0,
    "value_outflow_usd": 320.0,
    "value_inflow_usd_period": 2400.0,
    "value_outflow_usd_period": 150.0
  }
}
         
       

Notes:

• average_price_usd = all-time average purchase price
• average_price_usd_period = average price within requested timerange
• roi = return on investment as decimal (0.026 = 2.6%)
• *_period fields = values calculated only for the requested timerange

6. Get Portfolio Value Chart

Returns time series data for plotting portfolio value over time.

         
         

           Bash
         
 
         
         

           
           

             
1
2
           
 
           
           
curl 'https://api.1inch.com/portfolio/portfolio/v5.0/general/chart?addresses=0xd470055c6189b921c4d44b3d277ad868f79c0f75&timerange=1month' \
  -H 'Authorization: Bearer YOUR_API_KEY'
         
       

Response:

         
         

           JSON
         
 
         
         

           
           

             
1
2
3
4
5
6
7
           
 
           
           
{
  "result": [
    { "timestamp": 1704067200, "value_usd": 10234.50 },
    { "timestamp": 1704153600, "value_usd": 10456.78 },
    ...
  ]
}
         
       

Notes:

• Timestamps are Unix epoch seconds (UTC)
• Data points interval: 5min for 1day, 30min for 1week, 2h for 1month, daily for 1year, weekly for 3years

Common Use Cases