Instruments API - 1tx Documentation

List All Instruments

GET /instruments Retrieve a list of all available DeFi instruments with optional filtering and sorting.

Request

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

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

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

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 (except chainId which is in the path).

Response

Same structure as List All Instruments.

Get Single Instrument

GET /instruments/:instrumentId Retrieve detailed information about a specific instrument.

Request

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

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

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

Chains API

Get supported chains and contracts

Positions API

Query user positions

Metrics API

Historical APY and TVL data

​List All Instruments

​Request

​Query Parameters

​Enriched Request

​Response

​Optional Enriched Fields

​List Instruments by Chain

​Request

​Path Parameters

​Query Parameters

​Response

​Get Single Instrument

​Request

​Path Parameters

​Response

​TypeScript Example

​Next Steps

Chains API

Positions API

Metrics API

List All Instruments

Request

Query Parameters

Enriched Request

Response

Optional Enriched Fields

List Instruments by Chain

Request

Path Parameters

Query Parameters

Response

Get Single Instrument

Request

Path Parameters

Response

TypeScript Example

Next Steps