Build anything on RealiaX.
RealiaX is an on-chain exchange for Realia — real, redeemable things — tokenized and traded on a live central-limit order book with peer-to-peer perpetuals. This reference documents the complete REST API for programmatic trading, market making, and data.
https://commodities.gocube.org/api/v2/commodityQuick start.
Every market-data endpoint is public. Fetch the market list, then a book and candles:
# 1. all markets
curl https://commodities.gocube.org/api/v2/commodity/series
# 2. order book + candles
curl "https://commodities.gocube.org/api/v2/commodity/markets/egotv55usdt/orderbook"
curl "https://commodities.gocube.org/api/v2/commodity/ohlcv?symbol=egotv55usdt&interval=1h&limit=100"To trade, generate an API key and send it as X-API-Key. That’s the whole model — no request signing, no nonces.
Conventions.
| Concept | Rule |
|---|---|
symbol | Lowercase market id used by trading endpoints, e.g. egotv55usdt. Get the list from /series. |
ticker_id | Aggregator pair id, uppercase BASE_TARGET for spot (EGOTV55_USDT) and BASE-PERP for perps. |
| Numbers | All prices, sizes and amounts are decimal strings — never floats — to preserve precision. Parse with a decimal library. |
| Timestamps | Unix time. OHLCV bucket times are seconds; trade & book timestamps are milliseconds. |
| Base / target | Base = the Realia token; target = the settlement currency (USDT). Price is target per 1 base. |
| Fees | A flat 0.15% trading fee applies to every fill, maker and taker. |
| Errors | Non-2xx responses return { "errors": ["code"] }. See the error reference. |
Enumerations.
| Field | Values | Notes |
|---|---|---|
side | buy · sell | Order direction. |
type | limit · market · stop_loss · take_profit | Limit/stop require price; stop/take require stop_price. |
state | wait · done · cancel | wait = open/resting, done = fully filled, cancel = cancelled. |
interval | 1m 5m 15m 30m 1h 4h 1d 1w | OHLCV bucket sizes. |
product_type | Perpetual | Derivatives contract type. |
Authentication.
Market data is public — no key required. Trading requires an API key issued to your RealiaX (Cubemail) account. Send it on every trading request:
X-API-Key: cdx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxAPI keys.
Manage keys from your account or the generator below. Programmatic key management is also available with an existing session:
/keysIssue a new key. Body { "label": "my-bot" }. Returns the plaintext key once plus its id and prefix.
/keysList your keys (prefixes and labels only — never the secret).
/keys/:id/revokePermanently revoke a key.
Sign in with your Cubemail account to generate an API key.
Sign inRate limits.
Limits are generous and designed for real-time bots and minutely aggregator polling.
| Surface | Guidance |
|---|---|
| Market data | Poll as often as once per second per endpoint. Books and candles update continuously; there is no benefit to tighter polling. |
| Data polling | Minutely snapshot polling of market data is fully supported; no key or sign-up required. |
| Trading | Sustained order placement/cancel is fine for market making. Burst-cancel-and-replace loops of a few seconds are the intended pattern. |
| Abuse | Excessive traffic may be throttled per key/IP. If you need higher throughput, contact the team. |
Markets & tickers.
/seriesEvery listed market with live price, 24h statistics and top-of-book. This is the canonical market list.
Response — array of
| Field | Type | Description |
|---|---|---|
symbol | string | Trading symbol, e.g. egotv55usdt. |
market_id | string | Internal market identifier. |
token_currency_id | string | Base (Realia token) code. |
settlement_currency_id | string | Target (settlement) code, e.g. usdt. |
oracle | string | Reference/index price. |
last | string | Last trade price. |
best_bid / best_ask | string | Top of book. |
volume24h | string | 24h quote volume. |
high_24h / low_24h | string | 24h high / low. |
change24h | string | 24h change (percent). |
state | string | active · redemption_open · settling · closed. |
/series/:symbolA single market by symbol, e.g. /series/egotv55usdt.
/ratesReference/settlement FX rates used across the exchange.
Order book.
/markets/:symbol/orderbookAggregated depth for a market — resting bids and asks by price level.
{
"bids": [ ["388.10", "42.5"], ["388.05", "18.0"] ],
"asks": [ ["389.40", "31.2"], ["389.55", "12.8"] ]
}Trades.
/markets/:symbol/tradesRecent completed trades — the tape. Each trade carries price, amount, side and time.
OHLCV / klines.
/ohlcvCandlesticks aggregated from trades — the charting feed for any client.
Query parameters
| Param | Type | Req | Description |
|---|---|---|---|
symbol | string | one of | Market symbol, e.g. egotv55usdt. |
ticker_id | string | one of | Aggregator id, e.g. EGOTV55_USDT. |
interval | enum | no | Bucket size (default 1h). |
from / to | int | no | Unix seconds range. |
limit | int | no | Max candles (default 1000, cap 5000). |
{ "market": "egotv55usdt", "interval": "1h", "candles": [
{ "time": 1720008000, "open": "388.1", "high": "389.4",
"low": "387.6", "close": "388.9", "volume": "142.5" }
] }Account.
/meYour account and tradeable balances (available + locked) per currency.
Orders.
/ordersPlace an order.
Body
| Field | Type | Req | Description |
|---|---|---|---|
symbol | string | yes | Market symbol. |
side | enum | yes | buy or sell. |
type | enum | yes | limit · market · stop_loss · take_profit. |
price | string | limit/stop | Limit price. |
volume | string | yes | Order size in base units. |
stop_price | string | stop/tp | Trigger price. |
curl -X POST https://commodities.gocube.org/api/v2/commodity/orders \
-H "X-API-Key: $REALIAX_KEY" \
-H "content-type: application/json" \
-d '{"symbol":"egotv55usdt","side":"buy","type":"limit","price":"388.50","volume":"2"}'Response 201
{ "id": 5231, "uuid": "…", "market": "egotv55usdt",
"side": "buy", "type": "limit", "price": "388.50",
"volume": "2", "locked": "777.00", "state": "wait" }/ordersYour open (resting) orders.
/orders/:id/cancelCancel a resting order and release its lock.
/positionsYour holdings and unrealised P&L per market.
Margin & perpetuals.
/margin/openOpen an isolated-margin perpetual position. Body: symbol, side, leverage, collateral, size.
/margin/:id/closeClose a position; realises P&L to your balance.
/margin/positionsYour open margin positions with entry, size, leverage and liquidation price.
signed_order + order_signature). Off-chain markets — where most bots operate — take orders with no signature.Build a market-making bot.
A minimal two-sided quoter — read the reference price, lay a bid and an ask around it, and cancel-and-replace on a loop so your book is always fresh. This is the shape RealiaX’s own market maker uses.
const BASE = "https://commodities.gocube.org/api/v2/commodity";
const H = { "content-type": "application/json", "X-API-Key": process.env.REALIAX_KEY };
const SYMBOL = "egotv55usdt";
const SPREAD = 0.002, SIZE = "0.5"; // 20 bps each side
const j = (u, o) => fetch(BASE + u, o).then(r => r.json());
async function tick() {
const m = (await j("/series")).find(x => x.symbol === SYMBOL);
const ref = parseFloat(m.last) || parseFloat(m.oracle);
if (!ref) return;
const open = await j("/orders", { headers: H }); // clear our quotes
await Promise.all(open.map(o =>
fetch(`${BASE}/orders/${o.id}/cancel`, { method: "POST", headers: H })));
const bid = (ref * (1 - SPREAD)).toFixed(4); // re-quote both sides
const ask = (ref * (1 + SPREAD)).toFixed(4);
for (const [side, price] of [["buy", bid], ["sell", ask]])
await fetch(BASE + "/orders", { method: "POST", headers: H,
body: JSON.stringify({ symbol: SYMBOL, side, type: "limit", price, volume: SIZE }) });
console.log("quoted", bid, "/", ask);
}
setInterval(tick, 5000);Extend it with multiple ladder levels, inventory skew, protective stop_loss orders and perp hedges via /margin/open. Use /ohlcv for signals and /me to track inventory.
Error reference.
Errors return a non-2xx HTTP status with a body of { "errors": ["code"] }.
| HTTP | Code | Meaning |
|---|---|---|
| 400 | server.method.invalid_message_body | Malformed JSON body. |
| 401 | auth.required · api_key.invalid | Missing or invalid X-API-Key. |
| 404 | unknown ticker_id · record.not_found | No such market / ticker / order. |
| 422 | market.order.invalid_price · invalid_volume | Bad price or size. |
| 422 | market.account.insufficient_balance | Not enough balance to lock the order. |
| 422 | commodity.order.signature_required | On-chain market needs an EIP-712 signature. |
| 429 | rate_limited | Slow down; retry after a short backoff. |
Changelog.
The API is versioned in the path (/api/v2/commodity). Additive changes ship without a version bump; breaking changes get a new version.
