SKILL.md

---
name: qfex
license: CC-BY-4.0. Publication and distribution require attribution to “markpaper — QFEX knowledge base.” Full terms are in LICENSE.md next to the skill.
description: Use for QFEX exchange integrations and API analysis involving HMAC auth, trade WebSocket sessions, exact numeric frames, quotes and price bands, signed positions, open-order pages, fills, cancellation, leverage, weighted limits, or unknown outcomes. Triggers—QFEX, api.qfex.com, trade.qfex.com, mds.qfex.com, @markpaper/qfex-kit, QFEX order, QFEX balance, QFEX leverage. Read venue facts and implemented API boundaries before writing code; distinguish dated observations from documentation and experimental behavior.
---

# QFEX: how to use the knowledge base

## License

**CC BY 4.0.** This skill and the `knowledge/qfex/` knowledge base are markpaper materials. Publication/adaptation requires credit to “markpaper — QFEX knowledge base,” a link to the original and license, and indication of changes. Preserve attribution when moving material. Terms: [LICENSE.md](LICENSE.md).

Index: `knowledge/qfex/README.md`. Documentation and public metadata were checked through 2026-10-03; authenticated observations dated 2026-10-01 cover a primary account, not every subaccount mode.

## SDK and transport

Use `@markpaper/qfex-kit` (`packages/qfex-kit`, Apache-2.0) for implemented mechanics. It provides exact `numbers`, reference-data `markets`, HMAC and neutral tags in `auth`, `rest`, trade `frames` and `session`, `mds`, explicit `throttle`, `pending`, `orders`, `leverage`, and `account`. Synthetic exchange controls are an explicit import from `@markpaper/qfex-kit/testing`. The package README maps exports to topic files.

The separate `@markpaper/qfex-kit/experimental` entry contains `createFillLedger`, optional binding checks, `createHeaderAuthTradeSession`, and `createStreamAgeMarketData`. Core sessions use published query authentication, and core bands age from their own frame. The header-auth and stream-age alternatives need independent verification. Do not attach the ledger to account reads by default or describe its acceptance as proof of indexer freshness. Some transitions and expired evidence remain uncertain. Protocol types documented by the venue do not imply that the toolkit implements TWAP, modify, stop, funding, or onboarding workflows.

## A. Read the relevant file first

Open only the relevant topics, including their pitfalls and open questions. For multi-topic code, read each affected file. Labels control confidence: documentation-only, inferred, and experimental behavior must not be presented as live-verified facts. Verify current public facts when they may have changed.

| Topic | Reference |
|---|---|
| Hosts, credentials, handshake/auth, session/read correlation | `knowledge/qfex/api-and-auth.md` |
| Symbols, exact arithmetic, tick/lot/minimums, bands | `knowledge/qfex/markets-and-numbers.md` |
| BBO, band stream, REST book/contract fallback | `knowledge/qfex/market-data.md` |
| Placement/cancel, IDs, fills, reduce-only, unknowns | `knowledge/qfex/orders.md` |
| Signed state, full order pages, equity, leverage, fees | `knowledge/qfex/account-and-leverage.md` |
| Shared weights, EMA, throttling, REST pacing | `knowledge/qfex/rate-limits.md` |
| Reconnect, restart, diagnostics, verification | `knowledge/qfex/ops.md` |
| Dated traps and unresolved behavior | `knowledge/qfex/pitfalls.md` |

## B. Invariants that change implementation decisions

1. HMAC signs nonce and Unix seconds. Build fresh credentials, preserve canonical account IDs, and redact custom headers/query credentials. → `api-and-auth.md` §2
2. A successful upgrade still needs auth and subscriptions. Serialize reads per response kind; replace a socket after a read timeout before reusing that kind. → `api-and-auth.md` §3
3. Price/quantity are JSON numbers on wire. Use exact decimal/grid helpers to construct literals; booleans remain booleans. Market identity is complete base/quote symbol, and quotes are not universally USD. → `markets-and-numbers.md` §1–3
4. Refdata bands can be CDN-stale. A healthy live `minmax_price` band with explicit freshness is required for aggressive clamps. Passive out-of-band orders were accepted in observed behavior. → `markets-and-numbers.md` §4
5. Client IDs correlate and tag ownership; they **do not deduplicate**. Never replay a possibly sent placement. Caller magic/flags have no universal default. → `orders.md` §2
6. Keep original submitted size. Event quantity may be one execution; partial FILLED is not terminal. Resolve fill from remaining, deduplicated trades, and fresh signed delta. → `orders.md` §3
7. Exact UUID cancellation and client-ID cancellation have different scopes. NO_SUCH_ORDER is not proof of no fill. Broad account-cancel commands require a separate scoped workflow. → `orders.md` §4
8. Resting reduce-only does not shrink with exposure. Matching after zero/opposite exposure is not established. The observed resting ceiling is 20 total per symbol, combining both sides. → `orders.md` §5
9. Timeout/disconnect after send is unknown. Pending locks and exact history resolution precede another conflicting intent; a history miss proves nothing. → `orders.md` §6
10. Positions are signed. Only a final short order page proves pagination complete; malformed or interrupted reads never mean empty. REST count lag is not independent binding evidence. → `account-and-leverage.md` §1–2
11. Leverage lock is per symbol while it has a position/order. Equity is not available balance; zero available with positive margin remains ambiguous. → `account-and-leverage.md` §3–4
12. The documented budget is user-shared, weighted, and EMA based. Local pacing/fuse/concurrency values are explicit caller policy. Uncorrelated RateLimited can leave a sent intent unknown. → `rate-limits.md` §1–3

## C. Implement and validate within the task's scope

- Use the package helper before reimplementing its protocol logic. Keep workload windows, limits below venue ceilings, and polling settings explicit.
- Preserve local no-send, exchange rejected, accepted, and unknown outcome states in application interfaces.
- Test against synthetic fixtures and the fake exchange. Its adverse controls model simulation hypotheses rather than measured venue timing.
- Public smoke reads metadata and market data without keys, accounts, or orders. Authenticated/live validation is a separate action within the user's authorization; code generation alone does not authorize trading.
- If an unverified behavior matters, identify it and propose the smallest relevant query or separately authorized test. Never substitute a strategy-specific default for missing venue evidence.

## D. Investigate a discrepancy

Compare current metadata, raw correlated socket frames, complete order pages, signed REST rows, exact client-ID history, and cache/clock evidence. Check original sent size, minimum remaining, trade deduplication, ID case, and pending locks before interpreting alerts. Record new public facts with their date and confidence; resolve contradictions explicitly without publishing account identities or private samples.