> For the complete documentation index, see [llms.txt](https://bitbook.rwatokens.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bitbook.rwatokens.net/cedex-and-trading/cedex-and-trading/cedex-api-changelog.md). # CEDEX API Changelog ## CEDEX API Changelog **Version History · Breaking Changes · Deprecations · Migration Guides · Module-Aware** Versioned record of all changes to the CEDEX REST API and WebSocket API. The CEDEX API serves all three production modules: Equities (Module 1), Real Estate (Module 2), and CORECM — Carbon Ore, Rare Earth, and Critical Minerals (Module 3). Module-aware endpoints, WebSocket channels, and pre-flight failure reasons are tracked in the version history alongside cross-module changes. This changelog is maintained separately from the protocol-level Changelog (which tracks smart-contract and platform changes). Integrators should subscribe to the CEDEX API status page (status.cedex.market) and monitor this page for upcoming changes. *** ### Table of Contents 1. ​Versioning Policy​ 2. ​Current Version​ 3. ​Changelog​ 4. ​Deprecation Policy​ 5. ​Migration Guides​ 6. ​Upcoming Changes​ 7. ​SDK Compatibility Matrix​ *** ### 1. Versioning Policy #### Semantic Versioning The CEDEX API follows semantic versioning (`MAJOR.MINOR.PATCH`): | Component | Incremented When | Integrator Action | | ----------------------- | -------------------------------------------------------------- | ----------------------------------------------------------- | | MAJOR (v1 → v2) | Breaking changes that require code modifications | Must update integration before deprecation deadline | | MINOR (v1.0 → v1.1) | New endpoints, new fields, new features — backward compatible | No action required — existing integrations continue working | | PATCH (v1.0.0 → v1.0.1) | Bug fixes, documentation corrections, performance improvements | No action required | #### Module-Aware Versioning Module-specific endpoints, fields, and WebSocket channels follow the same versioning policy as cross-module surface. A new module-specific endpoint (for example, a future Module 4 oracle endpoint) is a MINOR change. A breaking change to a module-specific endpoint (for example, restructuring the NAV oracle response) is a MAJOR change. The platform does not maintain separate version trees per module — there is one CEDEX API version that covers all three modules uniformly. #### Base URLs | Environment | Base URL | WebSocket | | ----------- | ------------------------------------ | ------------------------------------- | | Mainnet | `https://api.cedex.market/v1` | `wss://api.cedex.market/ws/v1` | | Devnet | `https://api.devnet.cedex.market/v1` | `wss://api.devnet.cedex.market/ws/v1` | When a new MAJOR version is released, the old version remains available at its existing URL for the deprecation period (minimum 6 months). Both versions run simultaneously during the transition. #### Change Notification | Channel | What | Lead Time | | ---------------------- | ------------------------------ | ----------------------------------------- | | This changelog page | All changes | Published at release | | status.cedex.market | Breaking changes, deprecations | 30 days before | | Developer mailing list | Breaking changes | 60 days before | | API response headers | Deprecation warnings | At release — `X-CEDEX-Deprecation` header | *** ### 2. Current Version | Property | Value | | --------------- | -------------------------------------------------------------- | | Current version | v1.0.0 | | Release date | Q3 2026 (mainnet launch) | | Status | Active — current | | Base URL | `https://api.cedex.market/v1` | | SDK version | `@rwatokens/sdk` v1.0.x | | Module support | Module 1 (Equities), Module 2 (Real Estate), Module 3 (CORECM) | *** ### 3. Changelog #### v1.0.0 — Initial Release (Q3 2026) **Release type:** MAJOR — Initial public API release. **Status:** Current. The initial CEDEX API release supporting all ST22 Digital Securities trading operations, portfolio management, oracle monitoring, and WebSocket real-time data across all three modules at launch. **REST API — Public Endpoints (No Authentication)** | Method | Endpoint | Description | Module Scope | | ------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------- | | `GET` | `/v1/markets` | List all active ST22 trading pairs with 24h stats. Supports `?module=` filter. | All modules | | `GET` | `/v1/markets/{mint}` | Detailed market data for a single ST22 token. Returns module-specific fields. | All modules | | `GET` | `/v1/markets/{mint}/orderbook` | Current order book depth | All modules | | `GET` | `/v1/markets/{mint}/trades` | Recent trade history (paginated, default 50, max 200) | All modules | | `GET` | `/v1/markets/{mint}/ohlcv` | OHLCV candlestick data (1m, 5m, 15m, 1h, 4h, 1d, 1w) | All modules | | `GET` | `/v1/oracle/{mint}/custody` | Real-time custody attestation (custodied balance, supply, ratio, Ed25519 status) | All modules | | `GET` | `/v1/oracle/{mint}/nav` | NAV oracle response — appraised NAV, deviation, reappraisal target | Module 2 only | | `GET` | `/v1/oracle/{mint}/classification` | Classification oracle — USGS / DOE status, federal-action status | Module 3 only | | `GET` | `/v1/oracle/ofac/status` | OFAC SDN oracle freshness and entry count | All modules | | `GET` | `/v1/oracle/aml/{wallet}` | AML risk score (cached, public subset) | All modules | | `GET` | `/v1/health` | System health — oracle status (custody, OFAC, AML, TWAP, EDGAR, NAV, Classification), RPC latency, circuit-breaker state | All modules | **REST API — Authenticated Endpoints (Wallet Signature)** | Method | Endpoint | Description | | -------- | ---------------------- | -------------------------------------------------------------------------------------------------------- | | `POST` | `/v1/auth/challenge` | Request authentication challenge for wallet signature | | `POST` | `/v1/auth/verify` | Submit signed challenge — returns bearer token (24h TTL); response includes `eligibility` field | | `POST` | `/v1/orders` | Place market or limit order (requires Empire verification) | | `GET` | `/v1/orders` | List orders for the authenticated wallet (filter by status, mint, side) | | `DELETE` | `/v1/orders/{orderId}` | Cancel an open limit order | | `GET` | `/v1/portfolio` | Investor portfolio — balances, holding periods (with `regime` field), unlock dates | | `POST` | `/v1/estimate` | Pre-flight swap estimate — expected output, price impact, compliance check, module-aware failure reasons | **WebSocket API** | Channel | Description | Module Scope | | ------------------ | ------------------------------------------------------------------------------------------------------------- | ------------- | | `orderbook` | Order book updates (bids/asks) | All modules | | `trades` | Real-time trade stream for a specific ST22 token | All modules | | `custody` | Real-time Empire custody attestation updates per Solana block | All modules | | `circuit_breaker` | Circuit-breaker activation and deactivation events (8 breaker types) | All modules | | `nav` | Real-time NAV oracle updates and deviation tracking | Module 2 only | | `classification` | Routine Classification updates plus `federal_action_detected` and `federal_action_freeze_applied` event types | Module 3 only | | `orders` (private) | Real-time updates for the authenticated wallet's orders | All modules | **Authentication** | Property | Specification | | ------------------ | --------------------------------------------------------------------------------------------------- | | Method | Wallet signature (Ed25519) | | Flow | `POST /auth/challenge` → sign with wallet → `POST /auth/verify` → bearer token | | Token TTL | 24 hours | | Header | `Authorization: Bearer ` | | Empire requirement | All authenticated endpoints require Empire Stock Transfer KYC, KYB, AML, OFAC, and KYW verification | | Eligibility field | `RegD`, `RegS`, `RegCF`, or comma-separated combination | **Pre-Flight Compliance** The pre-flight pipeline at v1.0.0 covers eight steps: | Step | Hook Coverage | Module Scope | | ---- | ------------------------------------------------------------------ | ------------- | | 1 | Custody verification (CV-01 to CV-06) | All modules | | 2 | OFAC screening (SC-30 to SC-34) | All modules | | 3 | AML risk scoring (IV-09) | All modules | | 4 | KYC and eligibility (IV-07, IV-08) | All modules | | 5 | Holding period (HP-24) — Reg D 6mo / Reg S 12mo / Reg CF 12mo | All modules | | 6 | Price impact (CB-21) | All modules | | 7 | NAV deviation (CB-21 extension) | Module 2 only | | 8 | Classification freshness and federal-action freeze (CV-04, REG-42) | Module 3 only | **Pre-Flight Failure Reasons** | Reason | Underlying Control | Module Scope | | ------------------------ | ------------------ | ------------ | | `HOLDING_PERIOD_LOCKED` | HP-24 | All modules | | `WALLET_LIMIT_EXCEEDED` | PL-16 | All modules | | `PRICE_IMPACT_EXCEEDED` | CB-21 | All modules | | `OFAC_MATCH` | SC-30 to SC-34 | All modules | | `AML_HIGH_RISK` | IV-09 | All modules | | `CUSTODY_DISCREPANCY` | CV-01 to CV-06 | All modules | | `NAV_DEVIATION_EXCEEDED` | CB-21 (extension) | Module 2 | | `NAV_STALE` | CB-21 (extension) | Module 2 | | `CLASSIFICATION_STALE` | CV-04 (extension) | Module 3 | | `FEDERAL_ACTION_FROZEN` | REG-42 | Module 3 | **Rate Limits** | Tier | Requests/min | Orders/min | WebSocket Connections | | ----------------------------------------- | ------------ | ---------- | --------------------- | | Public (unauthenticated) | 60 | N/A | 2 | | Standard (authenticated, Empire verified) | 120 | 30 | 5 | | Verified (Empire KYC complete) | 600 | 120 | 10 | | Institutional (by arrangement) | Custom | Custom | Custom | **Error Response Format** All errors return the same envelope: ```json { "error": { "code": 6020, "name": "WalletLimitExceeded", "message": "Post-transfer balance would exceed 4.99% of supply", "category": "PositionLimit", "control_id": "PL-16", "recoverable": true, "details": { "current_balance": 450000, "transfer_amount": 100000, "max_allowed": 499000, "supply": 10000000 } }, "request_id": "req_m7n8o9" } ``` **Response Headers** | Header | Description | | ----------------------- | ------------------------------------------------------------- | | `X-CEDEX-Version` | API version serving the response (e.g., `1.0.0`) | | `X-RateLimit-Remaining` | Remaining requests in current window | | `X-RateLimit-Reset` | Unix timestamp when rate limit resets | | `X-CEDEX-Deprecation` | Present only if endpoint is deprecated — contains sunset date | **Idempotency** `POST /v1/orders` accepts an `idempotency_key` field (max 128 characters). Duplicate requests with the same key and same parameters return the original order without creating a duplicate. Same key with different parameters returns `409 IDEMPOTENCY_CONFLICT`. Keys expire after 24 hours. *** #### v1.1.0 — Planned (Q4 2026) **Release type:** MINOR — Backward-compatible additions. **Status:** Planned. | Change | Type | Description | | ------------------------------------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET /v1/markets/{mint}/stats` | New endpoint | Extended market statistics — 7d / 30d volume, unique traders, fee revenue. Module-specific breakdowns surfaced on Module 2 (NAV history) and Module 3 (classification refresh history). | | `GET /v1/governance/history` | New endpoint | On-chain governance action history (parameter changes, upgrades) | | `GET /v1/governance/pending` | New endpoint | Currently-timelocked governance proposals | | `GET /v1/pool/stats` | New endpoint | Global Pool TVL, cumulative fees, reserve ratios — aggregate across all modules | | `GET /v1/staking/summary` | New endpoint | Staking pool stats — total staked, current APY, epoch countdown | | `trades` channel — `fee_breakdown` field | New field | Per-recipient fee breakdown on trade events | | `portfolio` channel — `holding_period_pct` field | New field | Percentage completion of holding period — works across Reg D, Reg S, and Reg CF regimes | | `nav` channel — `appraisal_history` snapshot | New message type | Optional historical NAV snapshot on subscribe (Module 2 only) | | `classification` channel — `monitored_sources_summary` | New field | Roll-up summary of all monitored federal sources for the affected basin asset (Module 3 only) | All v1.0.0 endpoints and fields remain unchanged. No migration required. *** #### v1.2.0 — Planned (Q1 2027) **Release type:** MINOR — Backward-compatible additions. **Status:** Planned. | Change | Type | Description | | ---------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET /v1/oracle/{mint}/custody/history` | New endpoint | Historical custody attestation records (paginated, all modules) | | `GET /v1/oracle/{mint}/nav/history` | New endpoint | Historical NAV appraisals with deviation tracking (Module 2 only) | | `GET /v1/oracle/{mint}/classification/history` | New endpoint | Historical Classification status changes and federal-action events (Module 3 only) | | `GET /v1/oracle/aml/{wallet}/tier` | New endpoint | AML risk tier (Low / Medium / High) — abstracts the raw score for less-sensitive consumption | | `POST /v1/orders/batch` | New endpoint | Submit up to 10 orders in a single request, with atomic-or-best-effort semantics | | `alerts` WebSocket channel | New channel | Subscribe to circuit-breaker events, oracle staleness warnings, Control 42 freezes, and Module 3 federal-action detections across the entire wallet's holdings | | Pagination cursor | Enhancement | All paginated endpoints support cursor-based pagination (in addition to offset) | All v1.0.x and v1.1.x endpoints and fields remain unchanged. *** #### v2.0.0 — Future (TBD) **Release type:** MAJOR — Breaking changes. **Status:** Not scheduled. Potential breaking changes under consideration for a future v2 release. **These are not committed** and may change based on integrator feedback. | Potential Change | Rationale | | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authentication migration from wallet signature to OAuth 2.0 + wallet | Institutional integrators prefer OAuth flows for server-to-server | | Response envelope standardization | Wrap all responses in `{ data: ..., meta: ... }` envelope | | Decimal representation change (number → string) | Prevent floating-point precision loss for large amounts | | WebSocket protocol upgrade (JSON → Protobuf option) | Bandwidth reduction for high-frequency institutional feeds | | Module-aware namespacing | Optional `/v2/equities/...` and `/v2/real-estate/...` and `/v2/corecm/...` namespaces in addition to mint-keyed endpoints, for integrators who want to scope clients to a single module | When v2.0.0 is scheduled, this section will be replaced with a concrete migration guide and a minimum 6-month deprecation timeline for v1. *** ### 4. Deprecation Policy #### Timeline | Phase | Duration | Behavior | | ---------- | ------------------------- | --------------------------------------------------------------------------------------- | | Active | Current version | Full support, bug fixes, new features | | Deprecated | 6 months minimum | Still operational. `X-CEDEX-Deprecation` header added. No new features. Bug fixes only. | | Sunset | End of deprecation period | Endpoints return `410 Gone`. Integrators must have migrated. | #### Deprecation Signals When an endpoint or field is deprecated, three signals are emitted: ``` 1. CHANGELOG: Entry added to this page with deprecation date and replacement 2. RESPONSE HEADER: Every response from the deprecated endpoint includes: X-CEDEX-Deprecation: sunset=2027-06-30; replacement=/v2/markets 3. STATUS PAGE: Deprecation notice posted to status.cedex.market ``` #### Individual Endpoint Deprecation Individual endpoints within a MAJOR version can be deprecated independently. For example, if `/v1/markets/{mint}/orderbook` is replaced by a more efficient endpoint, the old endpoint enters the deprecation lifecycle while the rest of v1 remains active. #### Module-Specific Deprecation A module-specific endpoint (NAV oracle, Classification oracle) can be deprecated and replaced independently of cross-module endpoints. For example, the Module 2 NAV oracle endpoint structure could evolve to support multi-asset NAV (multiple properties under a single mint) in a future version. The original NAV endpoint would enter deprecation while the cross-module surface remains untouched. #### No Silent Deprecation The platform will never remove an endpoint, change a response format, or alter behavior without advance notice through the channels listed above. If you see `X-CEDEX-Deprecation` in any response header, check this changelog for migration instructions. *** ### 5. Migration Guides #### Migrating from Devnet to Mainnet No code changes required — only configuration: ```typescript // Devnet const client = new RwaTokensClient({ network: 'devnet', rpcEndpoint: 'https://devnet.helius-rpc.com/?api-key=YOUR_KEY', }); // Mainnet — same SDK, different config const client = new RwaTokensClient({ network: 'mainnet-beta', rpcEndpoint: 'https://mainnet.helius-rpc.com/?api-key=YOUR_KEY', }); ``` API base URLs: * Devnet: `https://api.devnet.cedex.market/v1` * Mainnet: `https://api.cedex.market/v1` Request and response formats are identical across environments. Devnet uses simulated oracle data and test tokens. Module-aware endpoints are available on both environments — the same `/v1/oracle/{mint}/nav` and `/v1/oracle/{mint}/classification` endpoints work for devnet test mints with simulated NAV and Classification data. #### Migrating Between Modules The CEDEX API is designed so that integrators do not need to change SDK calls when handling mints from different modules. The same `client.cedex.placeOrder()`, `client.cedex.estimateSwap()`, and `client.cedex.cancelOrder()` methods work for any ST22 mint regardless of module. Module-specific behavior is surfaced through module-specific oracle endpoints (`getNAVOracle()`, `getClassificationOracle()`) and module-specific WebSocket channel subscriptions. The recommended pattern for module-aware applications: 1. Read the `module` field on `GET /v1/markets/{mint}` to determine the mint's module. 2. For Module 2 mints, additionally subscribe to the `nav` WebSocket channel and surface NAV deviation in the UI. 3. For Module 3 mints, additionally subscribe to the `classification` WebSocket channel and surface federal-action status in the UI. 4. Handle the additional pre-flight failure reasons (`NAV_DEVIATION_EXCEEDED`, `CLASSIFICATION_STALE`, `FEDERAL_ACTION_FROZEN`) in error-handling code paths. #### Future: Migrating from v1 to v2 This section will be populated when v2 is scheduled. It will include: * Complete mapping of v1 endpoints to v2 equivalents. * Request and response format changes with before/after examples. * Authentication migration steps. * SDK upgrade instructions. * Timeline with deprecation and sunset dates. * Module-specific migration steps where applicable. *** ### 6. Upcoming Changes #### Under Consideration (Not Committed) These are features and changes being evaluated based on integrator feedback. Nothing in this section is guaranteed to ship. | Feature | Status | Description | | --------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GraphQL API | Evaluating | Alternative query interface for complex portfolio and market data queries; particularly useful for module-aware UIs that need to compose data across multiple oracles | | Webhook notifications | Evaluating | Server-to-server push notifications for trade fills, holding-period unlock, circuit-breaker events, NAV-deviation triggers (Module 2), and federal-action events (Module 3) | | FIX protocol gateway | Early research | FIX 4.4 / 5.0 interface for institutional trading desks | | Historical data API | Planned (v1.2) | Paginated historical trades, OHLCV, custody attestations, NAV appraisals (Module 2), and classification history (Module 3) | | Multi-mint batch operations | Planned (v1.2) | Batch order submission and portfolio queries across multiple ST22 tokens regardless of module | | Module 4 onboarding hooks | Future research | Generic oracle-extension framework for future asset classes beyond Equities, Real Estate, and CORECM | #### How to Request Features Submit feature requests through the platform's developer GitHub issue tracker or via . Include your use case, expected request/response format, and volume expectations. *** ### 7. SDK Compatibility Matrix | SDK Version | API Version | Node.js | Module Coverage | Status | | ---------------------- | ------------------------ | -------------- | ----------------- | -------------------------- | | `@rwatokens/sdk` 1.0.x | v1.0.0 | 20 LTS | All three modules | Current — active support | | `@rwatokens/sdk` 1.1.x | v1.0.0 + v1.1.0 | 20 LTS, 22 LTS | All three modules | Planned (Q4 2026) | | `@rwatokens/sdk` 1.2.x | v1.0.0 + v1.1.0 + v1.2.0 | 20 LTS, 22 LTS | All three modules | Planned (Q1 2027) | | `@rwatokens/sdk` 2.0.x | v2.0.0 | TBD | All three modules | Future (when v2 API ships) | #### SDK Update Policy | SDK Version Change | API Change | Action Required | | --------------------- | ----------------- | ---------------------------------- | | Patch (1.0.0 → 1.0.1) | Bug fixes only | Recommended but not required | | Minor (1.0.x → 1.1.0) | New methods added | Not required — existing code works | | Major (1.x → 2.0) | Breaking changes | Required — update before v1 sunset | #### Checking Your SDK Version ```typescript import { version } from '@rwatokens/sdk'; console.log(version); // "1.0.0" ``` #### Checking the API Version at Runtime ```typescript const response = await fetch('https://api.cedex.market/v1/health'); const apiVersion = response.headers.get('X-CEDEX-Version'); console.log(apiVersion); // "1.0.0" ``` #### Module-Aware SDK Usage The SDK exposes module-specific helpers without requiring integrators to instantiate per-module clients: ```typescript // Single client — handles all modules const client = new RwaTokensClient({ network: 'mainnet-beta', wallet }); // Standard methods — module-agnostic await client.cedex.placeOrder(/* ... */); await client.cedex.estimateSwap(/* ... */); // Module-specific oracle helpers const navData = await client.oracle.getNAV(mint); // Module 2 const classificationData = await client.oracle.getClassification(mint); // Module 3 ``` *** ### Related Documentation * **CEDEX API Reference** — Complete endpoint documentation with request/response schemas, code examples, and module-aware API surface. * **SDK Reference** — `RwaTokensClient` methods, error handling, WebSocket patterns. * **Changelog** — Protocol-level version history (smart contracts, platform changes). * **Network Configuration** — RPC endpoints, program IDs, environment variables, oracle PDAs. * **Smart Contract Reference** — On-chain program documentation (Transfer Hook, AMM, Oracle Aggregator, Liquidity Pool, Governance). * **Oracle Integration Guide** — Custody, OFAC, AML, TWAP, EDGAR, NAV, and Classification relay architecture. *** *RWA Tokens · CEDEX API Changelog · v1.0.0 · Q3 2026* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://bitbook.rwatokens.net/cedex-and-trading/cedex-and-trading/cedex-api-changelog.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.