If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/knowm/XChange shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3w ago
• 5 active contributors
• Distributed ownership (top contributor 43% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live knowm/XChange repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/knowm/XChange.

What it runs against: a local clone of knowm/XChange — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in knowm/XChange | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 49 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of knowm/XChange. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/knowm/XChange.git
#   cd XChange
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of knowm/XChange and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "knowm/XChange(\\.git)?\\b" \\
  && ok "origin remote is knowm/XChange" \\
  || miss "origin remote is not knowm/XChange (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop no longer exists"

# 4. Critical files exist
test -f "pom.xml" \\
  && ok "pom.xml" \\
  || miss "missing critical file: pom.xml"
test -f "xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/AscendexExchange.java" \\
  && ok "xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/AscendexExchange.java" \\
  || miss "missing critical file: xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/AscendexExchange.java"
test -f "xchange-bibox/src/main/java/org/knowm/xchange/bibox/BiboxExchange.java" \\
  && ok "xchange-bibox/src/main/java/org/knowm/xchange/bibox/BiboxExchange.java" \\
  || miss "missing critical file: xchange-bibox/src/main/java/org/knowm/xchange/bibox/BiboxExchange.java"
test -f "xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/service/AscendexMarketDataService.java" \\
  && ok "xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/service/AscendexMarketDataService.java" \\
  || miss "missing critical file: xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/service/AscendexMarketDataService.java"
test -f "xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/service/AscendexTradeService.java" \\
  && ok "xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/service/AscendexTradeService.java" \\
  || miss "missing critical file: xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/service/AscendexTradeService.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 49 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~19d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/knowm/XChange"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

XChange is a Java library that abstracts the API differences of 60+ cryptocurrency exchanges (Binance, Kraken, Bitfinex, Coinbase, etc.) behind a single unified interface. Instead of learning each exchange's proprietary REST API, developers write once and swap exchanges by changing configuration. Core capabilities include order placement/cancellation, account balances, market data (tickers, orderbooks, trade history), and real-time WebSocket streaming. Maven monorepo structure: root pom.xml declares 60+ exchange-specific modules (xchange-binance, xchange-kraken, xchange-bitfinex, etc.). Each module at xchange-{exchange}/ contains: (1) src/main/java/org/knowm/xchange/{exchange}/ with exchange implementation classes (Exchange, Adapters, Service implementations) (2) dto/ subpackage containing JSON-serializable data transfer objects mirroring each exchange's API (3) parallel test structure. Common interfaces defined in xchange-core (not shown but referenced by all modules).

Java developers building cryptocurrency trading bots, portfolio trackers, arbitrage systems, or market analysis tools who need to work with multiple exchanges without reimplementing API calls for each one. Also used by trading firms and fintech companies that need a consistent abstraction layer across their exchange integrations.

Highly mature and production-ready. The project has been active since 2012 (inceptionYear in pom.xml), spans 60+ exchanges with CI/CD workflows for major ones (Bitfinex, Kraken, Deribit, Gate.io, etc.), uses Maven for robust dependency management, and has structured test automation (.github/workflows/). Active maintenance visible in the develop branch snapshot releases and dedicated GitHub Actions for integration testing per exchange.

Low-to-moderate risk for production use but with exchange-specific volatility. Risk factors: (1) Dependency on external exchange APIs that change without warning—individual exchange modules can break (2) Single-maintainer organization (Tim Molter listed as primary developer in pom.xml) means critical fixes may wait (3) 60+ modules means maintenance surface area is large; not all exchanges are equally tested (4) Version 5.2.5-SNAPSHOT indicates the library is pre-release, so breaking changes are possible.

Active development on exchange integrations: dedicated GitHub Actions workflows for Bitfinex, Bitget, BitMEX, CoinEx, Deribit, Gate.io, Kraken, and MEXC indicate recent/ongoing work. Dependabot is configured (.github/dependabot.yml) to manage dependency updates. Version is 5.2.5-SNAPSHOT suggesting the next release is in progress on the develop branch.

Clone and build:

git clone https://github.com/knowm/XChange.git
cd XChange
mvn clean install

Or use snapshot jars from Maven Central (org.knowm.xchange:xchange-{exchange}:5.2.5-SNAPSHOT). Requires Java and Maven 3.6+. See README for credentials setup per exchange if testing authenticated endpoints.

Daily commands: XChange is a library, not an application—there is no 'dev server.' To test: (1) Run existing integration tests via Maven: mvn -pl xchange-{exchange} verify (2) GitHub Actions run these automatically on push/PR. To use in your own project: add dependency to pom.xml, instantiate an Exchange (e.g., ExchangeFactory.createExchange(BinanceExchange.class)), get a service, and call methods.

• pom.xml — Parent POM defining all module dependencies, versions, and build configuration for the multi-module XChange library; any dependency update or build change propagates to all 60+ exchange adapters
• xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/AscendexExchange.java — Exemplar Exchange implementation showing the standard pattern all exchange adapters must follow to initialize services and expose market data/trading APIs
• xchange-bibox/src/main/java/org/knowm/xchange/bibox/BiboxExchange.java — Second reference Exchange implementation demonstrating variant patterns and adapter-specific initialization logic used across the codebase
• xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/service/AscendexMarketDataService.java — Core market data service layer showing how exchanges expose ticker, orderbook, and trade data through the standardized XChange service interface
• xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/service/AscendexTradeService.java — Trading service implementation demonstrating order placement, cancellation, and trade history retrieval patterns used consistently across all adapters
• xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/AscendexAdapters.java — DTO-to-domain-model conversion layer; shows how raw exchange API responses are transformed into XChange's unified Currency, Ticker, and Order objects
• .github/workflows/maven.yml — CI/CD pipeline defining how the entire multi-module project is built, tested, and deployed on every commit; critical for maintaining release quality

Add a new cryptocurrency exchange adapter

1. Create new module directory xchange-{exchange-name}/ with pom.xml mirroring xchange-ascendex/pom.xml (xchange-{exchange-name}/pom.xml)
2. Define public REST API interface extending parent exchange contract (xchange-{exchange-name}/src/main/java/org/knowm/xchange/{exchange-name}/I{ExchangeName}.java)
3. Implement concrete Exchange class initializing MarketDataService, TradeService, AccountService (xchange-{exchange-name}/src/main/java/org/knowm/xchange/{exchange-name}/{ExchangeName}Exchange.java)
4. Create DTOs for each API endpoint response structure (Orderbook, Ticker, Order, etc.) (xchange-{exchange-name}/src/main/java/org/knowm/xchange/{exchange-name}/dto/{ExchangeName}OrderbookDto.java)
5. Implement adapters to transform DTOs into XChange domain objects (Ticker, Order, Wallet) (xchange-{exchange-name}/src/main/java/org/knowm/xchange/{exchange-name}/{ExchangeName}Adapters.java)
6. Create raw service classes with @Path methods delegating to IAscendexAuthenticated interface for HTTP calls (xchange-{exchange-name}/src/main/java/org/knowm/xchange/{exchange-name}/service/{ExchangeName}MarketDataServiceRaw.java)
7. Create public service classes wrapping raw services and returning adapted domain objects (xchange-{exchange-name}/src/main/java/org/knowm/xchange/{exchange-name}/service/{ExchangeName}MarketDataService.java)
8. Add unit tests loading JSON fixtures from test resources and validating DTO deserialization and adapter conversion (xchange-{exchange-name}/src/test/java/org/knowm/xchange/{exchange-name}/{ExchangeName}MarketDataJSONTest.java)

Add a new market data endpoint (e.g., new candle data API)

1. Add method signature to raw service interface fetching candles from the exchange API (xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/IAscendex.java)
2. Create DTO class modeling the exchange's candle response structure (xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/dto/marketdata/AscendexCandleDto.java)
3. Implement raw service method with @GET or @POST annotation calling the endpoint (xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/service/AscendexMarketDataServiceRaw.java)
4. Add adapter method converting AscendexCandleDto to XChange Kline or OHLC object (xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/AscendexAdapters.java)
5. Add public service method wrapping the raw call and adapter conversion (xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/service/AscendexMarketDataService.java)
6. Add JSON test fixture with sample API response and validate DTO deserialization (xchange-ascendex/src/test/resources/org/knowm/xchange/ascendex/ascendexCandleResponseExample.json)

Add authenticated trading capability to an exchange (e.g., place order)

1. Create DTO for the order placement request payload with currency pair, amount, price fields (xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/dto/trade/AscendexPlaceOrderRequestPayload.java)
2. Create DTO for the order placement response with order ID and status (xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/dto/trade/AscendexOrderResponse.java)
3. Add authenticated interface method and Digest class for HMAC-SHA256 signature generation (xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/IAscendexAuthenticated.java)
4. Implement raw trade service method with @POST annotation, request signing, and response deserialization (xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/service/AscendexTradeServiceRaw.java)
5. Add adapter converting AscendexOrderResponse to XChange Order object with status and fees (xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/AscendexAdapters.java)
6. Add public trade service method that validates input, calls raw service, adapts

Exchange API authentication requires API keys and secrets specific to each exchange (Binance, Kraken, etc.); tests using authenticated endpoints need valid credentials in environment variables or config files. Some exchanges have rate limits or IP whitelisting requirements. WebSocket streaming (referenced in workflows: stream-bitfinex.yaml, stream-deribit.yaml) requires separate handling from REST—check if the exchange module supports it before relying on real-time data. Exchange APIs change without notice; the library may lag behind API changes for less-maintained modules. No explicit Java version requirement shown but assume Java 8+ minimum based on Maven structure.

• Adapter Pattern — XChange's core design: each exchange has an Adapters class (e.g., AscendexAdapters.java) that converts exchange-specific DTOs into common XChange objects; understanding this is essential to modify data flows or add new exchange integrations
• Data Transfer Object (DTO) — Every exchange module heavily uses DTOs (e.g., AscendexOrderResponse.java) with Jackson annotations to deserialize JSON responses; you must understand DTO structure and Jackson's @JsonProperty to work with market data or add new API endpoints
• REST API Abstraction / Facade Pattern — XChange wraps 60+ distinct REST APIs (each with different parameter names, response formats, auth schemes) behind unified interfaces (TradeService, AccountService, MarketDataService); understanding this abstraction is why the library exists and why exchanges are swappable
• WebSocket Streaming (vs REST polling) — GitHub Actions workflows include stream-bitfinex.yaml and stream-deribit.yaml, indicating the library supports real-time updates via WebSocket; critical for trading bots, but requires separate service implementation from REST endpoints
• Maven Multi-Module Project / Monorepo — XChange uses a single parent pom.xml to coordinate 60+ exchange modules as a monorepo; managing dependencies, versions, and builds across this scale requires understanding Maven's module inheritance and reactor builds
• Exchange Authentication (API Key / Secret signing) — XChange supports two auth flows: public endpoints (market data, no auth) and authenticated endpoints (trading, account info) requiring HMAC-SHA256 signed requests; each exchange has different nonce/timestamp/signature requirements buried in service implementations
• Rate Limiting and Backoff Strategies — Exchanges enforce rate limits but XChange's approach to handling them is not visible in the file list; when contributing, you may need to implement or improve exponential backoff and request throttling per-exchange specifications

• ccxt/ccxt — Direct competitor: multi-language (JS/Python/PHP) unified exchange API wrapper; if you need language flexibility instead of JVM-only, CCXT is the alternative
• nixtla/exchangelib — Python-exclusive alternative with focus on real-time streaming and historical data; XChange users may compare if Python interop is needed
• binance/binance-java-api — Official Binance Java SDK; XChange abstracts this but single-exchange users sometimes fall back to official SDKs for undocumented features
• knowm/Yank — Sister project from Knowm Inc. (same org as XChange); Yank is a lightweight JDBC wrapper—XChange users building trading databases often integrate with Yank for persistence
• ta4j/ta4j — Technical analysis library often paired with XChange for building trading bots; consumes market data from XChange and outputs trade signals

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration test workflows for missing exchange modules

The .github/workflows directory shows selective CI coverage (bitfinex, bitget, bitmex, coinex, deribit, gateio-v4, kraken, mexc) but pom.xml lists 40+ exchange modules. Many exchanges like xchange-ascendex, xchange-bibox, xchange-binance lack dedicated workflow files. Adding workflows similar to it-template.yaml would catch exchange-specific API breakages early and improve maintainability.

• [ ] Review .github/workflows/it-template.yaml to understand the integration test pattern
• [ ] Identify top 5-10 high-traffic exchanges without workflows (binance, kraken-v2, coinbase, etc.) by checking module popularity and GitHub issues
• [ ] Create .github/workflows/{exchange-name}.yaml files following the existing pattern, configuring appropriate API endpoints and test credentials
• [ ] Add secrets configuration to GitHub repo settings for each new workflow
• [ ] Test workflows on a feature branch to ensure they pass and catch real issues

Add missing JSON test fixtures for xchange-ascendex exchange module

The xchange-ascendex module has AscendexMarketDataJSONTest.java and AscendexTradeDataJSONTest.java but xchange-ascendex/src/test/resources appears empty (no test data files). Without mock JSON responses, these tests cannot run. This pattern is essential for offline testing and should be consistent across all modules.

• [ ] Examine similar exchange modules (xchange-binance, xchange-bitfinex) to understand required JSON test fixture structure in src/test/resources/{exchange}/
• [ ] Review AscendexMarketDataJSONTest and AscendexTradeDataJSONTest to identify which API responses are being tested
• [ ] Create representative JSON fixtures for: orderbook responses, trade history, candlestick data, and order placement responses based on Ascendex API documentation
• [ ] Populate xchange-ascendex/src/test/resources/ with properly organized fixture files
• [ ] Verify tests pass locally and can run in CI without external API calls

Refactor and consolidate exchange base service classes to reduce duplication

Each exchange module (xchange-ascendex, xchange-bitget, etc.) contains similar class hierarchies: {Exchange}BaseService, {Exchange}Digest, {Exchange}AccountServiceRaw, {Exchange}TradeServiceRaw. This creates maintenance burden across 60+ modules. Creating a shared base service template and extracting common patterns would reduce code duplication and make adding new exchanges faster.

• [ ] Compare xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/service/ with 3-4 other exchange modules (xchange-bitget, xchange-binance) to identify common patterns
• [ ] Document shared concerns: authentication digest creation, request/response marshaling, error handling, and rate limiting
• [ ] Create xchange-core or update existing core module with abstract base classes like AbstractExchangeBaseService, AbstractExchangeDigest
• [ ] Refactor xchange-ascendex to extend the new abstractions, removing duplicated code
• [ ] Add documentation in README explaining the new base service patterns for contributors adding new exchanges

• Add missing unit tests for DTO deserialization in xchange-ascendex/src/test/ (and copy pattern to other modules)—many modules lack tests for JSON parsing edge cases like null/missing fields, which breaks when exchange API schema changes
• Create integration test template documentation in README or docs/ showing how to write exchange-specific integration tests (e.g., fetching real ticker data); currently workflows exist but pattern is not documented for contributors adding new exchanges
• Implement missing getOrderHistory() method stub for exchanges that lack trade history support (check TradeService interface vs. actual implementations)—many modules return 'not supported' but could be added by wrapping existing order endpoints

The XChange project is a financial/cryptocurrency trading library with moderate security posture. Key concerns include: 1) Incomplete dependency visibility in the provided pom.xml prevents full assessment of vulnerable libraries, 2) Multiple exchange authentication modules handle sensitive API credentials requiring secure practices, 3) Snapshot version usage suggests development state, 4) Missing security policy documentation. Strengths

