> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dialect.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Historical Position Data

> Track position value changes over time with historical snapshots from the Markets and Positions API.

<Check>
  Historical data is available from **October 8, 2025** onwards. Backfilling to earlier dates will be added in a future release.
</Check>

## Overview

Historical data allows you to track how your DeFi positions have changed over time.

<CardGroup cols={3}>
  <Card title="Portfolio Tracking" icon="wallet">
    See your total portfolio value across all protocols
  </Card>

  <Card title="Performance Analysis" icon="chart-line">
    Understand returns over time
  </Card>

  <Card title="Historical Charts" icon="chart-area">
    Visualize position growth and changes
  </Card>
</CardGroup>

Historical data tracks **cumulative values**, meaning the raw balances in your positions. This includes natural yield accumulation as well as any deposits or withdrawals you make.

## What Data is Available

Historical snapshots are available for **position attributes only**. These attributes enable you to track your portfolio's value over time in both native tokens and in USD.

| Attribute   | Description                                |
| ----------- | ------------------------------------------ |
| `amount`    | Position balance in native token units     |
| `amountUsd` | Position balance in USD equivalent         |
| `timestamp` | When this snapshot was recorded (RFC 3339) |

## Get Historical Snapshots

Fetch position snapshots for any time range:

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Get history from launch date (Oct 8, 2025) to now
  const endDate = new Date().toISOString();
  const startDate = '2025-10-08T00:00:00Z'; // Historical data starts from this date

  const response = await fetch(
    'https://markets.dial.to/api/v0/positions/history?' + new URLSearchParams({
      walletAddress: '6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176',
      startTime: startDate,
      endTime: endDate
    }),
    {
      headers: {
        'x-dialect-client-key': 'YOUR_CLIENT_KEY'
      }
    }
  );

  const data = await response.json();
  ```

  ```bash cURL theme={null}
  # Replace end date with current date
  curl -X GET "https://markets.dial.to/api/v0/positions/history?walletAddress=6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176&startTime=2025-10-08T00:00:00Z&endTime=2025-10-10T23:59:59Z" \
    -H "x-dialect-client-key: YOUR_CLIENT_KEY"
  ```
</CodeGroup>

### Query Parameters

| Parameter       | Required | Description                                                                                               |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `walletAddress` | Yes      | Wallet address to fetch position history for                                                              |
| `startTime`     | Yes      | Start of time range (RFC 3339 format, e.g., `2025-10-08T00:00:00Z`)                                       |
| `endTime`       | Yes      | End of time range (RFC 3339 format, e.g., `2025-10-10T23:59:59Z`)                                         |
| `positionIds`   | No       | Optional array of position IDs to filter. If empty, returns all positions                                 |
| `resolution`    | No       | Time interval for data points. Options: `1m`, `5m`, `1h`, `1d`. See [Resolution](#resolution) for details |

### Response Structure

In the example below, you see an example of the response structure, that shows the Lulo Regular position with two snapshots showing growth from 1.02 to 2.02 USDC. Later in this document, you will learn how to [use](/markets/history#practical-examples) and [interpret](/markets/history#understanding-cumulative-values) this data.

```json theme={null}
{
  "data": {
    "positions": [
      {
        "id": "lulo.regular.HwE39BAt5i6ymd8hhZbaxTrYf61ifm8PRwJpm4o9ULzj",
        "providerId": "lulo",
        "type": "yield",
        "marketId": "lulo.regular",
        "history": [
          {
            "timestamp": "2025-10-08T16:24:29.000Z",
            "amount": 1.018845,
            "amountUsd": 1.02
          },
          {
            "timestamp": "2025-10-09T21:16:12.000Z",
            "amount": 2.017082,
            "amountUsd": 2.02
          }
        ]
      }
    ]
  }
}
```

<Accordion title="View Full Response (11 positions)">
  The response above shows 2 positions of the response to facilitate readability. The full response for this wallet contains 11 positions across Lulo, Jupiter, and Kamino. The following examples use the complete dataset.

  ```json theme={null}
  {
    "data": {
      "positions": [
        {
          "id": "lulo.protected.HwE39BAt5i6ymd8hhZbaxTrYf61ifm8PRwJpm4o9ULzj",
          "providerId": "lulo",
          "type": "yield",
          "marketId": "lulo.protected",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 1.012845,
              "amountUsd": 1.01
            },
            {
              "timestamp": "2025-10-09T21:21:20.000Z",
              "amount": 1.999995,
              "amountUsd": 2
            }
          ]
        },
        {
          "id": "lulo.regular.HwE39BAt5i6ymd8hhZbaxTrYf61ifm8PRwJpm4o9ULzj",
          "providerId": "lulo",
          "type": "yield",
          "marketId": "lulo.regular",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 1.018845,
              "amountUsd": 1.02
            },
            {
              "timestamp": "2025-10-09T21:16:12.000Z",
              "amount": 2.017082,
              "amountUsd": 2.02
            }
          ]
        },
        {
          "id": "jupiter.earn.SOL.6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
          "providerId": "jupiter",
          "type": "yield",
          "marketId": "jupiter.earn.SOL",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 0.001000981,
              "amountUsd": 0.22
            }
          ]
        },
        {
          "id": "jupiter.borrow.1.2433.deposit",
          "providerId": "jupiter",
          "type": "lending",
          "marketId": "jupiter.borrow.1",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 0.015060546,
              "amountUsd": 3.34
            }
          ]
        },
        {
          "id": "jupiter.borrow.1.2433.borrow",
          "providerId": "jupiter",
          "type": "lending",
          "marketId": "jupiter.borrow.1",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 1.012172,
              "amountUsd": 1.01
            }
          ]
        },
        {
          "id": "jupiter.earn.USDC.6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
          "providerId": "jupiter",
          "type": "yield",
          "marketId": "jupiter.earn.USDC",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 0.100776,
              "amountUsd": 0.1
            }
          ]
        },
        {
          "id": "jupiter.borrow.7.1228.deposit",
          "providerId": "jupiter",
          "type": "lending",
          "marketId": "jupiter.borrow.7",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 1.331889,
              "amountUsd": 1.5
            }
          ]
        },
        {
          "id": "kamino.CnNvZzeBXiLxUmA6b5eP4MYsNCjfeXxDWMDVJtgZpAtU.EVbyPKrHG6WBfm4dLxLMJpUDY43cCAcHSpV3KYjKsktW",
          "providerId": "kamino",
          "type": "lending",
          "marketId": "kamino.EVbyPKrHG6WBfm4dLxLMJpUDY43cCAcHSpV3KYjKsktW",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 0.01643327,
              "amountUsd": 4.5
            }
          ]
        },
        {
          "id": "kamino.3YWBQnwgi7FE7e7Xahuea2eiM8aPAv84nHoAvWUtm2QV.F22tnLsbv66vEU2GZRc7coaqZsr8UcBbyp9V2kqWAiWK",
          "providerId": "kamino",
          "type": "lending",
          "marketId": "kamino.F22tnLsbv66vEU2GZRc7coaqZsr8UcBbyp9V2kqWAiWK",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 0.32602,
              "amountUsd": 0.33
            }
          ]
        },
        {
          "id": "kamino.EYqpfGinjQfcDkKvn7HWTGbxcrCZpeL9pSKgqhgWtAJg.Atj6UREVWa7WxbF2EMKNyfmYUY1U1txughe2gjhcPDCo",
          "providerId": "kamino",
          "type": "lending",
          "marketId": "kamino.Atj6UREVWa7WxbF2EMKNyfmYUY1U1txughe2gjhcPDCo",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 1.013233,
              "amountUsd": 1.01
            }
          ]
        },
        {
          "id": "kamino.CnNvZzeBXiLxUmA6b5eP4MYsNCjfeXxDWMDVJtgZpAtU.d4A2prbA2whesmvHaL88BH6Ewn5N4bTSU2Ze8P6Bc4Q",
          "providerId": "kamino",
          "type": "lending",
          "marketId": "kamino.d4A2prbA2whesmvHaL88BH6Ewn5N4bTSU2Ze8P6Bc4Q",
          "history": [
            {
              "timestamp": "2025-10-08T16:24:29.000Z",
              "amount": 0.012468525,
              "amountUsd": 2.76
            }
          ]
        }
      ]
    }
  }
  ```
</Accordion>

Each position includes:

| Field        | Description                                                                                                          |
| ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `id`         | Unique position identifier                                                                                           |
| `providerId` | Protocol providing the market (e.g., `lulo`, `jupiter`, `kamino`)                                                    |
| `type`       | Position type (`yield`, `lending`, `loop`, `perpetual`)                                                              |
| `marketId`   | Market identifier within the protocol                                                                                |
| `history`    | Array of historical snapshots with `timestamp`, `amount`, and `amountUsd` (limited to 1000 data points per position) |

## Resolution

Resolution let's you control the time interval between data points. This is especially useful if you plan to use the data for charting or analytics.

### Available Options

| Resolution | Interval  | Best For                                          |
| ---------- | --------- | ------------------------------------------------- |
| `1m`       | 1 minute  | Real-time monitoring, very short-term analysis    |
| `5m`       | 5 minutes | Short-term tracking, recent activity              |
| `1h`       | 1 hour    | Daily analysis, medium-term trends                |
| `1d`       | 1 day     | Long-term portfolio tracking, historical analysis |

### Usage

To use resolution, you need to specify the time interval you want to use. For example, to get hourly snapshots, you would use the `1h` resolution.

```typescript {7} theme={null}
// Hourly snapshots example
const response = await fetch(
  'https://markets.dial.to/api/v0/positions/history?' + new URLSearchParams({
    walletAddress: '6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176',
    startTime: '2025-10-08T00:00:00Z',
    endTime: '2025-10-09T23:59:59Z',
    resolution: '1h'
  }),
  {
    headers: {
      'x-dialect-client-key': 'YOUR_CLIENT_KEY'
    }
  }
);
```

<Info>
  **Note:** Each position's history is limited to 1000 data points. Using appropriate resolution values helps you stay within this limit for longer time ranges.
</Info>

## Understanding Cumulative Values

Historical data tracks **cumulative values** - the actual balance in each position at each point in time.

### What This Means

When you look at historical snapshots, the `amount` and `amountUsd` values reflect:

* **Yield** - Accumulated interest earned on deposits
* **Deposits** - When you add funds to a position
* **Withdrawals** - When you remove funds from a position

### Example: Deposits

Here's real data from a Lulo position showing a deposit:

```json theme={null}
// October 8, 2025 - Initial snapshot
{
  "timestamp": "2025-10-08T16:24:29.000Z",
  "amount": 1.018845,
  "amountUsd": 1.02
}

