CoinDCX Python API

This is an unofficial Python wrapper for the CoinDCX Exchange API with support for public market data and authenticated trading.

Features

✅ Single unified client for both public and authenticated endpoints
✅ Generic CLI tool for command-line usage with automatic method discovery
✅ Type hints for better IDE support
✅ Automatic HMAC-SHA256 signature generation
✅ Comprehensive error handling with custom exceptions
✅ Support for all CoinDCX endpoints:
- Public market data
- Spot trading
- Margin trading
- Futures trading
- WebSocket streams (coming soon)
✅ Context manager support for automatic resource cleanup
✅ Enums for constants (order types, sides, status, etc.)

Installation

pip install coindcx

Quick Start

Public Endpoints (No Authentication)

from coindcx import Client

# Initialize client without credentials for public endpoints
client = Client()

# Get all markets
markets = client.get_markets()
print(f"Available markets: {len(markets)}")

# Get ticker for all markets
tickers = client.get_ticker()
for ticker in tickers[:5]:  # Show first 5
    print(f"{ticker['market']}: {ticker['last_price']}")

# Get market details
details = client.get_markets_details()
for market in details[:3]:
    print(f"{market['coindcx_name']}: Min quantity = {market['min_quantity']}")

# Get order book
orderbook = client.get_orderbook('KC-BTC_USDT')
print(f"Best bid: {list(orderbook['bids'].keys())[0]}")
print(f"Best ask: {list(orderbook['asks'].keys())[0]}")

# Get recent trades
trades = client.get_trades('KC-BTC_USDT', limit=10)
print(f"Latest trade price: {trades[0]['p']}")

# Get candlestick data
candles = client.get_candles('KC-BTC_USDT', interval='1h', limit=24)
print(f"24h candles received: {len(candles)}")

Futures Endpoints (Public)

from coindcx import Client
import time

client = Client()

# Get all active USDT margined futures instruments
instruments = client.get_active_instruments(['USDT'])
print(f"Total USDT instruments: {len(instruments)}")
print(f"Sample instruments: {instruments[:5]}")

# Get detailed information for a specific instrument
details = client.get_instrument_details('B-BTC_USDT', 'USDT')
instrument = details['instrument']
print(f"Status: {instrument['status']}")
print(f"Max leverage: {instrument['max_leverage_long']}x")
print(f"Maker fee: {instrument['maker_fee']}%")
print(f"Min quantity: {instrument['min_quantity']}")

# Get futures candlestick data
to_time = int(time.time())
from_time = to_time - (7 * 24 * 60 * 60)  # 7 days ago
candles = client.get_futures_candles('B-BTC_USDT', from_time, to_time, '1D')
print(f"Futures candles: {len(candles['data'])}")

# Get futures trade history
trades = client.get_futures_trade_history('B-BTC_USDT')
for trade in trades[:5]:
    print(f"Trade: {trade['quantity']} @ {trade['price']} (Maker: {trade['is_maker']})")

Authenticated Endpoints

from coindcx import Client, OrderSide, OrderType, FuturesOrderType, TimeInForce

# Initialize client with API credentials
client = Client(
    api_key='your_api_key_here',
    api_secret='your_api_secret_here'
)

# Get account balances
balances = client.get_balances()
for balance in balances:
    if float(balance['balance']) > 0:
        print(f"{balance['currency']}: {balance['balance']}")

# Get user info
user_info = client.get_user_info()
print(f"User ID: {user_info['coindcx_id']}")
print(f"Email: {user_info['email']}")

Spot Trading

from coindcx import Client, OrderSide, OrderType

client = Client(api_key='your_key', api_secret='your_secret')

# Create a market buy order - buy 0.001 BTC at market price
market_order = client.create_spot_order(
    market='KC-BTC_USDT',
    side=OrderSide.BUY,
    order_type=OrderType.MARKET_ORDER,
    total_quantity=0.001
)
print(f"Market Order ID: {market_order['id']}, Status: {market_order['status']}")

