API reference, in plain language
Every endpoint the node exposes. JWT means it needs an Authorization: Bearer <access token> header. All requests and responses are JSON; amounts are integer minor units (1 XCH = 1e8).
Error convention
Every error returns { "error": "message" } with a proper HTTP status: 400 bad request, 401 unauthorized, 404 not found, 409 conflict, 500 internal, 429 rate limited.| Method | Path | Auth | What it does |
|---|---|---|---|
| GET | /health | public | Liveness check. Railway pings this. Returns status, service, env, chain height, node. |
| POST | /auth/challenge | public | Start sign-in-with-wallet: give your address, get a random single-use challenge (10 min expiry). |
| POST | /auth/login | public | Prove ownership: address + pubkey + challenge + signature. Verifies signature AND that pubkey derives to address. Returns access + refresh JWTs. |
| POST | /auth/refresh | public | Trade a valid refresh token for a fresh access + refresh pair (rotation). |
| GET | /auth/me | JWT | Who am I? Returns the token's address and its balances. |
| POST | /tx/submit | public | Submit a signed transaction. Validates hash, signature, nonce, balance, min fee, chain id. Returns {tx_hash, status:'pending'}. |
| GET | /tx/{hash} | public | Fetch a single transaction by its 64-hex hash. 404 if missing. |
| GET | /txs | public | Recent transactions. ?address= filters by wallet, else latest chain-wide. limit max 200. |
| POST | /faucet | public | Mint 100 XCH once per address. Node signs the tx with the faucet key. |
| GET | /wallet/{address} | public | Wallet summary: balances, nonce, last 20 transactions. Lazily creates the account row. |
| GET | /wallet/{address}/nonce | public | The account's next nonce — used for signing. |
| GET | /chain/height | public | {height} — the latest block index. |
| GET | /chain/blocks | public | Recent blocks (newest first). ?after=&limit= pagination. |
| GET | /chain/blocks/{sel} | public | One block by index (number) or by hash (64 hex), including its transactions. |
| GET | /chain/validators | public | Active validators ordered by stake (also aliased at /staking/validators). |
| GET | /chain/search | public | Universal search: number → block index, 64-hex → block hash, 0x… → matching transactions. |
| GET | /trade/orderbook | public | Order book depth: bids + asks as [price, size] pairs, plus best bid/ask. |
| POST | /trade/order | JWT | Place an order (limit or market). Locks funds, matches, settles, refunds remainder. Returns {order_id, filled, trades, status}. |
| GET | /trade/orders | JWT | The caller's last 50 orders. |
| DELETE | /trade/order/{id} | JWT | Cancel an open order, refund the unfilled lock, remove from the in-memory book. |
| GET | /trade/trades | public | Recent trades for the pair, newest first. |
| POST | /staking/register | JWT | Self-stake ≥ MIN_STAKE (10 XCH) and become a validator. |
| POST | /staking/stake | JWT | Lock XCH into a validator's escrow (defaults to self). |
| POST | /staking/unstake | JWT | Schedule release of eligible stake (cooldown = 2 epochs). |
| GET | /staking/positions | JWT | The caller's stake positions with a pending/active flag. |
| POST | /multisig/wallet | JWT | Create an N-of-M multisig wallet. Deterministic address → idempotent. |
| POST | /multisig/tx | JWT | Propose a transfer from a multisig wallet (signer only). |
| POST | /multisig/tx/{id}/sign | JWT | Endorse a proposal (signer only, deduped). |
| POST | /multisig/tx/{id}/execute | JWT | Execute once unique valid signatures ≥ threshold. Moves balances + bumps nonce. |
| GET | /multisig/wallet/{address} | public | Multisig wallet detail: signers, threshold, balances, txs, pending proposals. |
| GET | /admin/metrics | JWT | Chain-wide metrics: height, TVL, 24h volume, active wallets, total accounts, total staked, validator count, pending txs, blocks last hour. |
| GET | /admin/validators | JWT | Per-validator: address, stake, rewards, blocks proposed. |
Grouped by concern
- Auth: challenge → login → refresh → me. Backend → auth deep-dive
- Transactions & wallets: submit, tx, txs, faucet, wallet, nonce. Backend → transactions deep-dive
- Chain: height, blocks, block, validators, search. Backend → blockchain deep-dive
- Trading: orderbook, order, orders, cancel, trades. Backend → exchange deep-dive
- Staking: register, stake, unstake, positions. Backend → staking deep-dive
- Multisig: wallet, tx, sign, execute. Backend → multisig