Skip to main content
curl https://api.payonproof.com/api/health

GET /api/health

Returns the health status of PayOnProof API and its dependencies (Stellar Horizon, Supabase, anchor services).

Query parameters

None.

Response (healthy)

status
string
“ok” when all services are operational
version
string
API version (e.g., “0.1.0”)
timestamp
string
ISO 8601 timestamp of health check
services
object
stellar
string
Stellar Horizon status (“ok” or “error”)
supabase
string
Database status (“placeholder” - not yet implemented)
anchors
string
Anchor services status (“placeholder” - not yet implemented)
stellar
object
horizonUrl
string
Horizon server URL
latestLedger
number
Latest ledger sequence number from Horizon

Response example (healthy)

{
  "status": "ok",
  "version": "0.1.0",
  "timestamp": "2026-03-03T10:00:00.000Z",
  "services": {
    "stellar": "ok",
    "supabase": "placeholder",
    "anchors": "placeholder"
  },
  "stellar": {
    "horizonUrl": "https://horizon.stellar.org",
    "latestLedger": 54321098
  }
}

Response (degraded)

status
string
“degraded” when Stellar Horizon is unavailable
stellar.error
string
Error message from Horizon

Response example (degraded)

{
  "status": "degraded",
  "version": "0.1.0",
  "timestamp": "2026-03-03T10:00:00.000Z",
  "services": {
    "stellar": "error",
    "supabase": "placeholder",
    "anchors": "placeholder"
  },
  "stellar": {
    "horizonUrl": "https://horizon.stellar.org",
    "error": "Horizon timeout"
  }
}

HTTP status codes

200
status
All services operational (status: “ok”)
503
status
Service degraded (status: “degraded”) - Horizon unavailable

Use cases

Monitor API availability

async function checkApiHealth() {
  try {
    const response = await fetch('https://api.payonproof.com/api/health');
    const health = await response.json();
    
    if (health.status === 'ok') {
      console.log('✓ All systems operational');
      return true;
    } else {
      console.warn('⚠ Service degraded:', health.stellar?.error);
      return false;
    }
  } catch (error) {
    console.error('✗ API unavailable:', error);
    return false;
  }
}

Display status badge

function StatusBadge() {
  const [health, setHealth] = useState(null);
  
  useEffect(() => {
    fetch('/api/health')
      .then(r => r.json())
      .then(setHealth);
  }, []);
  
  if (!health) return <span>Checking...</span>;
  
  return (
    <span className={health.status === 'ok' ? 'status-ok' : 'status-degraded'}>
      {health.status === 'ok' ? '✓ Operational' : '⚠ Degraded'}
    </span>
  );
}

Pre-flight check before transfer

async function executeTransfer(route, amount, account) {
  // Check health first
  const healthResponse = await fetch('/api/health');
  const health = await healthResponse.json();
  
  if (health.status !== 'ok') {
    throw new Error(`Service degraded: ${health.stellar?.error || 'Unknown error'}`);
  }
  
  // Proceed with transfer
  return await fetch('/api/execute-transfer', {
    method: 'POST',
    body: JSON.stringify({
      phase: 'prepare',
      route,
      amount,
      senderAccount: account
    })
  });
}

Uptime monitoring

#!/bin/bash
# Check health every 60 seconds
while true; do
  STATUS=$(curl -s https://api.payonproof.com/api/health | jq -r '.status')
  TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
  
  if [ "$STATUS" = "ok" ]; then
    echo "$TIMESTAMP - OK"
  else
    echo "$TIMESTAMP - DEGRADED" | tee -a /var/log/api-health.log
    # Send alert
    curl -X POST https://alerts.example.com/webhook \
      -d '{"message": "PayOnProof API degraded"}'
  fi
  
  sleep 60
done

Implementation notes

  • Health check has a 5-second timeout for Horizon queries
  • Ledger sequence number proves Horizon connectivity and real-time data
  • Service returns 503 status code when degraded (important for load balancers)
  • Supabase and anchors checks are placeholders (always return “placeholder”)
  • Future versions will include:
    • Database connection pooling status
    • Active anchor count and operational percentage
    • Cache hit rates
    • Average response times

Build docs developers (and LLMs) love