CLAUDE.md · ccxt/ccxt

Sections

1. 1. Architecture
2. 2. Source of truth — edit ONLY these
3. 3. NEVER commit edits to generated files
4. 4. Files that are PARTLY hand-written, PARTLY transpiled
5. 5. Testing — TDD-first workflow
6. 6. Build & verify — required after every change
7. 7. Docstrings — required on every public method
8. 8. When you change behaviour, update the user-facing docs
9. 9. TS coding rules to keep the transpilers happy
10. 10. Common contributor questions
11. 11. Pull-request etiquette
12. 12. For AI agents — the rules that catch agents most often
13. 13. Keeping this guide alive
14. 14. Tooling — automated PR review
15. 15. Quick repo map

First lines (shown under the repo's MIT license)

# CCXT — Repository Guide for Contributors and AI Agents

CCXT is a unified cryptocurrency trading library with one source of truth (TypeScript) **transpiled** to JavaScript, Python, PHP, C#, Go, Java and Rust. The most common contributor mistake — especially by AI agents — is editing a generated file or shipping code without tests in all languages.

Authoritative rules: `CONTRIBUTING.md` (transpiler conventions), `wiki/Manual.md` (unified API spec), `wiki/Requirements.md` (new-exchange checklist).

---

## 1. Architecture

### REST vs Pro (WebSocket)

| | REST | Pro (WebSocket) |
|---|---|---|
| Source dir | `ts/src/<exchange>.ts` | `ts/src/pro/<exchange>.ts` |
| Class | `class <exchange> extends Exchange` | `class <exchange> extends <exchange>Rest` |
| Method prefix | `fetch*` (one-shot HTTP) | `watch*` / `unWatch*` (subscribe) |
| Base | `ts/src/base/Exchange.ts` | adds `ts/src/base/ws/{Client,Cache,OrderBook,Future,WsClient}.ts` |
| Transport (JS) | `node-fetch` / browser `fetch` | `ws` npm package |

The pro class imports the REST class as `<exchange>Rest` and extends it. `describe()` deep-extends the REST `describe()` to add `has.watch*` flags and `urls.api.ws`. WS subscriptions go through `client(url)` (one `Client` per URL) and resolve via `Future`s; live updates land in the right `Cache` (`ArrayCacheBySymbolById`, `ArrayCacheByTimestamp`, etc.). Read `ts/src/base/ws/Client.ts` and `ts/src/pro/binance.ts` before editing pro code.

### Per-language model

| Language | Sync | Async | WS transport | Notes |
|---|---|---|---|---|
| TS / JS | n/a | native `async/await` | `ws` / browser `WebSocket` | one ESM module |
| Python | `ccxt.<ex>` | `ccxt.async_support.<ex>` | `aiohttp` + `asyncio` | **sync auto-generated from async** |
| PHP | `ccxt\<ex>` | `ccxt\async\<ex>` | ReactPHP promises | **async auto-generated from sync** |
| C# | n/a | native `Task`/`async` | `System.Net.WebSockets` | PascalCase wrappers in `cs/ccxt/wrappers/` |
| Go | `(value, error)` returns | none | `gorilla/websocket` | three files per exchange: `<ex>.go`, `<ex>_api.go`, `<ex>_wrapper.go` |
| Rust | n/a | native `async` (tokio) | `tokio-tungstenite` | cargo workspace under `rust/`: `ccxt-base` (cores), `ccxt` / `ccxt-pro` / `ccxt-prediction` (typed wrappers) |

### Two transpilers

1. **Regex** — `build/transpile.ts`, `build/transpileWS.ts` → Python and PHP. Brittle; depends on TS formatting.
2. **AST** — `ast-transpiler` npm package, used by `build/csharpTranspiler.ts`, `build/goTranspiler.ts` and `build/rustTranspiler.ts` → C#, Go and Rust. More forgiving.

Code in `ts/src/` must satisfy **both**.

---

## 2. Source of truth — edit ONLY these

- `ts/src/*.ts` — REST exchange implementations
- `ts/src/pro/*.ts` — WS exchange implementations
- `ts/src/base/Exchange.ts` — base class (partly transpiled; see §4)
- `ts/src/base/ws/{Client,Cache,OrderBook,OrderBookSide,Future,WsClient}.ts` — pro base
- `ts/src/base/{errors,errorHierarchy,Precise,types,functions}.ts`
- `ts/src/test/Exchange/test.*.ts` — REST unified-method tests
- `ts/src/test/Exchange/base/test.<structure>.ts` — shared validators (orderBook, ticker, trade, …)
- `ts/src/pro/test/Exchange/test.watch*.ts` — WS unified-method tests
- `ts/src/test/base/**`, `ts/src/pro/test/base/**` — base unit tests
- Static fixtures: `ts/src/test/static/{request,response}/<exchange>.json`

---

## 3. NEVER commit edits to generated files

These are overwritten by the build:

- `js/**` (tsc output)
- `python/ccxt/*.py`, `python/ccxt/async_support/*.py` (per-exchange)
- `python/ccxt/test/tests_sync.py` and any transpiled test
- `php/*.php`, `php/async/*.php`, `php/pro/*.php` (per-exchange)
- `cs/ccxt/exchanges/**`, `cs/ccxt/ws/**`, `cs/ccxt/api/**`, `cs/ccxt/wrappers/**`
- `cs/ccxt/base/Exchange.BaseMethods.cs` (generated portion only)
- `go/v4/*.go` and `go/v4/pro/*.go` (every per-exchange Go file)
- `rust/**` — the whole generated tree is gitignored and rebuilt by `rust.yml` on every run (only `binance` is kept in git as the reference venue)
- `ts/src/abstract/*.ts` (emitted from each exchange's `api` block)
- `dist/**`, `build/ccxt.wiki`, `index.d.cts`
- `README.md` exchange tables, `wiki/Exchange-Markets*.md`
- `python/{README.md,LICENSE.txt,keys.json,package.json}` (copies)
- `package.json` version bumps (use `npm run vss`)

Generated files start with `// PLEASE DO NOT EDIT THIS FILE, IT IS GENERATED AND WILL BE OVERWRITTEN`. If you see it, find the TS source.

The per-language base type files are generated from `ts/src/base/types.ts` by `npm run transpile-types`: `python/ccxt/base/types.py`, `cs/ccxt/base/{Exchange.Types.cs,PredictionTypes.cs}`, `go/v4/exchange_types.go` and `java/lib/src/main/java/io/github/ccxt/types/*.java`. Edit `ts/src/base/types.ts`, then regenerate — CI runs `npm run transpile-types-check` and fails if they drifted. PHP has no type file (unified structures are plain arrays) and `js/` is `tsc` output.

---

## 4. Files that are PARTLY hand-written, PARTLY transpiled

The base `Exchange` class in each language has a delimiter. Everything **below** is regenerated from `ts/src/base/Exchange.ts`; everything **above** is hand-written (HTTP client, polyfills, crypto).

Marker: `METHODS BELOW THIS LINE ARE TRANSPILED FROM TYPESCRIPT`

| File | Marker (~line) | Above the marker |
|---|---|---|
| `python/ccxt/base/exchange.py` | 2547 | sync HTTP client, polyfills |
| `python/ccxt/async_support/base/exchange.py` | 680 | aiohttp client, asyncio glue |
| `php/Exchange.php` | 2771 | curl HTTP client, PHP polyfills |
| `php/async/Exchange.php` | 411 | ReactPHP HTTP client |

C#: only `cs/ccxt/base/Exchange.BaseMethods.cs` and the type files `cs/ccxt/base/{Exchange.Types.cs,PredictionTypes.cs}` are generated. Other `cs/ccxt/base/Exchange.*.cs` are hand-written. Behavioural changes go in `ts/src/base/Exchange.ts`, not per-language base files.

### Hand-written base files (safe to edit)

- `python/ccxt/base/{errors,precise,decimal_to_precision}.py`
- `python/ccxt/async_support/base/{throttler.py, ws/*.py}` + top of `exchange.py`
- `php/{<ErrorName>.php, Precise.php, Throttler.php}`, `php/static_dependencies/**`, `php/pro/{Client.php, ArrayCache*.php, OrderBook.php, BaseCache.php}`, top of `php/Exchange.php`
- `cs/ccxt/base/Exchange.*.cs` (except `BaseMethods.cs` and `Exchange.Types.cs`), `cs/ccxt/static/**`, `cs/ccxt/ws/{Client,ArrayCache,Future,OrderBook}.cs`
- Go base lives outside `go/v4/` (in separate base packages — confirm via imports in `go/v4/<exchange>.go`)

---

## 5. Testing — TDD-first workflow

**Default rule: every new method or behaviour change ships with a test.** Adding code without a test needs justification in the PR.

### 5.1 Test layers

| Layer | Source | Offline? | When |
|---|---|---|---|
| Base unit (REST) | `ts/src/test/base/test.*.ts` | yes | base utility changed |
| Base unit (WS) | `ts/src/pro/test/base/test.{cache,orderBook,close}.ts` | yes | `ts/src/base/ws/*` changed |
| Unified-method | `ts/src/test/Exchange/test.<method>.ts` (+ `pro/test/Exchange/test.watch<method>.ts`) | yes | new unified method / return shape changed |
| Structure validators | `ts/src/test/Exchange/base/test.<structure>.ts` | yes | unified return structure changed |
| Static request | `ts/src/test/static/request/<exchange>.json` | yes | exchange request URL/body changed |
| Static response | `ts/src/test/static/response/<exchange>.json` | yes | exchange response parsing changed |
| Static WS | `ts/src/test/static/ws/<exchange>.json` | yes | ws message handling / watch* parsing changed — replays canned frames into `handleMessage` via a mocked transport and asserts the watch result (`npm run ws-tests-<lang>`, entry needs the exact client `url`) |
| ID tests | `api` block | yes | new endpoints added |
| Live | real exchange | NO | smoke-check before merge; never primary gate |

### 5.2 TDD loop

1. Write/extend the test first (`ts/src/test/...` or static JSON fixture).
2. Edit `ts/src/`.
3. Fast verify: `npm run tsBuild && npm run lint`.
4. Offline tests in JS first (cheapest): `npm run test-base-rest-js`, `id-tests-js`, `request-js`, `response-js`.
5. Once green in JS, transpile and run in every other language (see §6).
6. Only after all five langs pass offline, run a live test: `node run-tests <exchange> --js` (and `--ws` if relevant).

A test passing only in TS means nothing — the regex transpiler can silently mangle code that compiles in TS, and AST-transpiled C#/Go can diverge on edge cases.

### 5.3 Static fixture workflow

Primary regression net for per-exchange behaviour. Regenerated via CLI:

```bash
npm run cli.ts -- <exchange> <method> <args...> --request    # request entry
npm run cli.ts -- <exchange> <method> <args...> --response   # response entry
```

Paste output into `methods.<methodName>` array of the respective JSON, then re-run:

```bash
npm run request-tests        # all langs
npm run response-tests       # all langs
# per-lang: npm run request-js/-py/-php/-cs/-go (same for response-*)
```

### 5.4 Per-language unified-method test entry points

| Lang | Entry | Lang | Entry |
|---|---|---|---|
| TS | `npm run ti-ts` | PHP | `npm run ti-php` (sync via `--sync`) |
| JS | `npm run ti-js` | C# | `npm run ti-cs` |
| Python | `npm run ti-py` (sync via `--sync`) | Go | `npm run ti-go` |