Contributing To The CCXT.NET Library

August 26, 2025 · View on GitHub

Thank you for your interest in contributing to CCXT.NET! This document provides guidelines and instructions for contributing to the project.

Code of Conduct
How To Submit An Issue
How To Contribute Code
Development Setup
Repository Structure
Coding Standards
Testing Guidelines
Pull Request Process
Adding New Exchanges
Documentation
Community

Code of Conduct

We are committed to providing a welcoming and inspiring community for all. Please read and follow our Code of Conduct:

Be respectful and inclusive
Welcome newcomers and help them get started
Focus on what is best for the community
Show empathy towards other community members

How To Submit An Issue

Before submitting an issue, please:

Search existing issues to avoid duplicates
Use issue templates when available
Provide detailed information:
- CCXT.NET version
- .NET version
- Operating system
- Exchange name (if applicable)
- Complete error messages
- Code sample that reproduces the issue
- Expected vs actual behavior

Issue Categories

Bug Report: Something isn't working as expected
Feature Request: Suggest new functionality
Exchange Request: Request support for a new exchange
Documentation: Improvements to documentation
Question: General questions (consider Stack Overflow first)

How To Contribute Code

Before You Start

Fork the repository to your GitHub account
Create a feature branch from master
Check existing PRs to avoid duplicate work
Discuss major changes by opening an issue first

Development Setup

Prerequisites

.NET SDK 8.0 or 9.0: Download from dotnet.microsoft.com
Visual Studio 2022 or VS Code with C# extension
Git: For version control
PowerShell: For running scripts (Windows) or bash (Linux/Mac)

Initial Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/ccxt.net.git
cd ccxt.net

# Add upstream remote
git remote add upstream https://github.com/odinsoft-lab/ccxt.net.git

# Install dependencies and build
dotnet restore
dotnet build

# Run tests
dotnet test

Repository Structure

ccxt.net/
├── src/                          # Main library source code
│   ├── exchanges/                # Exchange implementations (120 total)
│   │   ├── {country_code}/       # 2-letter ISO country code folders
│   │   │   └── {exchange}/       # Individual exchange folder
│   │   │       ├── {exchange}.cs # Main exchange client class
│   │   │       ├── private/      # Private API implementations
│   │   │       │   ├── privateApi.cs
│   │   │       │   ├── address.cs
│   │   │       │   ├── balance.cs
│   │   │       │   ├── transfer.cs
│   │   │       │   └── wallet.cs
│   │   │       ├── public/       # Public API implementations
│   │   │       │   ├── publicApi.cs
│   │   │       │   ├── completeOrder.cs
│   │   │       │   ├── market.cs
│   │   │       │   ├── ohlcv.cs
│   │   │       │   ├── orderBook.cs
│   │   │       │   └── ticker.cs
│   │   │       └── trade/        # Trading API implementations
│   │   │           ├── tradeApi.cs
│   │   │           ├── order.cs
│   │   │           ├── place.cs
│   │   │           ├── position.cs
│   │   │           └── trade.cs
│   ├── shared/                   # Shared components
│   │   ├── standard/             # Standard interfaces and base classes
│   │   │   ├── XApiClient.cs    # Base API client
│   │   │   ├── IXApiClient.cs   # Client interface
│   │   │   └── errorCode.cs     # Error code definitions
│   │   └── types/                # Type definitions
│   └── ccxt.net.csproj          # Main project file
├── tests/                        # Test projects
│   ├── ccxt.tests.csproj        # Test project file
│   ├── private/                  # Private API tests
│   ├── public/                   # Public API tests
│   └── trade/                    # Trading API tests
├── samples/                      # Sample applications
│   └── ccxt.samples.csproj      # Sample project file
├── docs/                         # Documentation
│   ├── CONTRIBUTING.md          # This file
├── scripts/                      # Build and deployment scripts
└── README.md                     # Main documentation

Coding Standards

C# Style Guidelines

We follow the .NET coding conventions:

// Use PascalCase for class names and methods
public class ExchangeClient
{
    // Use camelCase for local variables and parameters
    public async Task<ApiResult<Ticker>> GetTickerAsync(string symbol)
    {
        // Use meaningful variable names
        var tickerRequest = new TickerRequest(symbol);
        
        // Always use braces, even for single-line statements
        if (tickerRequest.IsValid)
        {
            return await SendRequestAsync(tickerRequest);
        }
        
        // Use explicit types for clarity
        ApiResult<Ticker> errorResult = new ApiResult<Ticker>();
        return errorResult;
    }
    
