CEDEX API Reference

CEDEX API Reference

Compliant Exchange for Digital Securities · REST + WebSocket · v1.0 · Module-Aware

API reference for cedex.market — the trading venue that preserves all 42 Transfer Hook security controls on every ST22 Digital Securities trade. Dual-layer architecture: centralized order matching (Web2 performance) with decentralized Solana settlement (Web3 finality). The 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, error codes, and WebSocket channels are documented inline.

---

Table of Contents

1. Overview​

2. ​Authentication​

3. ​Rate Limits​

4. ​Public Endpoints​

5. ​Authenticated Endpoints​

6. ​WebSocket API​

7. ​Compliance Pre-Flight​

8. ​Error Reference​

9. ​Pagination​

10. ​Idempotency​

11. ​Code Examples​

12. ​Module-Aware API Surface​

13. ​Changelog​

---

1. Overview

Base URLs

Environment	REST API	WebSocket
Production	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

Request Format

All requests use JSON. All responses return JSON.

Content-Type: application/json
Accept: application/json

Timestamps

All timestamps are Unix seconds (UTC) unless otherwise noted. ISO 8601 format is available via the ?format=iso query parameter.

Amounts

All token amounts are in raw units (with decimals applied). For an ST22 token with 9 decimals, 1_000_000_000 = 1.0 token. SOL amounts are in lamports (1_000_000_000 = 1.0 SOL). Stablecoin amounts (USDC, PYUSD) are in 6-decimal raw units (1_000_000 = 1.0 stablecoin unit).

Performance

Metric	Value
Pre-flight compliance	2,000–3,000ms
On-chain execution	400–600ms
Total order-to-settlement	3–4 seconds
Block finality	~13 seconds (32 confirmations)
Order book sync	400ms (1 Solana block)
Compute units per swap	~800,000 CU

---

2. Authentication

Wallet Signature Authentication

CEDEX uses Solana wallet signature authentication. All authenticated endpoints require a signed message proving wallet ownership.

Step 1: Request Challenge

POST /auth/challenge

Request:

{
  "wallet": "9aB2xY..."
}

Response:

{
  "challenge": "CEDEX-AUTH-1711929600-a1b2c3d4",
  "expires_at": 1711929900
}

Step 2: Sign and Submit

POST /auth/verify

Request:

{
  "wallet": "9aB2xY...",
  "challenge": "CEDEX-AUTH-1711929600-a1b2c3d4",
  "signature": "base58-encoded-ed25519-signature"
}

Response:

{
  "token": "eyJhbGciOiJFZDI1NTE5...",
  "expires_at": 1712016000,
  "wallet": "9aB2xY...",
  "empire_verified": true,
  "eligibility": "RegD",
  "jurisdiction": "US",
  "kyc_status": "verified",
  "kyc_expires": 1743465600
}

The eligibility field reports the offering exemption(s) the wallet is verified for: "RegD" (US accredited), "RegS" (non-US), "RegCF" (US retail crowdfunding), or a comma-separated combination such as "RegD,RegS" for wallets that satisfy multiple paths.

Using the Token

Include the bearer token in all authenticated requests:

Authorization: Bearer eyJhbGciOiJFZDI1NTE5...

Token lifetime: 24 hours. Refresh by repeating the challenge/verify flow.

Empire Verification Requirement

All authenticated endpoints require Empire Stock Transfer verification. Wallets that have not completed Empire's KYC, KYB, AML, OFAC, and KYW verification receive:

{
  "error": {
    "code": "EMPIRE_VERIFICATION_REQUIRED",
    "message": "Wallet not verified by Empire Stock Transfer. Complete onboarding through your issuer."
  }
}

Empire is the platform's sole investor onboarding authority. The platform does not perform investor verification or operate a KYC portal independent of Empire.

---

3. Rate Limits

Tier	Requests/min	Orders/min	WebSocket Subscriptions
Standard	120	30	10 channels
Verified (Empire KYC complete)	600	120	50 channels
Institutional (on request)	3,000	600	Unlimited

Rate-limit headers on every response:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1711929660

Exceeding limits returns 429 Too Many Requests:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 2026-04-01T00:01:00Z",
    "retry_after": 1711929660
  }
}

---

4. Public Endpoints

No authentication required. Read-only market data.

GET /markets

List all active ST22 trading pairs across all modules.

Query Parameters:

Parameter	Type	Description
module	string	Filter by module: "equities", "real_estate", "corecm"

Response:

{
  "markets": [
    {
      "mint": "7xK9p2...",
      "symbol": "ACME-ST22",
      "module": "equities",
      "issuer_name": "ACME Corporation",
      "issuer_cik": "0001234567",
      "decimals": 9,
      "price_sol": 0.0001153,
      "price_usd": 0.0184,
      "volume_24h_sol": 1250.5,
      "volume_24h_usd": 200080.0,
      "pool_depth_sol": 50000.0,
      "pool_depth_tokens": 433043000000000,
      "change_24h_pct": -2.14,
      "high_24h": 0.0001205,
      "low_24h": 0.0001098,
      "total_supply": 1000000000000000000,
      "circulating_supply": 200000000000000000,
      "custody_ratio": 1.0,
      "custody_verified": true,
      "hook_active": true,
      "controls_active": 42,
      "is_trading": true,
      "circuit_breaker_active": false,
      "listed_at": 1711929600
    }
  ],
  "count": 1,
  "timestamp": 1711930000
}

The module field on each market object is one of "equities", "real_estate", or "corecm". Module 2 markets include additional NAV-related fields (see §12.2). Module 3 markets include additional Classification-related fields (see §12.3).

