API Documentation

Base URL

https://addybook.xyz/api/v1/

Authentication

No authentication required. All endpoints are publicly accessible.

Endpoints

GET /protocol/{protocolId}.json

Get complete contract deployment data for a specific protocol

Parameters

Name	Type	Description
`protocolId`	string	Unique protocol identifier (e.g., "aave-v3", "uniswap-v3")

Example Request

GET https://addybook.xyz/api/v1/protocol/aave-v3.json

Example Response

{
  "id": "aave-v3",
  "name": "Aave V3",
  "type": "lending",
  "website": "https://aave.com",
  "deployments": {
    "ethereum": {
      "chain": "ethereum",
      "addresses": {
        "pool": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        "poolDataProvider": "0x7B4EB56E7CD4b454BA8ff71E4518426369a138a3"
      }
    }
  }
}

GET /search/chain/{chainName}.json

Get all protocols deployed on a specific blockchain

Parameters

Name	Type	Description
`chainName`	string	Blockchain name (e.g., "ethereum", "polygon", "arbitrum")

Example Request

GET https://addybook.xyz/api/v1/search/chain/ethereum.json

Example Response

{
  "chain": "ethereum",
  "chainId": 1,
  "protocols": ["aave-v3", "uniswap-v3", "curve-dex", ...]
}

GET /search/type/{protocolType}.json

Get all protocols of a specific type

Parameters

Name	Type	Description
`protocolType`	string	Protocol type (e.g., "lending", "dex", "yield")

Example Request

GET https://addybook.xyz/api/v1/search/type/lending.json

GET /metadata.json

Get registry metadata including protocol count, chain count, and last update

Example Request

GET https://addybook.xyz/api/v1/metadata.json

Example Response

{
  "version": "1.0.0",
  "lastUpdated": "2026-02-03",
  "stats": {
    "totalProtocols": 4366,
    "populatedProtocols": 8,
    "totalChains": 88,
    "totalCategories": 88
  },
  "chains": ["ethereum", "polygon", "arbitrum", ...],
  "categories": ["lending", "dex", "yield", ...]
}

Rate Limits

No rate limits. All data is served via Cloudflare CDN with global edge caching for optimal performance.

CORS

All endpoints support CORS (Cross-Origin Resource Sharing), allowing direct API calls from web browsers.

Response Format

All responses are in JSON format with UTF-8 encoding. Gzipped versions are available by adding .gz to any endpoint for reduced bandwidth usage.

Example

GET https://addybook.xyz/api/v1/metadata.json.gz

Error Handling

Status Code	Description
`200`	Success
`404`	Protocol, chain, or resource not found

Code Examples

JavaScript / Node.js

// Fetch protocol data
const response = await fetch(
  'https://addybook.xyz/api/v1/protocol/aave-v3.json'
);
const data = await response.json();

console.log(data.deployments.ethereum.addresses.pool);
// 0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2

Python

import requests

# Fetch protocol data
response = requests.get(
    'https://addybook.xyz/api/v1/protocol/aave-v3.json'
)
data = response.json()

print(data['deployments']['ethereum']['addresses']['pool'])
# 0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2

curl

curl https://addybook.xyz/api/v1/protocol/aave-v3.json

OpenAPI Specification

Full OpenAPI 3.0 specification available for integration with API tools like Postman, Insomnia, or Swagger UI.

GET https://addybook.xyz/api/v1/openapi.json