Protocols - Octav Developer Docs

Retrieve a paginated list of DeFi protocols available on a specific blockchain network. Use the chainKey from the Chains endpoint to specify which chain to query.

Cost: Free (0 credits)

Interactive Playground: Test this endpoint in the API Playground. Get your API key at data.octav.fi

Endpoint

GET https://api.octav.fi/v1/chains/:chainKey/protocols

curl -X GET "https://api.octav.fi/v1/chains/ethereum/protocols?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameters

chainKey

string

required

The chain identifier (e.g. ethereum, solana, arbitrum). Must match a chain’s key field from the Chains endpoint.

/v1/chains/ethereum/protocols

page

integer

default:"1"

Page number for pagination

Minimum: 1

limit

integer

default:"20"

Number of protocols per page

Minimum: 1
Maximum: 100

Response

Returns a paginated list of protocol objects.

Top-Level Fields

data

array

Array of protocol objects (see fields below)

pagination

object

Pagination metadata:

page — Current page number
limit — Items per page
hasMore — Whether more pages are available

Protocol Fields

uuid

string

Unique protocol identifier

key

string

Protocol key (e.g. "aave", "uniswap v3")

name

string

Display name (e.g. "Aave", "Uniswap V3")

imgSmall

string

URL to small protocol icon

imgLarge

string

URL to large protocol icon

isUserProtocol

boolean

true if this is a user-created custom protocol. Custom protocols only appear on page 1 and are listed before system protocols.

Example Request

curl "https://api.octav.fi/v1/chains/ethereum/protocols?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

const chainKey = 'ethereum';

const response = await fetch(
  `https://api.octav.fi/v1/chains/${chainKey}/protocols?page=1&limit=20`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);

const { data: protocols, pagination } = await response.json();
console.log(`Found ${protocols.length} protocols (hasMore: ${pagination.hasMore})`);

import requests

chain_key = 'ethereum'

response = requests.get(
    f'https://api.octav.fi/v1/chains/{chain_key}/protocols',
    params={'page': 1, 'limit': 20},
    headers={'Authorization': f'Bearer {api_key}'}
)

result = response.json()
protocols = result['data']
pagination = result['pagination']
print(f'Found {len(protocols)} protocols (hasMore: {pagination["hasMore"]})')

interface Protocol {
  uuid: string;
  key: string;
  name: string;
  imgSmall: string;
  imgLarge: string;
  isUserProtocol: boolean;
}

interface ProtocolResponse {
  data: Protocol[];
  pagination: {
    page: number;
    limit: number;
    hasMore: boolean;
  };
}

const chainKey = 'ethereum';

const response = await fetch(
  `https://api.octav.fi/v1/chains/${chainKey}/protocols?page=1&limit=20`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);

const { data: protocols, pagination }: ProtocolResponse = await response.json();
console.log(`Found ${protocols.length} protocols (hasMore: ${pagination.hasMore})`);

Example Response

{
  "data": [
    {
      "uuid": "abc12345-1234-5678-9abc-def012345678",
      "key": "aave",
      "name": "Aave",
      "imgSmall": "https://images.octav.fi/tokens/small/aave_small_icon.png",
      "imgLarge": "https://images.octav.fi/tokens/large/aave_large_icon.png",
      "isUserProtocol": false
    },
    {
      "uuid": "def67890-1234-5678-9abc-def012345678",
      "key": "uniswap v3",
      "name": "Uniswap V3",
      "imgSmall": "https://images.octav.fi/tokens/small/uniswap_small_icon.png",
      "imgLarge": "https://images.octav.fi/tokens/large/uniswap_large_icon.png",
      "isUserProtocol": false
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

Pagination

The endpoint uses page-based pagination. Use page and limit to navigate through results.

How Pagination Works

Default behavior: Returns 20 protocols per page starting from page 1
hasMore flag: Indicates whether additional pages exist
User protocols: Custom user-created protocols are prepended on page 1 only
Ordering: System protocols are returned in a consistent order

Paginating Through All Protocols

Fetch all protocols for a chain by iterating until hasMore is false:

async function getAllProtocols(chainKey) {
  const allProtocols = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://api.octav.fi/v1/chains/${chainKey}/protocols?page=${page}&limit=100`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );

    const result = await response.json();
    allProtocols.push(...result.data);
    hasMore = result.pagination.hasMore;
    page++;
  }

  return allProtocols;
}

const protocols = await getAllProtocols('ethereum');
console.log(`Total protocols on Ethereum: ${protocols.length}`);

Use Cases

Protocol Selector
Multi-Chain Protocols
Search Protocols

Build a protocol selection dropdown for your UI:

async function loadProtocolOptions(chainKey) {
  const response = await fetch(
    `https://api.octav.fi/v1/chains/${chainKey}/protocols?limit=100`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  );

  const { data: protocols } = await response.json();

  return protocols.map(protocol => ({
    value: protocol.key,
    label: protocol.name,
    icon: protocol.imgSmall,
    isCustom: protocol.isUserProtocol
  }));
}

// Populate dropdown when user selects a chain
const options = await loadProtocolOptions('ethereum');

Find which protocols are available across chains:

async function getProtocolsByChains(chainKeys) {
  const results = {};

  for (const chainKey of chainKeys) {
    const response = await fetch(
      `https://api.octav.fi/v1/chains/${chainKey}/protocols?limit=100`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );

    const { data } = await response.json();
    results[chainKey] = data.map(p => p.key);
  }

  return results;
}

const protocols = await getProtocolsByChains(['ethereum', 'arbitrum', 'base']);
console.log('Ethereum protocols:', protocols.ethereum.length);
console.log('Arbitrum protocols:', protocols.arbitrum.length);

Client-side filtering of protocol results:

async function searchProtocols(chainKey, query) {
  // Fetch all protocols (the API does not expose server-side search)
  const allProtocols = await getAllProtocols(chainKey);

  const lowerQuery = query.toLowerCase();
  return allProtocols.filter(p =>
    p.name.toLowerCase().includes(lowerQuery) ||
    p.key.toLowerCase().includes(lowerQuery)
  );
}

const results = await searchProtocols('ethereum', 'uniswap');
// => [{ name: "Uniswap V2", ... }, { name: "Uniswap V3", ... }]

Error Responses

400 Bad Request

Invalid query parameters.

{
  "error": "Validation Failed",
  "details": {
    "message": "\"limit\" must be less than or equal to 100"
  }
}

Common causes:

page is less than 1
limit exceeds 100

401 Unauthorized

Authentication failed.

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Solution: Check your API key in the Authorization header

404 Not Found

The specified chain key does not exist.

{
  "message": "Chain with key 'xyz' not found"
}

Solution: Use the Chains endpoint to discover valid chain keys

429 Too Many Requests

Rate limit exceeded.

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded your rate limit",
  "retry_after": 60
}

Solution: Wait for the specified time or implement retry logic

Chains

Get all supported chains and their keys

Portfolio

Get portfolio holdings by protocol

Protocol Types Reference

View all protocol type categories

Transactions

Query transactions filtered by protocol

​Endpoint

​Parameters

​Response

​Top-Level Fields

​Protocol Fields

​Example Request

​Example Response

​Pagination

​Use Cases

​Error Responses

​Related Endpoints

Chains

Portfolio

Protocol Types Reference

Transactions

Endpoint

Parameters

Response

Top-Level Fields

Protocol Fields

Example Request

Example Response

Pagination

Use Cases

Error Responses

Related Endpoints