/export

POST ASYNC

Exports a specific amount of coins from a wallet to a new file on the server.

POST /api/v1/export

Alias: /export-coins-to-file

Description

The `/export` endpoint takes a specific amount of coins from a wallet and saves them into a new file (e.g., `.stack`, `.png`) in a specified folder. This is the primary way to package coins to be sent to another person or for creating a "paper wallet" for cold storage.

💡 Sending Coins

After exporting coins to a file, you can send that file to another person via email, messaging app, or any other method. The recipient can then use the `/import` endpoint to claim the coins.

Asynchronous Workflow

Understanding Asynchronous API Calls

This is an asynchronous operation. The server will start the export process in the background and immediately return a task ID.

You send a `POST` request with the export parameters.
The server responds with a task ID.
You poll the /api/v1/tasks/{id} endpoint to check the progress.
A `status` of "completed" indicates the file has been successfully created on the server.

Request Body

The request must include a JSON body specifying the source wallet, amount, and export details.

Parameter	Type	Required	Description
`name`	string	Yes	The name of the source wallet.
`amount`	number	Yes	The amount of coins to export (e.g., 10.5).
`folder`	string	Yes	The absolute path to a folder on the server where the output file will be saved.
`type`	string	Yes	The format of the output file. Must be one of: `zip`, `stack`, or `png`.
`tag`	string	No	An optional tag to include in the filename for easier identification.

Example Request Body

{
  "name": "Default",
  "amount": 50,
  "folder": "/home/user/exported_coins",
  "type": "zip",
  "tag": "payment-to-alice"
}

Response

A successful export is confirmed when the polled task status becomes "completed". The result is the new file created on the server, not a data payload in the response.

Example Response Body (from task endpoint after completion)

{
    "status": "success",
    "payload": {
        "id": "c4b1d2e3-f5a6-7890-1b2c-3d4e5f6a7b8c",
        "status": "completed",
        "progress": 100,
        "message": "Export completed successfully",
        "data": {
            "result": null
        }
    }
}

Examples

JavaScript (async/await)

const API_HOST = 'http://localhost:8006';
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));

async function exportCoins() {
    try {
        const payload = {
            name: "Default",
            amount: 12.5,
            folder: "/home/user/exported_coins",
            type: "stack",
            tag: "for-alice"
        };
        const initialResponse = await fetch(`${API_HOST}/api/v1/export`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(payload)
        });
        const task = await initialResponse.json();
        console.log(`Export task created with ID: ${task.payload.id}`);
        while (true) {
            const statusResponse = await fetch(`${API_HOST}/api/v1/tasks/${task.payload.id}`);
            const taskStatus = await statusResponse.json();
            console.log(`Task progress: ${taskStatus.payload.progress}%`);
            if (taskStatus.payload.status === 'completed') {
                console.log('Export successful! File created on the server.');
                break;
            } else if (taskStatus.payload.status === 'error') {
                 console.error('Task failed:', taskStatus.payload.message);
                 break;
            }
            await sleep(1000);
        }
    } catch (error) {
        console.error('An error occurred:', error);
    }
}
exportCoins();

cURL

# Step 1: Initiate the export task
TASK_ID=$(curl -s -X POST "http://localhost:8006/api/v1/export" \
-H "Content-Type: application/json" \
-d '{"name":"Default","amount":50,"folder":"/home/user/exported_coins","type":"zip","tag":"trade"}' | jq -r .payload.id)
echo "Export 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)
  if [[ "$STATUS" == "completed" ]]; then
    echo "Export successful."
    break
  elif [[ "$STATUS" == "error" ]]; then
    echo "Export failed: $(echo $RESPONSE | jq -r .payload.message)"
    break
  fi
  echo "Polling task... Status: $STATUS"
  sleep 1
done

Go

package main

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

const ApiHost = "http://localhost:8006"
type ExportRequest struct {
    Name   string  `json:"name"`
    Amount float64 `json:"amount"`
    Folder string  `json:"folder"`
    Type   string  `json:"type"`
    Tag    string  `json:"tag"`
}

func main() {
    exportPayload := ExportRequest{
        Name:   "Default",
        Amount: 10.0,
        Folder: "/home/user/go_exports",
        Type:   "png",
        Tag:    "paper-wallet",
    }
    payloadBytes, _ := json.Marshal(exportPayload)
    
    req, _ := http.NewRequest("POST", fmt.Sprintf("%s/api/v1/export", ApiHost), bytes.NewBuffer(payloadBytes))
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()

    // The initial response just gives us the task ID to monitor.
    // Polling logic would be the same as other examples,
    // checking for taskStatus.Payload.Status == "completed".
    fmt.Println("Export task submitted. Status Code:", resp.StatusCode)
}

Related Endpoints

/import

After exporting coins, the recipient can use this endpoint to import the file into their wallet.

View Details

/backup

To create a full backup of an entire wallet for safety, rather than exporting a specific amount.

View Details