# Create a limit sell order - sell 0.001 BTC at $52,000
limit_order = client.create_spot_order(
    market='KC-BTC_USDT',
    side=OrderSide.SELL,
    order_type=OrderType.LIMIT_ORDER,
    total_quantity=0.001,
    price_per_unit=52000,
    client_order_id='my-custom-order-id'  # Optional tracking ID
)
print(f"Limit Order ID: {limit_order['id']}, Price: {limit_order['price_per_unit']}")

Futures Trading

from coindcx import Client, OrderSide, FuturesOrderType, TimeInForce

client = Client(api_key='your_key', api_secret='your_secret')

# Create a market futures order with 10x leverage
futures_market = client.create_futures_order(
    pair='B-BTC_USDT',
    side=OrderSide.BUY,
    order_type=FuturesOrderType.MARKET,
    total_quantity=0.01,
    leverage=10,
    margin_currency_short_name='USDT'
)
print(f"Futures Market Order: {futures_market['id']}, Leverage: {futures_market['leverage']}x")

# Create a limit futures order with take profit and stop loss
futures_limit = client.create_futures_order(
    pair='B-BTC_USDT',
    side=OrderSide.BUY,
    order_type=FuturesOrderType.LIMIT,
    total_quantity=0.01,
    price=49000,
    leverage=5,
    time_in_force=TimeInForce.GOOD_TILL_CANCEL,
    take_profit_price=55000,  # Take profit at $55,000
    stop_loss_price=47000,    # Stop loss at $47,000
    post_only=True           # Maker-only order
)
print(f"Futures Limit Order: {futures_limit['id']}")

# Create a stop-limit order (triggered when price hits stop_price)
stop_limit = client.create_futures_order(
    pair='B-ETH_USDT',
    side=OrderSide.SELL,
    order_type=FuturesOrderType.STOP_LIMIT,
    total_quantity=0.1,
    price=3200,        # Limit price once triggered
    stop_price=3250,   # Trigger price
    leverage=3,
    time_in_force=TimeInForce.FILL_OR_KILL
)

# Create a take profit market order
take_profit = client.create_futures_order(
    pair='B-BTC_USDT',
    side=OrderSide.SELL,
    order_type=FuturesOrderType.TAKE_PROFIT_MARKET,
    total_quantity=0.005,
    stop_price=60000,  # Trigger when BTC hits $60,000
    leverage=2
)

# List open futures orders
open_orders = client.list_futures_orders(
    side=OrderSide.BUY,
    status='open',
    margin_currency_short_name=['USDT']
)
print(f"Open Orders: {len(open_orders)}")

# Edit an existing futures order
edited_order = client.edit_futures_order(
    id='order_id_here',
    total_quantity=0.5,
    price=51000,
    take_profit_price=55000,
    stop_loss_price=48000
)
print(f"Edited Order ID: {edited_order['id']}")

Using Context Manager

from coindcx import Client

# Automatically closes session when done
with Client(api_key='...', api_secret='...') as client:
    balances = client.get_balances()
    print(balances)
# Session automatically closed here

Command-Line Interface (CLI)

The library includes a powerful generic CLI tool that automatically exposes all client methods for command-line usage. Perfect for quick testing, scripting, and automation.

Features

Automatic method discovery - Works with all current and future methods without modification
Type inference - Automatically converts arguments to correct types
Environment variable support - Securely pass API credentials
Pretty JSON output - Formatted for readability
Built-in help - View all available methods and their parameters

Basic Usage

# View all available methods and their parameters
python cli.py --help

# Call any method with named parameters
python cli.py [method_name] --arg1=value1 --arg2=value2

Examples

Public Endpoints (No Authentication):

# Get all markets
python cli.py get_markets

# Get ticker data for all markets
python cli.py get_ticker

# Get recent trades with parameters
python cli.py get_trades --pair=KC-BTC_USDT --limit=10

