Health & Utilities

Monitor API health, check usage, and access utility endpoints.

Try it Live

Open in Swagger UI → to test these endpoints interactively.

Endpoints

Endpoint	Description	Price
GET /api/health	API health	FREE
GET /api/usage	Your usage	FREE
GET /api/sources/health	Data source health	FREE
GET /api/convert/{amount}/{from}/{to}	Convert	$0.001

---

GET /api/health

Check API status.

Request

curl https://api.web3identity.com/api/health

Response

{
  "status": "healthy",
  "version": "2.8.0",
  "endpoints": 975,
  "uptime": "99.95%",
  "timestamp": "2026-02-08T04:30:00Z"
}

---

GET /api/usage

Check your current usage and remaining free tier.

Request

curl https://api.web3identity.com/api/usage

Response

{
  "used": 27,
  "limit": 100,
  "remaining": 73,
  "tier": "anonymous",
  "resetsAt": "2026-02-09T00:00:00Z",
  "resetIn": "19 hours"
}

SDK

const usage = await client.getUsage();
if (usage.remaining < 10) {
  console.log('Running low on free tier!');
}

---

GET /api/sources/health

Check health of upstream data sources.

Response

{
  "sources": {
    "coingecko": { "status": "healthy", "latency": 145 },
    "defillama": { "status": "healthy", "latency": 89 },
    "alchemy": { "status": "healthy", "latency": 52 },
    "neynar": { "status": "healthy", "latency": 123 }
  },
  "healthy": 4,
  "unhealthy": 0,
  "percentage": 100
}

---

GET /api/convert/{amount}/{from}/{to}

Convert between tokens/currencies.

Request

curl https://api.web3identity.com/api/convert/100/ETH/USD

Response

{
  "amount": 100,
  "from": "ETH",
  "to": "USD",
  "result": 324567.00,
  "rate": 3245.67,
  "timestamp": "2026-02-08T04:30:00Z"
}

SDK

const result = await client.convert(100, 'ETH', 'USD');
console.log(result.result); // 324567.00

SDK Examples

import { Web3IdentityClient } from '@web3identity/sdk';

const client = new Web3IdentityClient();

// Check conversion
const usdValue = await client.convert(1.5, 'ETH', 'USD');
console.log(`1.5 ETH = $${usdValue.result.toLocaleString()}`);

// Convert between tokens
const btcInEth = await client.convert(1, 'BTC', 'ETH');

// Batch conversions
const amounts = [1, 10, 100];
const conversions = await Promise.all(
  amounts.map(amt => client.convert(amt, 'ETH', 'USD'))
);

Python

import requests

BASE_URL = "https://api.web3identity.com"

def convert(amount: float, from_token: str, to_token: str) -> dict:
    url = f"{BASE_URL}/api/convert/{amount}/{from_token}/{to_token}"
    response = requests.get(url)
    return response.json()

# Convert 100 ETH to USD
result = convert(100, 'ETH', 'USD')
print(f"100 ETH = ${result['result']:,.2f}")

# Convert USDC to ETH
usdc_to_eth = convert(10000, 'USDC', 'ETH')
print(f"10,000 USDC = {usdc_to_eth['result']:.4f} ETH")

JavaScript

const BASE_URL = 'https://api.web3identity.com';

async function convert(amount, from, to) {
  const response = await fetch(
    `${BASE_URL}/api/convert/${amount}/${from}/${to}`
  );
  return response.json();
}

// Portfolio value calculator
async function calculatePortfolioValue(holdings) {
  const conversions = await Promise.all(
    holdings.map(({ amount, token }) => 
      convert(amount, token, 'USD')
    )
  );
  
  return conversions.reduce((sum, conv) => sum + conv.result, 0);
}

// Usage
const portfolio = [
  { amount: 10, token: 'ETH' },
  { amount: 0.5, token: 'BTC' },
  { amount: 5000, token: 'USDC' }
];

const totalValue = await calculatePortfolioValue(portfolio);
console.log(`Total: $${totalValue.toLocaleString()}`);

---

GET /api/openapi

Get the OpenAPI specification for all endpoints.

Request

curl https://api.web3identity.com/api/openapi

Response

Returns full OpenAPI 3.0 schema with 966 documented endpoints.

