# ContractABI API - Full Documentation

> Free REST API for smart contract ABIs across all EVM chains.
> Base URL: https://contractabi.com

---

## Authentication

No authentication required. All endpoints are publicly accessible.

---

## Rate Limits

- 100 requests per minute per IP
- ABI fetches may be slower on first request (cached thereafter)

---

## Endpoints

### GET /health

Health check endpoint.

**Response:**
```json
{
  "status": "healthy",
  "timestamp": "2025-01-01T00:00:00.000Z"
}
```

**Example:**
```bash
curl https://contractabi.com/health
```

---

### GET /stats

Returns aggregate statistics about the indexed contract database.

**Response:**
```json
{
  "contracts": {
    "total": 12345,
    "withNameTags": 8901
  },
  "chainsSupported": 15
}
```

**Example:**
```bash
curl https://contractabi.com/stats
```

---

### GET /:chainId/:address

Fetch the ABI for a smart contract on any EVM chain.

**Path Parameters:**
| Parameter | Type   | Description                         |
|-----------|--------|-------------------------------------|
| chainId   | number | EVM chain ID (e.g., 1 for Ethereum) |
| address   | string | Contract address (0x-prefixed, 40 hex chars) |

**Response:**
```json
{
  "success": true,
  "chainId": 1,
  "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "abi": [...],
  "source": "explorer",
  "contractName": "FiatTokenV2_2",
  "nameTag": "USD Coin",
  "explorerUrl": "https://explorer.example/address/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "relatedContracts": {
    "totalCalls": 5,
    "totalCalledBy": 12,
    "lastAnalyzed": "2025-01-01T00:00:00.000Z"
  }
}
```

**Error Response (404):**
```json
{
  "success": false,
  "chainId": 1,
  "contractAddress": "0x...",
  "error": "Contract not verified or not found on any explorer",
  "triedExplorers": ["explorer-1", "explorer-2"],
  "explorerErrors": ["Contract source code not verified"]
}
```

**Common Chain IDs:**
| Chain ID | Network      |
|----------|-------------|
| 1        | Ethereum    |
| 137      | Polygon     |
| 8453     | Base        |
| 42161    | Arbitrum    |
| 10       | Optimism    |
| 56       | BNB Chain   |
| 43114    | Avalanche   |
| 100      | Gnosis      |

**Examples:**
```bash
# Ethereum USDC
curl https://contractabi.com/1/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48

# Base USDC
curl https://contractabi.com/8453/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

# Polygon USDC
curl https://contractabi.com/137/0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174
```

---

### GET /search

Search indexed contracts by name, tag, or address.

**Query Parameters:**
| Parameter | Type   | Required | Default | Description                    |
|-----------|--------|----------|---------|--------------------------------|
| q         | string | No       | -       | Search query (name, tag, address) |
| chainId   | number | No       | -       | Filter by chain ID             |
| page      | number | No       | 1       | Page number                    |
| limit     | number | No       | 20      | Results per page (max 100)     |

**Response:**
```json
{
  "success": true,
  "results": [
    {
      "chainId": 1,
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "name": "FiatTokenV2_2",
      "nameTag": "USD Coin",
      "explorerUrl": "https://explorer.example/address/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}
```

**Examples:**
```bash
# Search for Uniswap contracts
curl "https://contractabi.com/search?q=uniswap"

# Search on Polygon only
curl "https://contractabi.com/search?q=aave&chainId=137"

# Paginated results
curl "https://contractabi.com/search?q=token&page=2&limit=50"
```

---

### GET /list

List contracts with usage statistics, optionally filtered by chain.

**Query Parameters:**
| Parameter | Type   | Required | Default | Description                           |
|-----------|--------|----------|---------|---------------------------------------|
| chainId   | number | No       | -       | Filter by chain ID                    |
| page      | number | No       | 1       | Page number                           |
| limit     | number | No       | 20      | Results per page (max 100)            |
| sortBy    | string | No       | tx_30d  | Sort by: tx_30d, users_30d, tx_7d, users_7d |