GET /markets/{mint}

Get detailed market data for a single ST22 token.

Path Parameters:

Parameter	Type	Description
mint	string	ST22 mint address (base58)

Response: Same structure as the single-market object above, plus:

{
  "...market fields...",
  "security_config": {
    "max_wallet_percent_bps": 499,
    "price_impact_max_bps": 200,
    "circuit_breaker_threshold_bps": 3000,
    "circuit_breaker_cooldown_secs": 86400,
    "holding_period_reg_d_secs": 15778800,
    "holding_period_reg_s_secs": 31536000,
    "holding_period_reg_cf_secs": 31536000
  },
  "custody": {
    "custodied_balance": 1000000000,
    "token_supply": 1000000000,
    "ratio": 1.0,
    "attestation_slot": 285000000,
    "ed25519_verified": true,
    "last_update_ms": 1711930000400
  },
  "fee_config": {
    "total_bps": 500,
    "pool_bps": 44,
    "issuer_bps": 200,
    "staking_bps": 150,
    "protocol_bps": 106
  }
}

For Module 2 markets, the response also includes a nav object (see §12.2). For Module 3 markets, the response also includes a classification object (see §12.3).

GET /markets/{mint}/orderbook

Current order book.

Query Parameters:

Parameter	Type	Default	Description
depth	integer	20	Number of levels per side (max 100)

Response:

{
  "mint": "7xK9p2...",
  "bids": [
    { "price": 0.0001150, "amount": 50000000000, "total": 50000000000 },
    { "price": 0.0001145, "amount": 30000000000, "total": 80000000000 },
    { "price": 0.0001140, "amount": 75000000000, "total": 155000000000 }
  ],
  "asks": [
    { "price": 0.0001155, "amount": 40000000000, "total": 40000000000 },
    { "price": 0.0001160, "amount": 25000000000, "total": 65000000000 },
    { "price": 0.0001165, "amount": 60000000000, "total": 125000000000 }
  ],
  "spread_bps": 4.3,
  "mid_price": 0.00011525,
  "timestamp": 1711930000
}

GET /markets/{mint}/trades

Recent trades. Newest first.

Query Parameters:

Parameter	Type	Default	Description
limit	integer	50	Results per page (max 200)
before	string	—	Cursor: trade ID for pagination
after	string	—	Cursor: trade ID for pagination

Response:

{
  "trades": [
    {
      "id": "trade_a1b2c3d4",
      "mint": "7xK9p2...",
      "side": "buy",
      "amount": 10000000000,
      "price": 0.0001153,
      "value_sol": 1.153,
      "fee_sol": 0.05765,
      "fee_breakdown": {
        "pool": 0.005074,
        "issuer": 0.02306,
        "staking": 0.017295,
        "protocol": 0.012221
      },
      "price_impact_bps": 12,
      "tx_signature": "5vGh7kJ...",
      "block_slot": 285000150,
      "timestamp": 1711929990
    }
  ],
  "has_more": true,
  "next_cursor": "trade_x9y8z7w6"
}

GET /markets/{mint}/ohlcv

Candlestick / OHLCV data.

Query Parameters:

Parameter	Type	Default	Description
interval	string	1h	1m, 5m, 15m, 1h, 4h, 1d, 1w
from	integer	—	Start time (Unix seconds)
to	integer	—	End time (Unix seconds)
limit	integer	100	Max candles (max 1000)

Response:

{
  "mint": "7xK9p2...",
  "interval": "1h",
  "candles": [
    {
      "timestamp": 1711929600,
      "open": 0.0001140,
      "high": 0.0001165,
      "low": 0.0001098,
      "close": 0.0001153,
      "volume_tokens": 500000000000,
      "volume_sol": 57.65,
      "trade_count": 142
    }
  ],
  "count": 1
}

GET /oracle/{mint}/custody

Current Empire Stock Transfer custody attestation.

Response:

{
  "mint": "7xK9p2...",
  "custodied_balance": 1000000000,
  "token_supply": 1000000000,
  "ratio": 1.0,
  "attestation_slot": 285000200,
  "attestation_timestamp": 1711930080,
  "ed25519_verified": true,
  "empire_pubkey": "EmpK3y...",
  "discrepancy_detected": false,
  "slot_age": 0,
  "latency_ms": 145
}

GET /oracle/{mint}/nav (Module 2 only)

Most recent appraised NAV for a Module 2 ST22 mint. See §12.2.

GET /oracle/{mint}/classification (Module 3 only)

Most recent USGS / DOE classification status and federal-action status for a Module 3 ST22 mint. See §12.3.

GET /oracle/ofac/status

OFAC oracle health.

Response:

{
  "last_refresh": 1711929600,
  "next_refresh": 1711933200,
  "entry_count": 12847,
  "list_hash": "a1b2c3d4e5f6...",
  "is_fresh": true,
  "staleness_threshold_secs": 86400,
  "halt_threshold_secs": 172800,
  "status": "healthy"
}

GET /oracle/aml/{wallet}

AML risk score for a wallet (cached, public subset).

Response:

{
  "wallet": "9aB2xY...",
  "risk_score": 12,
  "disposition": "approve",
  "provider": "chainalysis+trm",
  "scored_at": 1711926000,
  "cache_expires": 1711947600,
  "is_fresh": true
}

Scores 31–70 return "disposition": "review" with limited detail. Scores 71–100 return "disposition": "reject".

GET /health

System health check.

Response:

