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

http://127.0.0.1:5100/api

For the public testnet:

https://testnet.rougechain.io/api

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.

All API endpoints expect raw hex public keys, not rouge1 addresses:

✅ /api/balance/d67d8da279755a...
❌ /api/balance/rouge1q8f3x7k2m4n9p...

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 60 seconds), and rejects replayed nonces.

Endpoints Overview

System

EndpointMethodDescription
/api/healthGETNode health check
/api/statsGETNetwork statistics
/api/wsGETWebSocket for real-time events
/api/price/xrgeGETCurrent XRGE price

Blockchain

EndpointMethodDescription
/api/blocksGETGet all blocks
/api/blocks/summaryGETBlock summary for charts
/api/block/:heightGETGet block by height
/api/txsGETGet transactions
/api/tx/:hashGETGet transaction by hash
/api/tx/:hash/receiptGETGet transaction receipt
/api/eventsGETGet all events

Wallet & Accounts

EndpointMethodDescription
/api/balance/:publicKeyGETGet XRGE balance
/api/balance/:publicKey/:tokenGETGet token balance
/api/account/:pubkey/nonceGETGet account nonce
/api/resolve/:inputGETResolve address ↔ public key
/api/address/:pubkey/transactionsGETGet address transactions
/api/v2/transferPOSTTransfer tokens (signed)
/api/v2/faucetPOSTRequest testnet tokens (signed)

Tokens

EndpointMethodDescription
/api/tokensGETList all tokens
/api/token/:symbol/metadataGETGet token metadata
/api/token/:symbol/holdersGETGet token holders
/api/token/:symbol/transactionsGETGet token transactions
/api/burn-addressGETGet official burn address
/api/burnedGETGet burned token stats
/api/v2/token/createPOSTCreate token (signed)
/api/v2/token/metadata/updatePOSTUpdate token metadata (signed)
/api/v2/token/metadata/claimPOSTClaim metadata ownership (signed)

Token Allowances (ERC-20 Style)

EndpointMethodDescription
/api/v2/token/approvePOSTApprove spender allowance (signed)
/api/v2/token/transfer-fromPOSTTransfer using allowance (signed)
/api/v2/token/freezePOSTFreeze/unfreeze token transfers (signed)
/api/token/allowanceGETCheck specific allowance
/api/token/allowancesGETList allowances by owner/spender
/api/allowances/:pubkeyGETList all allowances for a key
/api/locks/:pubkeyGETGet token locks

Staking & Validators

EndpointMethodDescription
/api/validatorsGETList validators
/api/validators/statsGETValidator vote stats
/api/selectionGETProposer selection
/api/finalityGETFinality status
/api/votesGETVote quorum info
/api/v2/stakePOSTStake tokens (signed)
/api/v2/unstakePOSTUnstake tokens (signed)

Token Staking Pools

EndpointMethodDescription
/api/staking/poolsGETList all staking pools
/api/staking/pool/:pool_idGETGet staking pool details
/api/staking/stakes/:pubkeyGETGet stakes by owner
/api/staking/pool/:pool_id/stakesGETGet stakes in a pool

AMM/DEX

EndpointMethodDescription
/api/poolsGETList liquidity pools
/api/pool/:pool_idGETGet pool details
/api/pool/:pool_id/pricesGETGet price history
/api/pool/:pool_id/eventsGETGet pool events
/api/pool/:pool_id/statsGETGet pool statistics
/api/swap/quotePOSTGet swap quote
/api/v2/pool/createPOSTCreate liquidity pool (signed)
/api/v2/pool/add-liquidityPOSTAdd liquidity (signed)
/api/v2/pool/remove-liquidityPOSTRemove liquidity (signed)
/api/v2/swap/executePOSTExecute swap (signed)

NFTs

EndpointMethodDescription
/api/nft/collectionsGETList collections
/api/nft/collection/:idGETGet collection
/api/nft/collection/:id/tokensGETGet collection tokens
/api/nft/token/:coll/:idGETGet specific NFT
/api/nft/owner/:pubkeyGETGet NFTs by owner
/api/v2/nft/collection/createPOSTCreate collection (signed)
/api/v2/nft/mintPOSTMint NFT (signed)
/api/v2/nft/batch-mintPOSTBatch mint (signed)
/api/v2/nft/transferPOSTTransfer NFT (signed)
/api/v2/nft/burnPOSTBurn NFT (signed)
/api/v2/nft/lockPOSTLock/unlock NFT (signed)
/api/v2/nft/freeze-collectionPOSTFreeze collection (signed)

Smart Contracts

EndpointMethodDescription
/api/v2/contract/deployPOSTDeploy WASM contract (signed)
/api/v2/contract/callPOSTCall contract method (signed)
/api/contract/:addressGETGet contract metadata
/api/contract/:address/stateGETGet contract state
/api/contract/:address/eventsGETGet contract events

Bridge (ETH/USDC + XRGE)

