> ## 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.
# Instruments API
> Query and discover DeFi instruments
## List All Instruments
GET `/instruments`
Retrieve a list of all available DeFi instruments with optional filtering and sorting.
### Request
```bash theme={null}
curl "https://api.1tx.fi/api/v1/instruments?protocol=Aave&sortBy=apy&sortOrder=desc"
```
### Query Parameters
| Parameter | Type | Required | Description |
| ------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `chainId` | number | No | Filter by chain ID (e.g., 8453 for Base) |
| `protocol` | string | No | Filter by protocol name (Aave, Compound, Morpho, Euler, Fluid) |
| `isActive` | boolean | No | Filter by active status (defaults to `true`) |
| `isStablecoin` | boolean | No | Filter by stablecoin instruments only |
| `assetCategory` | string | No | Filter by asset category: `USD`, `EUR`, `ETH`, `BTC` |
| `sortBy` | string | No | Sort field: `apy`, `tvl`, `createdAt`, `cv`, `rewardShare`, `historyDays`. Metric-derived sort fields force enrichment |
| `sortOrder` | string | No | Sort direction: `asc`, `desc` |
| `limit` | number | No | Items per page (default: 20, max: 100) |
| `offset` | number | No | Number of items to skip (default: 0) |
| `enrich` | boolean | No | Attach metric-derived fields: `coefficientOfVariation`, `historyDays`, `rewardSharePct`, and `tier` |
| `tier` | string | No | Filter by data-derived tier: `Core`, `Yield`, `Frontier`. Forces enrichment |
| `maxCv` | number | No | Keep only instruments whose APY coefficient of variation is less than or equal to this value. Forces enrichment |
| `minHistoryDays` | number | No | Keep only instruments with at least this many APY history days. Forces enrichment |
| `maxRewardSharePct` | number | No | Keep only instruments whose reward-APY share percentage is less than or equal to this value. Forces enrichment |
Enriched filters and sorts are computed from synced metrics. The default listing path remains SQL-paginated, while enriched requests load the filtered universe, attach metrics, then sort/filter/paginate in memory.
### Enriched Request
```bash theme={null}
curl -H "x-api-key: your-api-key" \
"https://api.1tx.fi/api/v1/instruments?enrich=true&tier=Core&maxCv=0.2&minHistoryDays=90&sortBy=cv&sortOrder=asc"
```
### Response
```json theme={null}
{
"data": [
{
"instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
"protocol": "Aave",
"protocolInfo": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Aave",
"version": 3,
"displayName": "Aave V3",
"icon": "https://...",
"docsUrl": "https://docs.aave.com",
"deprecated": false
},
"chainId": 8453,
"protocolAddress": "0x...",
"marketId": "0x...",
"adapterAddress": "0xBACC8882E2a9f5a67570E1BC10d87062dB68dfDd",
"tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"tokenSymbol": "USDC",
"yieldTokenAddress": "0x...",
"yieldTokenSymbol": "aUSDC",
"description": "Aave V3 USDC lending pool on Base",
"symbol": "USDC",
"currentApy": 5.2,
"tvl": 1250000000,
"lastSyncedAt": "2024-01-15T14:30:00Z",
"isActive": true,
"isStablecoin": true,
"assetCategory": "USD",
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T14:30:00Z",
"coefficientOfVariation": 0.12,
"historyDays": 180,
"rewardSharePct": 3.85,
"tier": "Core"
}
],
"pagination": {
"total": 18,
"limit": 20,
"offset": 0,
"hasMore": true
}
}
```
### Optional Enriched Fields
These fields are present only when `enrich=true` or when an enriched sort/filter is requested.
| Field | Type | Description |
| ------------------------ | -------------- | ----------------------------------------------------------------------------------- |
| `coefficientOfVariation` | number \| null | APY standard deviation divided by mean. Lower values indicate steadier quoted yield |
| `historyDays` | number | Number of APY history days available for the instrument |
| `rewardSharePct` | number | Share of current APY driven by reward APY, as a percentage |
| `tier` | string | Data-derived tier: `Core`, `Yield`, or `Frontier` |
***
## List Instruments by Chain
GET `/instruments/by-chain/:chainId`
Retrieve all instruments for a specific blockchain.
### Request
```bash theme={null}
curl "https://api.1tx.fi/api/v1/instruments/by-chain/8453?sortBy=apy&sortOrder=desc"
```
### Path Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------- |
| `chainId` | number | Yes | The chain ID (e.g., 8453 for Base) |
### Query Parameters
Same as [List All Instruments](#list-all-instruments) (except `chainId` which is in the path).
### Response
Same structure as [List All Instruments](#list-all-instruments).
***
## Get Single Instrument
GET `/instruments/:instrumentId`
Retrieve detailed information about a specific instrument.
### Request
```bash theme={null}
curl "https://api.1tx.fi/api/v1/instruments/0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b"
```
### Path Parameters
| Parameter | Type | Required | Description |
| -------------- | ------ | -------- | ---------------------------------------------- |
| `instrumentId` | string | Yes | The unique instrument identifier (bytes32 hex) |
### Response
```json theme={null}
{
"instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
"protocol": "Aave",
"protocolInfo": {
"id": "uuid",
"name": "Aave",
"version": 3,
"displayName": "Aave V3",
"icon": "https://...",
"docsUrl": "https://docs.aave.com",
"deprecated": false
},
"chainId": 8453,
"protocolAddress": "0x...",
"marketId": "0x...",
"adapterAddress": "0xBACC8882E2a9f5a67570E1BC10d87062dB68dfDd",
"tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"tokenSymbol": "USDC",
"yieldTokenAddress": "0x...",
"yieldTokenSymbol": "aUSDC",
"description": "Aave V3 USDC lending pool on Base",
"symbol": "USDC",
"currentApy": 5.2,
"tvl": 1250000000,
"lastSyncedAt": "2024-01-15T14:30:00Z",
"isActive": true,
"isStablecoin": true,
"assetCategory": "USD",
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T14:30:00Z"
}
```
***
## TypeScript Example
```typescript theme={null}
const BASE_URL = 'https://api.1tx.fi/api/v1';
// List all instruments
async function getInstruments(params?: {
chainId?: number;
protocol?: string;
isActive?: boolean;
sortBy?: 'apy' | 'tvl' | 'createdAt' | 'cv' | 'rewardShare' | 'historyDays';
sortOrder?: 'asc' | 'desc';
limit?: number;
offset?: number;
enrich?: boolean;
tier?: 'Core' | 'Yield' | 'Frontier';
maxCv?: number;
minHistoryDays?: number;
maxRewardSharePct?: number;
}) {
const searchParams = new URLSearchParams();
if (params) {
Object.entries(params).forEach(([key, value]) => {
if (value !== undefined) searchParams.set(key, String(value));
});
}
const response = await fetch(`${BASE_URL}/instruments?${searchParams}`);
return response.json();
}
// Get instruments by chain
async function getInstrumentsByChain(chainId: number) {
const response = await fetch(`${BASE_URL}/instruments/by-chain/${chainId}`);
return response.json();
}
// Get single instrument
async function getInstrument(instrumentId: string) {
const response = await fetch(`${BASE_URL}/instruments/${instrumentId}`);
return response.json();
}
// Usage
const instruments = await getInstruments({
protocol: 'Aave',
sortBy: 'apy',
sortOrder: 'desc',
limit: 20,
});
console.log(`Found ${instruments.pagination.total} instruments`);
```
***
## Next Steps
Get supported chains and contracts
Query user positions
Get swap quotes
Historical APY and TVL data