{
  "openapi": "3.0.0",
  "info": {
    "title": "Web3 Identity API",
    "version": "2.8.0"
  },
  "paths": {
    "/api/health": {...},
    "/api/ens/{name}": {...}
  }
}

---

Monitoring & Alerts

Webhook Notifications (Coming Soon)

Set up alerts for:

• API downtime
• Rate limit warnings
• Usage threshold alerts
• Data source failures

Health Check Examples

Node.js Health Monitor:

const https = require('https');

function checkAPIHealth() {
  return new Promise((resolve, reject) => {
    https.get('https://api.web3identity.com/api/health', (res) => {
      let data = '';
      res.on('data', chunk => data += chunk);
      res.on('end', () => {
        const health = JSON.parse(data);
        resolve(health.status === 'healthy');
      });
    }).on('error', reject);
  });
}

// Use in production monitoring
setInterval(async () => {
  const healthy = await checkAPIHealth();
  if (!healthy) {
    console.error('❌ API is down!');
    // Send alert
  }
}, 60000); // Check every minute

Python Health Dashboard:

import requests
import time
from datetime import datetime

def monitor_api_health():
    while True:
        try:
            health = requests.get("https://api.web3identity.com/api/health").json()
            sources = requests.get("https://api.web3identity.com/api/sources/health").json()
            
            print(f"[{datetime.now()}] API Status: {health['status']}")
            print(f"Uptime: {health['uptime']}")
            print(f"Healthy sources: {sources['healthy']}/{sources['healthy'] + sources['unhealthy']}")
            
            if sources['percentage'] < 80:
                print("⚠️  Some data sources are degraded")
            
        except Exception as e:
            print(f"❌ Health check failed: {e}")
        
        time.sleep(300)  # Check every 5 minutes

if __name__ == "__main__":
    monitor_api_health()

Bash Monitoring Script:

#!/bin/bash
# monitor-api.sh

API_BASE="https://api.web3identity.com"
WEBHOOK_URL="YOUR_SLACK_WEBHOOK"  # Optional

while true; do
    # Check API health
    STATUS=$(curl -s "${API_BASE}/api/health" | jq -r '.status')
    
    if [ "$STATUS" != "healthy" ]; then
        echo "[$(date)] ❌ API unhealthy!"
        # Optional: Send Slack alert
        curl -X POST "$WEBHOOK_URL" \
          -H 'Content-Type: application/json' \
          -d "{\"text\":\"⚠️ API health check failed: $STATUS\"}"
    else
        echo "[$(date)] ✅ API healthy"
    fi
    
    # Check source health
    SOURCE_PCT=$(curl -s "${API_BASE}/api/sources/health" | jq -r '.percentage')
    echo "Source health: ${SOURCE_PCT}%"
    
    sleep 300  # 5 minutes
done

---

Free Endpoints

These endpoints never count against your quota:

Endpoint	Description
/api/health	API health check
/api/usage	Your usage stats
/api/sources/health	Data source status
/api/gas	Ethereum gas prices
/api/openapi	OpenAPI schema
/docs	Swagger UI
/demo	Interactive demo

---

Rate Limit Headers

Every response includes:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 73
X-RateLimit-Reset: 2026-02-09T00:00:00Z
X-RateLimit-Policy: anonymous

JavaScript Rate Limit Handler

async function fetchWithRateLimitHandling(url) {
  const response = await fetch(url);
  
  const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
  const reset = response.headers.get('X-RateLimit-Reset');
  
  if (remaining < 10) {
    console.warn(`⚠️ Only ${remaining} requests left until ${reset}`);
  }
  
  if (response.status === 429) {
    const retryAfter = response.headers.get('Retry-After');
    console.error(`Rate limited! Retry after ${retryAfter} seconds`);
    throw new Error('RATE_LIMITED');
  }
  
  return response.json();
}

---

Status Page

For real-time API status and incident history:

status.web3identity.com

Subscribe to Alerts

Get notified of:

• Downtime incidents
• Scheduled maintenance
• Performance degradations
• New feature announcements

---

Related Endpoints

• ENS Resolution — Core ENS functionality
• Gas Prices — Gas price monitoring
• Token Prices — Price data health