Skip to main content

​
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

ParameterTypeRequiredDescription
chainIdnumberNoFilter by chain ID (e.g., 8453 for Base)
protocolstringNoFilter by protocol name (Aave, Compound, Morpho, Euler, Fluid)
isActivebooleanNoFilter by active status (defaults to true)
isStablecoinbooleanNoFilter by stablecoin instruments only
assetCategorystringNoFilter by asset category: USD, EUR, ETH, BTC
sortBystringNoSort field: apy, tvl, createdAt
sortOrderstringNoSort direction: asc, desc
limitnumberNoItems per page (default: 20, max: 100)
offsetnumberNoNumber of items to skip (default: 0)

​
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"
    }
  ],
  "pagination": {
    "total": 18,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

​
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

ParameterTypeRequiredDescription
chainIdnumberYesThe 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

ParameterTypeRequiredDescription
instrumentIdstringYesThe 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';
  sortOrder?: 'asc' | 'desc';
  limit?: number;
  offset?: 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

Quotes API

Get swap quotes

Metrics API

Historical APY and TVL data