Skip to main content
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

​
contract
string
required
The contract address to look up. Accepts an EVM address (0x…) or a Solana base58 address.
contract=0x1f98431c8ad98523631ae4a59f267346ea31f984
​
chain
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

​
name
string
Protocol display name (e.g. "Uniswap V3")
​
key
string
Protocol key (e.g. "uniswap-v3")
​
imgSmall
string
URL to small protocol icon
​
imgLarge
string
URL to large protocol icon
​
chainKey
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

The contract parameter is missing.
{
  "error": "Validation Failed",
  "message": "\"contract\" is required"
}
Missing/invalid API key, or your key has no access to this endpoint.
{
  "message": "Unauthorized"
}
Solution: Check your API key in the Authorization header.
Insufficient credits.
{
  "message": "Insufficient credits",
  "creditsNeeded": 5
}
Solution: Purchase more credits at data.octav.fi
No protocol matches the contract address. The credits are refunded.
{
  "message": "No protocol found for contract 0x1f98... [on ethereum]"
}
Rate limit exceeded.
{
  "message": "Rate limit exceeded",
  "retryAfter": 60
}
Solution: Wait for the specified time or implement retry logic.
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