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](./methods).

## Response Format

All endpoints return responses wrapped in an envelope:

```json
{
  "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
?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
curl 'https://api.1inch.com/portfolio/portfolio/v5.0/general/current_value?addresses=0xd470055c6189b921c4d44b3d277ad868f79c0f75' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

Response:

```json
{
  "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
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
{
  "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
curl 'https://api.1inch.com/portfolio/portfolio/v5.0/tokens/snapshot?addresses=0xd470055c6189b921c4d44b3d277ad868f79c0f75' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

**DeFi positions:**

```bash
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
curl 'https://api.1inch.com/portfolio/portfolio/v5.0/tokens/metrics?addresses=0xd470055c6189b921c4d44b3d277ad868f79c0f75&timerange=1year' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

**Protocol metrics:**

```bash
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
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
{
  "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
curl 'https://api.1inch.com/portfolio/portfolio/v5.0/general/chart?addresses=0xd470055c6189b921c4d44b3d277ad868f79c0f75&timerange=1month' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

Response:

```json
{
  "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

| Use case                  | Endpoint                          | Required parameters                         |
| ------------------------- | --------------------------------- | ------------------------------------------- |
| Portfolio total value     | `/general/current_value`          | `addresses`                                 |
| PnL by chain              | `/general/profit_and_loss`        | `addresses`, `timerange`                    |
| Token balances            | `/tokens/snapshot`                | `addresses`                                 |
| DeFi positions            | `/protocols/snapshot`             | `addresses`                                 |
| Token metrics             | `/tokens/metrics`                 | `addresses`, `timerange`                    |
| Protocol metrics          | `/protocols/metrics`              | `addresses`, `timerange`                    |
| Single token analytics    | `/tokens/additional/details`      | `addresses`, `chain_id`, `contract_address` |
| Token transaction history | `/tokens/additional/transactions` | `addresses`, `chain_id`, `contract_address` |
| Portfolio value chart     | `/general/chart`                  | `addresses`, `timerange`                    |
| Single token chart        | `/tokens/additional/charts`       | `addresses`, `chain_id`, `contract_address` |