Skip to content

API_WALKTHROUGH.md

Latest commit

 

History

History
257 lines (197 loc) · 5.33 KB

API_WALKTHROUGH.md

File metadata and controls

257 lines (197 loc) · 5.33 KB

RustChain API Walkthrough

This guide walks you through making your first API calls to RustChain.

Base URL

https://rustchain.org

⚠️ Note: The node uses a self-signed certificate. Use -k or --insecure with curl.

1. Check Node Health

The simplest way to verify the node is running:

curl -k "https://rustchain.org/health"

Response:

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

2. Check Wallet Balance

Query any wallet balance using the miner_id parameter:

curl -k "https://rustchain.org/wallet/balance?miner_id=tomisnotcat"

Response:

{
  "amount_i64": 0,
  "amount_rtc": 0.0,
  "miner_id": "tomisnotcat"
}

Understanding the Response

Field Type Description
amount_i64 integer Raw amount (in smallest units)
amount_rtc float Human-readable RTC amount
miner_id string The wallet ID queried

3. Check Mining Eligibility

If you're mining, check your eligibility status:

curl -k "https://rustchain.org/lottery/eligibility?miner_id=tomisnotcat"

Response (not eligible):

{
  "eligible": false,
  "reason": "not_attested",
  "rotation_size": 27,
  "slot": 13839,
  "slot_producer": null
}

Response (eligible):

{
  "eligible": true,
  "reason": null,
  "rotation_size": 27,
  "slot": 13840,
  "slot_producer": "miner_name"
}

4. List Active Miners

curl -k "https://rustchain.org/api/miners"

Response (truncated):

[
  {
    "miner": "stepehenreed",
    "hardware_type": "PowerPC G4",
    "antiquity_multiplier": 2.5,
    "device_arch": "powerpc_g4",
    "last_attest": 1773010433
  },
  {
    "miner": "nox-ventures", 
    "hardware_type": "x86-64 (Modern)",
    "antiquity_multiplier": 1.0,
    "device_arch": "modern",
    "last_attest": 1773010407
  }
]

5. Signed Transfer (Advanced)

To send RTC from one wallet to another, you need to create a signed transfer.

Understanding Signed Transfers

RustChain uses Ed25519 signatures for transfers. You need:

  1. Your private key (from beacon identity new)
  2. The transfer payload
  3. Sign the payload with your key

Transfer Endpoint

POST /wallet/transfer/signed

Transfer Payload Structure

{
  "from_address": "RTC_sender_address",
  "to_address": "RTC_recipient_address",
  "amount_rtc": 100,
  "nonce": "unique_value",
  "chain_id": "rustchain-mainnet-v2",
  "public_key": "sender_ed25519_public_key_hex",
  "signature": "ed25519_signature_hex"
}

Example (Python)

import requests
import json
import nacl.signing
import nacl.encoding

# Load your private key
with open("/path/to/your/agent.key", "rb") as f:
    private_key = nacl.signing.SigningKey(f.read())

# Derive RTC address from public key
import hashlib
public_key_hex = private_key.verify_key.encode().hex()
from_address = "RTC" + hashlib.sha256(bytes.fromhex(public_key_hex)).hexdigest()[:40]

# Create canonical message to sign (uses from/to/amount, not from_address/to_address/amount_rtc)
transfer_msg = {
    "from": from_address,
    "to": "RTC_recipient_address",
    "amount": 100,
    "nonce": "1234567890",
    "memo": "",
    "chain_id": "rustchain-mainnet-v2"
}

# Sign the canonical message
message = json.dumps(transfer_msg, sort_keys=True, separators=(",", ":")).encode()
signed = private_key.sign(message)
signature_hex = signed.signature.hex()

# Build outer payload (uses from_address/to_address/amount_rtc)
payload = {
    "from_address": from_address,
    "to_address": "RTC_recipient_address",
    "amount_rtc": 100,
    "nonce": "1234567890",
    "memo": "",
    "chain_id": "rustchain-mainnet-v2",
    "public_key": public_key_hex,
    "signature": signature_hex
}

# Send transfer
response = requests.post(
    "https://rustchain.org/wallet/transfer/signed",
    json=payload,
    verify=False  # For self-signed cert
)
print(response.json())

Important Notes

  • RustChain Addresses: Signed transfers require RTC... addresses (43 chars: RTC + 40 hex), not simple wallet IDs or ETH/SOL addresses
  • Private Key: Your Ed25519 key from beacon identity new
  • Nonce: Must be unique per transfer (use timestamp or counter)
  • Public Key: Required in outer payload; must match the from_address
  • Chain ID: Optional for backward compatibility, but recommended. If supplied, it is verified and included in the signed message.

Common API Errors

Error Cause Solution
{"ok":false,"reason":"admin_required"} Endpoint requires admin Use appropriate endpoint
404 Not Found Wrong URL Check endpoint path
Connection refused Node down Check node status

SDK Alternative

Instead of raw API calls, use the Python SDK:

pip install rustchain-sdk
from rustchain_sdk import Client

client = Client("https://rustchain.org")

# Check balance
balance = client.get_balance("tomisnotcat")
print(balance)

# Get miners
miners = client.get_miners()
print(miners)

Next Steps