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

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

​
Example Response

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

​
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