Health Check & Utility Endpoints

These endpoints provide essential monitoring and information capabilities for the Renesis Stellar DEX Vaults API. Use these endpoints to verify API connectivity, monitor server health, and discover available API functionality.

Health Check Endpoints

GET /health

Basic health check endpoint that provides server status and uptime information.

Request

curl -X GET "https://api.renesis.fi/health"

Response

{
  "success": true,
  "message": "Server is healthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "uptime": 86400.5,
  "environment": "production"
}

Response Fields

success (boolean): Always true for successful health checks
message (string): Human-readable status message
timestamp (string): ISO 8601 timestamp of the health check
uptime (number): Server uptime in seconds since last restart
environment (string): Current environment (development, production, etc.)

GET /api/health

Detailed API health check endpoint with the same response format as /health. This endpoint is specifically for API health monitoring and follows the API path structure.

Request

curl -X GET "https://api.renesis.fi/api/health" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "message": "Server is healthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "uptime": 86400.5,
  "environment": "production"
}

Use Cases

Monitoring: Automated health checks for monitoring systems
Load Balancer: Health check endpoint for load balancer configuration
CI/CD: Verify API availability during deployment processes
Development: Quick connectivity testing during development

API Information Endpoints

GET /api

Returns general API information including version, available endpoints, and metadata.

Request

curl -X GET "https://api.renesis.fi/api" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "message": "Stellar Vault API",
  "version": "1.0.0",
  "endpoints": {
    "health": "/api/health",
    "vaults": "/api/vaults",
    "documentation": "/api/docs"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Response Fields

success (boolean): Always true for successful requests
message (string): API name and description
version (string): Current API version
endpoints (object): Key API endpoint paths
timestamp (string): ISO 8601 timestamp of the request

GET /api/docs

Comprehensive API documentation endpoint that returns detailed information about all available endpoints, examples, and supported features.

Request

curl -X GET "https://api.renesis.fi/api/docs" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "title": "Stellar Vault API Documentation",
  "version": "1.0.0",
  "description": "API for managing Stellar vault data and token holdings",
  "baseUrl": "https://api.renesis.fi/api",
  "endpoints": {
    "POST /vaults": "Create a new vault",
    "GET /vaults": "Get all vaults with pagination and filtering",
    "GET /vaults/:id": "Get vault by ID",
    "GET /vaults/by-address/:address": "Get vault by contract address",
    "GET /vaults/by-owner/:owner": "Get vaults by owner address",
    "GET /vaults/trade-permission": "Get vaults with trade permission",
    "GET /vaults/stats": "Get vault statistics",
    "GET /vaults/search": "Search vaults by name",
    "PUT /vaults/:id": "Update vault by ID",
    "PUT /vaults/by-address/:address": "Update vault by address",
    "PATCH /vaults/:id/toggle-trade": "Toggle trade permission",
    "DELETE /vaults/:id": "Delete vault by ID",
    "DELETE /vaults/by-address/:address": "Delete vault by address",
    "POST /vaults/:id/update-holdings": "Update token holdings for a vault",
    "GET /vaults/:id/holdings": "Get token holdings for a vault",
    "POST /vaults/update-all-holdings": "Update all vaults token holdings"
  },
  "examples": {
    "createVault": {
      "method": "POST",
      "url": "/api/vaults",
      "body": {
        "vaultName": "My Trading Vault",
        "vaultOwner": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
        "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
        "creationLedger": 123456789,
        "tradePermission": true,
        "slippageTolerance": 0.01,
        "dailyTradeLimit": 20,
        "maxTradeSize": 0.5
      }
    },
    "updateHoldings": {
      "method": "POST",
      "url": "/api/vaults/:id/update-holdings?network=testnet",
      "description": "Fetches current token balances from Stellar network"
    },
    "getHoldings": {
      "method": "GET",
      "url": "/api/vaults/:id/holdings",
      "description": "Returns stored token holdings for the vault"
    }
  },
  "supportedTokens": {
    "testnet": ["XLM", "USDC", "BTC", "EURC", "XTAR", "XRP"],
    "mainnet": []
  }
}

Response Fields

success (boolean): Always true for successful requests
title (string): API documentation title
version (string): Current API version
description (string): API description and purpose
baseUrl (string): Base URL for API requests
endpoints (object): Complete list of available endpoints with descriptions
examples (object): Sample requests for common operations
supportedTokens (object): Lists of supported tokens by network

Server Status Information

Uptime Monitoring

The health check endpoints provide server uptime in seconds, which can be used for:

Monitoring Dashboards: Display server uptime statistics
Alerting Systems: Detect server restarts or downtime
Performance Tracking: Monitor server stability over time

Environment Detection

All endpoints include environment information to help with:

Development vs Production: Identify which environment you’re connecting to
Configuration Validation: Ensure correct environment configuration
Debugging: Environment-specific troubleshooting

Integration Examples

Health Check Monitoring Script

#!/bin/bash
# Simple health check script for monitoring

HEALTH_URL="https://api.renesis.fi/health"
RESPONSE=$(curl -s "$HEALTH_URL")
SUCCESS=$(echo "$RESPONSE" | jq -r '.success')

if [ "$SUCCESS" = "true" ]; then
    echo "✅ API is healthy"
    echo "$RESPONSE" | jq '.uptime, .timestamp'
else
    echo "❌ API health check failed"
    exit 1
fi

API Discovery Script

#!/bin/bash
# Discover available API endpoints

API_DOCS_URL="https://api.renesis.fi/api/docs"
API_KEY="YOUR_API_KEY"

curl -s -H "Authorization: Bearer $API_KEY" "$API_DOCS_URL" | \
    jq -r '.endpoints | to_entries[] | "\(.key): \(.value)"'

Node.js Health Check

const axios = require('axios');

async function checkAPIHealth() {
    try {
        const response = await axios.get('https://api.renesis.fi/health');
        
        if (response.data.success) {
            console.log('✅ API is healthy');
            console.log(`Uptime: ${response.data.uptime} seconds`);
            console.log(`Environment: ${response.data.environment}`);
            return true;
        }
    } catch (error) {
        console.error('❌ Health check failed:', error.message);
        return false;
    }
}

// Use in your application
checkAPIHealth().then(isHealthy => {
    if (!isHealthy) {
        process.exit(1);
    }
});

Error Responses

Network Connectivity Issues

If the API is unreachable, you’ll receive standard HTTP connection errors:

Connection Timeout: Network connectivity issues
DNS Resolution: Domain name resolution problems
SSL/TLS Errors: Certificate or encryption issues

Server Errors

In rare cases where the server is experiencing issues:

{
  "success": false,
  "message": "Internal server error",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Best Practices

Health Check Frequency

Production Monitoring: Check every 30-60 seconds
Development: Check as needed during testing
Load Balancer: Configure appropriate intervals (typically 10-30 seconds)

Timeout Configuration

Health Checks: Set timeout to 5-10 seconds
API Discovery: Allow 15-30 seconds for complete response
Retry Logic: Implement exponential backoff for failed checks

Authentication

Health Endpoints: /health and /api/health don’t require authentication
API Information: /api and /api/docs require valid API key
Security: Never expose API keys in client-side code or logs

Monitoring Integration

Uptime Monitoring: Use health check endpoints for external monitoring services
Application Monitoring: Integrate health checks into your application startup
CI/CD Pipelines: Verify API availability before and after deployments

Getting Started

Vaults

Smart Contracts

Order Execution

Swap Infrastructure

Contract Addresses

API Reference

Disclaimers