# Get order book for a specific pair
python cli.py get_orderbook --pair=KC-BTC_USDT

# Get candlestick data
python cli.py get_candles --pair=KC-BTC_USDT --interval=1h --limit=24

# Get markets details
python cli.py get_markets_details

# Get futures candles
python cli.py get_futures_candles --pair=B-BTC_USDT --from_time=1700000000 --to_time=1700086400 --resolution=1D

# Get futures trade history
python cli.py get_futures_trade_history --pair=B-BTC_USDT

# Get active futures instruments (JSON format or comma-separated)
python cli.py get_active_instruments --margin_currency_short_name=["USDT"]
python cli.py get_active_instruments --margin_currency_short_name=USDT,INR

# Get instrument details
python cli.py get_instrument_details --pair=B-BTC_USDT --margin_currency_short_name=USDT

Authenticated Endpoints:

# Option 1: Pass credentials as arguments
python cli.py get_balances --api-key=YOUR_KEY --api-secret=YOUR_SECRET
python cli.py get_user_info --api-key=YOUR_KEY --api-secret=YOUR_SECRET

# Option 2: Use environment variables (recommended for security)
export COINDCX_API_KEY="your_api_key"
export COINDCX_API_SECRET="your_api_secret"
python cli.py get_balances
python cli.py get_user_info

# Create spot orders
python cli.py create_spot_order --market=KC-BTC_USDT --side=buy --order_type=market_order --total_quantity=0.001

python cli.py create_spot_order --market=KC-ETH_USDT --side=sell --order_type=limit_order --total_quantity=0.1 --price_per_unit=3500 --client_order_id=my-custom-id

# Create futures orders
python cli.py create_futures_order --pair=B-BTC_USDT --side=buy --order_type=market --total_quantity=0.01 --leverage=10 --margin_currency_short_name=USDT

python cli.py create_futures_order --pair=B-BTC_USDT --side=buy --order_type=limit --total_quantity=0.01 --price=50000 --leverage=5 --time_in_force=good_till_cancel

# List futures orders
python cli.py list_futures_orders --side=buy --status=open

# Edit futures order
python cli.py edit_futures_order --id=ORDER_ID --total_quantity=0.5 --price=51000

Additional Options:

# Customize timeout
python cli.py get_candles --pair=KC-BTC_USDT --interval=1h --timeout=60

# Disable pretty printing (compact JSON)
python cli.py get_markets --pretty=false

How It Works

The CLI uses Python's introspection to:

Discover all public methods from the Client class
Extract type hints and parameter information
Automatically convert string arguments to the correct types (int, float, bool, etc.)
Validate required vs optional parameters

This means any new methods you add to the Client class are automatically available in the CLI without any changes!

CLI Options

Option	Description	Example
`--api-key`	API key for authentication	`--api-key=YOUR_KEY`
`--api-secret`	API secret for authentication	`--api-secret=YOUR_SECRET`
`--timeout`	Request timeout in seconds (default: 30)	`--timeout=60`
`--pretty`	Pretty print JSON output (default: true)	`--pretty=false`
`--help`, `-h`	Show help message	`python cli.py --help`

Scripting Examples

The CLI is perfect for shell scripts and automation:

#!/bin/bash
# Monitor BTC price every 30 seconds

export COINDCX_API_KEY="your_key"
export COINDCX_API_SECRET="your_secret"

while true; do
  echo "Checking BTC price at $(date)"
  python cli.py get_orderbook --pair=KC-BTC_USDT | jq -r '.asks | keys[0]'
  sleep 30
done

#!/bin/bash
# Get account balances and filter non-zero balances

python cli.py get_balances | jq '.[] | select((.balance | tonumber) > 0)'

Error Handling

The library provides specific exceptions for different error scenarios:

from coindcx import Client, CoinDCXAPIException, CoinDCXAuthenticationException

client = Client()

try:
    # This will fail - authentication required
    balances = client.get_balances()