{
  "status": "operational",
  "version": "1.0.0",
  "solana_slot": 285000250,
  "solana_tps": 2847,
  "rpc_latency_ms": 45,
  "oracle_status": {
    "custody": "healthy",
    "ofac": "healthy",
    "aml": "healthy",
    "twap": "healthy",
    "edgar": "healthy",
    "nav": "healthy",
    "classification": "healthy"
  },
  "circuit_breaker_global": false,
  "mev_protection": "active",
  "timestamp": 1711930100
}

The nav and classification fields under oracle_status reflect the aggregate health of those oracle networks across all Module 2 and Module 3 mints respectively. Per-mint oracle health is reported by the per-mint endpoints.

---

5. Authenticated Endpoints

All endpoints below require Authorization: Bearer <token> from a wallet that has completed Empire Stock Transfer verification.

POST /orders

Place a market or limit order. Every order goes through pre-flight compliance verification (2–3 seconds) before on-chain submission.

Request (market):

{
  "mint": "7xK9p2...",
  "side": "buy",
  "type": "market",
  "amount": 50000000000,
  "slippage_bps": 100,
  "idempotency_key": "order_20260401_001"
}

Request (limit):

{
  "mint": "7xK9p2...",
  "side": "sell",
  "type": "limit",
  "amount": 100000000000,
  "limit_price": 0.0001200,
  "expiry": 1712016000,
  "idempotency_key": "order_20260401_002"
}

Request Fields:

Field	Type	Required	Description
mint	string	Yes	ST22 mint address
side	string	Yes	"buy" or "sell"
type	string	Yes	"market" or "limit"
amount	integer	Yes	Token amount (raw, with decimals)
limit_price	number	Limit only	SOL per token
slippage_bps	integer	Market only	Max slippage (default 100 = 1%, max 500 = 5%)
expiry	integer	Limit only	Unix timestamp (default: 24h from now)
idempotency_key	string	Recommended	Prevents duplicate orders (see §10)

Response (market — filled):

{
  "order_id": "ord_x1y2z3",
  "status": "filled",
  "side": "buy",
  "type": "market",
  "amount_requested": 50000000000,
  "amount_filled": 50000000000,
  "effective_price": 0.0001155,
  "value_sol": 5.775,
  "fee": {
    "total_sol": 0.28875,
    "total_bps": 500,
    "pool_sol": 0.025410,
    "issuer_sol": 0.11550,
    "staking_sol": 0.086625,
    "protocol_sol": 0.061215
  },
  "price_impact_bps": 18,
  "compliance_check": "passed",
  "controls_executed": 42,
  "tx_signature": "5vGh7kJ...",
  "block_slot": 285000300,
  "settled_at": 1711930200,
  "created_at": 1711930197
}

Response (limit — open):

{
  "order_id": "ord_a4b5c6",
  "status": "open",
  "side": "sell",
  "type": "limit",
  "amount_requested": 100000000000,
  "amount_filled": 0,
  "limit_price": 0.0001200,
  "expiry": 1712016000,
  "compliance_check": "passed",
  "created_at": 1711930210
}

Compliance flow:

1. CEDEX receives order
2. Pre-flight compliance (2-3s):
   ├─ Custody verification (Empire Ed25519, CV-01 through CV-06)
   ├─ OFAC screening (SC-30 through SC-34)
   ├─ AML risk scoring (IV-09)
   ├─ KYC / eligibility check (IV-07, IV-08)
   ├─ Holding period verification (HP-24)
   ├─ Price impact pre-check (CB-21)
   ├─ Module 2: NAV-deviation pre-check (CB-21 extension)
   └─ Module 3: Classification freshness + federal-action freeze pre-check (CV-04, REG-42)
3. If ANY pre-flight fails → return error immediately (no on-chain tx)
4. If pre-flight passes → submit to Solana
5. Token-2022 Transfer Hook executes all 42 controls on chain
6. If on-chain hook passes → settlement + fee distribution
7. If on-chain hook fails → atomic revert (no fee charged)

GET /orders

List orders for the authenticated wallet.

Query Parameters:

Parameter	Type	Default	Description
status	string	—	open, filled, cancelled, expired, rejected
mint	string	—	Filter by ST22 mint
side	string	—	buy or sell
limit	integer	50	Max results (max 200)
before	string	—	Cursor: order ID

Response:

{
  "orders": [
    {
      "order_id": "ord_a4b5c6",
      "mint": "7xK9p2...",
      "symbol": "ACME-ST22",
      "side": "sell",
      "type": "limit",
      "status": "open",
      "amount_requested": 100000000000,
      "amount_filled": 0,
      "limit_price": 0.0001200,
      "expiry": 1712016000,
      "created_at": 1711930210
    }
  ],
  "has_more": false
}

DELETE /orders/{order_id}

Cancel an open order.

Response:

{
  "order_id": "ord_a4b5c6",
  "status": "cancelled",
  "cancelled_at": 1711930500
}

Returns 404 if the order is not found or not owned by the authenticated wallet. Returns 409 if the order is already filled or expired.

GET /portfolio

Current ST22 holdings with holding-period status.

Response:

{
  "wallet": "9aB2xY...",
  "positions": [
    {
      "mint": "7xK9p2...",
      "symbol": "ACME-ST22",
      "module": "equities",
      "balance": 50000000000,
      "value_sol": 5.765,
      "value_usd": 922.40,
      "percent_of_supply": 0.50,
      "within_wallet_limit": true,
      "holding_period": {
        "purchase_timestamp": 1711929600,
        "jurisdiction": "US",
        "regime": "RegD",
        "holding_period_secs": 15778800,
        "unlock_timestamp": 1727708400,
        "is_locked": true,
        "seconds_remaining": 15778200,
        "unlock_date": "2026-09-30T00:00:00Z"
      },
      "custody": {
        "ratio": 1.0,
        "ed25519_verified": true,
        "last_attestation_ms": 1711930400
      }
    }
  ],
  "total_positions": 1,
  "total_value_sol": 5.765,
  "locked_positions": 1,
  "tradeable_positions": 0
}

