/sync_unopened_lockers

POST ASYNC

Finds pending incoming transfers (unopened lockers) for a wallet.

POST /api/v1/sync_unopened_lockers

Alias: /check-for-incoming-transfers

Description

This endpoint scans the RAIDA network to find any "unopened lockers" associated with the specified wallet. An unopened locker represents a pending transfer of coins that have been sent to the user's SkyWallet but have not yet been withdrawn into their local wallet. This is useful for discovering and retrieving incoming funds.

Asynchronous Operation

This is a long-running, asynchronous operation. The API responds immediately with a task ID, and the process runs in the background. You must poll the /tasks/{id} endpoint to get the final result.

Request Body

The request body should be a JSON object specifying the wallet to sync.

Request Body Parameters

Parameter	Type	Required	Description
`name`	string	Yes	The name of the wallet to sync for unopened lockers.

Example Request

{
    "name": "Default"
}

Response

Upon successful completion of the task, the task status endpoint will return a `200 OK` response. The `data` field will contain an object summarizing the unopened lockers that were found.

Response Properties (within completed task `data`)

new_lockers_foundinteger

The number of new lockers discovered during this sync.

lockersarray

An array of objects, each detailing an unopened locker.

Locker Object Properties

transmit_codestring

The transmit code needed to withdraw the coins.

amountinteger

The total value of coins in the locker.

Example Response (from task endpoint after completion)

{
    "status": "success",
    "payload": {
        "id": "f6g7h8i9-j0k1-l2m3-n4o5-p6q7r8s9t0u1",
        "status": "completed",
        "progress": 100,
        "message": "Command Completed",
        "data": {
            "new_lockers_found": 1,
            "lockers": [
                {
                    "transmit_code": "ABC-1234",
                    "amount": 25000000000
                }
            ]
        }
    }
}

Examples

JavaScript Example

const apiHost = 'http://localhost:8006';

async function pollTask(taskId) {
    const response = await fetch(`${apiHost}/api/v1/tasks/${taskId}`);
    const taskData = await response.json();
    const task = taskData.payload;

    console.log(`Task ${taskId} progress: ${task.progress}% - ${task.message}`);

    if (task.status === 'completed') {
        console.log('Sync Complete:', task.data);
        return true;
    } else if (task.status === 'error') {
        console.error('Task failed:', task.message);
        return true;
    }
    return false;
}

async function syncLockers(walletName) {
    try {
        const response = await fetch(`${apiHost}/api/v1/sync_unopened_lockers`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ name: walletName })
        });
        const taskInfo = await response.json();
        const taskId = taskInfo.payload.id;
        console.log(`Sync task created with ID: ${taskId}`);

        const pollInterval = setInterval(async () => {
            const isDone = await pollTask(taskId);
            if (isDone) {
                clearInterval(pollInterval);
            }
        }, 2000);
    } catch (error) {
        console.error('Error initiating sync task:', error);
    }
}

syncLockers('Default');

cURL Example

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

echo "Sync 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 '.payload.status')
  echo "Polling task.. Status: $STATUS"
  
  if [[ "$STATUS" == "completed" ]] || [[ "$STATUS" == "error" ]]; then
    echo "Final Response:"
    echo $RESPONSE | jq
    break
  fi
  
  sleep 2
done

Go Example

package main

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

const apiHost = "http://localhost:8006/api/v1"

type TaskResponse struct {
    Payload struct {
        ID       string      `json:"id"`
        Status   string      `json:"status"`
        Progress int         `json:"progress"`
        Message  string      `json:"message"`
        Data     interface{} `json:"data"`
    } `json:"payload"`
}

// pollTask polls a task until it is complete or fails.
func pollTask(taskId string) {
    for {
        resp, err := http.Get(fmt.Sprintf("%s/tasks/%s", apiHost, taskId))
        if err != nil {
            log.Printf("Error polling task: %v\n", err)
            return
        }
        defer resp.Body.Close()

        var taskResp TaskResponse
        json.NewDecoder(resp.Body).Decode(&taskResp)

        fmt.Printf("Polling... Status: %s, Progress: %d%%\n", taskResp.Payload.Status, taskResp.Payload.Progress)

        if taskResp.Payload.Status == "completed" {
            fmt.Printf("Task completed successfully. Result: %+v\n", taskResp.Payload.Data)
            return
        } else if taskResp.Payload.Status == "error" {
            fmt.Printf("Task failed: %s\n", taskResp.Payload.Message)
            return
        }
        time.Sleep(2 * time.Second)
    }
}

// syncLockers initiates a sync and then polls for the result.
func syncLockers(walletName string) {
    requestBody, _ := json.Marshal(map[string]string{"name": walletName})
    resp, err := http.Post(fmt.Sprintf("%s/sync_unopened_lockers", apiHost), "application/json", bytes.NewBuffer(requestBody))
    if err != nil {
        log.Fatalf("Failed to start sync task: %v", err)
    }
    defer resp.Body.Close()

    var taskResp TaskResponse
    json.NewDecoder(resp.Body).Decode(&taskResp)
    
    fmt.Printf("Sync task created with ID: %s\n", taskResp.Payload.ID)
    pollTask(taskResp.Payload.ID)
}

func main() {
    syncLockers("Default")
}