/api/coins/grade
GETGrades 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.
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:
- Reads the POWN string (25 characters, one per RAIDA)
- Counts 'p' (pass) characters in the POWN string
- Moves the coin based on pass count:
- 25 passes →
Bank/folder (perfect authentication) - 13-24 passes →
Fracked/folder (authentic, needs fixing) - 0-12 passes →
Counterfeit/folder (failed authentication)
- 25 passes →
- 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
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.
- 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
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)
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.