/detect
POST ASYNCChecks the authenticity of coins within one or more files without importing them into a wallet.
POST /api/v1/detect
Alias: /check-coin-authenticity
Description
The `/detect` endpoint allows you to verify the authenticity of coins from external files (like `.stack` or `.chest` files) before you import them. The system unpacks the coins from the provided file paths and checks them against the RAIDA network, providing a detailed report of their status.
💡 Pre-Import Verification
This is the ideal way to check coins you've received from someone else before adding them to your wallet. It helps prevent the import of counterfeit or problematic coins.
Asynchronous Workflow
Understanding Asynchronous API Calls
This endpoint is asynchronous, which means:
- You send a `POST` request with a list of file paths to check.
- The server immediately responds with a task ID.
- You then periodically poll the
/api/v1/tasks/{id}endpoint to check the progress. - Once the `status` is "completed", the `data` field will contain the full detection report.
Request Body
The request must include a JSON body specifying a list of files to be detected.
| Parameter | Type | Required | Description |
|---|---|---|---|
items |
array of objects | Yes | An array where each object represents a file to be processed. |
items[].data |
string | Yes | The absolute file path to the coin file (e.g., `.stack`) on the server. |
fix |
boolean | No | An optional flag that, if true, attempts to fix any fracked coins found during detection. |
Example Request
{
"items": [
{ "data": "/home/user/downloads/coins1.stack" },
{ "data": "/home/user/downloads/coins2.stack" }
]
}Response
After the task finishes, the task status endpoint (/api/v1/tasks/{id}) will return a `200 OK` response. The `data` field of the payload will contain a `result` object with a detailed breakdown of the detected coins.
Response Properties (within `data.result`)
total_coinsinteger
Total number of coins found and processed from the files.
total_authenticinteger
Total number of coins verified as authentic.
total_frackedinteger
Total number of coins identified as fracked.
total_counterfeitinteger
Total number of coins identified as counterfeit.
total_limbointeger
Total number of coins in a limbo state.
coinsarray of objects
A list of objects, each detailing an individual coin's status.
Example Response (from task endpoint after completion)
{
"status": "success",
"payload": {
"id": "d4e5f6g7-h8i9-j0k1-l2m3-n4o5p6q7r8s9",
"status": "completed",
"progress": 100,
"message": "Command Completed",
"data": {
"result": {
"total_coins": 2500,
"total_authentic": 2490,
"total_fracked": 5,
"total_counterfeit": 5,
"total_limbo": 0,
"coins": [
{ "sn": 123, "pownstring": "ppppppppppppppppppppppppp", "result": "Authentic" },
{ "sn": 124, "pownstring": "ppppppppppfpppppppppppppp", "result": "Fracked" },
{ "sn": 125, "pownstring": "fffffffffffffffffffffffff", "result": "Counterfeit" }
]
}
}
}
}Examples
JavaScript (async/await)
const API_HOST = 'http://localhost:8006';
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
async function detectCoinsInFile() {
try {
const payload = {
items: [
{ "data": "/home/user/downloads/new_coins.stack" }
]
};
const initialResponse = await fetch(`${API_HOST}/api/v1/detect`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload)
});
const task = await initialResponse.json();
console.log(`Detect task created with ID: ${task.id}`);
while (true) {
const statusResponse = await fetch(`${API_HOST}/api/v1/tasks/${task.id}`);
const taskStatus = await statusResponse.json();
console.log(`Task progress: ${taskStatus.progress}%`);
if (taskStatus.status === 'completed') {
console.log('Detection Complete:', taskStatus.data.result);
break;
} else if (taskStatus.status === 'error') {
console.error('Task failed:', taskStatus.message);
break;
}
await sleep(1000);
}
} catch (error) {
console.error('An error occurred:', error);
}
}
detectCoinsInFile();
cURL
# Step 1: Initiate the detect task
TASK_ID=$(curl -s -X POST "http://localhost:8006/api/v1/detect" \
-H "Content-Type: application/json" \
-d '{"items":[{"data":"/home/user/new_coins.stack"}]}' | jq -r .id)
echo "Detect 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/tasks/$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 DetectItem struct { Data string `json:"data"` }
type DetectRequest struct { Items []DetectItem `json:"items"` }
type TaskResponse struct {
ID string `json:"id"`
Status string `json:"status"`
Progress int `json:"progress"`
Data json.RawMessage `json:"data,omitempty"`
}
func main() {
detectPayload := DetectRequest{
Items: []DetectItem{{Data: "/home/user/new_coins.stack"}},
}
payloadBytes, _ := json.Marshal(detectPayload)
req, _ := http.NewRequest("POST", fmt.Sprintf("%s/api/v1/detect", 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("Detect task created with ID: %s\n", task.ID)
for {
taskResp, _ := http.Get(fmt.Sprintf("%s/api/v1/tasks/%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
/import
After detecting coins in a file and verifying they are authentic, use the import endpoint to add them to a wallet.