/api/coins/grade

GET

Grades authenticated coins and sorts them into Bank, Fracked, or Counterfeit folders based on RAIDA authentication results.

Description

The `/api/coins/grade` endpoint analyzes coins in the Grade folder and sorts them based on their POWN (Proof of Ownership) status from RAIDA authentication. Each coin is moved to the appropriate folder based on how many RAIDA servers successfully authenticated it.

💡 Cloud Consensus Authentication

CloudCoin uses distributed consensus for authentication:

  • 25 RAIDA servers independently verify each coin
  • 13+ passes = Authentic (majority consensus)
  • 25 passes = Perfect authentication (Bank)
  • 13-24 passes = Authentic but damaged (Fracked, can be healed)
  • 0-12 passes = Counterfeit (failed authentication)

Grading Algorithm

For each coin in the Grade folder, the system:

  1. Reads the POWN string (25 characters, one per RAIDA)
  2. Counts 'p' (pass) characters in the POWN string
  3. Moves the coin based on pass count:
    • 25 passesBank/ folder (perfect authentication)
    • 13-24 passesFracked/ folder (authentic, needs fixing)
    • 0-12 passesCounterfeit/ folder (failed authentication)
  4. Updates transaction receipts with grading results

POWN String Reference

Each coin has a 25-character POWN string representing authentication status with each RAIDA server:

POWN Status Characters

'p' (0x0A) Pass
RAIDA successfully authenticated the coin.
'f' (0x0F) Fail
RAIDA rejected the coin as counterfeit.
'n' (0x0C) No Reply
RAIDA timeout (network issue).
'e' (0x0E) Error
RAIDA returned an error response.
'u' (0x00) Untried
Not yet authenticated with this RAIDA.

Example POWN Strings

Perfect coin (25 passes → Bank):
ppppppppppppppppppppppppp

Fracked coin (18 passes → Fracked):
pppppppppppppppppfnfnfnfn

Counterfeit coin (3 passes → Counterfeit):
fffffffffffffffffffpppfff

Parameters

This endpoint does not require any parameters. It automatically processes all coins in the active wallet's Grade folder.

⚠️ Prerequisites
  • An active wallet must be selected
  • Coins must be in the Grade folder (typically from /api/coins/authenticate)
  • Coins must have valid POWN strings (authentication results)

Response

Returns a JSON object with grading operation results.

Response Properties

status string
Operation status: "success" or "error".
operation string
Always "coins-grade".
message string
Human-readable result message.
wallet string
Name of the active wallet.
note string
Additional information about the grading operation.

Success Response

{
  "status": "success",
  "operation": "coins-grade",
  "message": "Grading operation completed",
  "wallet": "Default",
  "note": "Coins moved to Bank/Fracked/Counterfeit based on POWN status"
}

Error Response (No Active Wallet)

{
  "status": "error",
  "operation": "coins-grade",
  "message": "No active wallet selected",
  "error_code": 400
}

Error Response (Operation Failed)

{
  "status": "error",
  "operation": "coins-grade",
  "message": "Grading operation failed",
  "error_code": 500
}

Typical Workflow

The grading operation is typically used as part of a coin management workflow:

1. /api/coins/import
   ↓ (Import coins from files to Import folder)

2. /api/coins/authenticate
   ↓ (Authenticate with RAIDA, move to Grade folder)

3. /api/coins/grade ← YOU ARE HERE
   ↓ (Sort to Bank/Fracked/Counterfeit)

4. /api/coins/fix (if fracked coins exist)
   ↓ (Heal fracked coins using Fix protocol)

5. /api/wallet/balance
   ↓ (Check final authenticated balance)
💡 About Fracked Coins

Fracked coins (13-24 passes) are still authentic and valuable, but some RAIDA servers have incorrect ANs (Authenticity Numbers). These coins can be healed using the /api/coins/fix endpoint, which uses the RAIDA Fix protocol to restore them to perfect 25/25 status.

Examples

JavaScript (fetch)

const API_HOST = 'http://localhost:8080';

