/wallets/{name}/leftovers

GET SYNC

Retrieves leftover or suspect coins from a wallet.

GET /api/v1/wallets/{name}/leftovers

Alias: /find-missing-coins/{name}

Description

This endpoint inspects the "Suspect" directory within a specific wallet. This directory holds "leftover" coins—those that may have failed a previous import process or authenticity check and are awaiting further action. Calling this endpoint updates the wallet's contents to reflect any coins found in this directory and returns the full wallet object.

Request

This endpoint does not require a request body. The wallet to be checked is specified in the URL path.

Path Parameters

Parameter	Type	Required	Description
`name`	string	Yes	The name of the wallet to inspect for leftovers, as part of the URL path.

Response

Returns a `200 OK` response with the full wallet object. The `amount_stats` field within the object will be updated to show the total value of coins found in the "Bank" and "Suspect" folders.

Response Properties

The response is a full Wallet Object. Key fields to observe for this call are:

amount_stats object

An object showing the total value of coins in each folder. The `Suspect` key will show the value of leftover coins.

Example Response

{
    "name": "Default",
    "email": "",
    "password_hash": "",
    "balance": 3000000020,
    "denominations": {
        "1": 3000000020
    },
    "transactions": [],
    "amount_stats": {
        "Bank": 3000000000,
        "Suspect": 20
    }
}

Examples

JavaScript Example

// Using Fetch API to make a direct synchronous call
const apiHost = 'http://localhost:8006';
const walletName = 'Default';

fetch(`${apiHost}/api/v1/wallets/${walletName}/leftovers`)
    .then(response => {
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return response.json();
    })
    .then(wallet => {
        console.log(`Successfully fetched wallet: ${wallet.name}`);
        
        if (wallet.amount_stats && wallet.amount_stats.Suspect > 0) {
            console.log(`Found leftover coins with a total value of: ${wallet.amount_stats.Suspect}`);
        } else {
            console.log('No leftover coins found in the Suspect folder.');
        }
    })
    .catch(error => {
        console.error('Error fetching leftovers:', error);
    });

cURL Example

# Make a GET request to the leftovers endpoint for the "Default" wallet
curl -X GET "http://localhost:8006/api/v1/wallets/Default/leftovers"

# Example response:
# {"name":"Default","email":"","password_hash":"","balance":3000000020,"denominations":{"1":3000000020},"transactions":[],"amount_stats":{"Bank":3000000000,"Suspect":20}}

Go Example

package main
import ("encoding/json"; "fmt"; "net/http")

type AmountStats struct {
    Bank    int64 `json:"Bank"`
    Suspect int64 `json:"Suspect"`
}

type WalletWithLeftovers struct {
    Name         string      `json:"name"`
    AmountStats  AmountStats `json:"amount_stats"`
}

func getLeftovers(name string) {
    // Make a GET request to the leftovers endpoint
    resp, err := http.Get(fmt.Sprintf("http://localhost:8006/api/v1/wallets/%s/leftovers", name))
    if err != nil { 
        panic(err) 
    }
    defer resp.Body.Close()

    var wallet WalletWithLeftovers
    if err := json.NewDecoder(resp.Body).Decode(&wallet); err != nil {
        panic(err)
    }

    if wallet.AmountStats.Suspect > 0 {
        fmt.Printf("Found %d leftover coins in wallet '%s'.\n", wallet.AmountStats.Suspect, wallet.Name)
    } else {
        fmt.Printf("No leftover coins found for wallet '%s'.\n", wallet.Name)
    }
}