// October 9, 2025 - After a deposit
{
  "timestamp": "2025-10-09T21:16:12.000Z",
  "amount": 2.017082,
  "amountUsd": 2.02
}
```

The jump in the example from \~1.02 to \~2.02 USDC between these two snapshots reflects a deposit action.

## Practical Examples

### Example 1: Calculate Total Portfolio Value

Sum up all position values across protocols:

```typescript theme={null}
const response = await fetch(
  'https://markets.dial.to/api/v0/positions/history?walletAddress=6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176&startTime=2025-10-08T00:00:00Z&endTime=2025-10-10T23:59:59Z',
  {
    headers: {
      'x-dialect-client-key': 'YOUR_CLIENT_KEY'
    }
  }
);

const result = await response.json();

// Calculate total portfolio value in USD
const totalValueUsd = result.data.positions.reduce((total, position) => {
  const latestSnapshot = position.history[position.history.length - 1];
  return total + (latestSnapshot?.amountUsd || 0);
}, 0);

console.log(`Total portfolio value: $${totalValueUsd.toFixed(2)}`);
```

**Output:**

```
Total portfolio value: $18.79
```

### Example 2: Track Specific Position Over Time

Filter for a single position to see its growth:

```typescript theme={null}
const response = await fetch(
  'https://markets.dial.to/api/v0/positions/history?' + new URLSearchParams({
    walletAddress: '6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176',
    startTime: '2025-10-08T00:00:00Z',
    endTime: '2025-10-10T23:59:59Z',
    'positionIds[]': 'lulo.regular.HwE39BAt5i6ymd8hhZbaxTrYf61ifm8PRwJpm4o9ULzj'
  }),
  {
    headers: {
      'x-dialect-client-key': 'YOUR_CLIENT_KEY'
    }
  }
);