**Response:**
```json
{
  "success": true,
  "results": [
    {
      "chainId": 1,
      "address": "0x...",
      "name": "ContractName",
      "nameTag": "Protocol Name",
      "txNumber30Days": 1234567,
      "txNumber7Days": 345678,
      "users30Days": 56789,
      "users7Days": 12345
    }
  ],
  "total": 500,
  "page": 1,
  "limit": 20,
  "sortBy": "tx_30d"
}
```

**Examples:**
```bash
# List trending contracts by 30-day transactions
curl "https://contractabi.com/list?sortBy=tx_30d"

# List Base contracts by users
curl "https://contractabi.com/list?chainId=8453&sortBy=users_30d"
```

---

### GET /:chainId/:address/related

Get contracts that interact with or are called by the specified contract.

**Path Parameters:**
| Parameter | Type   | Description                         |
|-----------|--------|-------------------------------------|
| chainId   | number | EVM chain ID                        |
| address   | string | Contract address (0x-prefixed)      |

**Response (200 - data available):**
```json
{
  "success": true,
  "chainId": 1,
  "contractAddress": "0x...",
  "contractName": "FiatTokenV2_2",
  "contractNameTag": "USD Coin",
  "calls": [
    {
      "address": "0x...",
      "interactionCount": 5000,
      "topFunctions": [
        { "signature": "transfer(address,uint256)", "functionName": "transfer", "count": 3000 }
      ],
      "lastSeen": "2025-01-01T00:00:00.000Z",
      "nameTag": "Uniswap V3: Router",
      "contractName": "SwapRouter"
    }
  ],
  "calledBy": [...],
  "totalCalls": 5,
  "totalCalledBy": 12,
  "lastUpdated": "2025-01-01T00:00:00.000Z",
  "dataSource": "dune"
}
```

**Response (202 - analysis in progress):**
```json
{
  "success": true,
  "chainId": 1,
  "contractAddress": "0x...",
  "calls": [],
  "calledBy": [],
  "totalCalls": 0,
  "totalCalledBy": 0,
  "message": "Analysis triggered. Check back in a few minutes.",
  "analyzing": true
}
```

**Example:**
```bash
curl https://contractabi.com/1/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/related
```

---

### POST /:chainId/:address/analyze

Trigger a relationship analysis for a contract using automated workflows.

**Path Parameters:**
| Parameter | Type   | Description                         |
|-----------|--------|-------------------------------------|
| chainId   | number | EVM chain ID                        |
| address   | string | Contract address (0x-prefixed)      |

**Query Parameters:**
| Parameter | Type   | Required | Default | Description                               |
|-----------|--------|----------|---------|-------------------------------------------|
| strategy  | string | No       | hybrid  | Analysis strategy: dune, explorer, hybrid |

**Response (202 - started):**
```json
{
  "success": true,
  "message": "Analysis workflow started",
  "workflowId": "abc123",
  "chainId": 1,
  "contractAddress": "0x...",
  "strategy": "hybrid",
  "statusUrl": "/1/0x.../related"
}
```

**Response (409 - already running):**
```json
{
  "success": false,
  "message": "Analysis already in progress",
  "workflowId": "abc123",
  "startedAt": "2025-01-01T00:00:00.000Z"
}
```

**Example:**
```bash
curl -X POST "https://contractabi.com/1/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/analyze?strategy=hybrid"
```

---

### POST /api/decode

Decode transaction calldata into function signatures.

**Request Body:**
```json
{
  "calldata": "0xa9059cbb000000000000000000000000...",
  "chainId": 1,
  "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}
```

| Field    | Type   | Required | Description                                |
|----------|--------|----------|--------------------------------------------|
| calldata | string | Yes      | Transaction calldata (hex string)          |
| chainId  | number | No       | Chain ID for ABI lookup                    |
| address  | string | No       | Contract address for ABI lookup            |