EndpointMethodDescription
/api/bridge/configGETETH/USDC bridge config
/api/bridge/claimPOSTClaim bridge deposit
/api/bridge/withdrawPOSTWithdraw to EVM
/api/bridge/withdrawalsGETList pending withdrawals
/api/bridge/withdrawals/:txIdDELETEFulfill withdrawal
/api/bridge/xrge/configGETXRGE bridge config
/api/bridge/xrge/claimPOSTClaim XRGE deposit
/api/bridge/xrge/withdrawPOSTWithdraw XRGE to EVM
/api/bridge/xrge/withdrawalsGETList XRGE withdrawals
/api/bridge/xrge/withdrawals/:txIdDELETEFulfill XRGE withdrawal

Shielded Transactions

EndpointMethodDescription
/api/v2/shielded/shieldPOSTShield tokens (signed)
/api/v2/shielded/transferPOSTPrivate transfer (signed)
/api/v2/shielded/unshieldPOSTUnshield tokens (signed)
/api/shielded/statsGETShielded pool statistics
/api/shielded/nullifier/:hashGETCheck nullifier

Rollup (Phase 3)

EndpointMethodDescription
/api/v2/rollup/statusGETRollup status
/api/v2/rollup/batch/:idGETGet rollup batch
/api/v2/rollup/submitPOSTSubmit rollup transfer (signed)

Governance

EndpointMethodDescription
/api/governance/proposalsGETList all proposals
/api/governance/proposals/:tokenGETProposals by token
/api/governance/proposal/:idGETGet proposal details
/api/governance/proposal/:id/votesGETGet proposal votes

Social

EndpointMethodDescription
/api/social/track/:trackId/statsGETGet track stats (plays, likes, comments)
/api/social/track/:trackId/commentsGETGet track comments
/api/social/artist/:pubkey/statsGETGet artist stats (followers, following)
/api/social/user/:pubkey/likesGETGet user's liked track/post IDs
/api/social/user/:pubkey/followingGETGet user's followed artists
/api/social/user/:pubkey/postsGETGet user's posts
/api/social/post/:postIdGETGet a single post with stats
/api/social/post/:postId/statsGETGet post stats (likes, reposts, replies)
/api/social/post/:postId/repliesGETGet replies to a post
/api/social/timelineGETGlobal timeline (newest first)
/api/v2/social/playPOSTRecord a play (signed)
/api/v2/social/likePOSTToggle like (signed)
/api/v2/social/commentPOSTPost a comment (signed)
/api/v2/social/comment/deletePOSTDelete a comment (signed)
/api/v2/social/followPOSTToggle follow (signed)
/api/v2/social/postPOSTCreate a post (signed)
/api/v2/social/post/deletePOSTDelete a post (signed)
/api/v2/social/repostPOSTToggle repost (signed)
/api/v2/social/feedPOSTGet following feed (signed)

Messenger

EndpointMethodDescription
/api/messenger/walletsGETList messenger wallets
/api/v2/messenger/wallets/registerPOSTRegister wallet (signed)
/api/v2/messenger/conversationsPOSTCreate conversation (signed)
/api/v2/messenger/conversations/listPOSTList conversations (signed)
/api/v2/messenger/conversations/deletePOSTDelete conversation (signed)
/api/v2/messenger/messagesPOSTSend message (signed)
/api/v2/messenger/messages/listPOSTList messages (signed)
/api/v2/messenger/messages/readPOSTMark as read (signed)
/api/v2/messenger/messages/deletePOSTDelete message (signed)

Mail

EndpointMethodDescription
/api/v2/names/registerPOSTRegister mail name (signed)
/api/v2/names/releasePOSTRelease a name (signed)
/api/names/resolve/:nameGETResolve name → wallet
/api/names/reverse/:walletIdGETReverse lookup → name
/api/v2/mail/sendPOSTSend encrypted mail (signed)
/api/v2/mail/folderPOSTGet inbox/sent/trash (signed)
/api/v2/mail/messagePOSTGet single mail item (signed)
/api/v2/mail/readPOSTMark as read (signed)
/api/v2/mail/movePOSTMove to folder (signed)
/api/v2/mail/deletePOSTDelete permanently (signed)

Push Notifications

EndpointMethodDescription
/api/push/registerPOSTRegister push token (PQC-signed)
/api/push/unregisterPOSTUnregister push token (PQC-signed)

P2P

EndpointMethodDescription
/api/peersGETList known peers
/api/peers/registerPOSTRegister as peer
/api/blocks/importPOSTImport block from peer
/api/tx/broadcastPOSTReceive broadcasted tx

Authentication

Some endpoints require an API key (if configured on the node):

curl -H "X-API-Key: your-api-key" https://testnet.rougechain.io/api/stats

Rate Limiting

Rate limiting is disabled by default (--rate-limit-per-minute 0). When enabled, the node supports tiered limits:

  • Tier 1 (Validators): Proven via X-Validator-Key header + signature
  • Tier 2 (Registered peers): Recognized by IP
  • Tier 3 (Public): Separate limits for read and write endpoints