/health

POST ASYNC

Performs a health check on all coins in a wallet to verify their authenticity and identify issues.

POST /api/v1/health
Alias: /check-wallet-health

Description

The `/health` endpoint is a diagnostic tool that verifies the authenticity of every coin in a specified wallet. It checks each coin against the RAIDA network and provides a detailed report classifying coins as authentic, fracked, counterfeit, or in limbo.

💡 Diagnostic Tool

This is the first step in wallet maintenance. Run a health check to get a clear picture of your wallet's status before attempting to repair any issues with the /fix endpoint.

Asynchronous Workflow

Understanding Asynchronous API Calls

This endpoint is asynchronous, which means:

  1. When you call this endpoint, it immediately returns a task ID.
  2. You then need to periodically check the task status using the /api/v1/task/{task_id} endpoint.
  3. Once the task is complete, the task status endpoint will return the full results of the health check.

Request Body

The request must include a JSON body specifying the name of the wallet to check.

Parameter Type Required Description
name string Yes The name of the wallet to perform the health check on. Ex: "Default".

Example Request Body

{
  "name": "Default"
}

Response

After the asynchronous task finishes, the `data` field of the task status response will contain a detailed report of the wallet's health.

Response Properties

total_coinsinteger
Total number of coins found in the wallet.
total_checkedinteger
Total number of coins that were processed.
total_authenticinteger
Total number of coins verified as authentic.
total_frackedinteger
Total number of coins identified as fracked (partially failing authenticity).
total_counterfeitinteger
Total number of coins identified as counterfeit (failing authenticity).
total_limbointeger
Total number of coins identified as in limbo (too many failures to determine status).
total_errorsinteger
Number of errors encountered during the health check.
coinsarray of objects
An array providing details for each coin with an issue. Authentic coins are omitted for brevity.

Example Response (from task endpoint after completion)

{
  "id": "task_def456",
  "status": "completed",
  "progress": 100,
  "message": "Health check complete.",
  "data": {
    "total_coins": 1050,
    "total_checked": 1050,
    "total_authentic": 1000,
    "total_fracked": 40,
    "total_counterfeit": 10,
    "total_limbo": 0,
    "total_errors": 0,
    "coins": [
      {
        "sn": 1234,
        "pownstring": "ppppppppppfpppppppppppppp",
        "result": "Fracked"
      },
      {
        "sn": 5678,
        "pownstring": "fffffffffffffffffffffffff",
        "result": "Counterfeit"
      }
    ]
  }
}

Examples

JavaScript (async/await)

const API_HOST = 'http://localhost:8006';
const WALLET_NAME = 'Default';

const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));

async function checkWalletHealth(walletName) {
    try {
        const initialResponse = await fetch(`${API_HOST}/api/v1/health`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ name: walletName })
        });
        const task = await initialResponse.json();
        console.log(`Health check task created with ID: ${task.id}`);
        while (true) {
            const statusResponse = await fetch(`${API_HOST}/api/v1/task/${task.id}`);
            const taskStatus = await statusResponse.json();
            console.log(`Task progress: ${taskStatus.progress}%`);
            if (taskStatus.status === 'completed') {
                console.log('Health check complete:', taskStatus.data);
                break;
            } else if (taskStatus.status === 'error') {
                 console.error('Task failed:', taskStatus.message);
                 break;
            }
            await sleep(1000);
        }
    } catch (error) {
        console.error('An error occurred:', error);
    }
}

checkWalletHealth(WALLET_NAME);

cURL

# Step 1: Initiate the health check task
TASK_ID=$(curl -s -X POST "http://localhost:8006/api/v1/health" \
-H "Content-Type: application/json" \
-d '{"name": "Default"}' | jq -r .id)
echo "Task started with ID: $TASK_ID"

# Step 2: Poll the task endpoint until finished
while true; do
  RESPONSE=$(curl -s "http://localhost:8006/api/v1/task/$TASK_ID")
  STATUS=$(echo $RESPONSE | jq -r .status)
  echo "Polling task... Status: $STATUS"
  if [[ "$STATUS" == "completed" || "$STATUS" == "error" ]]; then
    echo "Final Response:"
    echo $RESPONSE | jq
    break
  fi
  sleep 2
done

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "time"
)

const ApiHost = "http://localhost:8006"
type HealthRequest struct { Name string `json:"name"` }
type TaskResponse struct {
    ID       string          `json:"id"`
    Status   string          `json:"status"`
    Progress int             `json:"progress"`
    Data     json.RawMessage `json:"data,omitempty"`
}

func main() {
    payloadBytes, _ := json.Marshal(HealthRequest{Name: "Default"})
    req, _ := http.NewRequest("POST", fmt.Sprintf("%s/api/v1/health", ApiHost), bytes.NewBuffer(payloadBytes))
    req.Header.Set("Content-Type", "application/json")
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()

    var task TaskResponse
    json.NewDecoder(resp.Body).Decode(&task)
    fmt.Printf("Health check task created with ID: %s\n", task.ID)
    
    // Poll for the result
    for {
        taskResp, _ := http.Get(fmt.Sprintf("%s/api/v1/task/%s", ApiHost, task.ID))
        var taskStatus TaskResponse
        json.NewDecoder(taskResp.Body).Decode(&taskStatus)
        taskResp.Body.Close()
        
        fmt.Printf("Task status: %s, Progress: %d%%\n", taskStatus.Status, taskStatus.Progress)
        if taskStatus.Status == "completed" || taskStatus.Status == "error" {
            fmt.Printf("Final result: %s\n", string(taskStatus.Data))
            break
        }
        time.Sleep(1 * time.Second)
    }
}

Related Endpoints

/fix

After running a health check, use the `/fix` endpoint to repair any fracked or limbo coins found in the report.

/task/{task_id}

Poll this endpoint to check the status, progress, and results of any asynchronous operation.