Use REST when the job is request-response lookup
REST is the right entry point when you need:- public request-response market data or stats lookups
- initial snapshots before you hand off to realtime updates
- private request submission through the signed and encrypted operator write path
- a deterministic source-artifact trail for the currently published public REST contract
Base URL rule
| Contract | Meaning |
|---|---|
| Generated endpoint paths | Treat them as deployment-relative paths, not as a single fixed host guarantee |
| Current public examples | Public docs may show the active hosted domain in surrounding examples, but that is not the same thing as a canonical OpenAPI servers[] declaration |
| Adjacent private write path | GET /v2/encryption-key and POST /v2/request live under the target deployment base URL where used, but they are documented manually rather than through the generated public Swagger bundle |
Quickstart map
Strong API docs do not treat authentication, limits, and errors as footnotes. A complete DerivaDEX REST integration usually needs all of the routes below:| Concern | Start here | Why it matters |
|---|---|---|
| Authentication and private-write posture | Authentication | Private request submission depends on signing, replay-window handling, and encryption |
| Throughput and retry planning | Rate Limits | Builders need to budget request patterns before they hit production traffic |
| Failure handling | Errors | Recovery behavior differs materially across 4xx, 421, 422, 429, and 503 classes |
| Endpoint and schema discovery | Generated Reference Status | Shows which public REST surfaces are generated and how to find them |
| Source-of-truth ownership | Source Artifacts | Keeps the generated/public contract tied to the right repo-owned artifacts |
| SDK and example posture | Examples and SDKs | States what public code-starting points exist today and what does not |
The two main REST entry paths
| Path | What it covers | Primary routes |
|---|---|---|
| Public read path | Market data, stats, and initial state lookup | Generated REST reference plus family-level auth/rate-limit/error pages |
| Adjacent private write path | Trading and account-affecting requests submitted to the operator | Authentication, How to Sign DerivaDEX Requests with EIP-712, How to Encrypt Requests for the Operator |
A typical REST integration shape
| Stage | What builders usually do next |
|---|---|
| Choose transport | Confirm the job is request-response rather than streaming |
| Read public contract ownership | Check generated-reference status and source artifacts |
| Implement auth correctly | Add signing, replay-window fields, and encryption for private writes |
| Add resilience | Budget rate limits and classify errors before shipping |
| Pair with realtime | Use REST for bootstrap and realtime for ongoing updates when the client needs live state |
Scope rule
REST is not the whole platform interface. DerivaDEX integrations often use REST and realtime together:- REST for bootstrap and deterministic request-response lookup
- realtime for live deltas and account/order updates