/locker

POST ASYNC

Puts coins from a local wallet to the remote locker.

POST /api/v1/locker

Alias: /deposit-coins-to-locker

Description

This endpoint transfers a specified amount of coins from a local wallet to the remote RAIDA locker. This process is asynchronous. The API immediately returns a task ID, and the final result of the operation, including a unique `transmit_code` for retrieving the coins, will be available once the task is complete.

Asynchronous Operation

This is a long-running, asynchronous operation. The API responds immediately with a task ID. You must poll the /tasks/{id} endpoint to get the final result, which will contain the `transmit_code`.

Request Body

The request must be a JSON object specifying the source wallet and amount.

Request Body Parameters

Parameter	Type	Required	Description
`name`	string	Yes	The name of the wallet to transfer coins from.
`amount`	integer	Yes	The amount of CloudCoins to transfer to the locker.
`tag`	string	No	An optional memo or note to associate with this transfer.
`transmit_code`	string	No	An optional, custom transmit code. If not provided, a random one will be generated.

Example Request Body

{
    "name": "Default",
    "amount": 20,
    "tag": "Payment for invoice #1234"
}

Response

The final result is available by polling the task endpoint. Upon completion, the task's `data` field will contain the following object:

Response Properties (within completed task `data`)

transmit_codestring

The transmit code required to retrieve the coins.

receipt_idstring

A unique identifier for this transaction.

total_storedinteger

The total value of coins successfully stored.

total_failedinteger

The total value of coins that failed to be stored.

Example Final Response (from task endpoint)

{
    "status": "success",
    "payload": {
        "id": "some-task-id",
        "status": "completed",
        "progress": 100,
        "message": "Command Completed",
        "data": {
            "transmit_code": "AAC-WS5I-F90000000E",
            "receipt_id": "930c58c367f4b8a3201a066b69529768",
            "total_stored": 20,
            "total_failed": 0
        }
    }
}

Examples

JavaScript Example

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

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

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

    if (task.status === 'completed') {
        console.log(`Task finished successfully!`, task.data);
        return true; // Stop polling
    } else if (task.status === 'error') {
        console.error(`Task failed:`, task.message);
        return true; // Stop polling
    }
    return false; // Continue polling
}

async function storeInLocker(walletName, amount, tag) {
    try {
        const response = await fetch(`${apiHost}/api/v1/locker`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ name: walletName, amount, tag })
        });
        const taskInfo = await response.json();
        const taskId = taskInfo.payload.id;
        console.log(`Store to locker task created with ID: ${taskId}`);
        
        const pollInterval = setInterval(async () => {
            const isDone = await pollTask(taskId);
            if (isDone) clearInterval(pollInterval);
        }, 2000); // Check every 2 seconds
    } catch (error) {
        console.error('Failed to initiate store to locker:', error);
    }
}

storeInLocker('Default', 50, 'for a friend');

cURL Example

# Step 1: Initiate the store to locker task
TASK_ID=$(curl -s -X POST "http://localhost:8006/api/v1/locker" \
 -H "Content-Type: application/json" \
 -d '{"name":"Default", "amount": 50, "tag":"for a friend"}' | jq -r '.payload.id')

echo "Store to locker 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)
    }
}

// storeInLocker initiates storing coins in the locker and then polls for the result.
func storeInLocker(walletName string, amount int, tag string) {
    requestBody, err := json.Marshal(map[string]interface{}{
        "name":   walletName,
        "amount": amount,
        "tag":    tag,
    })
    if err != nil {
        log.Fatalf("Failed to marshal request: %v", err)
    }

    resp, err := http.Post(fmt.Sprintf("%s/locker", apiHost), "application/json", bytes.NewBuffer(requestBody))
    if err != nil {
        log.Fatalf("HTTP post failed: %v", err)
    }
    defer resp.Body.Close()

    var taskResp TaskResponse
    if err := json.NewDecoder(resp.Body).Decode(&taskResp); err != nil {
        log.Fatalf("Failed to decode response: %v", err)
    }
    
    fmt.Printf("Store to locker task created with ID: %s\n", taskResp.Payload.ID)
    pollTask(taskResp.Payload.ID)
}

func main() {
    storeInLocker("Default", 50, "for a friend")
}