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

# Metrics API

> Get historical APY, TVL, and performance metrics

## Get Instrument Metrics

<span style={{color: '#10B981', fontWeight: 'bold'}}>GET</span> `/metrics/instruments/:instrumentId`

Retrieve historical metrics (APY, TVL) for a specific instrument.

### Request

```bash theme={null}
curl "https://api.1tx.fi/api/v1/metrics/instruments/0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b?days=30"
```

### Path Parameters

| Parameter      | Type   | Required | Description               |
| -------------- | ------ | -------- | ------------------------- |
| `instrumentId` | string | Yes      | The instrument identifier |

### Query Parameters

| Parameter | Type   | Required | Description                                      |
| --------- | ------ | -------- | ------------------------------------------------ |
| `days`    | number | No       | Number of days of history to fetch (default: 30) |

### Response

```json theme={null}
{
  "instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
  "metrics": [
    {
      "timestamp": "2024-01-15T00:00:00Z",
      "tvlUsd": 1250000000,
      "apy": 5.2,
      "apyBase": 4.8,
      "apyReward": 0.4
    },
    {
      "timestamp": "2024-01-14T00:00:00Z",
      "tvlUsd": 1240000000,
      "apy": 5.1,
      "apyBase": 4.7,
      "apyReward": 0.4
    }
  ]
}
```

### Response Fields

| Field          | Type   | Description                 |
| -------------- | ------ | --------------------------- |
| `instrumentId` | string | The instrument identifier   |
| `metrics`      | array  | Array of metric data points |

### Metric Data Point

| Field       | Type   | Description                           |
| ----------- | ------ | ------------------------------------- |
| `timestamp` | string | ISO 8601 timestamp                    |
| `tvlUsd`    | number | Total value locked in USD             |
| `apy`       | number | Total APY percentage                  |
| `apyBase`   | number | Base APY from lending (optional)      |
| `apyReward` | number | Reward APY from incentives (optional) |

***

## Get Bulk Instrument Metrics

<span style={{color: '#10B981', fontWeight: 'bold'}}>GET</span> `/metrics/bulk`

Retrieve historical metrics for multiple instruments in a single request.

### Request

```bash theme={null}
curl "https://api.1tx.fi/api/v1/metrics/bulk?instrumentIds=0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b&instrumentIds=0x00002105e1d832a44e229e784c3d4afba9a1ca44a288e34f7e5ddcba23155adc&days=7"
```

### Query Parameters

| Parameter       | Type      | Required | Description                                      |
| --------------- | --------- | -------- | ------------------------------------------------ |
| `instrumentIds` | string\[] | Yes      | Array of instrument IDs (pass multiple times)    |
| `days`          | number    | No       | Number of days of history to fetch (default: 30) |

### Response

```json theme={null}
[
  {
    "instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
    "metrics": [
      {
        "timestamp": "2024-01-15T00:00:00Z",
        "tvlUsd": 1250000000,
        "apy": 5.2,
        "apyBase": 4.8,
        "apyReward": 0.4
      }
    ]
  },
  {
    "instrumentId": "0x00002105e1d832a44e229e784c3d4afba9a1ca44a288e34f7e5ddcba23155adc",
    "metrics": [
      {
        "timestamp": "2024-01-15T00:00:00Z",
        "tvlUsd": 980000000,
        "apy": 4.8,
        "apyBase": 4.5,
        "apyReward": 0.3
      }
    ]
  }
]
```

***

## TypeScript Example

```typescript theme={null}
const BASE_URL = 'https://api.1tx.fi/api/v1';

interface MetricDataPoint {
  timestamp: string;
  tvlUsd: number;
  apy: number;
  apyBase?: number;
  apyReward?: number;
}

interface InstrumentMetrics {
  instrumentId: string;
  metrics: MetricDataPoint[];
}

// Get metrics for a single instrument
async function getInstrumentMetrics(
  instrumentId: string,
  days: number = 30
): Promise<InstrumentMetrics> {
  const response = await fetch(
    `${BASE_URL}/metrics/instruments/${instrumentId}?days=${days}`
  );

  if (!response.ok) {
    throw new Error(`Failed to fetch metrics: ${response.status}`);
  }

  return response.json();
}

// Get metrics for multiple instruments
async function getBulkMetrics(
  instrumentIds: string[],
  days: number = 30
): Promise<InstrumentMetrics[]> {
  const params = new URLSearchParams();
  instrumentIds.forEach((id) => params.append('instrumentIds', id));
  params.set('days', String(days));

  const response = await fetch(`${BASE_URL}/metrics/bulk?${params}`);

  if (!response.ok) {
    throw new Error(`Failed to fetch bulk metrics: ${response.status}`);
  }

  return response.json();
}

// Usage
const metrics = await getInstrumentMetrics(
  '0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b',
  30
);

console.log(`Fetched ${metrics.metrics.length} data points`);

// Calculate average APY over the period
const avgApy =
  metrics.metrics.reduce((sum, m) => sum + m.apy, 0) / metrics.metrics.length;
console.log(`Average APY: ${avgApy.toFixed(2)}%`);

// Get latest TVL
const latestTvl = metrics.metrics[0]?.tvlUsd;
console.log(`Current TVL: $${(latestTvl / 1e6).toFixed(2)}M`);
```

***

## Chart Integration Example

```typescript theme={null}
import { LineChart, Line, XAxis, YAxis, Tooltip } from 'recharts';

function APYChart({ instrumentId }: { instrumentId: string }) {
  const [data, setData] = useState<MetricDataPoint[]>([]);

  useEffect(() => {
    getInstrumentMetrics(instrumentId, 30).then((result) => {
      // Reverse to show oldest first
      setData(result.metrics.reverse());
    });
  }, [instrumentId]);

  return (
    <LineChart width={600} height={300} data={data}>
      <XAxis
        dataKey="timestamp"
        tickFormatter={(t) => new Date(t).toLocaleDateString()}
      />
      <YAxis domain={['auto', 'auto']} />
      <Tooltip
        labelFormatter={(t) => new Date(t).toLocaleString()}
        formatter={(value: number) => [`${value.toFixed(2)}%`, 'APY']}
      />
      <Line type="monotone" dataKey="apy" stroke="#10B981" dot={false} />
    </LineChart>
  );
}
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Instruments API" icon="fingerprint" href="/api-reference/endpoints/instruments">
    Query available instruments
  </Card>

  <Card title="Positions API" icon="wallet" href="/api-reference/endpoints/positions">
    Check user positions
  </Card>
</CardGroup>