/locker/{code}

GET POST ASYNC

Peek at or retrieve coins from a remote locker using a transmit code.

GET /api/v1/locker/{code}

Alias: /verify-locker-contents/{code}

POST /api/v1/locker/{code}

Alias: /retrieve-coins-from-locker/{code}

Description

This endpoint interacts with coins stored in a remote locker, identified by its `transmit_code`. You can "peek" at the contents to verify the amount without downloading them (GET), or you can retrieve (remove) the coins from the locker and deposit them into a local wallet (POST).

Asynchronous Operation

Both GET and POST operations are asynchronous. They return a task ID immediately, and the final result must be retrieved by polling the /tasks/{id} endpoint.

GET /locker/{code} (Peek)

Peeks at the coins in a locker, returning their details without moving them. This is useful for verifying the contents before retrieval.

Response (in completed task `data`)

totalinteger

Total value of coins in the locker.

coinsarray

An array of coin objects in the locker.

POST /locker/{code} (Retrieve)

Removes coins from the locker and deposits them into the specified local wallet.

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	The name of the destination wallet for the retrieved coins.

Response (in completed task `data`)

totalinteger

Total value of coins successfully retrieved.

receipt_idstring

A unique identifier for this transaction.

Examples

JavaScript: Peek at Locker

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 peekLocker(transmitCode) {
    try {
        const response = await fetch(`${apiHost}/api/v1/locker/${transmitCode}`);
        const taskInfo = await response.json();
        const taskId = taskInfo.payload.id;
        console.log(`Peek 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 start peek task:', error);
    }
}

peekLocker('AAC-WS5I-F90000000E');

JavaScript: Retrieve from Locker

async function retrieveFromLocker(transmitCode, walletName) {
    try {
        const response = await fetch(`${apiHost}/api/v1/locker/${transmitCode}`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ name: walletName })
        });
        const taskInfo = await response.json();
        const taskId = taskInfo.payload.id;
        console.log(`Retrieve 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 start retrieve task:', error);
    }
}

retrieveFromLocker('AAC-WS5I-F90000000E', 'Default');

cURL: Peek at Locker

# Step 1: Initiate the peek task
TASK_ID=$(curl -s -X GET "http://localhost:8006/api/v1/locker/AAC-WS5I-F90000000E" | jq -r '.payload.id')
echo "Peek 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

cURL: Retrieve from Locker

# Step 1: Initiate the retrieve task
TASK_ID=$(curl -s -X POST "http://localhost:8006/api/v1/locker/AAC-WS5I-F90000000E" \
-H "Content-Type: application/json" \
-d '{"name":"Default"}' | jq -r '.payload.id')
echo "Retrieve 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: Peek at Locker

package main

import (
    "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)
    }
}

// peekLocker initiates a peek operation and then polls for the result.
func peekLocker(transmitCode string) {
    resp, err := http.Get(fmt.Sprintf("%s/locker/%s", apiHost, transmitCode))
    if err != nil {
        log.Fatalf("Failed to start peek task: %v", err)
    }
    defer resp.Body.Close()

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

Go: Retrieve from Locker

package main

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

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

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

    fmt.Printf("Retrieve task created with ID: %s\n", taskResp.Payload.ID)
    pollTask(taskResp.Payload.ID) // Assumes pollTask function from above example
}