The holding_period.regime field reports the offering exemption applied to the position: "RegD" (6 months), "RegS" (12 months), or "RegCF" (12 months). The holding_period_secs value reflects the regime.

POST /estimate

Estimate swap output without executing. No on-chain transaction; no fee charged.

Request:

{
  "mint": "7xK9p2...",
  "side": "buy",
  "input_amount": 10000000000
}

Response:

{
  "mint": "7xK9p2...",
  "side": "buy",
  "input_amount": 10000000000,
  "output_amount": 86758000000,
  "effective_price": 0.00011527,
  "price_impact_bps": 95,
  "would_trigger_circuit_breaker": false,
  "would_succeed": true,
  "fee": {
    "total_lamports": 500000000,
    "total_bps": 500,
    "pool_lamports": 44000000,
    "issuer_lamports": 200000000,
    "staking_lamports": 150000000,
    "protocol_lamports": 106000000
  },
  "pool_state": {
    "sol_reserve": 100000000000000,
    "token_reserve": 1000000000000000000,
    "k": "100000000000000000000000000000000"
  },
  "timestamp": 1711930300
}

If the pre-flight check would fail, would_succeed is false and a failure_reason field is returned with one of: "HOLDING_PERIOD_LOCKED", "WALLET_LIMIT_EXCEEDED", "PRICE_IMPACT_EXCEEDED", "OFAC_MATCH", "AML_HIGH_RISK", "CUSTODY_DISCREPANCY", "NAV_DEVIATION_EXCEEDED" (Module 2), "CLASSIFICATION_STALE" (Module 3), "FEDERAL_ACTION_FROZEN" (Module 3).

---

6. WebSocket API

Real-time data streams via persistent WebSocket connection.

Connection

wss://api.cedex.market/ws/v1

Authenticated connection (required for private channels):

wss://api.cedex.market/ws/v1?token=eyJhbGciOiJFZDI1NTE5...

Subscribe

{
  "action": "subscribe",
  "channel": "orderbook",
  "mint": "7xK9p2..."
}

Unsubscribe

{
  "action": "unsubscribe",
  "channel": "orderbook",
  "mint": "7xK9p2..."
}

Heartbeat

Server sends ping every 30 seconds. Client must respond with pong within 10 seconds or the connection is terminated.

{ "type": "ping", "timestamp": 1711930400 }

{ "type": "pong" }

Channel: orderbook

Real-time order book updates. Snapshot on subscribe, then incremental deltas.

Subscription:

{ "action": "subscribe", "channel": "orderbook", "mint": "7xK9p2..." }

Snapshot (sent on subscribe):

{
  "type": "snapshot",
  "channel": "orderbook",
  "mint": "7xK9p2...",
  "bids": [
    { "price": 0.0001150, "amount": 50000000000 },
    { "price": 0.0001145, "amount": 30000000000 }
  ],
  "asks": [
    { "price": 0.0001155, "amount": 40000000000 },
    { "price": 0.0001160, "amount": 25000000000 }
  ],
  "sequence": 100001,
  "timestamp": 1711930400
}

Delta (incremental updates):

{
  "type": "delta",
  "channel": "orderbook",
  "mint": "7xK9p2...",
  "changes": [
    { "side": "bid", "price": 0.0001150, "amount": 45000000000 },
    { "side": "ask", "price": 0.0001155, "amount": 0 }
  ],
  "sequence": 100002,
  "timestamp": 1711930400
}

amount: 0 = level removed. Apply deltas sequentially by sequence. If a sequence gap is detected, re-subscribe for a fresh snapshot.

Channel: trades

Real-time trade feed.

Subscription:

{ "action": "subscribe", "channel": "trades", "mint": "7xK9p2..." }

Message:

{
  "type": "trade",
  "channel": "trades",
  "mint": "7xK9p2...",
  "id": "trade_a1b2c3d4",
  "side": "buy",
  "amount": 10000000000,
  "price": 0.0001153,
  "value_sol": 1.153,
  "price_impact_bps": 12,
  "tx_signature": "5vGh7kJ...",
  "timestamp": 1711930410
}

Channel: custody

Real-time Empire custody attestation updates (~400ms per Solana block).

Subscription:

{ "action": "subscribe", "channel": "custody", "mint": "7xK9p2..." }

Message:

{
  "type": "custody_update",
  "channel": "custody",
  "mint": "7xK9p2...",
  "custodied_balance": 1000000000,
  "token_supply": 1000000000,
  "ratio": 1.0,
  "attestation_slot": 285000400,
  "ed25519_verified": true,
  "discrepancy_detected": false,
  "timestamp": 1711930410
}

If discrepancy_detected: true, all transfers are halted on this mint by Transfer Hook controls CV-01 through CV-06 until 2-of-3 oracle consensus resolves the discrepancy.

Channel: circuit_breaker

Circuit-breaker activation and deactivation events.

Subscription:

{ "action": "subscribe", "channel": "circuit_breaker", "mint": "7xK9p2..." }

Message:

{
  "type": "circuit_breaker",
  "channel": "circuit_breaker",
  "mint": "7xK9p2...",
  "event": "triggered",
  "breaker_type": "price_halt",
  "trigger_value": 1250,
  "threshold": 1000,
  "cooldown_secs": 900,
  "resume_at": 1711931310,
  "timestamp": 1711930410
}