except CoinDCXAuthenticationException as e:
    print(f"Authentication error: {e}")

try:
    # Invalid market
    orderbook = client.get_orderbook('INVALID_MARKET')
except CoinDCXAPIException as e:
    print(f"API error [{e.status_code}]: {e.message}")

Exception Hierarchy

CoinDCXException (base)
├── CoinDCXAPIException          # API errors (4xx, 5xx responses)
├── CoinDCXRequestException      # Network/timeout errors
├── CoinDCXAuthenticationException  # Missing or invalid credentials
├── CoinDCXRateLimitException    # Rate limit exceeded (429)
└── CoinDCXOrderException        # Order-related errors
    └── CoinDCXInvalidOrderException

Using Enums

The library provides enums for various constants:

from coindcx import Client, OrderSide, OrderType, CandleInterval

# Use enums for type safety
candles = client.get_candles(
    pair='KC-BTC_USDT',
    interval=CandleInterval.ONE_HOUR,
    limit=100
)

Available enums:

OrderSide: BUY, SELL
OrderType: MARKET_ORDER, LIMIT_ORDER, STOP_LIMIT, TAKE_PROFIT
OrderStatus: INIT, OPEN, FILLED, CANCELLED, etc.
CandleInterval: ONE_MINUTE, FIVE_MINUTES, ONE_HOUR, ONE_DAY, etc.
ExchangeCode: COINDCX_INR, BINANCE, HUOBI, KUCOIN
TimeInForce: GOOD_TILL_CANCEL, IMMEDIATE_OR_CANCEL, FILL_OR_KILL
FuturesMarginMode: INR, USDT
PositionMarginType: ISOLATED, CROSSED

API Coverage

✅ Implemented

Public Endpoints:

get_ticker() - Get ticker for all markets
get_markets() - Get list of all markets
get_markets_details() - Get detailed market information
get_trades(pair, limit) - Get recent trades
get_orderbook(pair) - Get order book
get_candles(pair, interval, ...) - Get candlestick data

Futures Public Endpoints:

get_futures_candles(pair, from_time, to_time, resolution) - Get futures candlestick data
get_active_instruments(margin_currency_short_name) - Get list of active futures instruments
get_instrument_details(pair, margin_currency_short_name) - Get detailed instrument information
get_futures_trade_history(pair) - Get real-time trade history for futures

Authenticated Endpoints:

get_balances() - Get account balances
get_user_info() - Get user information

Spot Trading:

create_spot_order(market, side, order_type, total_quantity, ...) - Create spot orders (market/limit)

Futures Trading:

create_futures_order(pair, side, order_type, total_quantity, ...) - Create futures orders (market/limit/stop/take-profit)
list_futures_orders(side, status, ...) - List futures orders filtering by status
edit_futures_order(id, total_quantity, price, ...) - Edit open futures orders

🚧 Coming Soon

Spot Trading:

Cancel order
Get order status
Get active orders
Get trade history

Margin Trading:

Place margin order
Cancel margin order
Edit target/stop-loss
Add/remove margin

Futures Trading:

Cancel futures order
List positions
Update leverage
Get transactions

WebSocket Streams:

Balance updates
Order updates
Trade updates
Price feeds
Order book streams

Configuration

You can customize the client behavior:

from coindcx import Client

client = Client(
    api_key='your_key',
    api_secret='your_secret',
    timeout=60,  # Request timeout in seconds (default: 30)
    base_url='https://api.coindcx.com',  # Override base URL if needed
    public_url='https://public.coindcx.com',  # Override public URL
)

Development

Project Structure

coindcx-python/
├── coindcx/
│   ├── __init__.py
│   ├── client.py          # Main Client class
│   ├── exceptions.py      # Custom exceptions
│   ├── enums.py          # Enums and constants
│   └── endpoints/        # Modular endpoint implementations
│       ├── __init__.py
│       ├── market.py     # Public market endpoints
│       ├── spot.py       # Spot trading
│       ├── margin.py     # Margin trading
│       └── futures.py    # Futures trading
├── examples/
│   └── basic_usage.py
├── cli.py                # Command-line interface tool
├── setup.py
├── requirements.txt
└── README.md

