API Reference

The RougeChain node exposes a REST API on the configured --api-port (default: 5101).

Important: All write operations (POST/PUT/DELETE) require v2 signed requests using ML-DSA-65 client-side signing. Legacy unsigned v1 write endpoints return 410 GONE in production. Private keys never leave your application.

Base URL

Local node:

http://127.0.0.1:5101/api

Public testnet:

https://testnet.rougechain.io/api

Public mainnet:

https://api.rougechain.io/api

Both public endpoints send Access-Control-Allow-Origin: *, so browser dApps and localhost dev servers can call them directly with no per-origin allowlisting. (The API has no cookie/session auth — every write is ML-DSA-65 signed — so a wildcard is safe, the same posture as public RPC providers.)

Address Format

RougeChain uses Bech32m addresses with the rouge1 prefix (e.g., rouge1q8f3x7k2m4n9p...). These are derived from the SHA-256 hash of the raw ML-DSA-65 public key.

Accepted formats differ per endpoint:

When in doubt, pass the hex public key.

Tip: Use GET /api/resolve/:input to convert between rouge1… addresses and hex public keys.

v2 Signed Request Format

All write endpoints use a standard signed-request envelope:

{
  "payload": {
    "...endpoint-specific fields...",
    "from": "your-signing-public-key-hex",
    "timestamp": 1706745600000,
    "nonce": "random-hex-string"
  },
  "signature": "ml-dsa65-signature-of-payload-hex",
  "public_key": "your-signing-public-key-hex"
}

The payload is JSON-serialized with keys sorted alphabetically, then signed with your ML-DSA-65 private key. The server verifies the signature, checks the timestamp (must be within ±5 minutes of the server clock), and rejects a signature it has already seen within that window. Messenger, mail and name endpoints additionally require a unique nonce of 8–128 characters. The envelope may also carry an optional payload_bytes_hex (the exact bytes that were signed); when present the node verifies those bytes and checks that they decode to payload.

Endpoints Overview

System

Blockchain

Wallet & Accounts

Tokens

Token Allowances (ERC-20 Style)

Staking & Validators

Token Staking Pools (suspended since block 245)

create_staking_pool, token_stake and token_unstake are suspended transaction types since mainnet block 245 (testnet 1390): no block may carry them. These read routes answer with empty data on mainnet (no pool was ever created). See Status.

AMM/DEX

NFTs

Smart Contracts

Bridge (ETH/USDC + XRGE)

Shielded Transactions (suspended since block 245)

The V1 shielded pool is suspended: shield, shielded_transfer and unshield are refused (this transaction type is suspended) and a block carrying them is invalid. The mainnet pool is empty (shielded_supply 0). A redesigned pool (V2) is in development and unaudited — see Status.

Rollup (research prototype — not part of consensus)

The rollup accumulator batches transfers in memory and proves them with a STARK, but nothing in consensus reads a batch: a submitted transfer moves no funds and enters no block.

Governance (suspended since block 245)

On-chain governance (create_proposal, cast_vote, execute_proposal, delegate, undelegate) is suspended: no block may carry these types, and none was ever used on mainnet. These read routes return empty lists on mainnet. Treasury decisions for Regenerate use the node-hosted Regenerate votes in the meantime.

Social

Messenger

Mail

Push Notifications

P2P

Authentication

If a node is started with --api-keys, most REST routes require a key — reads included, not just writes. Exempt are /, /api/health, /api/stats, /api/v2/*, /api/bridge/*, /api/messenger/*, /api/mail/*, /api/names/* and the faucet. Send the key as X-API-Key or Authorization: Bearer:

curl -H "X-API-Key: your-api-key" http://127.0.0.1:5101/api/blocks

The public endpoints (api.rougechain.io, testnet.rougechain.io) do not require a key.

Rate Limiting

Rate limiting is disabled by default (all limits 0 = unlimited). Limits are per minute and tiered:

• Tier 1 (Validators): Proven via X-Validator-Key / X-Validator-Sig / X-Validator-Ts headers (the signed timestamp must be within 30 seconds) — --rate-limit-validator
• Tier 2 (Registered peers): Recognized by IP — --rate-limit-peer
• Tier 3 (Public): GET requests use --rate-limit-read-per-minute, all other methods --rate-limit-write-per-minute

--rate-limit-per-minute is a deprecated alias: when it is set and neither read nor write limit is, it applies to both (a deprecation warning is logged); explicit read/write limits take precedence.

Clients are keyed by the connecting IP. Behind a reverse proxy on the same host, start the node with --trust-proxy (env QV_TRUST_PROXY=true): requests whose TCP peer is loopback are then keyed by X-Real-IP, else the rightmost X-Forwarded-For entry; requests from any other peer always use the socket IP. Every route is rate-limited, including the peer routes /api/finality/* (which stay API-key exempt).