Breaker types:

Type	Trigger	Module Scope
price_halt	Price move > threshold in 5 min	All modules
price_impact	Single trade price impact > 2% (or per-mint config)	All modules
volume_halt	Wallet daily-sell limit > 30%	All modules
oracle_failure	Custody or OFAC oracle stale beyond threshold	All modules
nav_deviation	On-chain price deviates from NAV beyond nav_deviation_max_bps	Module 2
nav_stale	NAV oracle exceeds nav_reappraisal_max_age_secs	Module 2
classification_stale	Classification oracle exceeds classification_max_age_secs	Module 3
federal_action	Federal-action freeze active (Control 42)	Module 3

Channel: nav (Module 2 only)

Real-time NAV oracle updates for Module 2 mints. See §12.2.

Channel: classification (Module 3 only)

Real-time Classification oracle updates and federal-action events for Module 3 mints. See §12.3.

Channel: orders (Authenticated)

Private channel — requires authenticated WebSocket connection. Real-time updates for the authenticated wallet's orders.

Subscription:

{ "action": "subscribe", "channel": "orders" }

Message:

{
  "type": "order_update",
  "channel": "orders",
  "order_id": "ord_x1y2z3",
  "status": "filled",
  "amount_filled": 50000000000,
  "effective_price": 0.0001155,
  "tx_signature": "5vGh7kJ...",
  "timestamp": 1711930420
}

---

7. Compliance Pre-Flight

Every order runs through pre-flight compliance verification before on-chain submission. This saves the user gas fees on trades that would fail the Transfer Hook.

Pre-Flight Sequence

Step	Hook	Source	Latency	Module Scope
1	Custody Verification (CV-01 to CV-06)	Empire Ed25519 oracle	100–150ms	All modules
2	OFAC Screening (SC-30 to SC-34)	OFAC SDN oracle	200–500ms	All modules
3	AML Risk (IV-09)	Chainalysis + TRM Labs	300–400ms	All modules
4	KYC and eligibility (IV-07, IV-08)	Empire registry	50–100ms	All modules
5	Holding Period (HP-24)	On-chain HoldingPeriodAccount	<10ms	All modules
6	Price Impact (CB-21)	TWAP oracle (Pyth Network)	50–100ms	All modules
7	NAV Deviation (CB-21 extension)	NAVOracle PDA	50–100ms	Module 2 only
8	Classification + Federal Action (CV-04, REG-42)	ClassificationOracle PDA	50–100ms	Module 3 only

Total pre-flight: 2,000–3,000ms

If pre-flight fails, the API returns the specific error code immediately — no on-chain transaction submitted, no gas fee charged. The user can see exactly which control would reject the trade and why.

Pre-Flight Response (Failure)

{
  "order_id": null,
  "status": "rejected",
  "compliance_check": "failed",
  "failed_control": {
    "control_id": "HP-24",
    "code": 6024,
    "name": "TokensLocked",
    "message": "Tokens locked — Reg D / Reg S / Reg CF holding period not elapsed",
    "details": {
      "mint": "7xK9p2...",
      "beneficiary": "9aB2xY...",
      "purchase_timestamp": 1711929600,
      "unlock_timestamp": 1727708400,
      "seconds_remaining": 15778200,
      "jurisdiction": "US",
      "regime": "RegD"
    }
  }
}

Module 2 Pre-Flight Failure (NAV Deviation)

{
  "order_id": null,
  "status": "rejected",
  "compliance_check": "failed",
  "failed_control": {
    "control_id": "CB-21",
    "code": 6021,
    "name": "NavDeviationExceeded",
    "message": "Price deviates from NAV beyond configured tolerance",
    "details": {
      "mint": "7xK9p2...",
      "current_price_usd": 1250.00,
      "appraised_nav_usd": 1000.00,
      "deviation_bps": 2500,
      "max_allowed_bps": 2200,
      "last_appraisal_timestamp": 1709251200,
      "next_appraisal_target": 1740787200
    }
  }
}

Module 3 Pre-Flight Failure (Federal Action)

{
  "order_id": null,
  "status": "rejected",
  "compliance_check": "failed",
  "failed_control": {
    "control_id": "REG-42",
    "code": 6042,
    "name": "FederalActionFrozen",
    "message": "Mint frozen by federal-action regulatory override",
    "details": {
      "mint": "7xK9p2...",
      "freeze_timestamp": 1711930000,
      "freeze_authority": "LegalCounsel+3of5",
      "trigger_source": "Federal Register",
      "action_reference": "EO-14118",
      "expected_resolution": "pending"
    }
  }
}

---

8. Error Reference

HTTP Status Codes

Status	Meaning	When
200	Success	Request completed
201	Created	Order placed
400	Bad Request	Invalid parameters
401	Unauthorized	Missing or expired token
403	Forbidden	Empire verification required or wallet blacklisted
404	Not Found	Resource does not exist
409	Conflict	Order already filled or cancelled; idempotency-key reuse
422	Unprocessable	Compliance pre-flight failed (Transfer Hook error)
429	Rate Limited	Exceeded rate limit
500	Server Error	Internal error
503	Unavailable	Maintenance or Solana network issue

Error Response Format

{
  "error": {
    "code": 6024,
    "name": "TokensLocked",
    "message": "Tokens locked — Reg D / Reg S / Reg CF holding period not elapsed",
    "category": "HoldingPeriod",
    "control_id": "HP-24",
    "recoverable": true,
    "details": {
      "mint": "7xK9p2...",
      "beneficiary": "9aB2xY...",
      "purchase_timestamp": 1711929600,
      "unlock_timestamp": 1727708400,
      "seconds_remaining": 15778200,
      "jurisdiction": "US",
      "regime": "RegD"
    }
  },
  "request_id": "req_m7n8o9"
}

