/locker

POST ASYNC

Puts coins from a local wallet to the remote locker.

POST /api/v1/locker

Description

This endpoint transfers coins from a local wallet to the remote RAIDA locker. The function returns a transmit code that can be used to retrieve the coins later. This is useful for sending coins to other users or backing up your coins remotely.

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.

Request

This endpoint accepts a JSON object with the following properties:

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 Optional tag or note to associate with this transfer.
transmit_code string No Optional custom transmit code. If not provided, a random code will be generated.

Example Request

{
    "name": "Default",
    "amount": 20,
    "tag": "hello",
    "transmit_code": "AAB-45PQ"
}

Response

Returns a 200 OK response with a JSON object containing details about the transfer operation.

Response Properties

transmit_code string
The transmit code that can be used to retrieve the coins from the locker. Share this code with the intended recipient.
receipt_id string
Unique identifier for the transaction receipt.
total_stored integer
Total value of coins successfully stored in the locker.
total_failed integer
Total value of coins that failed to be stored in the locker.

Example Response

{
  "transmit_code": "AAC-WS5I-F90000000E",
  "receipt_id": "930c58c367f4b8a3201a066b69529768",
  "total_stored": 10,
  "total_failed": 10
}

Examples

JavaScript Example

// Using Fetch API to make the asynchronous call and check task status
const apiHost = 'http://localhost:8004';

// Step 1: Call the locker endpoint to create a task
fetch(`${apiHost}/api/v1/locker`, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        name: 'Default',
        amount: 20,
        tag: 'Payment for invoice #1234'
    })
})
.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 storage results:');
                    console.log(`Transmit code: ${result.transmit_code}`);
                    console.log(`Receipt ID: ${result.receipt_id}`);
                    console.log(`Total stored: ${result.total_stored}`);
                    console.log(`Total failed: ${result.total_failed}`);
                    
                    // Display the transmit code to the user
                    alert(`Coins have been stored in the locker. Share this transmit code with the recipient: ${result.transmit_code}`);
                } 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 storage task:', error);
});

cURL Example

# Step 1: Call the locker endpoint to create a task
curl -X POST "http://localhost:8004/api/v1/locker" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Default",
    "amount": 20,
    "tag": "Payment for invoice #1234"
  }'

# 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":{"transmit_code":"AAC-WS5I-F90000000E","receipt_id":"930c58c367f4b8a3201a066b69529768","total_stored":10,"total_failed":10}}

Related Endpoints

/locker/{code}

Peeks coins in the RAIDA locker by transmit code, showing information without downloading them.