new-exchange — Claude Code skill: add an exchange to CCXT
new-exchange scaffolds a new cryptocurrency exchange integration in CCXT on TypeScript, following the certified-exchange template.
MIT 134 installs ★ 44,950 updated 2026-10-24
npx skills add ccxt/ccxt --skill new-exchange -a claude-codeWhat new-exchange does
The skill walks through the exchange module structure: the describe() method with capability flags and rate limits, unified methods (fetchMarkets, fetchTicker, createOrder), API response parsers, the sign() function for request authentication, and handleErrors() for exception mapping. It starts by copying a similar exchange from ts/src/ (Binance, OKX, Kraken) and adapting it to the new API. The skill prompts you to run npm run emitAPITs after declaring endpoints to generate types under ts/src/abstract/, and requires JSDoc on every public method for automatic documentation builds.
Inputs: exchange ID, name, API documentation URL, testnet availability. For WebSocket support the skill points to ts/src/pro/ and references like binance.ts. Without Node.js and a cloned CCXT repository the skill is useless.
What it helps with
- Scaffold a new CCXT exchange module from the certified-exchange template
- Pick a reference exchange (spot, futures, derivatives, on-chain)
- Set up
describe()with capability flags and credentials - Implement parsers for markets, tickers, orders and balance
- Sign requests in
sign()without external libraries
Example prompts for the agent
- Create an integration for
mynewexexchange based on Kraken, spot only - Add Hyperliquid Pro exchange under
ts/src/pro/, usebinance.tsas reference - Generate types after declaring API endpoints with
npm run emitAPITs
How to install new-exchange
1Skills CLI (Vercel)
npx skills add ccxt/ccxt --skill new-exchange -a claude-code2Manually: put the files in place
~/.claude/skills/new-exchange/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/new-exchange/
1Skills CLI (Vercel)
npx skills add ccxt/ccxt --skill new-exchange -a codex2Manually: put the files in place
.agents/skills/new-exchange/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ccxt/ccxt --skill new-exchange -a cursor2Manually: put the files in place
.cursor/skills/new-exchange/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ccxt/ccxt .claude/skills/new-exchange2Manually: put the files in place
.github/skills/new-exchange/SKILL.md1Skills CLI (Vercel)
npx skills add ccxt/ccxt --skill new-exchange -a gemini-cli2Platform CLI
gemini skills install https://github.com/ccxt/ccxt --path .claude/skills/new-exchangeManually: put the files in place
.devin/skills/new-exchange/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ccxt/ccxt --skill new-exchange -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about new-exchange
How to install new-exchange in Claude Code?
Run npx skills add ccxt/ccxt --skill new-exchange -a claude-code, then open ~/.claude/skills/new-exchange/SKILL.md.
What does the new-exchange skill do?
It scaffolds a cryptocurrency exchange integration in CCXT on TypeScript: module structure, unified methods, API parsers, request signing and error handling, following the certified-exchange template.
Which exchange should I use as a reference for spot-only integration?
The skill recommends ts/src/kraken.ts or ts/src/coinbase.ts for spot-only exchanges; binance.ts or okx.ts for spot + futures; bybit.ts for derivatives.
Source text
SKILL.md · MIT
---
name: new-exchange
description: Scaffold a new CCXT exchange integration in TypeScript, following the certified-exchange template. Walks through describe(), required unified methods, parsers, capability flags, sandbox setup, and static fixtures. Use when adding support for an exchange that does not exist yet under ts/src/.
---
# New Exchange Integration
Scaffold a new exchange in `ts/src/<id>.ts` (REST) and optionally `ts/src/pro/<id>.ts` (WebSocket).
> **Read first:** `wiki/Requirements.md` (mandatory unified methods) and `CONTRIBUTING.md` (transpiler rules). The CCXT root `CLAUDE.md` is the contributor guide.
## Inputs
- `<id>`: lowercase exchange id, no separators (e.g. `mynewex`)
- `<Name>`: human-readable name (e.g. `My New Exchange`)
- API docs URL(s)
- Whether the exchange has a testnet/sandbox
## Step 1 — Pick a reference exchange
Don't write from scratch. Copy a similar exchange that's already certified and adapt it.
| Style | Reference |
|---|---|
| Spot + futures, signed REST | `ts/src/binance.ts`, `ts/src/okx.ts` |
| Spot only | `ts/src/kraken.ts`, `ts/src/coinbase.ts` |
| Derivatives focus | `ts/src/bybit.ts`, `ts/src/hyperliquid.ts` |
| Decentralised / on-chain signing | `ts/src/hyperliquid.ts`, `ts/src/dydx.ts` |
| WebSocket reference | `ts/src/pro/binance.ts`, `ts/src/pro/okx.ts` |
Open the reference next to your new file and pattern-match — never invent new conventions.
## Step 2 — Create `ts/src/<id>.ts`
Skeleton:
```ts
import Exchange from './abstract/<id>.js';
import { /* errors needed */ } from './base/errors.js';
import { Precise } from './base/Precise.js';
import type { /* types needed */ } from './base/types.js';
export default class <id> extends Exchange {
describe (): any {
return this.deepExtend (super.describe (), {
'id': '<id>',
'name': '<Name>',
'countries': [ 'XX' ],
'rateLimit': 1000, // ms between requests
'version': 'v1',
'certified': false,
'pro': false, // flip to true when pro/<id>.ts exists
'has': {
// start everything false; flip to true as you implement
'CORS': undefined,
'spot': true,
'margin': false,
'swap': false,
'future': false,
'option': false,
'fetchMarkets': true,
'fetchCurrencies': true,
'fetchTicker': true,
'fetchTickers': false,
'fetchOrderBook': true,
'fetchTrades': true,
'fetchOHLCV': false,
'fetchBalance': true,
'createOrder': true,
'cancelOrder': true,
'fetchOrder': true,
'fetchOpenOrders': true,
'fetchOrders': false,
'fetchClosedOrders': false,
'fetchMyTrades': true,
'fetchDeposits': false,
'fetchWithdrawals': false,
'withdraw': false,
},
'urls': {
'logo': 'https://...',
'api': {
'public': 'https://api.<id>.com',
'private': 'https://api.<id>.com',
},
'test': { // OPTIONAL — only if testnet exists
'public': 'https://testnet.<id>.com',
'private': 'https://testnet.<id>.com',
},
'www': 'https://<id>.com',
'doc': [ 'https://docs.<id>.com' ],
'fees': 'https://<id>.com/fees',
},
'api': {
'public': {
'get': [
'symbols',
'ticker/{pair}',
'orderbook/{pair}',
],
},
'private': {
'get': [ 'account', 'orders' ],
'post': [ 'order' ],
'delete': [ 'order/{id}' ],
},
},
'requiredCredentials': {
'apiKey': true,
'secret': true,
// 'password': true, // for passphrase-based exchanges
// 'walletAddress': true, // for on-chain
// 'privateKey': true,
},
'fees': {
'trading': {
'tierBased': false,
'percentage': true,
'maker': 0.001,
'taker': 0.001,
},
},
'precisionMode': /* TICK_SIZE | DECIMAL_PLACES | SIGNIFICANT_DIGITS */,
'options': {
// exchange-specific defaults
},
'exceptions': {
'exact': {
// 'ERROR_CODE': BadRequest,
},
'broad': {
// 'invalid signature': AuthenticationError,
},
},
});
}
// implement the unified methods you flipped on in `has`
async fetchMarkets (params = {}): Promise<Market[]> { /* ... */ }
parseMarket (market: Dict): Market { /* ... */ }
async fetchTicker (symbol: string, params = {}): Promise<Ticker> { /* ... */ }
parseTicker (ticker: Dict, market: Market = undefined): Ticker { /* ... */ }
// ...
sign (path, api = 'public', method = 'GET', params = {}, headers = undefined, body = undefined) {
// build URL, sign request — use this.hmac, this.jwt, this.ecdsa, never external libs
}
handleErrors (httpCode, reason, url, method, headers, body, response, requestHeaders, requestBody) {
// throw the right exception based on response
}
}
```
## Step 3 — Define implicit API methods
URLs in the `api` block become methods automatically:
- `'symbols'` → `this.publicGetSymbols(params)`
- `'ticker/{pair}'` → `this.publicGetTickerPair({ pair: market['id'] })`
- `'orders'` under `private.get` → `this.privateGetOrders(params)`
Don't write explicit HTTP wrappers. After listing the URL in `api`, run `npm run emitAPITs` to regenerate `ts/src/abstract/<id>.ts` (the auto-typed declarations).
## Step 4 — Docstrings on every public method
Every public method needs a JSDoc block. The transpilers convert it to native docstrings in Python/PHP/C#/Go, and `npm run build-docs` produces wiki entries from them. Pattern:
```ts
/**
* @method
* @name <id>#fetchMyTrades
* @description fetches all completed trades made by the user
* @see https://docs.<id>.com/api/trades // spot
* @see https://docs.<id>.com/api/derivatives/trades // swap
* @param {string} symbol unified market symbol
* @param {int} [since] earliest timestamp in ms
* @param {int} [limit] maximum number of trades to return
* @param {object} [params] extra parameters specific to the exchange API endpoint
* @param {int} [params.until] latest timestamp in ms
* @returns {object[]} a list of [trade structures](https://docs.ccxt.com/#/?id=trade-structure)
*/
async fetchMyTrades (symbol: Str = undefined, since: Int = undefined, limit: Int = undefined, params = {}): Promise<Trade[]> {
// ...
}
```
Rules: lowercase `@description`, `@param {object} [params]` always present, document every `params.<key>` you read in the body, link `@returns` to the manual structure. See CLAUDE.md §7 for the full ruleset.
## Step 5 — Required parsers
For every fetch method, write a matching parser. The parser is what makes output uniform across all exchanges:
| Fetch method | Parser | Validator (test) |
|---|---|---|
| `fetchMarkets` | `parseMarket` | `ts/src/test/Exchange/base/test.market.ts` |
| `fetchCurrencies` | `parseCurrency` | `test.currency.ts` |
| `fetchTicker` | `parseTicker` | `test.ticker.ts` |
| `fetchOrderBook` | base `parseOrderBook` | `test.orderBook.ts` |
| `fetchTrades`, `fetchMyTrades` | `parseTrade` | `test.trade.ts` |
| `fetchOHLCV` | `parseOHLCV` | `test.ohlcv.ts` |
| `fetchBalance` | `parseBalance` | `test.balance.ts` |
| `createOrder`, `fetchOrder`, `fetchOpenOrders` | `parseOrder` | `test.order.ts` |
| `fetchPositions` | `parsePosition` | `test.position.ts` |
**Parsing rules** (also in CLAUDE.md §7):
- Always `safeString` first, parse with `Precise` for math, finalise with `parseNumber` only at the return.
- Symbol resolution: `this.safeSymbol(marketId, market)` — never put exchange-specific ids into unified output.
- Time: convert seconds → ms using `safeTimestamp`; everything in unified output is ms.
## Step 6 — Static fixtures (TDD)
Capture a request/response fixture as soon as a method works once. Re-run on every change.
> 🚨 **Never hand-write or invent a static fixture — always capture it with the CLI.**
> `--static` performs a **real** call and records the actual URL, body and HTTP response. A fabricated fixture
> asserts what you *assumed* the exchange does, so the test goes green while the integration is broken — and it
> then becomes the reference every language is verified against. If you cannot reach the endpoint (no
> credentials, geo-block, venue down), ship no fixture and say so explicitly; do not guess one.
```bash
# capture BOTH the request and the response entry from one live call, and save them
npm run cli.ts -- <id> fetchTicker BTC/USDT --static --name "spot ticker"
```
`--static` writes a `methods.fetchTicker` entry into both `ts/src/test/static/request/<id>.json` and
`ts/src/test/static/response/<id>.json`. Details:
- **`--name "…"` auto-saves.** Without it the two entries are only printed, so you can review before saving.
- `--request` / `--response` capture just one side; `--static` is both.
- **`watch*` methods:** `--static` records ws frames until you press ctrl+c and writes a
`ts/src/test/static/ws/<id>.json` entry. `--recordLimit <n>` keeps only the first n resolutions.
- Prediction exchanges land in the `static/{request,response}/prediction/` subfolder automatically.
Then run:
```bash
npm run request-tests
npm run response-tests
```
The *capture* hits the network; the *tests* replay the recording with no HTTP, in every language, and are your
primary regression net.
## Step 7 — Verify in all languages
A new exchange means thousands of new lines in Python, PHP, C#, Go and Java. The transpilers must like all of it.
```bash
npm run lint
npm run tsBuild
npm run transpile # → Python, PHP
npm run transpileCS # → C#
npm run buildCS
npm run transpileGO # → Go
npm run buildGO
npm run check-python-syntax
npm run check-php-syntax
npm run id-tests
npm run request-tests
npm run response-tests
```
Then a live smoke test on at least one public method per language:
```bash
npm run cli.ts -- <id> fetchTicker BTC/USDT --verbose
npm run cli.py -- <id> fetchTicker BTC/USDT --verbose
npm run cli.php -- <id> fetchTicker BTC/USDT --verbose
npm run cli.cs -- <id> fetchTicker BTC/USDT --verbose
npm run cli.go -- <id> fetchTicker BTC/USDT --verbose
```
## Step 8 — WebSocket support (optional)
If the exchange has WS, create `ts/src/pro/<id>.ts`. It must `extends <id>Rest` and add `watch*` methods. Reference: `ts/src/pro/binance.ts`. Flip `'pro': true` in REST `describe()`.
## Step 9 — Update user-facing docs
A new exchange means new public surface area. Update the touchpoints listed in CLAUDE.md §8:
- `wiki/Manual.md` doesn't usually list per-exchange specifics, but add a section if your exchange introduces a new pattern (e.g. a new auth scheme, new params).
- Verify `examples/ts/<id>-example.ts` has at least one runnable snippet (transpiled to other languages by `npm run tsBuildExamples`).
- The end-user skills under `.claude/skills/ccxt-{typescript,python,php,csharp,go}/` mention "all 100+ exchanges" — usually no edit needed unless your exchange has unique credential requirements (e.g. wallet/private key) worth calling out.
- `npm run build-docs` regenerates wiki entries from your JSDoc — run it once and inspect the output.
## Step 10 — PR
Title: `feat(<id>): add <Name> integration`. Description follows the template in CLAUDE.md §11 — list every test you ran with results, and reference any related issue/PR.
## Output checklist
- [ ] `ts/src/<id>.ts` written (uses Precise, safeString*, safeSymbol)
- [ ] **Every public method has a JSDoc block** (CLAUDE.md §7)
- [ ] `'has'` flags accurately reflect implemented methods
- [ ] `'urls.test'` set if exchange has a testnet
- [ ] `'requiredCredentials'` matches what `sign()` actually uses
- [ ] All required parsers (`parseMarket`, `parseTicker`, `parseTrade`, `parseOrder`, …)
- [ ] `handleErrors` maps exchange error codes to CCXT exception classes
- [ ] `ts/src/abstract/<id>.ts` regenerated via `npm run emitAPITs`
- [ ] Static request + response fixtures for every implemented method
- [ ] `npm run lint && npm run tsBuild && npm run transpile && npm run transpileCS && npm run transpileGO` all pass
- [ ] `npm run id-tests && npm run request-tests && npm run response-tests` all pass
- [ ] Live smoke tested in TS + at least one transpiled language (`cli.py`, `cli.cs`, `cli.go`, …) with `--verbose`
- [ ] `npm run build-docs` ran, generated wiki entries look correct
- [ ] User-facing docs reviewed (CLAUDE.md §8) — Manual.md / examples / language skills if anything is non-standard
- [ ] PR title follows `feat(<id>): ...`; description fills CLAUDE.md §11 template
---
## Prediction-market exchange variant
A prediction-market venue (Polymarket-style: events → markets → binary/categorical outcomes) does **not** extend `Exchange` — it lives in its own namespace. The differences from the checklist above:
1. **File** — `ts/src/prediction/<id>.ts`, `class <id> extends PredictionExchange` (import `Exchange` from `./abstract/prediction/<id>.js`). Read `.claude/rules/prediction-outcomes.md` for the outcome-cache contract and `ts/src/base/PredictionExchange.ts` for the base helpers you inherit (`loadOutcome`/`loadOutcomes`/`fetchOutcome`/`populateOutcomes`/`indexMarketOutcomes`/`safeOutcome`/`outcome`, `setEvents`/`getEvent`/`eventsList`/`applyEventFetchParams`, `parsePredictionTrades`/`parsePredictionOrders`/`parsePredictionPositions`, `safePrediction*`).
2. **describe()** — `has.prediction: true`; address methods by an `outcome` handle, not a `symbol`. Implement `fetchEvents(params)` (scope-required via `requireEventQuery`) and, if the venue has a single-event endpoint, `fetchEvent(id)`. Return `Prediction*` types from `ts/src/base/types.ts` (never base `Ticker`/`Order`/…). `loadAllOutcomes` defaults to `false` (a cache miss resolves one outcome via the base search-backed `fetchOutcome`); override `fetchOutcome` with a by-id fetch when the venue has one (see kalshi), and set `loadAllOutcomes: true` only when the whole universe is a single cheap request (see hyperliquid). No-arg `fetchTickers()` must throw `ArgumentsRequired` unless the venue has a true all-tickers endpoint.
3. **Never call the base `parseTrades`/`parseOrders`/`parsePositions`** — they filter by `symbol` and drop prediction rows. Use `parsePredictionTrades`/`Orders`/`Positions`. Never call `buildOHLCVC` (transpiles to a mangled name) — bucket candles inline.
4. **Registration** — `npm run export-exchanges` adds the id to `exchanges.json` `prediction[]` and wires `ts/ccxt.ts` / the per-language namespaces / README table. `npm run emitAPI` emits `ts/src/abstract/prediction/<id>.ts`. Add a `skip-tests.json` entry with `preferredEventQuery` (the harness's fetchEvents scope) and `preferredPredictionOutcome` (a tradeable handle — validated against the live listing).
5. **Transpile** — the scoped single-exchange transpilers auto-route a bare prediction-only id (`tsx build/transpile.ts <id>`, `csharpTranspiler.ts <id>`, `goTranspiler.ts <id>`). After editing `PredictionExchange.ts` you must also regen the base per language: `tsx build/{transpile,csharpTranspiler,goTranspiler,javaTranspiler}.ts --baseClass`. Any base→override call (like `fetchOutcome`) must be registered in `VIRTUAL_BASE_METHODS` in `build/goTranspiler.ts` or Go won't dispatch it.
6. **Test** — `node run-tests <id> --js --prediction --private` (add `--sandbox` for demo hosts like kalshi). Static fixtures live in the normal flat `ts/src/test/static/{request,response}/<id>.json`; the python/php **sync** harness skips prediction (they carry `"asyncOnly": true`).
© ccxt · MIT · ccxt/ccxt