Transfer Hook Error Codes (6001–6042)

Code	Name	HTTP	Recoverable	User Action
6001	CustodyDiscrepancy	422	No	System-level. Wait for oracle consensus.
6002	CustodyOracleUnavailable	422	Yes	Retry after ~400ms (1 block)
6003	SenderSanctioned	403	No	OFAC-flagged wallet. Cannot trade.
6004	ReceiverSanctioned	403	No	Receiver OFAC-flagged.
6005	OfacOracleStale	422	Yes	OFAC refreshing. Retry in minutes.
6006	AMLHighRisk	403	No	AML score above 70. Contact Empire.
6007	InvalidSigner	403	No	KYC, eligibility, or wallet registration missing.
6008–6019	CEI / Integrity	422	Varies	See error message.
6020	WalletLimitExceeded	422	Yes	Reduce amount below 4.99% of supply.
6021	PriceImpactExceeded	422	Yes	Reduce order size or split into smaller orders.
6022	VelocityExceeded	422	Yes	Slow down. Wait for velocity window.
6023	CrossWalletDetected	403	No	Behavioral clustering flagged. Contact compliance.
6024	TokensLocked	422	Yes	Wait for holding period (Reg D 6mo / Reg S 12mo / Reg CF 12mo).
6036	GlobalCircuitBreaker	503	Yes	All trading halted. Wait for cooldown (~15 min).
6037	DailySellLimitExceeded	422	Yes	30% daily sell limit reached. Wait 24h.
6038	CustodyDiscrepancyHalt	503	No	Custody issue. Await 2-of-3 consensus.
6039	OFACEmergencyBlock	503	No	Treasury emergency SDN update.
6040	OracleConsensusFail	503	Yes	Oracle consensus not reached. Retry.
6041	ControlledMigration	503	Yes	Upgrade in progress. Wait.
6042	RegulatoryOverride	503	No	Legal Counsel + 3-of-5 freeze. Module 3 federal-action freezes also use this code.

Module 2 Specific Error Annotations

Code	Variant	Detail Field	User Action
6021	NavDeviationExceeded	deviation_bps, max_allowed_bps, appraised_nav_usd	Wait for fresh appraisal that restores price within bounds
6021	NavStale	last_appraisal_timestamp, nav_reappraisal_max_age_secs	Mint paused pending fresh appraisal

Module 3 Specific Error Annotations

Code	Variant	Detail Field	User Action
6002	ClassificationOracleUnavailable	last_refresh, classification_max_age_secs	Retry after relay refresh
6042	FederalActionFrozen	freeze_timestamp, trigger_source, action_reference	No user action — await federal-action resolution

CEDEX Application Error Codes

Code	Name	HTTP	Description
INVALID_MINT	Invalid Mint	400	Mint address not a valid ST22 token
INVALID_SIDE	Invalid Side	400	Must be "buy" or "sell"
INVALID_AMOUNT	Invalid Amount	400	Amount must be > 0
SLIPPAGE_EXCEEDED	Slippage Exceeded	422	Output below minimum after slippage
DEADLINE_EXCEEDED	Deadline Exceeded	422	Order deadline passed before execution
INSUFFICIENT_BALANCE	Insufficient Balance	422	Wallet balance < order amount
ORDER_NOT_FOUND	Order Not Found	404	Order ID does not exist for this wallet
ORDER_NOT_CANCELLABLE	Not Cancellable	409	Order already filled or expired
EMPIRE_VERIFICATION_REQUIRED	Not Verified	403	Empire KYC, KYB, AML, OFAC, or KYW not complete
RATE_LIMITED	Rate Limited	429	Request rate exceeded
MAINTENANCE	Maintenance	503	System maintenance window
POOL_NOT_ACTIVE	Pool Inactive	503	Trading pair not active
IDEMPOTENCY_CONFLICT	Duplicate	409	Same idempotency key with different params

---

9. Pagination

All list endpoints use cursor-based pagination.

GET /markets/{mint}/trades?limit=50
GET /markets/{mint}/trades?limit=50&before=trade_x9y8z7w6

Response pagination fields:

{
  "data": [...],
  "has_more": true,
  "next_cursor": "trade_x9y8z7w6"
}

Pass next_cursor as the before parameter to fetch the next page. When has_more is false, no more results exist.

---

10. Idempotency

Prevent duplicate orders by including an idempotency_key in order placement requests.

{
  "...order fields...",
  "idempotency_key": "order_20260401_001"
}

Behavior:

Scenario	Response
First request with key	Order created normally
Duplicate request with same key + same params	Returns original order (no duplicate)
Duplicate request with same key + different params	409 IDEMPOTENCY_CONFLICT
Key reuse after 24 hours	Key expired — treated as new request

Key format: Any string up to 128 characters. Recommended: {purpose}_{date}_{sequence}.

---

11. Code Examples

TypeScript (SDK)

import { RwaTokensClient } from '@rwatokens/sdk';

const client = new RwaTokensClient({ network: 'mainnet-beta', wallet });

// Market buy
const order = await client.cedex.placeOrder({
  mint:        mintAddress,
  side:        'buy',
  type:        'market',
  amount:      50_000_000_000n,
  slippageBps: 100,
});
console.log(`Filled: ${order.txSignature}`);

Python

import requests

BASE  = "https://api.cedex.market/v1"
TOKEN = "eyJhbGciOiJFZDI1NTE5..."

