# QFEX knowledge base

Practical knowledge about QFEX API and exchange mechanics: HMAC, trading sessions, exact decimals, quotes and bands, order outcomes, account reads, leverage, and limits. The material contains public protocol facts and synthetic illustrations, without individual accounts, strategies, or private operational data.

Freshness: documentation and public metadata checked through 2026-10-03. Authenticated protocol observations are dated 2026-10-01 and cover a primary account, not every subaccount mode. QFEX operates an offchain matching/margin exchange with blockchain funding rails according to its architecture documentation.

Annotations distinguish **observed / verified with a request or order** (limited dated evidence), **according to documentation / public source** (not necessarily live-tested), **implementation safeguard** (client policy), and **experimental / not verified** (unresolved behavior). Newer documentation alone does not expand the implemented toolkit.

## Files

| File | Covers | Open when |
|---|---|---|
| [api-and-auth.md](api-and-auth.md) | Hosts, HMAC, key scope, frame variants, REST errors | Connecting or authenticating |
| [markets-and-numbers.md](markets-and-numbers.md) | Symbols, metadata, exact decimals, minimums, bands | Building a price/quantity |
| [market-data.md](market-data.md) | MDS BBO/bands, REST summaries/books | Reading quotes or live bounds |
| [orders.md](orders.md) | IDs, submit/cancel, fills, reduce-only, unknowns | Interpreting a write |
| [account-and-leverage.md](account-and-leverage.md) | Signed positions, complete orders, equity, leverage, fees | Reading state or changing leverage |
| [rate-limits.md](rate-limits.md) | Weights, shared EMA, backoff, explicit pacing | Budgeting requests |
| [ops.md](ops.md) | Reconnect/restart, diagnostics, verification | Recovering or validating |
| [pitfalls.md](pitfalls.md) | Dated traps and uncertainty | Reviewing a change |

## Quick answers

**Where do orders go?** The authenticated trade WebSocket; public REST alone cannot place or enumerate live orders. → [api-and-auth.md](api-and-auth.md) §1

**What is signed?** HMAC over nonce and Unix seconds, with account selection separate. → [api-and-auth.md](api-and-auth.md) §2

**Can a client ID make a retry safe?** No: repeated IDs created another order. → [orders.md](orders.md) §2

**What is the fill quantity?** Preserve sent quantity and compare remaining, deduplicated trades, and fresh signed position delta. → [orders.md](orders.md) §3

**What identifies a market?** Complete base/quote symbol. → [markets-and-numbers.md](markets-and-numbers.md) §1

**What minimum applies?** The metadata quantity/lot bounds; no universal dollar minimum is asserted. → [markets-and-numbers.md](markets-and-numbers.md) §3

**Does reduce-only resting size follow position size?** No in the observed book; later zero-position matching is unresolved. → [orders.md](orders.md) §5

**Can 20 bids and 20 asks rest?** The observed ceiling is 20 total per symbol. → [orders.md](orders.md) §5

**Why do socket and REST counts disagree?** Their snapshots can catch up at different speeds. → [account-and-leverage.md](account-and-leverage.md) §2

**When can leverage change?** When that symbol is flat and has no orders. → [account-and-leverage.md](account-and-leverage.md) §4

**Is refdata a fresh band source?** It is CDN-cached; use a healthy live band for an IoC clamp. → [market-data.md](market-data.md) §2

**Does a fill journal prove REST freshness?** No; the optional ledger is experimental and exposes uncertainty. → [orders.md](orders.md) §6

## Open questions (summary)

- Subaccount auth/event scope, UAT provisioning, heartbeat semantics. → [api-and-auth.md](api-and-auth.md), [ops.md](ops.md)
- Resting reduce-only at zero/opposite exposure, IoC dust/minimums, documented terminal variants and stop visibility. → [orders.md](orders.md)
- Equity endpoint freshness, available-balance floor, fee reconciliation, stream cadence. → [account-and-leverage.md](account-and-leverage.md)
- Throttle envelope/cancel capacity and HTTP/handshake limits. → [rate-limits.md](rate-limits.md)
- Live-band cadence and non-USD quote conversion. → [market-data.md](market-data.md), [markets-and-numbers.md](markets-and-numbers.md)
- Fill-ledger and optional binding-probe evidence remains experimental. → [orders.md](orders.md), [ops.md](ops.md)

## Code

The `packages/qfex-kit` package (`@markpaper/qfex-kit`) implements the described primitives under Apache-2.0. Core namespaces cover numbers, markets, auth/tags, REST, frames, session, market data, throttle, pending memory, orders, leverage, and accounts. Synthetic exchange controls and fixtures are available through `@markpaper/qfex-kit/testing`. The separate experimental entry contains the optional ledger, binding checks, header-auth sessions, and stream-based band-age alternative. Core sessions use query authentication; core band freshness uses the band frame's own age. Workload policy is explicit; the package contains exchange primitives rather than a trading strategy.

## Disclaimer

This is not financial advice or a recommendation to trade. APIs, eligibility, listings, limits, and response shapes can change; verify current official sources and any unverified route before using funds. Examples and offline fixtures do not authorize live orders.

## Sources and license

Official sources: [QFEX documentation](https://docs.qfex.com) and [Public QFEX reference data](https://api.qfex.com/refdata). Architecture: [Architecture](https://docs.qfex.com/qfex/architecture). Topic files provide precise routes and dated proof classes.

The knowledge base and `qfex` skill are **CC BY 4.0**. Publication or adaptation requires attribution, a link to the original and license, and indication of changes. See [LICENSE.md](LICENSE.md).

<!-- license-footer -->
_© markpaper authors. Licensed under [CC BY 4.0](LICENSE.md): when publishing or adapting this material, credit “markpaper — QFEX knowledge base” and link to the original and the license._