📚 API Reference — Official Endpoint Documentation

[sophiaeagent-beep]

RustChain API Reference — Canonical Documentation

Base URL: https://50.28.86.131 (self-signed cert, use -k with curl)

All examples use the external HTTPS endpoint. Internally on VPS, use http://localhost:8099.

---

Public Endpoints (No Authentication Required)

Health & Status

Endpoint	Method	Purpose
/health	GET	Node health check
/ready	GET	Readiness probe

Example:

curl -sk https://50.28.86.131/health

Response:

{
  "ok": true,
  "version": "2.2.1-rip200",
  "uptime_s": 4313,
  "db_rw": true,
  "backup_age_hours": 17.15,
  "tip_age_slots": 0
}

---

Epoch Information

Endpoint	Method	Returns
/epoch	GET	Current epoch, slot, pot, enrolled miners

Example:

curl -sk https://50.28.86.131/epoch

Response:

{
  "epoch": 75,
  "slot": 10800,
  "blocks_per_epoch": 144,
  "epoch_pot": 1.5,
  "enrolled_miners": 10
}

---

Network Data

Endpoint	Method	Description
/api/miners	GET	List active miners with architecture, multiplier, attestation times
/api/nodes	GET	Connected attestation nodes

Example:

curl -sk https://50.28.86.131/api/miners

Response (truncated):

[
  {
    "miner": "eafc6f14eab6d5c5362fe651e5e6c23581892a37RTC",
    "device_arch": "G4",
    "device_family": "PowerPC",
    "hardware_type": "PowerPC G4 (Vintage)",
    "antiquity_multiplier": 2.5,
    "entropy_score": 0.0,
    "last_attest": 1771187406,
    "first_attest": null
  }
]

---

Wallet Queries

Endpoint	Method	Description
/wallet/balance?miner_id=NAME	GET	Check RTC balance for miner wallet

Example:

curl -sk 'https://50.28.86.131/wallet/balance?miner_id=scott'

Response:

{
  "ok": true,
  "miner_id": "scott",
  "amount_rtc": 42.5
}

---

Block Explorer

Endpoint	Method	Purpose
/explorer	GET	Web UI for block/transaction browsing

Open in browser: https://50.28.86.131/explorer

---

Authenticated Endpoints (Require X-Admin-Key Header)

# All admin endpoints require this header:
-H "X-Admin-Key: rustchain_admin_key_2025_secure64"

Endpoint	Method	Purpose
/wallet/transfer	POST	Internal RTC transfer (admin only)
/rewards/settle	POST	Trigger epoch settlement

Example - Admin Transfer:

curl -sk -X POST https://50.28.86.131/wallet/transfer \
  -H "X-Admin-Key: rustchain_admin_key_2025_secure64" \
  -H "Content-Type: application/json" \
  -d '{"from_miner":"scott","to_miner":"pffs1802","amount_rtc":5.0}'

---

Common Mistakes (What NOT to Do)

❌ Wrong Endpoints That Don't Exist

• /balance/{address} — Use /wallet/balance?miner_id=NAME instead
• /miners?limit=N — No pagination; use /api/miners for full list
• /block/{height} — Use /explorer web UI instead
• /tx/{txid} — Use /explorer web UI instead
• /blocks — Not an endpoint; check /epoch for block info
• /api/balance — Use /wallet/balance?miner_id=...

❌ Wrong Field Names

When reading responses, use EXACT field names:

Epoch response (CORRECT):

{
  "epoch": 75,
  "slot": 10800,
  "blocks_per_epoch": 144,
  "epoch_pot": 1.5,
  "enrolled_miners": 10
}

NOT:

• ❌ epoch_number (it's epoch)
• ❌ current_slot (it's slot)
• ❌ per_epoch_pot (it's epoch_pot)
• ❌ total_miners (it's enrolled_miners)

Miner object (CORRECT):

{
  "miner": "wallet_id",
  "device_arch": "G4",
  "device_family": "PowerPC",
  "antiquity_multiplier": 2.5,
  "last_attest": 1771187406
}

NOT:

• ❌ miner_id (it's miner)
• ❌ architecture (it's device_arch)
• ❌ multiplier (it's antiquity_multiplier)
• ❌ last_attestation (it's last_attest)

---

Wallet Format Rules

RTC wallets are simple text identifiers (UTF-8 strings, 1-256 chars):

Valid wallet names:

• ✅ scott
• ✅ pffs1802
• ✅ liu971227-sys
• ✅ my-wallet-2025
• ✅ sophia-nas-c4130

NOT valid wallet names (will be rejected):

• ❌ Solana addresses: 4TRdr... (use as-is without modification)
• ❌ Ethereum addresses: 0x2A91...
• ❌ Ed25519 public keys: 88c394...
• ❌ Bitcoin addresses: 1A1z...

---

RIP-200 Attestation Endpoints

For miner integration, see Miner Integration Guide.

Endpoint	Method	Purpose
/attest/submit	POST	Submit hardware attestation
/lottery/eligibility?miner_id=NAME	GET	Check reward eligibility

---

HTTPS Certificate Warning

The node uses a self-signed certificate. When using curl, add -k flag:

# ✅ Correct
curl -sk https://50.28.86.131/health

# If you want to verify the cert, get it first:
openssl s_client -connect 50.28.86.131:443 -showcerts

---

Response Status Codes

Code	Meaning
200	✅ Success
400	❌ Bad request (check your JSON syntax)
401	❌ Unauthorized (missing or invalid X-Admin-Key)
404	❌ Endpoint doesn't exist
500	❌ Server error (check node logs)

---

Node Infrastructure

Primary Node (RIP-200 Consensus):

• Address: 50.28.86.131 (LiquidWeb VPS)
• HTTPS Port: 443 (nginx proxy)
• Internal Port: 8099 (Flask app)
• Version: 2.2.1-rip200

Secondary Node (Ergo Anchor):

• Address: 50.28.86.153 (LiquidWeb VPS)
• Note: Serves different services, not mirrored

Tertiary Node (Community):

• Address: 76.8.228.245 (Ryan's Proxmox)
• Tailscale: 100.88.109.32:8099
• Status: Community-operated

---

For Contributors

When submitting RustChain integration code:

1. Always test endpoints first using the examples above
2. Use exact field names from response JSON
3. Handle HTTP 401 errors gracefully (node may restart)
4. Don't hardcode IP addresses — use documented URLs
5. Reference this issue in your PR if you're adding new API usage

Questions? Comment below or open an issue tagged documentation.

---

Last updated: 2026-02-15. Epoch 75, 10 enrolled miners, 1.5 RTC/epoch.

[createkr]

PR submitted: https://github.com/Scottcjn/Rustchain/pull/224\n\nComplete API reference with field name precision guides and security notes finished.\n- Miner ID: createker02140054RTC

[Scottcjn]

@createkr — PR #224 was referenced but appears to be closed. Is there a current PR with the API docs?

[dagangtj]

I've submitted a comprehensive API reference document that covers all endpoints.

PR: dagangtj#1

The documentation includes:

• All health, stats, and network endpoints
• Miner and node information endpoints
• Wallet and balance queries
• Epoch and mining endpoints
• Attestation system
• Rewards and settlement
• Complete curl examples with real responses
• Error handling and authentication details

All endpoints were tested against the live mainnet node at https://50.28.86.131