const result = await response.json();
const position = result.data.positions[0];

// Show growth over time
position.history.forEach(snapshot => {
  console.log(`${snapshot.timestamp}: ${snapshot.amount} USDC ($${snapshot.amountUsd})`);
});
```

**Output:**

```
2025-10-08T16:24:29.000Z: 1.018845 USDC ($1.02)
2025-10-09T21:16:12.000Z: 2.017082 USDC ($2.02)
```

### Example 3: Compare Positions Across Protocols

See how different protocol positions have performed:

```typescript theme={null}
const response = await fetch(
  'https://markets.dial.to/api/v0/positions/history?walletAddress=6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176&startTime=2025-10-08T00:00:00Z&endTime=2025-10-10T23:59:59Z',
  {
    headers: {
      'x-dialect-client-key': 'YOUR_CLIENT_KEY'
    }
  }
);

const result = await response.json();

// Group by provider
const byProvider = result.data.positions.reduce((acc, position) => {
  const provider = position.providerId;
  const latestSnapshot = position.history[position.history.length - 1];

  if (!acc[provider]) {
    acc[provider] = { totalUsd: 0, positions: 0 };
  }

  acc[provider].totalUsd += latestSnapshot?.amountUsd || 0;
  acc[provider].positions += 1;

  return acc;
}, {});

console.log(byProvider);
```

**Output:**

```json theme={null}
{
  "lulo": { "totalUsd": 4.02, "positions": 2 },
  "jupiter": { "totalUsd": 6.17, "positions": 5 },
  "kamino": { "totalUsd": 8.6, "positions": 4 }
}
```

## API Playground

<Card title="Test the API" href="/api-reference/positions/get-historical-position-snapshots" icon="bolt">
  Play with the API and see the results in real-time.
</Card>