ICC Transaction Submission API (1.0.0)

This API allows external systems to submit cryptocurrency transaction data to ICC for processing and tracking.

API Key Authentication:

• Include your API key in the X-Api-Key header
• Include your signature in the X-Signature header
• Include your timestamp in the X-Timestamp header
• API keys are provided by ICC administrators
• Rate-limited and IP-restricted for security

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 ICC API authentication
    
    Args:
        method: HTTP method (e.g., 'POST', 'GET')
        path: API endpoint path (e.g., '/v1/transactions/crypto')
        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/transactions/crypto"
    timestamp = 1763474667930
    client_secret = "your_api_secret_here"
    
    # Sample request body
    request_data = {
        "request_id": "3ed3502d-321b-4b84-b1b1-df45629bd46f",
        "request_ts_ms": 1763474667930,
        "payload_type": "transactions-crypto-v3",
        "payload": {
            "transactions": [
                {
                    "tx_id": "5023ed3d-321b-4b84-b1b1-d29bd4f4566f",
                    "user_id": "IN001222",
                    "recipient_user_id": "IN001468",
                    "asset_code": "UNI",
                    "asset_name": "Uniswap",
                    "tx_type": "DEPOSIT",
                    "tx_channel": "BLOCKCHAIN",
                    "tx_network": "TRON",
                    "amount": "1",
                    "transfer_fee": "0",
                    "tx_ts_ms": 1763474667930,
                    "tx_status": "COMPLETED",
                    "tx_hash": "0x5e8d51f6eabb3d2c5d7c5f9a56a6e3b77cfa8939c57f9c3cf6c60d39e2e7f3a4",
                    "asset_id": "ICEX-BTC",
                    "wallet_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
                    "metadata": [
                        {
                            "key": "info_boolean",
                            "value_type": "boolean",
                            "value": False
                        },
                        {
                            "key": "info_number",
                            "value_type": "number",
                            "value": 10000
                        },
                        {
                            "key": "info_string",
                            "value_type": "string",
                            "value": "info"
                        }
                    ]
                }
            ]
        }
    }
    
    # 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

curl --location 'https://api-staging.icc.id/v1/transactions/crypto' \
--header 'X-Api-Key: your-api-key-here' \
--header 'X-Signature: your-signature-here' \
--header 'X-Timestamp: your-timestamp-here' \
--header 'Content-Type: application/json' \
--data '{
"request_id": "3ed3502d-321b-4b84-b1b1-df45629bd46f",
"request_ts_ms": 1763474667930,
"payload_type": "transactions-crypto-v3",
"payload": {
    "transactions": [
        {
            "tx_id": "5023ed3d-321b-4b84-b1b1-d29bd4f4566f",
            "user_id": "IN001222",
            "recipient_user_id": "IN001468",
            "asset_code": "UNI",
            "asset_name": "Uniswap",
            "tx_type": "DEPOSIT",
            "tx_channel": "BLOCKCHAIN",
            "tx_network": "TRON",
            "amount": "1",
            "transfer_fee": "0",
            "tx_ts_ms": 1763474667930,
            "tx_status": "COMPLETED",
            "tx_hash": "0x5e8d51f6eabb3d2c5d7c5f9a56a6e3b77cfa8939c57f9c3cf6c60d39e2e7f3a4",
            "asset_id": "ICEX-BTC",
            "wallet_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
            "metadata": [
                {
                    "key": "info_boolean",
                    "value_type": "boolean",
                    "value": false
                },
                {
                    "key": "info_number",
                    "value_type": "number",
                    "value": 10000
                },
                {
                    "key": "info_string",
                    "value_type": "string",
                    "value": "info"
                }
            ]
        }
    ]
  }
}

• tx_type: Must be UPPERCASE ("DEPOSIT" or "WITHDRAWAL")
• tx_status: Must be UPPERCASE ("IN_PROGRESS", "COMPLETED", "FAILED")
• tx_network: Must be UPPERCASE (e.g., "SOLANA", "BITCOIN", "ETHEREUM", "BSC")
• Timestamps: Unix timestamps in milliseconds (not seconds)
• asset_id: Format is SYMBOL-ID (e.g., "ICEX-SOL", "ICEX-BTC")

System health check

Submit and manage cryptocurrency transactions

v1.1.0 — Envelope & Response Enhancements

• Added tx_id as a required field in each transaction object
• Metadata now uses typed key-value pairs with explicit value_type field (string, number, boolean)
• transactions array is now nested under a payload wrapper object in the request body
• Added 207 PARTIAL_SUCCESS response for mixed-result batch submissions, returning per-transaction tx_id and reason
• Added 500 INTERNAL_SERVER_ERROR response

v1.0.0 — Initial Release

• Cryptocurrency transaction submission for external systems via transactions-crypto-v3 envelope payload
• Support for DEPOSIT and WITHDRAWAL transaction types
• Support for BLOCKCHAIN and INTERNAL transaction channels
• Required fields: user_id, asset_id, asset_code, asset_name, tx_type, tx_channel, tx_network, amount, transfer_fee, tx_ts_ms, tx_status
• Optional recipient_user_id field (required when tx_channel is INTERNAL)
• Optional tx_hash, wallet_address fields
• HMAC-SHA512 request signature authentication (X-Api-Key, X-Signature, X-Timestamp)
• Optional metadata support via key-value pairs
• Idempotency support via client-generated request_id
• Asynchronous processing — submission enqueues the payload; status visible from the ICEx dashboard