Python Example for Calling API

Python Example for Calling the CatFee.IO REST API

Prerequisites

You need a valid API Key and API Secret.

Make sure your environment has the requests library installed. You can install it using:

pip install requests

Use Python version 3.8 or above.

---

Example Code

import base64
import hashlib
import hmac
import json
import uuid
from datetime import datetime, timezone
from urllib.parse import urlencode

import requests

API_KEY = "your_api_key"  # Replace with your actual API Key
API_SECRET = "your_api_secret"  # Replace with your actual API Secret
BASE_URL = "https://api.catfee.io"
TIMEOUT_SECONDS = 15

def generate_timestamp():
    """Generate an ISO 8601 UTC timestamp with milliseconds."""
    return datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace(
        "+00:00", "Z"
    )

def build_request_path(path, query_params):
    """Build request path with query parameters"""
    if not query_params:
        return path
    query_string = urlencode(query_params)
    return f"{path}?{query_string}"

def generate_signature(timestamp, method, request_path):
    """Generate request signature"""
    sign_string = timestamp + method.upper() + request_path
    return hmac_sha256(sign_string, API_SECRET)

def hmac_sha256(data, secret):
    """Generate HMAC-SHA256 signature"""
    return base64.b64encode(
        hmac.new(secret.encode('utf-8'), data.encode('utf-8'), hashlib.sha256).digest()
    ).decode()

def create_request(url, method, timestamp, signature):
    """Create and send HTTP request"""
    headers = {
        "Content-Type": "application/json",
        "CF-ACCESS-KEY": API_KEY,
        "CF-ACCESS-SIGN": signature,
        "CF-ACCESS-TIMESTAMP": timestamp,
    }
    
    if method == "POST":
        response = requests.post(url, headers=headers, timeout=TIMEOUT_SECONDS)
    elif method == "GET":
        response = requests.get(url, headers=headers, timeout=TIMEOUT_SECONDS)
    elif method == "PUT":
        response = requests.put(url, headers=headers, timeout=TIMEOUT_SECONDS)
    elif method == "DELETE":
        response = requests.delete(url, headers=headers, timeout=TIMEOUT_SECONDS)
    else:
        raise ValueError(f"Unsupported HTTP method: {method}")
    
    return response

def main():
    method = "POST"  # Can be changed to "GET", "PUT", or "DELETE"
    path = "/v1/order"
    
    # Example: Create Order
    client_order_id = str(uuid.uuid4())
    query_params = [
        ("quantity", "65000"),
        ("receiver", "TRON_ADDRESS"),
        ("duration", "1h"),
        ("client_order_id", client_order_id),
        ("activate", "true"),
    ]
    
    # Generate request headers
    timestamp = generate_timestamp()
    request_path = build_request_path(path, query_params)
    signature = generate_signature(timestamp, method, request_path)
    
    # Construct full request URL
    url = BASE_URL + request_path
    
    print("Client Order ID:", client_order_id)
    try:
        response = create_request(url, method, timestamp, signature)
        print("HTTP Status:", response.status_code)
        print("Response Body:", response.text)
        response.raise_for_status()

        result = json.loads(response.text)
        if result.get("code") != 0:
            message = result.get("msg") or result.get("sub_msg")
            raise RuntimeError(
                f"API request failed: code={result.get('code')}, message={message}"
            )

        data = result.get("data") or {}
        print("Order ID:", data.get("id"))
    except requests.Timeout:
        print("Request timed out. Retry with the same Client Order ID:", client_order_id)
    except json.JSONDecodeError as error:
        print("Response is not valid JSON:", error)
    except requests.RequestException as error:
        print("HTTP request failed:", error)
    except RuntimeError as error:
        print(error)

if __name__ == "__main__":
    main()

---

Code Explanation

• generate_timestamp() Generates an ISO 8601 UTC timestamp with milliseconds using datetime.now(timezone.utc).

• build_request_path() Builds the full request path including query parameters. If no parameters are provided, it returns the original path.

• generate_signature() Concatenates timestamp + method + request_path, then generates a signature using the hmac_sha256() function.

• hmac_sha256() Uses the HMAC-SHA256 algorithm with your API_SECRET as the key, and encodes the result with Base64.

• create_request() Sends the HTTP request using the requests library. Supports POST, GET, PUT, and DELETE methods.

• main() Creates an order, prints its idempotency key, and checks both the HTTP status and the API response code.

---

Notes

• API Key and Secret Replace API_KEY and API_SECRET with the actual credentials you obtained from CatFee.IO.

• Signed request path The encoded query string and its parameter order must be identical in the signature and the actual URL.

• Order parameters quantity must be at least 65000, duration currently supports only 1h, and receiver must be a valid TRON address.

• Idempotent retries Use a unique client_order_id of no more than 64 characters for each new order. Reuse it after a timeout or connection failure.

• Response handling HTTP 200 does not necessarily mean business success. Always verify that the response body's code is 0.

---

Summary

This example demonstrates how to use Python to securely call the CatFee.IO Rest API. It ensures security through HMAC-SHA256 signature authentication. You can adjust the code as needed to support different endpoints and HTTP methods.

If you have any questions or need further assistance, feel free to contact the CatFee.IO support team.