/health

POST ASYNC

Perform HealthCheck on all coins in the Bank.

POST /api/v1/health

Description

This endpoint launches health checks on the wallet. It verifies the authenticity of all coins stored in the Bank by checking them against the RAIDA network.

Note

This is an asynchronous API call. It creates a task and returns its ID. You can query the task status until it completes, showing a progress indicator to the user.

Understanding Asynchronous API Calls

This endpoint is asynchronous, which means:

  1. When you call this endpoint, it immediately returns a task ID rather than waiting for the full operation to complete.
  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.
Task Status Response Structure

When checking a task's status, you'll get a JSON response with the following structure:

{
    "id": "task123",              // The task identifier
    "status": "running",          // Status can be "running", "completed", or "error"
    "progress": 60,               // Progress percentage (0-100)
    "message": "...",             // Optional status message or error details
    "data": { ... }               // Only present when status is "completed"
}
Task Status Types

running The task is still in progress. Continue to check the status.

completed The task is finished successfully. The response will include the full result data.

error The task encountered an error. The response will include an error message.

Tip

When displaying task progress to users, consider implementing a progress bar that updates based on the progress value returned by the task status API.

Request

This endpoint accepts a JSON object with the following properties:

Request Body Parameters

Parameter Type Required Description
wallet string No The name of the wallet to check. If not specified, the default wallet will be used.

Example Request

{
    "wallet": "Default"
}

Response

Returns a 200 OK response with a JSON object containing details about the health check results.

Response Properties

total_coins integer
Total number of coins in the wallet.
total_checked integer
Total number of coins that were checked.
total_authentic integer
Total number of coins that were verified as authentic.
total_already_fracked integer
Number of coins that were already in fracked state before the health check.
total_already_limbo integer
Number of coins that were already in limbo state before the health check.
total_fracked integer
Number of coins that were newly identified as fracked during this health check.
total_counterfeit integer
Number of coins identified as counterfeit.
total_limbo integer
Number of coins newly identified as being in limbo state.
total_errors integer
Number of errors encountered during the health check process.
coins array
Array of coin objects containing details about individual coin health.

Coin Object Properties

sn integer
Serial number of the coin.
pownstring string
String representation of pass/fail status for each RAIDA server. 'p' indicates a pass, 'f' indicates a fail.
result string
Overall result for this coin (e.g., "Authentic", "Counterfeit", "Fracked", "Limbo").

Example Response

{
  "total_coins": 3000000020,
  "total_checked": 3000000020,
  "total_authentic": 3000000020,
  "total_already_fracked": 0,
  "total_already_limbo": 0,
  "total_fracked": 0,
  "total_counterfeit": 0,
  "total_limbo": 0,
  "total_errors": 0,
  "coins": [
    {
      "sn": 23,
      "pownstring": "ppppppppppppppppppppppppp",
      "result": "Authentic"
    },
    {
      "sn": 24,
      "pownstring": "ppppppppppppppppppppppppp",
      "result": "Authentic"
    },
    {
      "sn": 25,
      "pownstring": "ppppppppppppppppppppppppp",
      "result": "Authentic"
    },
    {
      "sn": 16,
      "pownstring": "ppppppppppppppppppppppppp",
      "result": "Authentic"
    },
    {
      "sn": 17,
      "pownstring": "ppppppppppppppppppppppppp",
      "result": "Authentic"
    }
  ]
}

Examples

JavaScript Example

// Using Fetch API to make the asynchronous call and check task status
const apiHost = 'http://localhost:8004';

// Step 1: Call the health endpoint to create a task
fetch(`${apiHost}/api/v1/health`, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        wallet: 'Default'
    })
})
.then(response => response.json())
.then(task => {
    console.log('Task created:', task);
    
    // Step 2: Monitor task status
    const taskId = task.id;
    const checkTaskInterval = setInterval(() => {
        fetch(`${apiHost}/api/v1/task/${taskId}`)
            .then(response => response.json())
            .then(taskStatus => {
                console.log(`Task progress: ${taskStatus.progress}%`);
                
                // Step 3: Check if the task is complete
                if (taskStatus.status === 'completed') {
                    clearInterval(checkTaskInterval);
                    const result = taskStatus.data;
                    
                    console.log('Health check results:');
                    console.log(`Total coins: ${result.total_coins}`);
                    console.log(`Authentic coins: ${result.total_authentic}`);
                    console.log(`Fracked coins: ${result.total_fracked}`);
                    console.log(`Counterfeit coins: ${result.total_counterfeit}`);
                    
                    // Display information about individual coins
                    console.log('Coin status details:');
                    result.coins.forEach(coin => {
                        console.log(`Coin SN ${coin.sn}: ${coin.result}`);
                    });
                } else if (taskStatus.status === 'error') {
                    clearInterval(checkTaskInterval);
                    console.error('Task error:', taskStatus.message);
                }
            })
            .catch(error => {
                clearInterval(checkTaskInterval);
                console.error('Error checking task status:', error);
            });
    }, 1000); // Check every second
})
.catch(error => {
    console.error('Error initiating health check task:', error);
});

cURL Example

# Step 1: Call the health endpoint to create a task
curl -X POST "http://localhost:8004/api/v1/health" \
  -H "Content-Type: application/json" \
  -d '{"wallet":"Default"}'

# Example response:
# {"id":"task123","status":"running","progress":0}

# Step 2: Check the task status (replace 'task123' with your actual task ID)
curl -X GET "http://localhost:8004/api/v1/task/task123" -H "accept: application/json"

# Example response while in progress:
# {"id":"task123","status":"running","progress":60}

# Example response when complete:
# {"id":"task123","status":"completed","progress":100,"data":{"total_coins":3000000020,"total_checked":3000000020,"total_authentic":3000000020,"total_already_fracked":0,"total_already_limbo":0,"total_fracked":0,"total_counterfeit":0,"total_limbo":0,"total_errors":0,"coins":[...]}}