ICEx Trading System API (1.0.1)

The ICEx API facilitates advanced and automated trade reporting for trading exchanges and market participants.

ICEx provides a comprehensive trading infrastructure that enables:

• Real-time trade validation and processing
• Secure authentication with API key and signature verification
• Comprehensive error handling and response codes

• snake_case is applied on parameters naming. uppercase & snake_case are both applied for enum values.
• For pairs naming, use the snake_case and pairs should be written in uppercase (e.g. ICEX-BTC, ICEX-ETH, ICEX-SOL, etc).
• API_URL (Staging): https://api-staging.icex.id

API requests must include three authentication headers:

• X-API-Key: Your unique API key provided by ICEx
• X-Signature: HMAC-SHA512 signature of the request body using your API secret
• X-Timestamp: Current Unix timestamp in milliseconds

Generating Signature

To generate the HMAC-SHA512 signature, follow these steps:

1. Create canonical JSON: Sort the request body JSON keys alphabetically to ensure consistent ordering
2. Build payload string: Format as "METHOD|PATH|BODY|TIMESTAMP"
3. Calculate HMAC-SHA512: Use your API secret as the key
4. Convert to hex: Get the lowercase hexadecimal representation

Python Implementation

import hmac
import hashlib
import json

def generate_signature(method, path, raw_body, timestamp, client_secret):
    """
    Generate HMAC-SHA512 signature for ICEx API authentication
    
    Args:
        method: HTTP method (e.g., 'POST', 'GET')
        path: API endpoint path (e.g., '/v1/trades/spot')
        raw_body: Raw request body JSON string (empty string for GET/DELETE)
        timestamp: Unix timestamp in milliseconds
        client_secret: Your API secret key
    
    Returns:
        Hexadecimal signature string
    """
    # Create canonical JSON with sorted keys
    if raw_body:
        try:
            # Parse and re-sort JSON to ensure canonical ordering
            body_dict = json.loads(raw_body)
            canonical_body = json.dumps(body_dict, sort_keys=True, separators=(',', ':'))
        except json.JSONDecodeError:
            canonical_body = raw_body
    else:
        canonical_body = ""
    
    # Build payload
    payload = f"{method}|{path}|{canonical_body}|{timestamp}"
    
    # Generate HMAC-SHA512 signature
    signature = hmac.new(
        client_secret.encode("utf-8"),
        payload.encode("utf-8"),
        hashlib.sha512
    ).hexdigest()
    
    return signature

# Example usage
if __name__ == "__main__":
    # Sample request data
    method = "POST"
    path = "/v1/trades/spot"
    timestamp = 1760662221648
    client_secret = "your_api_secret_here"
    
    # Sample request body
    request_data = {
        "request_id": "5023ed3d-321b-4b84-b1b1-d29bd4f4566f",
        "message_body": {
            "trades": [
                {
                    "trade_id": "8a13fe23-3035-4015-9acf-c52823d1fc23",
                    "trade_ts_ms": 1760662221648,
                    "side": "BUY",
                    "price": "2000000",
                    "traded_qty": "2",
                    "notional": "4000000",
                    "base_asset_id": "ICEX-SOL",
                    "quote_asset_id": "IDR",
                    "notional_asset": "IDR",
                    "maker_id": "EXCHANGE-USER-001",
                    "taker_id": "EXCHANGE-USER-002",
                    "maker_fees": {
                        "platform": {"value": "4888", "asset_id": "IDR"},
                        "tax": {"value": "8400", "asset_id": "IDR"},
                        "other": {"value": "0.00", "asset_id": "IDR"},
                        "bourse": {"value": "0.00", "asset_id": "IDR"}
                    },
                    "taker_fees": {
                        "platform": {"value": "8888", "asset_id": "IDR"},
                        "tax": {"value": "0", "asset_id": "IDR"},
                        "other": {"value": "0.00", "asset_id": "IDR"},
                        "bourse": {"value": "0.00", "asset_id": "IDR"}
                    },
                    "extras": [
                        {"key": "eth_idr_rate", "value_type": "number", "value": "2000.00"}
                    ]
                }
            ]
        }
    }
    
    # Convert to canonical JSON
    raw_body = json.dumps(request_data, sort_keys=True, separators=(',', ':'))
    
    # Generate signature
    signature = generate_signature(method, path, raw_body, timestamp, client_secret)
    
    print(f"Payload: {method}|{path}|{raw_body}|{timestamp}")
    print(f"Signature: {signature}")
    
    # Headers to include in request
    headers = {
        "X-API-Key": "your_api_key_here",
        "X-Signature": signature,
        "X-Timestamp": str(timestamp)
    }

Important Notes

• Canonical JSON: Always sort JSON keys alphabetically to ensure consistent signature generation
• Timestamp: Use current Unix timestamp in milliseconds (must be within 5 minutes of server time)
• Empty body: For GET/DELETE requests, use empty string for the BODY component
• Path: Use only the path portion, no host or query parameters
• Encoding: Use UTF-8 encoding for both payload and secret key

• Trades must be reported with accurate timestamps and asset information
• Each trade requires unique trade_id for idempotency
• Base and quote assets must use ICEx asset IDs (e.g., ICEX-BTC, IDR)
• Fees are broken down into platform, tax, and other categories

Email: support@icex.id

System health monitoring and status checks

Asset list retrieval and asset information management

Trade report submission and processing with real-time validation

Market maker CRUD operations and management

Get Fiat Reconcile Summary

v1.0.1 — 2026-06-04

• Added data.status_summary field to POST /v1/trades/spot responses (200, 207, 400)
• status_summary contains trade batch processing counts: success, late, and super_late
• Clarified that late and super_late in status_summary represent valid accepted trades flagged for late submission — they are not rejections and are counted in reconciliation
• invalid_trades in 207 now only lists truly rejected trades (e.g., unknown asset ID, zero amount); late/super_late are no longer listed as invalid

v1.0.0 — Initial Release

• Spot trade report submission via POST /v1/trades/spot with HMAC-SHA512 authentication
• Per-trade fee breakdown into platform, tax, other, and bourse categories for both maker and taker
• Invalid trade retrieval via GET /v1/trades/spot/invalid/{requestId} with pagination support
• Asset list retrieval via GET /v1/assets with filters (asset_id, asset_code, asset_name) and pagination
• Market maker CRUD operations: create, list, get detail, update, and soft-delete
• Market maker types: LiquidityProvider (impacts balance reconciliation) and MarketMaker (does not impact balance)
• Fiat reconciliation summary via POST /v1/fiat/reconcile-summary with up to 30-day period range
• Optional extras array on trades for arbitrary typed key-value metadata (string, number, boolean)
• Asynchronous trade processing — submission enqueues payload; status visible from the ICEx dashboard
• bourse fee type treated as non-deduction factor, unlike platform, tax, and other