Node RPC

xrs-node 0.1.1port 5600148 routes

Four routes write; everything else reads.

Base

base URLhttp://<host>:56001
transportHTTP/1.1, no TLS
CORS*
bodyJSON
errors{"error":"…"}, HTTP 200; 501 only on the governance and claim stubs
write rate30 per minute per IP
write body256 KiB
planner body16 KiB
readsno limit
amountslamports unless the key ends _xrs
token amountsthe token's decimals

Write

RouteFirst instructionPre-checksSuccess
POST /submitanyadmission{"status": "ok", "signature"}
POST /stakeStakesigner = pubkey; balance ≥ amount; roster key on mainnet{"status": "queued", "staked", …}
POST /unstakeUnstakestake ≥ amount; unstake all or keep ≥ 1,000 XRS; at least 1 XRS{"status": "queued", "unstaked", "unbonding_period_slots": 151200}
POST /pq-registerPqKeyRegistersigner = ed25519_pubkey{"status": "queued", "ed25519_pubkey"}

Body for all four: {"tx_base64":"…"}, the bincode transaction in base64 (envelope).

curl -s -X POST http://138.197.116.81:56001/submit \ -H 'Content-Type: application/json' \ -d '{"tx_base64":"<base64>"}' # {"status":"ok","signature":"<base58>"} | {"error":"…"}
await client.sendInstruction(wallet, ix); // POST /submit await client.stakeXrs(wallet, 1000); // POST /stake await client.unstakeXrs(wallet, 1000); // POST /unstake // POST /pq-register, 1,952-byte key await client.pqKeyRegister(wallet, pqPublicKey, 'dilithium3', 3);

Admission

rate limitRate limited. Max 30 write RPCs per minute per IP.
base64Invalid base64 encoding
bincodeFailed to deserialize transaction
signatureTransaction validation failed: Invalid transaction signature
instruction countTransaction validation failed: Too many instructions in transaction
instruction sizeTransaction validation failed: Instruction data exceeds size limit
legacy transferTransaction validation failed: Legacy SystemInstruction::Transfer is disabled
SubDelegateTransaction validation failed: SubDelegate is disabled (XWC-82)
federationPublic self-staking is closed during federated beta
on chain alreadyTransaction already processed
in the mempool alreadyTransaction already in mempool
blockhashTransaction rejected: recent_blockhash expired or unknown
payer below the fee, quota full"status":"rejected_underfunded_quota"
pool full"status":"rejected_mempool_full"
The hint's /v2/recent_blockhash does not exist. Use JSON-RPC getLatestBlockhash, port 50008.

Chain and stake

GET /health{"status":"ok"}
GET /blocks50 newest blocks, hashes as byte arrays
GET /stake/{address}stake, isValidator (≥ 1,000 XRS), earns_staking_rewards (≥ 100 XRS), 7 % APR estimates
GET /account/{address}/unstakingsessions[]; *_time = slot × 4 s
GET /network/economicsemission, block reward, halving, fees, staking totals
curl -s http://138.197.116.81:56001/network/economics # {"chain_height":…,"current_block_reward_xrs":10.0, # "emission_cap_xrs":500000000.0,"base_tx_fee_xrs":0.001,…}

Tokens

GET /tokens{"tokens":[…]}, unpaginated
GET /token/balance/{address}/{token_id}balance, token_info
GET /token/accounts/{address}native_xrs (lamports), token_accounts[]

Contracts and launchpads

GET /contractscontract_id, type, owner, is_active
GET /contract/{id}contract.state, keyed by type
GET /contract/{id}/quote?input_token=&amount=swap quote; price_impact_pct is a string
GET /contract/{id}/vesting/{wallet}{"vesting":{"enabled":false}}: deploy refuses vesting
GET /launchpadsevery launchpad, newest first; xeris_fee_bps 77
GET /launchpad/{id}/quote?xrs_amount=tokens_out, fees, price_impact_pct (number)

Agents, capabilities, tasks

GET /agent/registry/{owner}agents[]: limits, spend, revoked
GET /agent/validate/{agent}/{owner}authorized, revoked, expired, agent
GET /capabilitiesactive listings with an active identity
GET /tasksopen_tasks, data[]
GET /tasks/{id}one TaskEntry

Planner

Route, actionRequestReturns
POST /agent/plan{"action":"…",…}variant_index, variant_name, params
transferfrom, to, amount_xrsNativeTransfer, fee, sufficient_balance
swappool_id, token_in, amount_in, slippage_pctContractCall, args as 16 bytes, quote
buy_launchpadlaunchpad_id, xrs_amount, slippage_pctContractCall, args as a JSON object, quote
stakepubkey, amount_xrsStake
wrap, unwrapamount_xrsWrapXrs, UnwrapXrs

Read-only: returns what to sign, never signs.

curl -s -X POST http://138.197.116.81:56001/agent/plan \ -H 'Content-Type: application/json' \ -d '{"action":"transfer","from":"<from>","to":"<to>","amount_xrs":1.5}' # {"action":"transfer","variant_index":11,"variant_name":"NativeTransfer", # "params":{"from":"…","to":"…","amount":1500000000},"amount_xrs":1.5, # "fee":1000000,"fee_xrs":0.001,"sender_balance":…, # "sufficient_balance":true}
import { fromPlan } from 'xeris-sdk'; // POST /agent/plan const plan = await client.planTransfer(wallet.publicKey, to, 1.5); await client.sendInstruction(wallet, fromPlan(plan)); // signs and submits

Governance, ZK, PQ

GET /governance/proposalsproposals[]; timestamps are slot × 4,000 ms
GET /governance/lock/{address}locked_amount, locked_xrs, delegate
GET /zk/proofs/{identity}proofs[] by submitter
GET /zk/verify/{proof_id}one ZkProofRecord
GET /zk/statstotal_proofs, total_verified
GET /pq/keys/{address}has_pq_key, algorithm, security_level, key_hash, active
GET /pq/statustotal_registered, algorithms, quantum_ready_pct

Prices

GET /price-history?pool_id=&limit=last limit (500, ≤ 10,080); one per 100 blocks
GET /pools/price-historylast 100 per pool

Node-local, not consensus.

Disabled

/airdrop/{address}/{amount}HTTP 200, "status":501
POST /stake/claimHTTP 501
POST /governance/{vote,propose,lock,delegate}HTTP 501, variants 39–41 instead
POST /token/{mint,transfer,burn,create}HTTP 200, Direct RPC mutation disabled…
POST /contract/{deploy,call}HTTP 200, Direct RPC mutation disabled…
POST /rwa/{create,update_status}HTTP 200, Direct RPC mutation disabled…

State changes go through /submit.