Start heredocs/integration/README.md
Magma DEX — Integration Documentation
Technical package for third-party integrators, covering the currently available Magma DEX API surface: authentication, spot markets, trading, balances, deposits and withdrawals, WebSocket streaming and error handling.
Every page here is written against the backend as implemented. Where a capability does not exist it is stated as not implemented rather than described aspirationally.
Scope
Magma is a spot exchange. All 32 listed markets are spot. Perpetual futures, leverage, margin and funding are not current functionality; /v1/perps/account/{address} is retained for compatibility and reports empty for every address.
What this API does not have, so you do not go looking for it:
| Not available | Use instead |
|---|---|
| API-key authentication | EIP-712 wallet signature → JWT (authentication.md) |
| Swap / quote / route endpoints | POST /v1/orders against the order book |
| Liquidity pools, LP tokens, LP positions | Magma is a CLOB. Magma Earn is a separate pooled market-making product |
| Webhooks / callbacks | The WebSocket stream (events-and-websocket.md) |
| A published SDK package | Call the REST API directly, or generate a client from the OpenAPI document |
| First-party 24 h traded volume | Derive from /v1/trades/{market} — see the volume note in endpoint-inventory.md |
Contents
| Document | Covers |
|---|---|
| endpoint-inventory.md | Every route, its method, auth requirement and rate limit, split into Public / Authenticated / Admin |
| authentication.md | EIP-712 challenge → JWT → refresh rotation; admin authorization; token lifetimes |
| wallet-and-settlement-flows.md | Wallet connect, network selection, deposit, withdrawal, balances, trade execution, on-chain settlement |
| events-and-websocket.md | The WebSocket protocol and its message types |
| errors.md | Status codes, error bodies, verbatim error strings and the recommended client action for each |
| environments.md | Production environment details — base URLs, supported chains, configuration |
| MULTX_MAGMADEX_INTEGRATION.md | Using Magma DEX alongside an external bridge provider (MultX): architecture boundary, required APIs, the deposit-to-trade flow |
| ../openapi.yaml | OpenAPI 3.1 specification |
Trading model
Magma DEX is a central limit order book (CLOB). Trading is POST /v1/orders against a resting order book, with price protection via a maxSlippageBps cap on market orders. See MULTX_MAGMADEX_INTEGRATION.md § Architecture boundary for how this fits with an external bridge/funding provider.
Two documents, two purposes
Both are current. They are generated differently and are authoritative for different things — use them together.
| Generated Swagger | This package + openapi.yaml | |
|---|---|---|
| Where | https://api.magmadex.trade/docs (UI), /docs/json (raw) | https://magmadex.trade/docs, /docs/openapi.yaml |
| Produced by | @fastify/swagger, from the live route schemas | Hand-maintained in this repository |
| Authoritative for | Request/response JSON shapes — emitted from the very objects Fastify validates against | Auth semantics, rate limits, error strings, and the public/authenticated/admin split |
Note the two different
/docspaths: on the API domain it is Swagger UI; on the web app domain it is this package. See environments.md for the full URL table, including a caution about the separatedocs.magmadex.tradesite.
To generate a client, download /docs/openapi.yaml or pull /docs/json from the running API.