    // Private fields start with underscore
    private readonly HttpClient _httpClient;
    
    // Properties use PascalCase
    public string ExchangeName { get; set; }
}

Best Practices

Async/Await: Use async methods for all I/O operations
Null Safety: Use nullable reference types and null checks
Exception Handling: Catch specific exceptions, log errors appropriately
Resource Management: Use using statements for disposable resources
SOLID Principles: Follow Single Responsibility, Open/Closed, etc.
DRY: Don't repeat yourself - extract common code
Comments: Write XML documentation for public APIs

Naming Conventions

Namespaces: CCXT.NET.{ExchangeName}
Classes: {Exchange}Client, {Exchange}PublicApi
Interfaces: I{Name} (e.g., IXApiClient)
Async Methods: {Method}Async (e.g., GetTickerAsync)
Private Fields: _{fieldName} (e.g., _httpClient)

Testing Guidelines

Writing Tests

[Fact]
public async Task GetTicker_WithValidSymbol_ReturnsTickerData()
{
    // Arrange
    var client = new BinanceClient("public");
    var symbol = "BTC/USDT";
    
    // Act
    var result = await client.GetTickerAsync(symbol);
    
    // Assert
    Assert.True(result.Success);
    Assert.NotNull(result.Data);
    Assert.Equal(symbol, result.Data.Symbol);
}

Test Categories

Unit Tests: Test individual methods in isolation
Integration Tests: Test API endpoints with real exchanges
Performance Tests: Measure response times and throughput

Running Tests

# Run all tests
dotnet test

# Run specific test category
dotnet test --filter "Category=Public"

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

Pull Request Process

Before Submitting

Update your branch with the latest upstream changes:

git fetch upstream
git rebase upstream/master

Run all tests and ensure they pass:
```
dotnet test
```
Check code style and fix any issues:
```
dotnet format
```
Update documentation if you've made API changes

PR Guidelines

Title: Use clear, descriptive titles
- ✅ "Add support for Binance futures trading"
- ❌ "Fixed stuff"
Description: Include:
- What changes were made
- Why they were necessary
- How to test the changes
- Related issues (use "Fixes #123")

Commits:

Use meaningful commit messages
Squash minor commits

Follow conventional commits format:

feat: add Binance futures support
fix: correct rate limiting for Kraken
docs: update API documentation
test: add tests for new endpoints

Size: Keep PRs focused and reasonably sized
- Separate large changes into multiple PRs
- One feature/fix per PR

Review Process

Automated Checks: CI/CD runs tests and code analysis
Code Review: Maintainers review code quality and design
Testing: Additional manual testing may be required
Feedback: Address reviewer comments promptly
Merge: Once approved, maintainers will merge your PR

Adding New Exchanges

Step 1: Create Exchange Structure

# Create directory structure
mkdir -p src/exchanges/{country_code}/{exchange_name}
mkdir -p src/exchanges/{country_code}/{exchange_name}/private
mkdir -p src/exchanges/{country_code}/{exchange_name}/public
mkdir -p src/exchanges/{country_code}/{exchange_name}/trade

Step 2: Implement Main Client Class

Create src/exchanges/{country_code}/{exchange_name}/{exchange_name}.cs:

using CCXT.NET.Shared.Coin;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace CCXT.NET.{ExchangeName}
{
    public sealed class {ExchangeName}Client : XApiClient, IXApiClient
    {
        public override string DealerName { get; set; } = "{ExchangeName}";
        
        public {ExchangeName}Client(string division)
            : base(division)
        {
        }
        
        public {ExchangeName}Client(string division, string connect_key, string secret_key)
            : base(division, connect_key, secret_key, authentication: true)
        {
        }
        
        public override ExchangeInfo ExchangeInfo
        {
            get
            {
                // Implementation details
            }
        }
    }
}

Step 3: Implement API Endpoints

Follow the existing pattern for public, private, and trade APIs.

Step 4: Add Tests

Create corresponding test files in the tests/ directory.

Step 5: Update Documentation

Add the exchange to README.md and update the supported exchanges list.

Documentation

Code Documentation

Use XML documentation comments for all public APIs:

/// <summary>
/// Retrieves the current ticker information for a trading pair
/// </summary>
/// <param name="symbol">Trading pair symbol (e.g., "BTC/USDT")</param>
/// <returns>Ticker information including price, volume, and 24h changes</returns>
/// <exception cref="ArgumentNullException">Thrown when symbol is null</exception>
public async Task<ApiResult<Ticker>> GetTickerAsync(string symbol)
{
    // Implementation
}