async function gradeCoins() {
    try {
        const response = await fetch(`${API_HOST}/api/coins/grade`);
        const result = await response.json();

        if (result.status === 'success') {
            console.log('✓ Grading completed successfully');
            console.log(`Wallet: ${result.wallet}`);
            console.log(result.note);

            // Check balance after grading
            const balanceResp = await fetch(`${API_HOST}/api/wallet/balance`);
            const balance = await balanceResp.json();
            console.log(`\nAuthenticated coins: ${balance.authentic}`);
            console.log(`Fracked coins: ${balance.fracked}`);
            console.log(`Counterfeit coins: ${balance.counterfeit}`);
        } else {
            console.error('✗ Grading failed:', result.message);
        }
    } catch (error) {
        console.error('Error grading coins:', error);
    }
}

gradeCoins();

cURL

# Grade authenticated coins
curl -X GET "http://localhost:8080/api/coins/grade"

# Complete workflow example
# 1. Import coins
curl -X POST "http://localhost:8080/api/coins/import" \
     -H "Content-Type: application/json" \
     -d '{"file_path": "/path/to/coins.stack"}'

# 2. Authenticate with RAIDA
curl -X GET "http://localhost:8080/api/coins/authenticate"

# 3. Grade coins (sort to folders)
curl -X GET "http://localhost:8080/api/coins/grade"

# 4. Check balance
curl -X GET "http://localhost:8080/api/wallet/balance"

# 5. Fix fracked coins if any
curl -X GET "http://localhost:8080/api/coins/fix"

Go

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

const ApiHost = "http://localhost:8080"

type GradeResponse struct {
    Status    string `json:"status"`
    Operation string `json:"operation"`
    Message   string `json:"message"`
    Wallet    string `json:"wallet"`
    Note      string `json:"note"`
}

type BalanceResponse struct {
    Status       string `json:"status"`
    Authentic    int    `json:"authentic"`
    Fracked      int    `json:"fracked"`
    Counterfeit  int    `json:"counterfeit"`
}

func gradeCoins() error {
    // Grade coins
    resp, err := http.Get(fmt.Sprintf("%s/api/coins/grade", ApiHost))
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)

    var result GradeResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return err
    }

    if result.Status != "success" {
        return fmt.Errorf("grading failed: %s", result.Message)
    }

    fmt.Printf("✓ Grading completed successfully\n")
    fmt.Printf("Wallet: %s\n", result.Wallet)
    fmt.Printf("%s\n\n", result.Note)

    // Check balance after grading
    balResp, err := http.Get(fmt.Sprintf("%s/api/wallet/balance", ApiHost))
    if err != nil {
        return err
    }
    defer balResp.Body.Close()

    balBody, _ := ioutil.ReadAll(balResp.Body)

    var balance BalanceResponse
    if err := json.Unmarshal(balBody, &balance); err != nil {
        return err
    }

    fmt.Printf("Authenticated coins: %d\n", balance.Authentic)
    fmt.Printf("Fracked coins: %d\n", balance.Fracked)
    fmt.Printf("Counterfeit coins: %d\n", balance.Counterfeit)

    return nil
}

func main() {
    if err := gradeCoins(); err != nil {
        panic(err)
    }
}

Transaction Receipts

The grading operation generates a transaction receipt file in the wallet's Receipts/ folder with detailed results:

Receipt File: 2025-01-31_15-30-45.grade.txt

Task ID: 1706715045
Transaction Type: Grade Coins
Wallet: Default

Summary:
- Coins moved to Bank: 15
- Coins moved to Fracked: 3
- Coins moved to Counterfeit: 1

Coin Details:
SN 1234567 (100) → Bank    [POWN: ppppppppppppppppppppppppp]
SN 2345678 (100) → Bank    [POWN: ppppppppppppppppppppppppp]
SN 3456789 (100) → Fracked [POWN: pppppppppppppppppfnfnfnfn]
SN 4567890 (  1) → Counterfeit [POWN: ffffffffffffffffffffffff]
...

Related Endpoints

/api/coins/authenticate

Authenticate coins with RAIDA before grading. Generates POWN strings needed for the grading process.

/api/coins/fix

Heal fracked coins using the RAIDA Fix protocol. Restores coins to perfect 25/25 authentication status.

/api/wallet/balance

View the current balance of authentic, fracked, and counterfeit coins in all wallet folders.

/api/wallet/show-coins

Display detailed information about coins in each folder, including serial numbers and POWN status.