API
Read SpotEx.trade market data with no key, or trade from your own software with a signed private API.
Public API
/api/public/v1/*
Market data anyone may read — prices, the order book, trades, candles, markets and assets.
No key and no signature. 1200 requests per minute per address, and readable from a browser on any site.
Private API
/api/private/v1/*
Your account — balances, orders, fills and a private live feed.
Every request is signed with an API key. No key can ever withdraw.
Public API
Binance's endpoint and field names, and Binance's types: every price, amount and volume is a decimal string, while times and counts are numbers. Only the endpoints below exist; anything else under /api/public/v1 is 404.
| Request | Parameters | Does |
|---|---|---|
| GET /api/public/v1/time | — | Server time in ms — the clock private signatures are checked against |
| GET /api/public/v1/ping | — | Connectivity check |
| GET /api/public/v1/exchangeInfo | — | Every market: status, precision, tick and step size, minimum notional, fees |
| GET /api/public/v1/coins | symbol? | Assets, their price, and whether deposits and withdrawals are open |
| GET /api/public/v1/ticker/24hr | symbol? | 24-hour statistics for one market, or every market |
| GET /api/public/v1/ticker/price | symbol? | Last price for one market, or every market that has one |
| GET /api/public/v1/ticker/bookTicker | symbol? | Best bid and ask for one market, or all |
| GET /api/public/v1/depth | symbol, limit (1–100 per side) | Order book as [price, amount] pairs, best price first |
| GET /api/public/v1/trades | symbol, limit (1–200) | Recent trades, newest first |
| GET /api/public/v1/aggTrades | symbol, limit (1–200) | Recent trades, aggregated |
| GET /api/public/v1/klines | symbol, interval, limit (1–1000), endTime? | Candles — intervals 1m 5m 15m 30m 1h 4h 1D 1W |
Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; past the limit you get 429 rate_limited with Retry-After. Market data is cached for one second.
A symbol that is not a listed market is 404 not_found on every endpoint that takes one — never a market full of zeros. A listed market with nothing in it is a normal 200: an empty book, an empty trade list.
limit accepts anything from 1 and caps quietly at the maximum shown. On depth it counts each side separately, so limit=20 returns up to 20 bids and up to 20 asks. A parameter that cannot be read is 400 bad_request, not an absence: limit=abc, limit=0 and endTime=yesterday all say so rather than quietly serving the default.
klines returns one candle per interval, so limit counts candles. An interval nothing traded in stands still — open, high, low and close all the previous close, with volume and trade count 0 — and the series begins at the market's first trade. closeTime is the open plus the interval less one millisecond, as Binance has it, so it is not the next candle's open time. Weekly candles open Monday 00:00 UTC and close Sunday 23:59:59.999.
A candle with a given open time is the same candle in every response. The series has one source, chosen by the market and not by the request: a market that has ever traded is built from its own trades at every limit and every endTime, and only a market that has never traded is built from the imported feed. A window holding none of a market's trades gives its price standing still, never another venue's prices for those hours.
The 24-hour figures are a rolling window read when you ask for it. A market that has not traded in 24 hours reports volume 0, change 0, flat and count 0, with open, high and low all equal to the last price it did trade at — and a market that has never traded reports the same shape around its reference price.
klines takes endTime in milliseconds and returns only candles opening strictly before it — pass the open time of the oldest candle you hold to page further back, and you get [] once there is nothing older. It selects candles by open time and never cuts one short: the candle it lands inside comes back whole, with all of its trades. endTime=0 is the epoch itself, so nothing opens before it.
A market that has never traded shows imported candles so it has a price history at all; their volume is 0, because the prices come from an external feed and the volume is not trading that happened here. Each interval's imported series begins at its own first candle and is never filled from a coarser one, so a daily page before the first imported daily candle is [], as is an interval the feed holds nothing at.
ticker/24hr answers for every listed market. ticker/price leaves out a market that has no price at all rather than quoting it at zero. Alongside Binance's fields, ticker/24hr carries SpotEx's own as JSON numbers — last, change24h, high24h, baseVolume24h and the rest, plus direction, the sign of the 24-hour change. Each of those numbers carries the same decimal as the Binance string beside it, not the float it was computed in. The best bid and ask are not among them: they live in ticker/bookTicker, for one market or for all, and neither are firstId and lastId — SpotEx trade ids are strings, and trades carries them itself, with quoteQty beside the price and quantity.
For updates as they happen, subscribe to public topics on the WebSocket — no ticket needed. See streaming.
curl "https://spotex.trade/api/public/v1/depth?symbol=BTC-USDT&limit=5"
// in a browser, from any site — reads are CORS-open
const book = await fetch("https://spotex.trade/api/public/v1/ticker/24hr?symbol=BTC-USDT")
.then((r) => r.json());Aggregator endpoints
The same market data, shaped to CoinGecko's and CoinMarketCap's exchange-integration specs — their endpoint names, their field names. Pair ids use underscores: BTC_USDT.
| Request | Parameters | Does |
|---|---|---|
| GET /api/coingecko/pairs | — | Every listed pair: ticker_id, base, target |
| GET /api/coingecko/tickers | — | 24-hour statistics with best bid and ask, per pair |
| GET /api/coingecko/orderbook | ticker_id, depth? | The book; depth counts both sides together |
| GET /api/coingecko/historical_trades | ticker_id, type?, limit? | Recent trades; type filters on the taker's side (buy or sell) |
| GET /api/coinmarketcap/summary | — | 24-hour statistics per pair, CMC field names |
| GET /api/coinmarketcap/assets | — | Coins with deposit and withdrawal availability |
| GET /api/coinmarketcap/ticker | — | Prices and volumes keyed by pair |
| GET /api/coinmarketcap/orderbook/BTC_USDT | depth?, level? | The book for one pair; level 1 is the best bid and ask only |
| GET /api/coinmarketcap/trades/BTC_USDT | — | Recent trades for one pair |
No key, open CORS, and the public API's rate limit, whose two headers these endpoints send too. All-pairs answers are cached for ten seconds; books and trades for one.
Prices and volumes are numbers here, as both specs state, rather than the public API's decimal strings. Errors are flat — { "error": "<message>" } — not the public and private APIs' { "error": { "code", "message" } }. A pair that is not listed is 404; one that is not even shaped like a pair id is 400.
Every listed pair appears, traded or not. One with no trades of its own carries a reference last_price with zero volume and no bid or ask — both specs enumerate an exchange's pairs, and leaving listed ones out would read as a delisting.
Private API — keys
Create keys under Security → API keys. A key can read your account and, if you allow it, place and cancel orders. No key can ever withdraw.
The secret is shown once and stored only encrypted. Restrict trading keys to your server's IP address, and revoke a key the moment you suspect it has leaked — it stops working at once.
Signing a request
X-SPOTEX-KEY— your key idX-SPOTEX-TIMESTAMP— milliseconds since the epoch; within 5 s of server time (setX-SPOTEX-RECV-WINDOWup to 60000 ms for more). Sync fromGET /api/public/v1/time.X-SPOTEX-SIGNATURE— hex HMAC-SHA256 oftimestamp + METHOD + path + query + bodywith your secret
Path and query exactly as sent; the body is the exact JSON string sent, or nothing. Amounts are decimal strings — "0.015", never 0.015.
import { createHmac } from "node:crypto";
async function call(method, pathAndQuery, body) {
const timestamp = String(Date.now());
const raw = body ? JSON.stringify(body) : "";
const signature = createHmac("sha256", SECRET)
.update(timestamp + method + pathAndQuery + raw)
.digest("hex");
const res = await fetch(BASE_URL + pathAndQuery, {
method,
headers: {
"X-SPOTEX-KEY": KEY_ID,
"X-SPOTEX-TIMESTAMP": timestamp,
"X-SPOTEX-SIGNATURE": signature,
...(raw && { "Content-Type": "application/json" }),
},
body: raw || undefined,
});
return res.json();
}
await call("POST", "/api/private/v1/order", {
symbol: "BTC-USDT", side: "BUY", type: "LIMIT",
price: "78000.00", size: "0.0150", timeInForce: "GTC",
clientOrderId: "grid-42",
});import hashlib, hmac, json, time, requests
def call(method, path_and_query, body=None):
ts = str(int(time.time() * 1000))
raw = json.dumps(body, separators=(",", ":")) if body else ""
sig = hmac.new(SECRET.encode(), (ts + method + path_and_query + raw).encode(),
hashlib.sha256).hexdigest()
headers = {"X-SPOTEX-KEY": KEY_ID, "X-SPOTEX-TIMESTAMP": ts, "X-SPOTEX-SIGNATURE": sig}
if raw:
headers["Content-Type"] = "application/json"
return requests.request(method, BASE_URL + path_and_query,
headers=headers, data=raw or None).json()Private endpoints
The stream ticket connects you to the same WebSocket the website uses: send {"op":"auth","token":"…"}, then subscribe to book:, trades: or tickers. Your own balances, orders and fills arrive without subscribing.
| Request | Key needs | Does |
|---|---|---|
| GET /api/private/v1/account | read | Balances (available, locked) and whether the key can trade |
| GET /api/private/v1/openOrders?symbol= | read | Orders still holding funds |
| GET /api/private/v1/order?clientOrderId= | ?orderId= | read | One order |
| GET /api/private/v1/myTrades?symbol=&limit= | read | Your fills, newest first (limit up to 500) |
| GET /api/private/v1/stream | read | A short-lived ticket for the private WebSocket feed |
| POST /api/private/v1/order | trade | Place an order |
| DELETE /api/private/v1/order?clientOrderId= | ?orderId= | trade | Ask to cancel one order |
| DELETE /api/private/v1/openOrders?symbol= | trade | Ask to cancel every resting order |
Orders
A limit order needs price and size; timeInForce is GTC (default), IOC or FOK, and postOnly applies to GTC. A market sell needs size; a market buy needs quoteAmount, the total to spend. Market orders never fill beyond the exchange's price-protection band; a limit priced far through the book is refused.
The response state is open (resting), processing (IOC/FOK/market — read the order back for the result), queued (held until the matching engine answers), waiting (a stop order held until its trigger) or replayed (nothing new was placed).
Send a clientOrderId (1–40 of A–Z a–z 0–9 . _ : -) and a retry is always safe: the same id returns the existing order. Without one, the id is derived from the signature, so replaying the identical signed request places nothing new. A cancel is a request — the order closes when the engine confirms, usually within a second.
Errors and limits
The public and private APIs answer errors as { "error": { "code", "message" } } — missing_credentials, invalid_key, invalid_timestamp, invalid_signature, timestamp_outside_window, ip_not_allowed, trading_not_permitted, rate_limited (with Retry-After), rejected, engine_unavailable and, on the public API, bad_request, not_found and market_data_unavailable. The aggregator feeds use their own flat shape.
- Public, per address
- 1200 / minute
- Private reads, per key
- 120 / 10 s
- Orders and cancels, per key
- 100 / 10 s
- Orders, across all keys
- 300 / 10 s
- Cancel-alls
- 10 / 10 s