Health Check

Check API health and service status. No payment required.

Endpoints

X-Router provides two health check endpoints:

/v1/health - API service health
/health - Root health with network info

/v1/health

Check the API service health and backend connectivity.

Request


GET /v1/health

No parameters required.

Response


{
  status: 'ok';
  timestamp: string;  // ISO 8601 timestamp
}

Example


curl https://api.x-router.ai/v1/health


{
  "status": "ok",
  "timestamp": "2025-10-31T23:15:42.123Z"
}

/health

Root health check with network and configuration details.

Request


GET /health

No parameters required.

Response


{
  status: 'ok';
  timestamp: string;       // ISO 8601 timestamp
  network: string;         // Blockchain network ID
  mainnet: boolean;        // Whether running on mainnet
  cdp: string;            // CDP configuration status
}

Example


curl https://api.x-router.ai/health


{
  "status": "ok",
  "timestamp": "2025-10-31T23:15:42.123Z",
  "network": "base",
  "mainnet": true,
  "cdp": "configured"
}

Usage Examples

TypeScript Health Check


async function checkHealth() {
  try {
    const response = await fetch('https://api.x-router.ai/v1/health');
    const data = await response.json();
 
    if (data.status === 'ok') {
      console.log('API is healthy');
    } else {
      console.error('API is unhealthy');
    }
  } catch (error) {
    console.error('Failed to connect to API:', error);
  }
}

Monitoring Script


async function monitorHealth() {
  const checks = [];
 
  // Check both endpoints
  const v1Health = await fetch('https://api.x-router.ai/v1/health')
    .then(r => r.json());
 
  const rootHealth = await fetch('https://api.x-router.ai/health')
    .then(r => r.json());
 
  console.log('Health Check Results:');
  console.log('===================');
  console.log(`API Status: ${v1Health.status}`);
  console.log(`Network: ${rootHealth.network}`);
  console.log(`Mainnet: ${rootHealth.mainnet}`);
  console.log(`CDP: ${rootHealth.cdp}`);
  console.log(`Timestamp: ${v1Health.timestamp}`);
 
  return {
    healthy: v1Health.status === 'ok',
    details: { v1Health, rootHealth }
  };
}
 
// Run every 60 seconds
setInterval(monitorHealth, 60000);

Retry Logic with Health Check


async function makeRequestWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      // Check health before making request
      const health = await fetch('https://api.x-router.ai/v1/health');
      const healthData = await health.json();
 
      if (healthData.status !== 'ok') {
        console.log('API unhealthy, waiting...');
        await new Promise(resolve => setTimeout(resolve, 5000));
        continue;
      }
 
      // Make actual request
      const response = await fetchWithPayment(url, options);
      return response;
 
    } catch (error) {
      console.log(`Attempt ${i + 1} failed:`, error);
 
      if (i === maxRetries - 1) throw error;
 
      // Wait before retrying
      await new Promise(resolve => setTimeout(resolve, 2000 * (i + 1)));
    }
  }
}

Integration with Load Balancer


class XRouterClient {
  private baseUrl = 'https://api.x-router.ai';
  private isHealthy = true;
 
  async checkHealth(): Promise<boolean> {
    try {
      const response = await fetch(`${this.baseUrl}/v1/health`);
      const data = await response.json();
 
      this.isHealthy = data.status === 'ok';
      return this.isHealthy;
    } catch {
      this.isHealthy = false;
      return false;
    }
  }
 
  async chatCompletion(messages, options = {}) {
    if (!this.isHealthy) {
      await this.checkHealth();
 
      if (!this.isHealthy) {
        throw new Error('API is currently unavailable');
      }
    }
 
    return fetchWithPayment(`${this.baseUrl}/v1/chat/completions`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ messages, ...options })
    });
  }
}
 
// Use the client
const client = new XRouterClient();
 
// Check health periodically
setInterval(() => client.checkHealth(), 30000);
 
// Make requests
const response = await client.chatCompletion([
  { role: 'user', content: 'Hello!' }
]);

Status Meanings

API Status

ok: API is running and healthy
degraded: API is running but experiencing issues
down: API is not responding

Network Status

network: The blockchain network being used (e.g., “base”)
mainnet: true for production (Base Mainnet)
cdp: Coinbase Developer Platform configuration status

Best Practices

Health Checks in Production

Monitor regularly: Check health every 30-60 seconds
Circuit breaker: Stop making requests if health checks fail repeatedly
Alerts: Set up alerts for health check failures
Fallback: Have a fallback plan if the API is down

Pre-flight Checks

Always check health before making expensive operations:


// Good: Check health before batch operations
const health = await fetch('/v1/health').then(r => r.json());
if (health.status === 'ok') {
  await processBatchRequests();
}
 
// Bad: Make batch requests without checking
await processBatchRequests(); // Might fail midway

Logging

Log health check results for debugging:


async function logHealth() {
  const health = await fetch('https://api.x-router.ai/v1/health')
    .then(r => r.json());
 
  console.log(JSON.stringify({
    timestamp: new Date().toISOString(),
    api_status: health.status,
    server_timestamp: health.timestamp
  }));
}