/locker/{code}

GET ASYNC

Peek coins in the RAIDA locker by transmit code.

GET /api/v1/locker/{code}

Description

This endpoint allows you to peek at coins stored in the RAIDA locker using a transmit code. It provides information about the coins without actually downloading them to your wallet. This is useful for verifying the contents of a locker before retrieving the coins.

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.

Parameters

Path Parameters

Parameter Type Required Description
code string Yes The transmit code for the locker to peek at.

Response

Returns a 200 OK response with a JSON object containing details about the coins in the locker.

Response Properties

coins array
Array of coin objects containing details about individual coins in the locker.
total integer
Total value of coins in the locker.

Coin Object Properties

coin_id integer
Internal identifier for the coin.
denomination integer
Denomination of the coin (e.g., 1, 5, 25, 100, 250).
sn integer
Serial number of the coin.
ans array
Array of authentication numbers for the coin. This may be empty during a peek operation.
pownstring string
String representation of pass/fail status for each RAIDA server. 'p' indicates a pass, 'f' indicates a fail.

Example Response

{
  "coins": [
    {
      "coin_id": 4,
      "denomination": 249,
      "sn": 14,
      "ans": [],
      "pownstring": "ppppppppppppppppppppppppp"
    },
    {
      "coin_id": 4,
      "denomination": 249,
      "sn": 15,
      "ans": [],
      "pownstring": "ppppppppppppppppppppppppp"
    },
    {
      "coin_id": 4,
      "denomination": 1,
      "sn": 20,
      "ans": [],
      "pownstring": "ppppppppppppppppppppppppp"
    },
    {
      "coin_id": 4,
      "denomination": 1,
      "sn": 21,
      "ans": [],
      "pownstring": "ppppppppppppppppppppppppp"
    },
    {
      "coin_id": 4,
      "denomination": 1,
      "sn": 22,
      "ans": [],
      "pownstring": "ppppppppppppppppppppppppp"
    }
  ],
  "total": 3000000020
}

Examples

JavaScript Example

// Using Fetch API to make the asynchronous call and check task status
const apiHost = 'http://localhost:8004';
const transmitCode = 'AAC-WS5I-F90000000E'; // Replace with your transmit code

// Step 1: Call the locker peek endpoint to create a task
fetch(`${apiHost}/api/v1/locker/${encodeURIComponent(transmitCode)}`)
    .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('Locker peek results:');
                        console.log(`Total value: ${result.total}`);
                        console.log(`Number of coins: ${result.coins.length}`);
                        
                        // Display information about the coins
                        console.log('Coins in locker:');
                        let denominationCounts = {};
                        
                        result.coins.forEach(coin => {
                            // Count coins by denomination
                            if (!denominationCounts[coin.denomination]) {
                                denominationCounts[coin.denomination] = 0;
                            }
                            denominationCounts[coin.denomination]++;
                            
                            // Log detailed coin info
                            console.log(`Coin SN ${coin.sn}, Denomination: ${coin.denomination}, Status: ${coin.pownstring}`);
                        });
                        
                        // Display denomination breakdown
                        console.log('Denomination breakdown:');
                        for (const [denom, count] of Object.entries(denominationCounts)) {
                            console.log(`  ${count} x ${denom} denomination coins`);
                        }
                    } 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 locker peek task:', error);
    });

cURL Example

# Step 1: Call the locker peek endpoint to create a task
curl -X GET "http://localhost:8004/api/v1/locker/AAC-WS5I-F90000000E" \
  -H "accept: application/json"

# 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":{"coins":[{"coin_id":4,"denomination":249,"sn":14,"ans":[],"pownstring":"ppppppppppppppppppppppppp"},...],"total":3000000020}}

Related Endpoints

/locker

Puts coins from a local wallet to the remote locker, generating a transmit code.