• Medium · Snapshot Version in Production — pom.xml - <version>5.2.5-SNAPSHOT</version>. The project version is set to '5.2.5-SNAPSHOT' in pom.xml, indicating this is a development/snapshot build. Snapshot versions can introduce instability and unexpected changes. Production deployments should use stable release versions. Fix: Use stable release versions for production deployments. Only use SNAPSHOT versions for development and testing environments.
• Medium · Incomplete Dependency Analysis — pom.xml - dependencies section. The pom.xml file provided is truncated and does not show the complete dependency declarations. This prevents full assessment of vulnerable third-party libraries. The project interacts with cryptocurrency exchanges and handles sensitive financial data, requiring careful dependency management. Fix: Review the complete pom.xml to identify all dependencies. Run 'mvn dependency:tree' and use tools like 'mvn dependency-check' to identify known vulnerabilities in dependencies. Keep all dependencies up to date.
• Medium · Potential API Key/Secret Exposure in Service Classes — xchange-ascendex/src/main/java/org/knowm/xchange/ascendex/service/ and similar exchange modules. The codebase includes multiple service classes (AscendexAccountService, AscendexTradeService, etc.) that handle authentication and API keys for cryptocurrency exchanges. If not properly protected, these could expose sensitive credentials. The presence of AscendexDigest suggests cryptographic signing of requests, which requires secure key management. Fix: Ensure all API keys and secrets are: 1) Never logged or exposed in error messages, 2) Stored only in secure configuration files outside the codebase, 3) Loaded from environment variables at runtime, 4) Marked as sensitive in any debugging frameworks. Implement proper credential rotation policies.
• Low · Missing Security Policy Documentation — Repository root. No SECURITY.md or security policy documentation visible in the repository structure, which is important for a library handling financial transactions and cryptocurrency operations. Fix: Create a SECURITY.md file documenting: 1) How to report security vulnerabilities responsibly, 2) Security best practices for users of the library, 3) Known limitations and security considerations, 4) Update frequency and security patching procedures.
• Low · Test Resources Exposure — xchange-ascendex/src/test/resources/. The repository includes test resources with example JSON responses from exchanges (e.g., ascendexOrderbookResponseExample.json, ascendexOpenOrdersResponseExample.json). While these appear to be example data, they should be reviewed to ensure they don't contain real sensitive information. Fix: Ensure all test resources and example files contain only sanitized, non-sensitive data. Use fixtures that are clearly synthetic. Add pre-commit hooks to scan for API keys or real credentials in test files.
• Low · GitHub Workflow Configurations Require Review — .github/workflows/. Multiple GitHub Actions workflows exist for integration testing with various exchanges (bitfinex.yaml, kraken.yaml, etc.). These workflows may require secrets management for API credentials. Fix: Ensure all exchange API credentials used in CI/CD workflows are: 1) Stored as encrypted GitHub Secrets, 2) Never logged in workflow output, 3) Limited to read-only or testing accounts, 4) Rotated regularly. Use GitHub's OIDC token provider when possible instead of long-lived credentials.
• Low · Dependabot Configuration Present — .github/dependabot.yml. While Dependabot configuration exists (.github/dependabot.yml), the specific configuration details are not visible to assess if it's properly configured for security updates. Fix: Ensure dependabot.yml is configured to: 1) Check for security updates weekly or more frequently, 2) Auto-merge security patches when possible, 3) Monitor all package managers (Maven, etc.), 4) Include all modules in the monorepo.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.