# Get markets
markets = requests.get(f"{BASE}/markets").json()

# Place order
order = requests.post(
    f"{BASE}/orders",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "mint":             "7xK9p2...",
        "side":             "buy",
        "type":             "market",
        "amount":           50000000000,
        "slippage_bps":     100,
        "idempotency_key":  "py_order_001",
    },
).json()

print(f"Status: {order['status']}, TX: {order.get('tx_signature')}")

cURL

# Public: Get order book
curl -s https://api.cedex.market/v1/markets/7xK9p2.../orderbook?depth=10 | jq

# Authenticated: Place order
curl -X POST https://api.cedex.market/v1/orders \
  -H "Authorization: Bearer eyJhbGciOiJFZDI1NTE5..." \
  -H "Content-Type: application/json" \
  -d '{
    "mint": "7xK9p2...",
    "side": "buy",
    "type": "market",
    "amount": 50000000000,
    "slippage_bps": 100
  }' | jq

# Cancel order
curl -X DELETE https://api.cedex.market/v1/orders/ord_x1y2z3 \
  -H "Authorization: Bearer eyJhbGciOiJFZDI1NTE5..." | jq

WebSocket (JavaScript)

const ws = new WebSocket('wss://api.cedex.market/ws/v1');

ws.onopen = () => {
  // Subscribe to order book
  ws.send(JSON.stringify({
    action:  'subscribe',
    channel: 'orderbook',
    mint:    '7xK9p2...',
  }));

  // Subscribe to trades
  ws.send(JSON.stringify({
    action:  'subscribe',
    channel: 'trades',
    mint:    '7xK9p2...',
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  if (msg.type === 'ping') {
    ws.send(JSON.stringify({ type: 'pong' }));
    return;
  }

  switch (msg.channel) {
    case 'orderbook':
      if (msg.type === 'snapshot') console.log('Book snapshot:', msg.bids.length, 'bids');
      if (msg.type === 'delta')    console.log('Book delta:', msg.changes);
      break;
    case 'trades':
      console.log(`Trade: ${msg.side} ${msg.amount} @ ${msg.price}`);
      break;
    case 'custody':
      if (msg.discrepancy_detected) console.error('CUSTODY DISCREPANCY');
      break;
    case 'nav':
      console.log(`NAV update: ${msg.appraised_nav_usd} (deviation ${msg.current_deviation_bps} bps)`);
      break;
    case 'classification':
      if (msg.federal_action_active) console.error(`FEDERAL ACTION: ${msg.action_reference}`);
      break;
  }
};

---

12. Module-Aware API Surface

The CEDEX API serves all three modules through the same endpoints, the same authentication, and the same WebSocket protocol. Module-specific behavior surfaces as additional fields on existing endpoints, dedicated oracle endpoints, dedicated WebSocket channels, and module-specific failure-reason codes. This section consolidates the module-specific surface for integrators building module-aware applications.

12.1 Module 1 — Equities

Module identifier in API responses: "equities".

Distinguishing endpoints. None beyond the standard set. Module 1 mints use the standard custody, OFAC, AML, and TWAP oracles.

Distinguishing WebSocket channels. None.

Distinguishing fields. issuer_cik (for SEC-reporting issuers). The EDGAR pipeline that supplies issuer-disclosure intelligence to Layer 9 IDOS off-chain compliance is not exposed through the public API; Module 1 IDOS-driven status changes appear through the circuit_breaker channel as oracle_failure events when issuer eligibility lapses.

12.2 Module 2 — Real Estate

Module identifier in API responses: "real_estate".

Additional Public Endpoint: GET /oracle/{mint}/nav

Returns the most recent appraised NAV for a Module 2 mint:

{
  "mint": "5xR3p9...",
  "appraised_nav_usd": 1000.00,
  "appraiser_signature": "Ed25519AppraiserSig...",
  "appraiser_id": "appraiser_xyz_456",
  "last_appraisal_timestamp": 1709251200,
  "next_appraisal_target": 1740787200,
  "nav_deviation_max_bps": 2200,
  "current_price_usd": 1018.50,
  "current_deviation_bps": 185,
  "is_within_bounds": true,
  "is_fresh": true,
  "staleness_threshold_secs": 31536000,
  "status": "healthy"
}

Additional Market Object Field (Module 2 mints):

{
  "...standard market fields...",
  "nav": {
    "appraised_nav_usd": 1000.00,
    "current_deviation_bps": 185,
    "is_within_bounds": true,
    "next_appraisal_target": 1740787200
  }
}

Additional Health Field:

The oracle_status.nav field on GET /health reports aggregate NAV oracle health: "healthy", "degraded" (any per-mint NAV staleness above warning threshold), or "halted" (any per-mint NAV exceeds halt threshold).

Additional WebSocket Channel: nav

Real-time NAV oracle updates for a specific Module 2 mint.

{ "action": "subscribe", "channel": "nav", "mint": "5xR3p9..." }

{
  "type": "nav_update",
  "channel": "nav",
  "mint": "5xR3p9...",
  "appraised_nav_usd": 1000.00,
  "current_price_usd": 1018.50,
  "current_deviation_bps": 185,
  "is_within_bounds": true,
  "appraisal_timestamp": 1709251200,
  "appraiser_id": "appraiser_xyz_456",
  "timestamp": 1711930410
}

Module 2 Pre-Flight Failure Reasons:

Reason	Underlying Control	Recoverable
NAV_DEVIATION_EXCEEDED	CB-21 (extension)	Yes — wait for fresh appraisal
NAV_STALE	CB-21 (extension)	Yes — fresh appraisal will resume trading

Application Pattern. Applications displaying real-time price for Module 2 mints should subscribe to the nav channel for the same mint and display the NAV reference alongside the live AMM price. The deviation warning surfaces UX context for users when the NAV-deviation breaker triggers.

12.3 Module 3 — CORECM (Carbon Ore, Rare Earth, and Critical Minerals)

Module identifier in API responses: "corecm".

Additional Public Endpoint: GET /oracle/{mint}/classification

Returns the most recent USGS / DOE classification status and federal-action status for a Module 3 mint:

{
  "mint": "8mB4q1...",
  "usgs_critical_minerals_status": "critical_mineral_rare_earth",
  "doe_critical_materials_status": "high_priority",
  "section_232_applicable": false,
  "dpa_title_iii_applicable": true,
  "federal_action_active": false,
  "active_action_references": [],
  "last_refresh_timestamp": 1711930000,
  "classification_max_age_secs": 86400,
  "is_fresh": true,
  "status": "healthy",
  "monitored_sources": [
    "Federal Register",
    "DOE Critical Materials Strategy",
    "USGS Critical Minerals List",
    "DOD Procurement Directives"
  ]
}

Additional Market Object Field (Module 3 mints):

{
  "...standard market fields...",
  "classification": {
    "usgs_critical_minerals_status": "critical_mineral_rare_earth",
    "doe_critical_materials_status": "high_priority",
    "federal_action_active": false,
    "is_fresh": true
  }
}

Additional Health Field:

The oracle_status.classification field on GET /health reports aggregate Classification oracle health.

Additional WebSocket Channel: classification

Real-time Classification oracle updates and federal-action events for a specific Module 3 mint.

{ "action": "subscribe", "channel": "classification", "mint": "8mB4q1..." }

Routine update message:

{
  "type": "classification_update",
  "channel": "classification",
  "mint": "8mB4q1...",
  "usgs_critical_minerals_status": "critical_mineral_rare_earth",
  "doe_critical_materials_status": "high_priority",
  "federal_action_active": false,
  "last_refresh_timestamp": 1711930000,
  "is_fresh": true,
  "timestamp": 1711930410
}

Federal-action event message (P0 incident):

{
  "type": "federal_action_detected",
  "channel": "classification",
  "mint": "8mB4q1...",
  "action_reference": "EO-14118",
  "trigger_source": "Federal Register",
  "detected_timestamp": 1711930000,
  "freeze_pending": true,
  "expected_freeze_timestamp": 1711933600,
  "timestamp": 1711930000
}

Federal-action freeze applied:

{
  "type": "federal_action_freeze_applied",
  "channel": "classification",
  "mint": "8mB4q1...",
  "action_reference": "EO-14118",
  "freeze_authority": "LegalCounsel+3of5",
  "freeze_timestamp": 1711933600,
  "trading_halted": true,
  "timestamp": 1711933600
}

Module 3 Pre-Flight Failure Reasons:

Reason	Underlying Control	Recoverable
CLASSIFICATION_STALE	CV-04 (extension)	Yes — wait for relay refresh
FEDERAL_ACTION_FROZEN	REG-42	No — await federal-action resolution

Application Pattern. Applications handling Module 3 mints should subscribe to the classification channel for every mint they display. The federal_action_detected event provides up-to-an-hour advance notice of a likely Control 42 freeze (the platform's incident response runbook §13 specifies a 60-minute SLA from detection to freeze execution); applications can warn users that orders submitted during this window may revert.

12.4 Cross-Module Properties

The following properties are identical across all three modules:

• Authentication, rate limits, idempotency, pagination.

• Order placement and cancellation endpoints.

• The markets, trades, orderbook, OHLCV, custody, circuit_breaker, and orders (private) WebSocket channels.

• The 5% fee distribution structure (2% / 1.5% / 1.06% / 0.44%).

• Stablecoin settlement (USDC, PYUSD).

• Pre-flight steps 1–6 (custody, OFAC, AML, KYC, holding period, price impact).

• Holding-period regimes — Reg D (6 months), Reg S (12 months), Reg CF (12 months).

• Transfer Hook error codes 6001–6042.

---

13. Changelog

v1.0.0 (Q3 2026)

• Initial release — CEDEX mainnet launch.

• Public endpoints: markets, orderbook, trades, OHLCV, oracle status, health.

• Authenticated endpoints: orders (market and limit), portfolio, estimate.

• WebSocket channels: orderbook, trades, custody, circuit_breaker, orders (private).

• Wallet signature authentication with Empire verification gate.

• Pre-flight compliance verification (42 controls).

• Idempotency support for order placement.

• Three rate-limit tiers (standard, verified, institutional).

• Module-aware endpoint surface: NAV oracle and nav WebSocket channel for Module 2; Classification oracle and classification WebSocket channel for Module 3.

• Module-specific failure reasons surfaced in pre-flight responses.

---

Related Documentation

• SDK Reference — RwaTokensClient wrapping this API.

• Smart Contract Reference — On-chain program documentation.

• Transfer Hook Reference — Standalone reference for the 42 controls.

• Stablecoin Settlement Guide — USDC and PYUSD settlement architecture and developer integration.

• Oracle Integration Guide — Custody, OFAC, AML, TWAP, EDGAR, NAV (Module 2), Classification (Module 3) relay architecture.

• Compliance Integration Guide — Regulatory mapping for each pre-flight control.

• Issuer Onboarding Guide — Module-specific issuer onboarding flow.

• Incident Response Playbook — Module 3 federal-action freeze runbook (§13).

---

RWA Tokens · CEDEX API Reference · v1.0 · cedex.market · Q3 2026