Contract Protocol

Resolve a contract address to the DeFi protocol it belongs to. Provide a chain to look up a single protocol on that chain, or omit it to search the address across every chain Octav knows it on.

Cost: 5 credits per lookup. The credits are refunded if no protocol is found (404).

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

Endpoint

GET https://api.octav.fi/v1/contract-protocol

curl "https://api.octav.fi/v1/contract-protocol?contract=0x1f98431c8ad98523631ae4a59f267346ea31f984&chain=ethereum" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameters

string

required

The contract address to look up. Accepts an EVM address (0x…) or a Solana base58 address.

contract=0x1f98431c8ad98523631ae4a59f267346ea31f984

string

Chain key (e.g. ethereum, arbitrum, base, polygon, solana). Match a chain’s key field from the Chains endpoint.If omitted, the endpoint returns every chain the address is known on.

Response

The response shape depends on whether you provide chain:

chain provided → a single { protocol } object.
chain omitted → a { protocols } array, where each entry is additionally tagged with its chainKey. The array is unordered.

Because the top-level field differs (protocol vs protocols), branch on which key is present rather than assuming a fixed shape.

Protocol Fields

string

Protocol display name (e.g. "Uniswap V3")

string

Protocol key (e.g. "uniswap-v3")

string

URL to small protocol icon

string

URL to large protocol icon

string

Chain the match belongs to. Only present in the array response (when chain is omitted).

Example Request

# Single chain
curl "https://api.octav.fi/v1/contract-protocol?contract=0x1f98431c8ad98523631ae4a59f267346ea31f984&chain=ethereum" \
  -H "Authorization: Bearer YOUR_API_KEY"

# All chains (address only)
curl "https://api.octav.fi/v1/contract-protocol?contract=0x1f98431c8ad98523631ae4a59f267346ea31f984" \
  -H "Authorization: Bearer YOUR_API_KEY"

async function getContractProtocol(contract, chain) {
  const params = new URLSearchParams({ contract });
  if (chain) params.set('chain', chain);

  const response = await fetch(
    `https://api.octav.fi/v1/contract-protocol?${params}`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  );

  const data = await response.json();
  // Single match when chain is given, array of matches otherwise
  return data.protocol ?? data.protocols;
}

const single = await getContractProtocol(
  '0x1f98431c8ad98523631ae4a59f267346ea31f984',
  'ethereum'
);
const allChains = await getContractProtocol(
  '0x1f98431c8ad98523631ae4a59f267346ea31f984'
);

import requests

def get_contract_protocol(contract, chain=None):
    params = {'contract': contract}
    if chain:
        params['chain'] = chain

    response = requests.get(
        'https://api.octav.fi/v1/contract-protocol',
        params=params,
        headers={'Authorization': f'Bearer {api_key}'}
    )

    data = response.json()
    # Single match when chain is given, array of matches otherwise
    return data.get('protocol') or data.get('protocols')

single = get_contract_protocol(
    '0x1f98431c8ad98523631ae4a59f267346ea31f984',
    chain='ethereum'
)
all_chains = get_contract_protocol(
    '0x1f98431c8ad98523631ae4a59f267346ea31f984'
)

interface Protocol {
  name: string;
  key: string;
  imgSmall: string;
  imgLarge: string;
}

interface ProtocolWithChain extends Protocol {
  chainKey: string;
}

type SingleResponse = { protocol: Protocol };
type MultiResponse = { protocols: ProtocolWithChain[] };

async function getContractProtocol(
  contract: string,
  chain?: string
): Promise<Protocol | ProtocolWithChain[]> {
  const params = new URLSearchParams({ contract });
  if (chain) params.set('chain', chain);

  const response = await fetch(
    `https://api.octav.fi/v1/contract-protocol?${params}`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  );

  const data: SingleResponse | MultiResponse = await response.json();
  return 'protocol' in data ? data.protocol : data.protocols;
}

Example Response

{
  "protocol": {
    "name": "Uniswap V3",
    "key": "uniswap-v3",
    "imgSmall": "https://images.octav.fi/...small.png",
    "imgLarge": "https://images.octav.fi/...large.png"
  }
}

{
  "protocols": [
    {
      "name": "Uniswap V3",
      "key": "uniswap-v3",
      "imgSmall": "https://images.octav.fi/...small.png",
      "imgLarge": "https://images.octav.fi/...large.png",
      "chainKey": "ethereum"
    },
    {
      "name": "Uniswap V3",
      "key": "uniswap-v3",
      "imgSmall": "https://images.octav.fi/...small.png",
      "imgLarge": "https://images.octav.fi/...large.png",
      "chainKey": "arbitrum"
    }
  ]
}

Error Responses

400 Bad Request

The contract parameter is missing.

{
  "error": "Validation Failed",
  "message": "\"contract\" is required"
}

401 Unauthorized

Missing/invalid API key, or your key has no access to this endpoint.

{
  "message": "Unauthorized"
}

Solution: Check your API key in the Authorization header.

402 Payment Required

Insufficient credits.

{
  "message": "Insufficient credits",
  "creditsNeeded": 5
}

Solution: Purchase more credits at data.octav.fi

404 Not Found

No protocol matches the contract address. The credits are refunded.

{
  "message": "No protocol found for contract 0x1f98... [on ethereum]"
}

429 Too Many Requests

Rate limit exceeded.

{
  "message": "Rate limit exceeded",
  "retryAfter": 60
}

Solution: Wait for the specified time or implement retry logic.

500 Internal Server Error

Unexpected server error.

{
  "message": "Error while searching for contract protocol"
}

Protocols

List all DeFi protocols on a specific chain

Chains

Get all supported chains and their keys

Portfolio

Get portfolio holdings by protocol

Protocol Types Reference

View all protocol type categories

Getting Started

Endpoints

Playground

AI Development

Migrate to Octav

Reference

Endpoint

Parameters

Response

Protocol Fields

Example Request

Example Response

Error Responses

Protocols

Chains

Portfolio

Protocol Types Reference

​Endpoint

​Parameters

​Response

​Protocol Fields

​Example Request

​Example Response

​Error Responses

​Related Endpoints

Protocols

Chains

Portfolio

Protocol Types Reference

Endpoint

Parameters

Response

Protocol Fields

Example Request

Example Response

Error Responses

Related Endpoints