**Response:**
```json
{
  "success": true,
  "selector": "0xa9059cbb",
  "calldata": "0xa9059cbb000000000000000000000000...",
  "signatures": [
    "transfer(address,uint256)"
  ],
  "contract": {
    "contractName": "FiatTokenV2_2",
    "nameTag": "USD Coin",
    "abi": [...]
  }
}
```

**Example:**
```bash
curl -X POST https://contractabi.com/api/decode \
  -H "Content-Type: application/json" \
  -d '{"calldata": "0xa9059cbb0000000000000000000000001234567890abcdef1234567890abcdef12345678000000000000000000000000000000000000000000000000000000003b9aca00", "chainId": 1, "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"}'
```

---

### GET /sync

Manually trigger sync of trending contracts. Contracts are fetched from multiple analytics sources covering Ethereum, Base, Polygon, Arbitrum, Optimism, Avalanche, and BNB Chain.

**Response:**
```json
{
  "success": true,
  "message": "Sync process initiated",
  "processed": 500,
  "queued": 450
}
```

**Example:**
```bash
curl https://contractabi.com/sync
```

---

## Error Responses

All error responses follow this format:

```json
{
  "success": false,
  "error": "Description of the error"
}
```

**HTTP Status Codes:**
| Code | Description                            |
|------|----------------------------------------|
| 200  | Success                                |
| 202  | Accepted (async operation started)     |
| 400  | Bad request (invalid parameters)       |
| 404  | Not found (contract/chain not found)   |
| 409  | Conflict (operation already in progress)|
| 500  | Internal server error                  |
| 503  | Service unavailable                    |

---

## Supported Chains

The API supports any EVM chain with verified contract support, including but not limited to:

| Chain ID | Network       |
|----------|--------------|
| 1        | Ethereum     |
| 137      | Polygon      |
| 8453     | Base         |
| 42161    | Arbitrum     |
| 10       | Optimism     |
| 56       | BNB Chain    |
| 43114    | Avalanche    |
| 100      | Gnosis       |
| 250      | Fantom       |
| 324      | zkSync Era   |
| 59144    | Linea        |
| 534352   | Scroll       |
| 5000     | Mantle       |
| 81457    | Blast        |
| 7777777  | Zora         |

---

## Caching

- **Database hits:** Cached for 24 hours
- **Fresh explorer fetches:** Cached for 1 hour
- **Search/List results:** Not cached (real-time)
- **Related contracts:** Cached for 1 hour
- **Stats:** Not cached (real-time)

---

## Data Sources

- **ABIs:** Block explorers across all EVM chains
- **Name Tags:** Extracted from explorer metadata
- **Usage Stats:** On-chain analytics (synced via cron)
- **Relationships:** On-chain analysis (via automated workflows)

---

## Integration Examples

### JavaScript/TypeScript
```typescript
// Fetch ABI
const response = await fetch("https://contractabi.com/1/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48");
const data = await response.json();
const abi = data.abi;

// Use with ethers.js
import { Contract, JsonRpcProvider } from "ethers";
const provider = new JsonRpcProvider("https://eth.llamarpc.com");
const contract = new Contract("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", abi, provider);

// Use with viem
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const client = createPublicClient({ chain: mainnet, transport: http() });
const balance = await client.readContract({
  address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  abi,
  functionName: "balanceOf",
  args: ["0x..."],
});
```

### Python
```python
import requests
from web3 import Web3

# Fetch ABI
response = requests.get("https://contractabi.com/1/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48")
data = response.json()
abi = data["abi"]

# Use with web3.py
w3 = Web3(Web3.HTTPProvider("https://eth.llamarpc.com"))
contract = w3.eth.contract(address="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", abi=abi)
```

### cURL
```bash
# Fetch ABI and save to file
curl -s https://contractabi.com/1/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 | jq '.abi' > usdc_abi.json

# Search contracts
curl -s "https://contractabi.com/search?q=uniswap&chainId=1" | jq '.results[].nameTag'

# Decode calldata
curl -s -X POST https://contractabi.com/api/decode \
  -H "Content-Type: application/json" \
  -d '{"calldata":"0xa9059cbb..."}' | jq '.signatures'
```