Running Examples

# Set your API credentials as environment variables (optional)
export COINDCX_API_KEY="your_api_key"
export COINDCX_API_SECRET="your_api_secret"

# Run Python examples
python examples/basic_usage.py
python examples/futures_instruments.py  # Futures instruments example

# Or use the CLI tool for quick testing
python cli.py get_markets
python cli.py get_ticker
python cli.py get_balances  # Requires API credentials
python cli.py get_active_instruments --margin_currency_short_name=USDT
python cli.py get_instrument_details --pair=B-BTC_USDT

Getting API Credentials

Sign up at CoinDCX
Go to API Dashboard
Click "Create API Key"
Store your key and secret securely

Security Notes:

Never commit API credentials to version control
Use environment variables for credentials in production
Bind API keys to specific IP addresses when possible
Regularly rotate your API keys

Rate Limits

CoinDCX enforces rate limits on API calls. The library will raise CoinDCXRateLimitException when limits are exceeded.

Endpoint	Limit	Period
Create Order	2000	60s
Cancel Order	2000	60s
Order Status	2000	60s
Active Orders	300	60s

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License

Disclaimer

This library is not officially affiliated with CoinDCX. Use at your own risk. Trading cryptocurrencies carries risk - ensure you understand the risks before trading.

Support

Changelog

v0.2.0 (2024-12-XX)

NEW: Spot order creation - create_spot_order() for spot trading
- Support for market and limit orders
- Optional client order ID tracking
- Comprehensive parameter validation
NEW: Futures order creation - create_futures_order() for futures trading
- Support for all futures order types: market, limit, stop-limit, stop-market, take-profit-limit, take-profit-market
- Advanced features: leverage control, take profit/stop loss, time-in-force options
- Post-only orders and hidden orders support
- Isolated/crossed margin support
NEW: Futures order management
- list_futures_orders() - List orders with status filters
- edit_futures_order() - Edit open order quantity, price, and TP/SL triggers
ENHANCED: CLI tool now supports order creation commands
ENHANCED: Documentation with comprehensive trading examples
ENHANCED: Better error handling for order validation

v0.1.0 (2024-01-XX)

Initial release
Support for public market data endpoints
Support for basic authenticated endpoints
HMAC-SHA256 signature generation
Comprehensive error handling
Generic CLI tool with automatic method discovery
Futures endpoints support

Development Notes

How to prepare markdown documentation

Copy HTML from https://docs.coindcx.com/ to ai/coindcx_documentation.html
Run

make

OR

html-to-markdown ai/coindcx_documentation.html -o ai/coindcx_documentation.md

Name		Name	Last commit message	Last commit date
ai		ai
coindcx		coindcx
dev		dev
examples		examples
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
FUTURES_POSITIONS_API.md		FUTURES_POSITIONS_API.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
Makefile		Makefile
README.md		README.md
cli.py		cli.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setup.py		setup.py

Latest commit

History

Folders and files

Repository files navigation

CoinDCX Python API

Features

Installation

Quick Start

Public Endpoints (No Authentication)

Futures Endpoints (Public)

Authenticated Endpoints

Spot Trading

Futures Trading

Using Context Manager

Command-Line Interface (CLI)

Features

Basic Usage

Examples

How It Works

CLI Options

Scripting Examples

Error Handling

Exception Hierarchy

Using Enums

API Coverage

✅ Implemented

🚧 Coming Soon

Configuration

Development

Project Structure

Running Examples

Getting API Credentials

Rate Limits

Contributing

License

Disclaimer

Support

Changelog

v0.2.0 (2024-12-XX)

v0.1.0 (2024-01-XX)

Development Notes

How to prepare markdown documentation

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages