The ccxt library is a collection of available cryptoexchanges or exchange classes. Each class implements the public and private API for a particular crypto exchange. All exchanges are derived from the base Exchange class and share a set of common methods. To access a particular exchange from ccxt library you need to create an instance of corresponding exchange class. Supported exchanges are updated frequently and new exchanges are added regularly.

The structure of the library can be outlined as follows:

                                 User    +-------------------------------------------------------------+    |                            CCXT                             |    +------------------------------+------------------------------+    |            Public            |           Private            |    +=============================================================+    │                              .                              |    │                    The Unified CCXT API                     |    │                              .                              |    |       loadMarkets            .           fetchBalance       |    |       fetchMarkets           .            createOrder       |    |       fetchCurrencies        .            cancelOrder       |    |       fetchTicker            .             fetchOrder       |    |       fetchTickers           .            fetchOrders       |    |       fetchOrderBook         .        fetchOpenOrders       |    |       fetchOHLCV             .      fetchClosedOrders       |    |       fetchStatus            .          fetchMyTrades       |    |       fetchTrades            .                deposit       |    |                              .               withdraw       |    │                              .                              |    +=============================================================+    │                              .                              |    |                     Custom Exchange API                     |    |         (Derived Classes And Their Implicit Methods)        |    │                              .                              |    |       publicGet...           .          privateGet...       |    |       publicPost...          .         privatePost...       |    |                              .          privatePut...       |    |                              .       privateDelete...       |    |                              .                   sign       |    │                              .                              |    +=============================================================+    │                              .                              |    |                      Base Exchange Class                    |    │                              .                              |    +=============================================================+

Full public and private HTTP REST APIs for all exchanges are implemented. WebSocket implementations in JavaScript, PHP, Python are available inCCXT Pro, which is a professional addon to CCXT with support for WebSocket streams.

• Exchanges
• Markets
• Implicit API
• Unified API
• Public API
• Private API
• Error Handling
• Troubleshooting
• CCXT Pro

• Follow us on Twitter
• Read our blog on Medium
• Join our Discord
• CCXT Chat on Telegram (technical support)
• Announcement channels:
• • 
• • 

• Instantiation
• Exchange Structure
• Rate Limit

logo	id	name	ver	type	certified	pro
	alpaca	Alpaca
	apex	Apex
	ascendex	AscendEX
	bequant	Bequant
	bigone	BigONE
	binance	Binance
	binancecoinm	Binance COIN-M
	binanceus	Binance US
	binanceusdm	Binance USDⓈ-M
	bingx	BingX
	bit2c	Bit2C
	bitbank	bitbank
	bitbns	Bitbns
	bitfinex	Bitfinex
	bitflyer	bitFlyer
	bitget	Bitget
	bithumb	Bithumb
	bitmart	BitMart
	bitmex	BitMEX
	bitopro	BitoPro
	bitrue	Bitrue
	bitso	Bitso
	bitstamp	Bitstamp
	bitteam	BIT.TEAM
	bittrade	BitTrade
	bitvavo	Bitvavo
	blockchaincom	Blockchain.com
	blofin	BloFin
	btcalpha	BTC-Alpha
	btcbox	BtcBox
	btcmarkets	BTC Markets
	btcturk	BTCTurk
	bybit	Bybit
	cex	CEX.IO
	coinbase	Coinbase Advanced
	coinbaseexchange	Coinbase Exchange
	coinbaseinternational	Coinbase International
	coincatch	CoinCatch
	coincheck	coincheck
	coinex	CoinEx
	coinmate	CoinMate
	coinmetro	Coinmetro
	coinone	CoinOne
	coinsph	Coins.ph
	coinspot	CoinSpot
	cryptocom	Crypto.com
	cryptomus	Cryptomus
	defx	Defx X
	delta	Delta Exchange
	deribit	Deribit
	derive	derive
	digifinex	DigiFinex
	ellipx	Ellipx
	exmo	EXMO
	fmfwio	FMFW.io
	gate	Gate.io
	gemini	Gemini
	hashkey	HashKey Global
	hitbtc	HitBTC
	hollaex	HollaEx
	htx	HTX
	hyperliquid	Hyperliquid
	independentreserve	Independent Reserve
	indodax	INDODAX
	kraken	Kraken
	krakenfutures	Kraken Futures
	kucoin	KuCoin
	kucoinfutures	KuCoin Futures
	latoken	Latoken
	lbank	LBank
	luno	luno
	mercado	Mercado Bitcoin
	mexc	MEXC Global
	modetrade	Mode Trade
	myokx	MyOKX (EEA)
	ndax	NDAX
	novadax	NovaDAX
	oceanex	OceanEx
	okcoin	OKCoin
	okx	OKX
	okxus	OKX (US)
	onetrading	One Trading
	oxfun	OXFUN
	p2b	p2b
	paradex	Paradex
	paymium	Paymium
	phemex	Phemex
	poloniex	Poloniex
	probit	ProBit
	timex	TimeX
	tokocrypto	Tokocrypto
	tradeogre	tradeogre
	upbit	Upbit
	vertex	Vertex
	wavesexchange	Waves.Exchange
	whitebit	WhiteBit
	woo	WOO X
	woofipro	WOOFI PRO
	xt	XT
	yobit	YoBit
	zaif	Zaif
	zonda	Zonda

Besides making basic market and limit orders, some exchanges offer margin trading (leverage), various derivatives (like futures contracts and options) and also havedark pools,OTC (over-the-counter trading), merchant APIs and much more.

To connect to an exchange and start trading you need to instantiate an exchange class from ccxt library.

To get the full list of ids of supported exchanges programmatically:

constccxt=require('ccxt')console.log(ccxt.exchanges)

importccxtprint (ccxt.exchanges)

include'ccxt.php';var_dump (\ccxt\Exchange::$exchanges);

An exchange can be instantiated like shown in the examples below:

constccxt=require('ccxt')letexchange=newccxt.kraken()// default idletkraken1=newccxt.kraken({id:'kraken1'})letkraken2=newccxt.kraken({id:'kraken2'})letid='coinbasepro'letcoinbasepro=newccxt[id]();// from variable idconstexchangeId='binance',exchangeClass=ccxt[exchangeId],exchange=newexchangeClass({'apiKey':'YOUR_API_KEY','secret':'YOUR_SECRET',})

importccxtexchange=ccxt.okcoin ()# default idokcoin1=ccxt.okcoin ({'id':'okcoin1' })okcoin2=ccxt.okcoin ({'id':'okcoin2' })id='btcchina'btcchina=eval ('ccxt.%s ()'%id)coinbasepro=getattr (ccxt,'coinbasepro') ()# from variable idexchange_id='binance'exchange_class=getattr(ccxt,exchange_id)exchange=exchange_class({'apiKey':'YOUR_API_KEY','secret':'YOUR_SECRET',})

The ccxt library in PHP uses builtin UTC/GMT time functions, therefore you are required to set date.timezone in your php.ini or calldate_default_timezone_set() function before using the PHP version of the library. The recommended timezone setting is"UTC".

// PHPdate_default_timezone_set('UTC');include'ccxt.php';$bitfinex =new \ccxt\bitfinex();// default id$bitfinex1 =new \ccxt\bitfinex(array('id' =>'bitfinex1'));$bitfinex2 =new \ccxt\bitfinex(array('id' =>'bitfinex2'));$id ='kraken';$exchange ='\\ccxt\\' .$id;$kraken =new$exchange();// from variable id$exchange_id ='binance';$exchange_class ="\\ccxt\\$exchange_id";$exchange =new$exchange_class(array('apiKey' =>'YOUR_API_KEY','secret' =>'YOUR_SECRET',));

Major exchanges have the.features property available, where you can see what methods and functionalities are supported for each market-type (if any method is set tonull/undefined it means method is "not supported" by the exchange)

this feature is currently a work in progress and might be incomplete, feel free to report any issues you find in it

constexchange=newccxt.binance()console.log(exchange.features);// outputs like:{spot:{sandbox:true,// whether testnet is supportedcreateOrder:{triggerPrice:true,// if trigger order is supportedtriggerPriceType:undefined,// if trigger price type is supported (last, mark, index)triggerDirection:false,// if trigger direction is supported (up, down)stopLossPrice:true,// if stop-loss order is supported (read "Stop Loss Orders" paragraph)takeProfitPrice:true,// if take-profit order is supportedattachedStopLossTakeProfit:{triggerPriceType:{last:true,mark:true,index:true,},price:true,// whether 'limit' price can be used (instead of market order)},marginMode:true,// if `marginMode` param is supported (cross, isolated)timeInForce:{// supported TIF typesGTC:true,IOC:true,FOK:true,PO:true,GTD:false},hedged:false,// if `hedged` param is supported (true, false)leverage:false,// if `leverage` param is supported (true, false)selfTradePrevention:true,// if `selfTradePrevention` param is supported (true, false)trailing:true,// if trailing order is supportediceberg:true,// if iceberg order is supportedmarketBuyByCost:true,// if creating market buy order is possible with `cost` parammarketBuyRequiresPrice:true,// if creating market buy order (if 'cost' not used) requires `price` param to be set},createOrders:{'max':50,// if batch order creation is supported},fetchMyTrades:{limit:1000,// max limit per calldaysBack:undefined,// max historical period that can be accesseduntilDays:1// if `until` param is supported, then this is permitted distance from `since`},fetchOrder:{marginMode:true,// when supported, margin order should be fetched with this flagtrigger:false,// similar as abovetrailing:false// similar as above},// other methods have similar propertiesfetchOpenOrders:{limit:undefined,marginMode:true,trigger:false,trailing:false},fetchOrders:{limit:1000,daysBack:undefined,untilDays:10000,marginMode:true,trigger:false,trailing:false},fetchClosedOrders:{limit:1000,daysBackClosed:undefined,// max days-back for closed ordersdaysBackCanceled:undefined,// max days-back for canceled ordersuntilDays:10000,marginMode:true,trigger:false,trailing:false},fetchOHLCV:{paginate:true,limit:1000}},swap:{linear:{ ...},// similar to above dictinverse:{ ...},// similar to above dict}future:{linear:{ ...},// similar to above dictinverse:{ ...},// similar to above dict}}

Most of exchange properties as well as specific options can be overrided upon exchange class instantiation or afterwards, like shown below:

constexchange=newccxt.binance({'rateLimit':10000,// unified exchange property'headers':{'YOUR_CUSTOM_HTTP_HEADER':'YOUR_CUSTOM_VALUE',},'options':{'adjustForTimeDifference':true,// exchange-specific option}})exchange.options['adjustForTimeDifference']=false

exchange=ccxt.binance ({'rateLimit':10000,# unified exchange property'headers': {'YOUR_CUSTOM_HTTP_HEADER':'YOUR_CUSTOM_VALUE',    },'options': {'adjustForTimeDifference':True,# exchange-specific option    }})exchange.options['adjustForTimeDifference']=False

$exchange_id ='binance';$exchange_class ="\\ccxt\\$exchange_id";$exchange =new$exchange_class(array('rateLimit' =>10000,// unified exchange property'headers' =>array('YOUR_CUSTOM_HTTP_HEADER' =>'YOUR_CUSTOM_VALUE',    ),'options' =>array('adjustForTimeDifference' =>true,// exchange-specific option    ),));$exchange->options['adjustForTimeDifference'] =false;

In all CCXT-supported languages, you can override instance methods during runtime:

constex=newccxt.binance();ex.fetch_ticker=function(symbol,params={}){// your codes go here};console.log(ex.fetch_ticker('BTC/USDT'));

ex=ccxt.binance()defmy_overload(symbol,params= {}):# your codes go hereex.fetch_ticker=my_overloadprint(ex.fetch_ticker('BTC/USDT'))

$ex =new \ccxt\binance();$ex->add_method('fetch_ticker',function($symbol,$params = []) {// your codes go here});var_dump($ex->call_method('fetch_ticker', ['BTC/USDT']));

Some exchanges also offer separate APIs for testing purposes that allows developers to trade virtual money for free and test out their ideas. Those APIs are called"testnets", "sandboxes" or "staging environments" (with virtual testing assets) as opposed to"mainnets" and "production environments" (with real assets). Most often a sandboxed API is a clone of a production API, so, it's literally the same API, except for the URL to the exchange server.

CCXT unifies that aspect and allows the user to switch to the exchange's sandbox (if supported by the underlying exchange).To switch to the sandbox one has to call theexchange.setSandboxMode (true) orexchange.set_sandbox_mode(true)immediately after creating the exchange before any other call!

constexchange=newccxt.binance(config)exchange.setSandboxMode(true)// enable sandbox mode

exchange=ccxt.binance(config)exchange.set_sandbox_mode(True)# enable sandbox mode

$exchange =new \ccxt\binance($config);$exchange->set_sandbox_mode(true);// enable sandbox mode

• Theexchange.setSandboxMode (true) / exchange.set_sandbox_mode (True) has to be your first call immediately after creating the exchange (before any other calls)
• To obtain theAPI keys to the sandbox the user has to register with the sandbox website of the exchange in question and create a sandbox keypair
• Sandbox keys are not interchangeable with production keys!

Every exchange has a set of properties and methods, most of which you can override by passing an associative array of params to an exchange constructor. You can also make a subclass and override everything.

Here's an overview of generic exchange properties with values added for example:

{'id':'exchange'// lowercase string exchange id'name':'Exchange'// human-readable string'countries':['US','CN','EU'],// array of ISO country codes'urls':{'api':'https://api.example.com/data',// string or dictionary of base API URLs'www':'https://www.example.com'// string website URL'doc':'https://docs.example.com/api',// string URL or array of URLs},'version':'v1',// string ending with digits'api':{ ...},// dictionary of api endpoints'has':{// exchange capabilities'CORS':false,'cancelOrder':true,'createDepositAddress':false,'createOrder':true,'fetchBalance':true,'fetchCanceledOrders':false,'fetchClosedOrder':false,'fetchClosedOrders':false,'fetchCurrencies':false,'fetchDepositAddress':false,'fetchMarkets':true,'fetchMyTrades':false,'fetchOHLCV':false,'fetchOpenOrder':false,'fetchOpenOrders':false,'fetchOrder':false,'fetchOrderBook':true,'fetchOrders':false,'fetchStatus':'emulated','fetchTicker':true,'fetchTickers':false,'fetchBidsAsks':false,'fetchTrades':true,'withdraw':false,},'timeframes':{// empty if the exchange.has['fetchOHLCV'] !== true'1m':'1minute','1h':'1hour','1d':'1day','1M':'1month','1y':'1year',},'timeout':10000,// number in milliseconds'rateLimit':2000,// number in milliseconds'userAgent':'ccxt/1.1.1 ...'// string, HTTP User-Agent header'verbose':false,// boolean, output error details'markets':{ ...}// dictionary of markets/pairs by symbol'symbols':[ ...]// sorted list of string symbols (traded pairs)'currencies':{ ...}// dictionary of currencies by currency code'markets_by_id':{ ...},// dictionary of array of dictionaries (markets) by id'currencies_by_id':{ ...},// dictionary of dictionaries (markets) by id'apiKey':'92560ffae9b8a0421...',// string public apiKey (ASCII, hex, Base64, ...)'secret':'9aHjPmW+EtRRKN/Oi...'// string private secret key'password':'6kszf4aci8r',// string password'uid':'123456',// string user id'options':{ ...},// exchange-specific options// ... other properties here ...}

Below is a detailed description of each of the base exchange properties:

• id: Each exchange has a default id. The id is not used for anything, it's a string literal for user-land exchange instance identification purposes. You can have multiple links to the same exchange and differentiate them by ids. Default ids are all lowercase and correspond to exchange names.

• name: This is a string literal containing the human-readable exchange name.

• countries: An array of string literals of 2-symbol ISO country codes, where the exchange is operating from.

• urls['api']: The single string literal base URL for API calls or an associative array of separate URLs for private and public APIs.

• urls['www']: The main HTTP website URL.

• urls['doc']: A single string URL link to original documentation for exchange API on their website or an array of links to docs.

• version: A string literal containing version identifier for current exchange API. The ccxt library will append this version string to the API Base URL upon each request. You don't have to modify it, unless you are implementing a new exchange API. The version identifier is a usually a numeric string starting with a letter 'v' in some cases, like v1.1. Do not override it unless you are implementing your own new crypto exchange class.

• api: An associative array containing a definition of all API endpoints exposed by a crypto exchange. The API definition is used by ccxt to automatically construct callable instance methods for each available endpoint.

• has: This is an associative array of exchange capabilities (e.gfetchTickers,fetchOHLCV orCORS).

• timeframes: An associative array of timeframes, supported by the fetchOHLCV method of the exchange. This is only populated whenhas['fetchOHLCV'] property is true.

• timeout: A timeout in milliseconds for a request-response roundtrip (default timeout is 10000 ms = 10 seconds). If the response is not received in that time, the library will throw anRequestTimeout exception. You can leave the default timeout value or set it to a reasonable value. Hanging forever with no timeout is not your option, for sure. You don't have to override this option in general case.

• rateLimit: A request rate limit in milliseconds. Specifies the required minimal delay between two consequent HTTP requests to the same exchange. The built-in rate-limiter is enabled by default and can be turned off by setting theenableRateLimit property to false.

• enableRateLimit: A boolean (true/false) value that enables the built-in rate limiter and throttles consecutive requests. This setting istrue (enabled) by default.The user is required to implement ownrate limiting or leave the built-in rate limiter enabled to avoid being banned from the exchange.

• userAgent: An object to set HTTP User-Agent header to. The ccxt library will set its User-Agent by default. Some exchanges may not like it. If you are having difficulties getting a reply from an exchange and want to turn User-Agent off or use the default one, set this value to false, undefined, or an empty string. The value ofuserAgent may be overrided by HTTPheaders property below.

• headers: An associative array of HTTP headers and their values. Default value is empty{}. All headers will be prepended to all requests. If theUser-Agent header is set withinheaders, it will override whatever value is set in theuserAgent property above.

• verbose: A boolean flag indicating whether to log HTTP requests to stdout (verbose flag is false by default). Python people have an alternative way of DEBUG logging with a standard pythonic logger, which is enabled by adding these two lines to the beginning of their code:

  importlogginglogging.basicConfig(level=logging.DEBUG)

• markets: An associative array of markets indexed by common trading pairs or symbols. Markets should be loaded prior to accessing this property. Markets are unavailable until you call theloadMarkets() / load_markets() method on exchange instance.

• symbols: A non-associative array (a list) of symbols available with an exchange, sorted in alphabetical order. These are the keys of themarkets property. Symbols are loaded and reloaded from markets. This property is a convenient shorthand for all market keys.

• currencies: An associative array (a dict) of currencies by codes (usually 3 or 4 letters) available with an exchange. Currencies are loaded and reloaded from markets.

• markets_by_id: An associative array of arrays of markets indexed by exchange-specific ids. Typically a length one array unless there are multiple markets with the same marketId. Markets should be loaded prior to accessing this property.

• apiKey: This is your public API key string literal. Most exchanges requireAPI keys setup.

• secret: Your private secret API key string literal. Most exchanges require this as well together with the apiKey.

• password: A string literal with your password/phrase. Some exchanges require this parameter for trading, but most of them don't.

• uid: A unique id of your account. This can be a string literal or a number. Some exchanges also require this for trading, but most of them don't.

• requiredCredentials: A unified associative dictionary that shows which of the above API credentials are required for sending private API calls to the underlying exchange (an exchange may require a specific set of keys).

• options: An exchange-specific associative dictionary containing special keys and options that are accepted by the underlying exchange and supported in CCXT.

• precisionMode: The exchange decimal precision counting mode, read more aboutPrecision And Limits

• For proxies -proxyUrl,httpUrl,httpsUrl,socksProxy,wsProxy,wssProxy,wsSocksProxy : An url of specific proxy. Read details inProxy section.

See this section onOverriding exchange properties.

• has: An assoc-array containing flags for exchange capabilities, including the following:

  'has':{'CORS':false,// has Cross-Origin Resource Sharing enabled (works from browser) or not// unified methods availability flags (can be true, false, or 'emulated'):'cancelOrder':true,'createDepositAddress':false,'createOrder':true,'fetchBalance':true,'fetchCanceledOrders':false,'fetchClosedOrder':false,'fetchClosedOrders':false,'fetchCurrencies':false,'fetchDepositAddress':false,'fetchMarkets':true,'fetchMyTrades':false,'fetchOHLCV':false,'fetchOpenOrder':false,'fetchOpenOrders':false,'fetchOrder':false,'fetchOrderBook':true,'fetchOrders':false,'fetchStatus':'emulated','fetchTicker':true,'fetchTickers':false,'fetchBidsAsks':false,'fetchTrades':true,'withdraw':false,    ...}

  The meaning of each flag showing availability of this or that method is:

  • a value ofundefined /None /null means the method is not currently implemented in ccxt (either ccxt has not unified it yet or the method isn't natively available from the exchange API)
  • booleanfalse specifically means that the endpoint isn't natively available from the exchange API
  • booleantrue means the endpoint is natively available from the exchange API and unified in the ccxt library
  • 'emulated' string means the endpoint isn't natively available from the exchange API but reconstructed (as much as possible) by the ccxt library from other available true-methods

  For a complete list of all exchages and their supported methods, please, refer to this example:https://github.com/ccxt/ccxt/blob/master/examples/js/exchange-capabilities.js

Exchanges usually impose what is called arate limit. Exchanges will remember and track your user credentials and your IP address and will not allow you to query the API too frequently. They balance their load and control traffic congestion to protect API servers from (D)DoS and misuse.

WARNING: Stay under the rate limit to avoid ban!

Most exchanges allowup to 1 or 2 requests per second. Exchanges may temporarily restrict your access to their API or ban you for some period of time if you are too aggressive with your requests.

Theexchange.rateLimit property is set to a safe default which is sub-optimal. Some exchanges may have varying rate limits for different endpoints. It is up to the user to tweakrateLimit according to application-specific purposes.

The CCXT library has a built-in experimental rate-limiter that will do the necessary throttling in background transparently to the user.WARNING: users are responsible for at least some type of rate-limiting: either by implementing a custom algorithm or by doing it with the built-in rate-limiter..

You can turn on/off the built-in rate-limiter with.enableRateLimit property, like so:

// enable built-in rate limiting upon instantiation of the exchangeconstexchange=newccxt.bitfinex({// 'enableRateLimit': true, // enabled by default})// or switch the built-in rate-limiter on or off later after instantiationexchange.enableRateLimit=true// enableexchange.enableRateLimit=false// disable

# enable built-in rate limiting upon instantiation of the exchangeexchange=ccxt.bitfinex({# 'enableRateLimit': True,  # enabled by default})# or switch the built-in rate-limiter on or off later after instantiationexchange.enableRateLimit=True# enableexchange.enableRateLimit=False# disable

// enable built-in rate limiting upon instantiation of the exchange$exchange =new \ccxt\bitfinex (array (// 'enableRateLimit' => true, // enabled by default));// or switch the built-in rate-limiter on or off later after instantiation$exchange->enableRateLimit =true;// enable$exchange->enableRateLimit =false;// disable

In case your calls hit a rate limit or get nonce errors, the ccxt library will throw anInvalidNonce exception, or, in some cases, one of the following types:

• DDoSProtection
• ExchangeNotAvailable
• ExchangeError
• InvalidNonce

A later retry is usually enough to handle that.

The rate limiter is a property of the exchange instance, in other words, each exchange instance has its own rate limiter that is not aware of the other instances. In many cases the user should reuse the same exchange instance throughout the program. Do not use multiple instances of the same exchange with the same API keypair from the same IP address.

// DO NOT DO THIS!constbinance1=newccxt.binance()constbinance2=newccxt.binance()constbinance3=newccxt.binance()while(true){constresult=awaitPromise.all([binance1.fetchOrderBook('BTC/USDT'),binance2.fetchOrderBook('ETH/USDT'),binance3.fetchOrderBook('ETH/BTC'),])console.log(result)}

Reuse the exchange instance as much as possible as shown below:

// DO THIS INSTEAD:constbinance=newccxt.binance()while(true){constresult=awaitPromise.all([binance.fetchOrderBook('BTC/USDT'),binance.fetchOrderBook('ETH/USDT'),binance.fetchOrderBook('ETH/BTC'),])console.log(result)}

Since the rate limiter belongs to the exchange instance, destroying the exchange instance will destroy the rate limiter as well. Among the most common pitfalls with the rate limiting is creating and dropping the exchange instance over and over again. If in your program you are creating and destroying the exchange instance (say, inside a function that is called multiple times), then you are effectively resetting the rate limiter over and over and that will eventually break the rate limits. If you are recreating the exchange instance every time instead of reusing it, CCXT will try to load the markets every time. Therefore, you will force-load the markets over and over as explained in theLoading Markets section. Abusing the markets endpoint will eventually break the rate limiter as well.

// DO NOT DO THIS!asyncfunctiontick(){constexchange=newccxt.binance()constresponse=awaitexchange.fetchOrderBook('BTC/USDT')// ... some processing here ...returnresponse}while(true){constresult=awaittick()console.log(result)}

Do not break this rule unless you really understand the inner workings of the rate-limiter and you are 100% sure you know what you're doing. In order to stay safe always reuse the exchange instance throughout your functions and methods callchain like shown below:

// DO THIS INSTEAD:asyncfunctiontick(exchange){constresponse=awaitexchange.fetchOrderBook('BTC/USDT')// ... some processing here ...returnresponse}constexchange=newccxt.binance()while(true){constresult=awaittick(exchange)console.log(result)}

Some exchanges areDDoS-protected byCloudflare orIncapsula. Your IP can get temporarily blocked during periods of high load. Sometimes they even restrict whole countries and regions. In that case their servers usually return a page that states a HTTP 40x error or runs an AJAX test of your browser / captcha test and delays the reload of the page for several seconds. Then your browser/fingerprint is granted access temporarily and gets added to a whitelist or receives a HTTP cookie for further use.

The most common symptoms for a DDoS protection problem, rate-limiting problem or for a location-based filtering issue:

• GettingRequestTimeout exceptions with all types of exchange methods
• CatchingExchangeError orExchangeNotAvailable with HTTP error codes 400, 403, 404, 429, 500, 501, 503, etc..
• Having DNS resolving issues, SSL certificate issues and low-level connectivity issues
• Getting a template HTML page instead of JSON from the exchange

If you encounter DDoS protection errors and cannot reach a particular exchange then:

• use aproxy (this is less responsive, though)
• ask the exchange support to add you to a whitelist
• try an alternative IP within a different geographic region
• run your software in a distributed network of servers
• run your software in close proximity to the exchange (same country, same city, same datacenter, same server rack, same server)
• ...

• Currency Structure
• Market Structure
• Precision And Limits
• Loading Markets
• Symbols And Market Ids
• Market Cache Force Reload

Each exchange is a place for trading some kinds of valuables. The exchanges may use differing terms to call them:"a currency","an asset","a coin","a token","stock","commodity","crypto", "fiat", etc. A place for trading one asset for another is usually called"a market","a symbol","a trading pair","a contract", etc.

In terms of the ccxt library, every exchange offers multiplemarkets within itself. Each market is defined by two or morecurrencies. The set of markets differs from exchange to exchange opening possibilities for cross-exchange and cross-market arbitrage.

{'id':'btc',// string literal for referencing within an exchange'code':'BTC',// uppercase unified string literal code of the currency'name':'Bitcoin',// string, human-readable name, if specified'active':true,// boolean, currency status (tradeable and withdrawable)'fee':0.123,// withdrawal fee, flat'precision':8,// number of decimal digits "after the dot" (depends on exchange.precisionMode)'deposit':true// boolean, deposits are available'withdraw':true// boolean, withdraws are available'limits':{// value limits when placing orders on this market'amount':{'min':0.01,// order amount should be > min'max':1000,// order amount should be < max},'withdraw':{ ...},// withdrawal limits'deposit':{...},},'networks':{...}// network structures indexed by unified network identifiers (ERC20, TRC20, BSC, etc)'info':{ ...},// the original unparsed currency info from the exchange}

Each currency is an associative array (aka dictionary) with the following keys:

• id. The string or numeric ID of the currency within the exchange. Currency ids are used inside exchanges internally to identify coins during the request/response process.
• code. An uppercase string code representation of a particular currency. Currency codes are used to reference currencies within the ccxt library (explained below).
• name. A human-readable name of the currency (can be a mix of uppercase & lowercase characters).
• fee. The withdrawal fee value as specified by the exchange. In most cases it means a flat fixed amount paid in the same currency. If the exchnange does not specify it via public endpoints, thefee can beundefined/None/null or missing.
• active. A boolean indicating whether trading or funding (depositing or withdrawing) for this currency is currently possible, more about it here:active status.
• info. An associative array of non-common market properties, including fees, rates, limits and other general market information. The internal info array is different for each particular market, its contents depend on the exchange.
• precision. Precision accepted in values by exchanges upon referencing this currency. The value of this property depends onexchange.precisionMode.
• limits. The minimums and maximums for amounts (volumes), withdrawals and deposits.

{'id':'tron',// string literal for referencing within an exchange'network':'TRC20'// unified network'name':'Tron Network',// string, human-readable name, if specified'active':true,// boolean, currency status (tradeable and withdrawable)'fee':0.123,// withdrawal fee, flat'precision':8,// number of decimal digits "after the dot" (depends on exchange.precisionMode)'deposit':true// boolean, deposits are available'withdraw':true// boolean, withdraws are available'limits':{// value limits when placing orders on this market'amount':{'min':0.01,// order amount should be > min'max':1000,// order amount should be < max},'withdraw':{ ...},// withdrawal limits'deposit':{...},// deposit limits},'info':{ ...},// the original unparsed currency info from the exchange}

Each network is an associative array (aka dictionary) with the following keys:

• id. The string or numeric ID of the network within the exchange. Network ids are used inside exchanges internally to identify networks during the request/response process.
• network. An uppercase string representation of a particular network. Networks are used to reference networks within the ccxt library.
• name. A human-readable name of the network (can be a mix of uppercase & lowercase characters).
• fee. The withdrawal fee value as specified by the exchange. In most cases it means a flat fixed amount paid in the same currency. If the exchnange does not specify it via public endpoints, thefee can beundefined/None/null or missing.
• active. A boolean indicating whether trading or funding (depositing or withdrawing) for this currency is currently possible, more about it here:active status.
• info. An associative array of non-common market properties, including fees, rates, limits and other general market information. The internal info array is different for each particular market, its contents depend on the exchange.
• precision. Precision accepted in values by exchanges upon referencing this currency. The value of this property depends onexchange.precisionMode.
• limits. The minimums and maximums for amounts (volumes), withdrawals and deposits.

{'id':'btcusd',// string literal for referencing within an exchange'symbol':'BTC/USD',// uppercase string literal of a pair of currencies'base':'BTC',// uppercase string, unified base currency code, 3 or more letters'quote':'USD',// uppercase string, unified quote currency code, 3 or more letters'baseId':'btc',// any string, exchange-specific base currency id'quoteId':'usd',// any string, exchange-specific quote currency id'active':true,// boolean, market status'type':'spot',// spot for spot, future for expiry futures, swap for perpetual swaps, 'option' for options'spot':true,// whether the market is a spot market'margin':true,// whether the market is a margin market'future':false,// whether the market is a expiring future'swap':false,// whether the market is a perpetual swap'option':false,// whether the market is an option contract'contract':false,// whether the market is a future, a perpetual swap, or an option'settle':'USDT',// the unified currency code that the contract will settle in, only set if `contract` is true'settleId':'usdt',// the currencyId of that the contract will settle in, only set if `contract` is true'contractSize':1,// the size of one contract, only used if `contract` is true'linear':true,// the contract is a linear contract (settled in quote currency)'inverse':false,// the contract is an inverse contract (settled in base currency)'expiry':1641370465121,// the unix expiry timestamp in milliseconds, undefined for everything except market['type'] `future`'expiryDatetime':'2022-03-26T00:00:00.000Z',// The datetime contract will in iso8601 format'strike':4000,// price at which a put or call option can be exercised'optionType':'call',// call or put string, call option represents an option with the right to buy and put an option with the right to sell// note, 'taker' and 'maker' compose extended data for markets, however it might be better to use `fetchTradingFees` for more accuracy'taker':0.002,// taker fee rate, 0.002 = 0.2%'maker':0.0016,// maker fee rate, 0.0016 = 0.16%'percentage':true,// whether the taker and maker fee rate is a multiplier or a fixed flat amount'tierBased':false,// whether the fee depends on your trading tier (your trading volume)'feeSide':'get',// string literal can be 'get', 'give', 'base', 'quote', 'other''precision':{// number of decimal digits "after the dot"'price':8,// integer or float for TICK_SIZE roundingMode, might be missing if not supplied by the exchange'amount':8,// integer, might be missing if not supplied by the exchange'cost':8,// integer, very few exchanges actually have it},'limits':{// value limits when placing orders on this market'amount':{'min':0.01,// order amount should be > min'max':1000,// order amount should be < max},'price':{ ...},// same min/max limits for the price of the order'cost':{ ...},// same limits for order cost = price * amount'leverage':{ ...},// same min/max limits for the leverage of the order},'marginModes':{'cross':false,// whether pair supports cross-margin trading'isolated':false,// whether pair supports isolated-margin trading},'info':{ ...},// the original unparsed market info from the exchange}

Each market is an associative array (aka dictionary) with the following keys:

• id. The string or numeric ID of the market or trade instrument within the exchange. Market ids are used inside exchanges internally to identify trading pairs during the request/response process.
• symbol. An uppercase string code representation of a particular trading pair or instrument. This is usually written asBaseCurrency/QuoteCurrency with a slash as inBTC/USD,LTC/CNY orETH/EUR, etc. Symbols are used to reference markets within the ccxt library (explained below).
• base. A unified uppercase string code of base fiat or crypto currency. This is the standardized currency code that is used to refer to that currency or token throughout CCXT and throughout the Unified CCXT API, it's the language that CCXT understands.
• quote. A unified uppercase string code of quoted fiat or crypto currency.
• baseId. An exchange-specific id of the base currency for this market, not unified. Can be any string, literally. This is communicated to the exchange using the language the exchange understands.
• quoteId. An exchange-specific id of the quote currency, not unified.
• active. A boolean indicating whether or not trading this market is currently possible, more about it here:active status.
• maker. Float, 0.0015 = 0.15%. Maker fees are paid when you provide liquidity to the exchange i.e. youmarket-make an order and someone else fills it. Maker fees are usually lower than taker fees. Fees can be negative, this is very common amongst derivative exchanges. A negative fee means the exchange will pay a rebate (reward) to the user for trading this market (note, 'taker' and 'maker' publicly available fees, not taking into consideration your vip-level/volume/etc. UsefetchTradingFees to get the fees specific to your account).
• taker. Float, 0.002 = 0.2%. Taker fees are paid when youtake liquidity from the exchange and fill someone else's order.
• percentage. A boolean true/false value indicating whethertaker andmaker are multipliers or fixed flat amounts.
• tierBased. A boolean true/false value indicating whether the fee depends on your trading tier (usually, your traded volume over a period of time).
• info. An associative array of non-common market properties, including fees, rates, limits and other general market information. The internal info array is different for each particular market, its contents depend on the exchange.
• precision. Precision accepted in order values by exchanges upon order placement for price, amount and cost. (The value inside this property depend on theexchange.precisionMode).
• limits. The minimums and maximums for prices, amounts (volumes) and costs (where cost = price * amount).
• optionType. The type of the option,call option represents an option with the right to buy andput an option with the right to sell.
• strike. Price at which an option can be bought or sold when it is exercised.

Theactive flag is typically used incurrencies andmarkets. The exchanges might put a slightly different meaning into it. If a currency is inactive, most of the time all corresponding tickers, orderbooks and other related endpoints return empty responses, all zeroes, no data or outdated information. The user should check if the currency isactive andreload markets periodically.

Note: thefalse value for theactive property doesn't always guarantee that all of the possible features like trading, withdrawing or depositing are disabled on the exchange. Likewise, neither thetrue value guarantees that all those features are enabled on the exchange. Check the underlying exchanges' documentation and the code in CCXT for the exact meaning of theactive flag for this or that exchange. This flag is not yet supported or implemented by all markets and may be missing.

WARNING! The information about the fee is experimental, unstable and may be partial or not available at all.

Do not confuselimits withprecision! Precision has nothing to do with min limits. A precision of0.01 does not necessarily mean that a minimum limit for market is0.01. The opposite is also true: a min limit of0.01 does not necessarily mean a precision is0.01.

Examples:

market['limits']['amount']['min'] == 0.05 &&market['precision']['amount'] == 0.0001 &&market['precision']['price'] == 0.01

• Theamount value should be >= 0.05:

  + good: 0.05, 0.051, 0.0501, 0.0502, ..., 0.0599, 0.06, 0.0601, ...- bad: 0.04, 0.049, 0.0499

• Precision of the amount should be up to 4 digits after dot (0.0001):

  + good: 0.05, 0.0501, ..., 0.06, ..., 0.0719, ...- bad: 0.05001, 0.05000, 0.06001

• Precision of the price should be up to 2 digits after dot (0.01):

  + good: 1.6, 1.61, 123.01, ..., 1234.56, ...- bad: 1.601, ..., 123.012, ..., 1234.567

2. (market['precision']['amount'] == -1)

   A negativeprecision might only theoretically happen if exchange'sprecisionMode isSIGNIFICANT_DIGIT orDECIMAL_PRECISION. It means that the amount should be an integer multiple of 10 (to the absolute power specified):

   + good: 10, 50, ..., 110, ... 1230, ..., 1000000, ..., 1234560, ...- bad: 9.5, ... 10.1, ..., 11, ... 200.71, ...

   In case of-2 the acceptable values would be multiple of100 (e.g. 100, 200, ... ), and so on.

Supported precision modes inexchange['precisionMode'] are:

• TICK_SIZE – almost all exchanges use this precision mode. In this mode, the numbers inmarket_or_currency['precision'] designate the minimal precision fractions (floats) for rounding or truncating.
• SIGNIFICANT_DIGITS – counts non-zero digits only, some exchanges (bitfinex and maybe a few other) implement this mode of counting decimals. With this mode of precision, the numbers inmarket_or_currency['precision'] designate the Nth place of the last significant (non-zero) decimal digit after the dot.
• DECIMAL_PLACES (DEPRECATED, CCXT no longer uses this mode anywhere) – counts all digits. With this mode of precision, the numbers inmarket_or_currency['precision'] designate the number of decimal digits after the dot for further rounding or truncation.

The user is required to stay within all limits and precision! The values of the order should satisfy the following conditions:

• Orderamount >=limits['amount']['min']
• Orderamount <=limits['amount']['max']
• Orderprice >=limits['price']['min']
• Orderprice <=limits['price']['max']
• Ordercost (amount * price) >=limits['cost']['min']
• Ordercost (amount * price) <=limits['cost']['max']
• Precision ofamount must be <=precision['amount']
• Precision ofprice must be <=precision['price']

The above values can be missing with some exchanges that don't provide info on limits from their API or don't have it implemented yet.

Each exchange has its own rounding, counting and padding modes.

Supported rounding modes are:

• ROUND – will round the last decimal digits to precision
• TRUNCATE– will cut off the digits after certain precision

The decimal precision counting mode is available in theexchange.precisionMode property.

Supported padding modes are:

• NO_PADDING – default for most cases
• PAD_WITH_ZERO – appends zero characters up to precision

Most of the time the user does not have to take care of precision formatting, since CCXT will handle that for the user when the user places orders or sends withdrawal requests, if the user follows the rules as described onPrecision And Limits. However, in some cases precision-formatting details may be important, so the following methods may be useful in the userland.

The exchange base class contains thedecimalToPrecision method to help format values to the required decimal precision with support for different rounding, counting and padding modes.

functiondecimalToPrecision(x,roundingMode,numPrecisionDigits,countingMode=DECIMAL_PLACES,paddingMode=NO_PADDING)

# WARNING! The `decimal_to_precision` method is susceptible to getcontext().prec!defdecimal_to_precision(n,rounding_mode=ROUND,precision=None,counting_mode=DECIMAL_PLACES,padding_mode=NO_PADDING):

function decimalToPrecision ($x,$roundingMode =ROUND,$numPrecisionDigits =null,$countingMode =DECIMAL_PLACES,$paddingMode =NO_PADDING)

For examples of how to use thedecimalToPrecision to format strings and floats, please, see the following files:

• Typescript:https://github.com/ccxt/ccxt/blob/master/ts/src/test/base/functions/test.number.ts
• #"https://github.com/ccxt/ccxt/blob/master/js/src/test/base/functions/test.number.js">https://github.com/ccxt/ccxt/blob/master/js/src/test/base/functions/test.number.js
• Python:https://github.com/ccxt/ccxt/blob/master/python/ccxt/test/base/test_number.py
• PHP:https://github.com/ccxt/ccxt/blob/master/php/test/base/test_number.php

Python WARNING! Thedecimal_to_precision method is susceptible togetcontext().prec!

For users' convenience CCXT base exchange class also implements the following methods:

functionamountToPrecision(symbol,amount)functionpriceToPrecision(symbol,price)functioncostToPrecision(symbol,cost)functioncurrencyToPrecision(code,amount)

defamount_to_precision (symbol,amount):defprice_to_precision (symbol,price):defcost_to_precision (symbol,cost):defcurrency_to_precision (code,amount):

function amount_to_precision($symbol,$amount)function price_to_precision($symbol,$price)function cost_to_precision($symbol,$cost)function currency_to_precision($code,$amount)

Every exchange has its own precision settings, the above methods will help format those values according to exchange-specific precision rules, in a way that is portable and agnostic of the underlying exchange. In order to make that possible, markets and currencies have to be loaded prior to formatting any values.

Make sure toload the markets withexchange.loadMarkets() before calling these methods!

For example:

awaitexchange.loadMarkets()constsymbol='BTC/USDT'constamount=1.2345678// amount in base currency BTCconstprice=87654.321// price in quote currency USDTconstformattedAmount=exchange.amountToPrecision(symbol,amount)constformattedPrice=exchange.priceToPrecision(symbol,price)console.log(formattedAmount,formattedPrice)

exchange.load_markets()symbol='BTC/USDT'amount=1.2345678# amount in base currency BTCprice=87654.321# price in quote currency USDTformatted_amount=exchange.amount_to_precision(symbol,amount)formatted_price=exchange.price_to_precision(symbol,price)print(formatted_amount,formatted_price)

$exchange->load_markets();$symbol ='BTC/USDT';$amount =1.2345678;// amount in base currency BTC$price =87654.321;// price in quote currency USDT$formatted_amount =$exchange->amount_to_precision($symbol,$amount);$formatted_price =$exchange->price_to_precision($symbol,$price);echo$formatted_amount,"",$formatted_price,"\n";

More practical examples that describe the behavior ofexchange.precisionMode:

// case Aexchange.precisionMode=ccxt.DECIMAL_PLACESmarket=exchange.market(symbol)market['precision']['amount']===8// up to 8 decimals after the dotexchange.amountToPrecision(symbol,0.123456789)===0.12345678exchange.amountToPrecision(symbol,0.0000000000123456789)===0.0000000===0.0

// case Bexchange.precisionMode=ccxt.TICK_SIZEmarket=exchange.market(symbol)market['precision']['amount']===0.00000001// up to 0.00000001 precisionexchange.amountToPrecision(symbol,0.123456789)===0.12345678exchange.amountToPrecision(symbol,0.0000000000123456789)===0.00000000===0.0

// case Cexchange.precisionMode=ccxt.SIGNIFICANT_DIGITSmarket=exchange.market(symbol)market['precision']['amount']===8// up to 8 significant non-zero digitsexchange.amountToPrecision(symbol,0.0000000000123456789)===0.000000000012345678exchange.amountToPrecision(symbol,123.4567890123456789)===123.45678

In most cases you are required to load the list of markets and trading symbols for a particular exchange prior to accessing other API methods. If you forget to load markets the ccxt library will do that automatically upon your first call to the unified API. It will send two HTTP requests, first for markets and then the second one for other data, sequentially. For that reason, your first call to a unified CCXT API method like fetchTicker, fetchBalance, etc will take more time, than the consequent calls, since it has to do more work loading the market information from the exchange API. SeeNotes On Rate Limiter for more details.

In order to load markets manually beforehand call theloadMarkets () /load_markets () method on an exchange instance. It returns an associative array of markets indexed by trading symbol. If you want more control over the execution of your logic, preloading markets by hand is recommended.

(async()=>{letkraken=newccxt.kraken()letmarkets=awaitkraken.loadMarkets()console.log(kraken.id,markets)})()

okcoin=ccxt.okcoin()markets=okcoin.load_markets()print(okcoin.id,markets)

$id ='huobipro';$exchange ='\\ccxt\\' .$id;$huobipro =new$exchange();$markets =$huobipro->load_markets();var_dump($huobipro->id,$markets);

Apart from the market info, theloadMarkets() call will also load the currencies from the exchange and will cache the info in the.markets and the.currencies properties respectively.

The user can also bypass the cache and call unified methods for fetching that information from the exchange endpoints directly,fetchMarkets() andfetchCurrencies(), though using these methods is not recommended for end-users. The recommended way to preload markets is by calling theloadMarkets() unified method. However, new exchange integrations are required to implement these methods if the underlying exchange has the corresponding API endpoints.

A currency code is a code of three to five letters, likeBTC,ETH,USD,GBP,CNY,JPY,DOGE,RUB,ZEC,XRP,XMR, etc. Some exchanges have exotic currencies with longer codes.

A symbol is usually an uppercase string literal name of a pair of traded currencies with a slash in between. The first currency before the slash is usually calledbase currency, and the one after the slash is calledquote currency. Examples of a symbol are:BTC/USD,DOGE/LTC,ETH/EUR,DASH/XRP,BTC/CNY,ZEC/XMR,ETH/JPY.

Market ids are used during the REST request-response process to reference trading pairs within exchanges. The set of market ids is unique per exchange and cannot be used across exchanges. For example, the BTC/USD pair/market may have different ids on various popular exchanges, likebtcusd,BTCUSD,XBTUSD,btc/usd,42 (numeric id),BTC/USD,Btc/Usd,tBTCUSD,XXBTZUSD. You don't need to remember or use market ids, they are there for internal HTTP request-response purposes inside exchange implementations.

The ccxt library abstracts uncommon market ids to symbols, standardized to a common format. Symbols aren't the same as market ids. Every market is referenced by a corresponding symbol. Symbols are common across exchanges which makes them suitable for arbitrage and many other things.

Sometimes the user might notice a symbol like'XBTM18' or'.XRPUSDM20180101' or some other"exotic/rare symbols". The symbol isnot required to have a slash or to be a pair of currencies. The string in the symbol really depends on the type of the market (whether it is a spot market or a futures market, a darkpool market or an expired market, etc). Attempting to parse the symbol string is highly discouraged, one should not rely on the symbol format, it is recommended to use market properties instead.

Market structures are indexed by symbols and ids. The base exchange class also has builtin methods for accessing markets by symbols. Most API methods require a symbol to be passed in their first argument. You are often required to specify a symbol when querying current prices, making orders, etc.

Most of the time users will be working with market symbols. You will get a standard userland exception if you access non-existent keys in these dicts.

(async()=>{console.log(awaitexchange.loadMarkets())letbtcusd1=exchange.markets['BTC/USD']// get market structure by symbolletbtcusd2=exchange.market('BTC/USD')// same result in a slightly different wayletbtcusdId=exchange.marketId('BTC/USD')// get market id by symbolletsymbols=exchange.symbols// get an array of symbolsletsymbols2=Object.keys(exchange.markets)// same as previous lineconsole.log(exchange.id,symbols)// print all symbolsletcurrencies=exchange.currencies// a dictionary of currenciesletbitfinex=newccxt.bitfinex()awaitbitfinex.loadMarkets()bitfinex.markets['BTC/USD']// symbol → market (get market by symbol)bitfinex.markets_by_id['XRPBTC'][0]// id → market (get market by id)bitfinex.markets['BTC/USD']['id']// symbol → id (get id by symbol)bitfinex.markets_by_id['XRPBTC'][0]['symbol']// id → symbol (get symbol by id)})()

print(exchange.load_markets())etheur1=exchange.markets['ETH/EUR']# get market structure by symboletheur2=exchange.market('ETH/EUR')# same result in a slightly different wayetheurId=exchange.market_id('ETH/EUR')# get market id by symbolsymbols=exchange.symbols# get a list of symbolssymbols2=list(exchange.markets.keys())# same as previous lineprint(exchange.id,symbols)# print all symbolscurrencies=exchange.currencies# a dictionary of currencieskraken=ccxt.kraken()kraken.load_markets()kraken.markets['BTC/USD']# symbol → market (get market by symbol)kraken.markets_by_id['XXRPZUSD'][0]# id → market (get market by id)kraken.markets['BTC/USD']['id']# symbol → id (get id by symbol)kraken.markets_by_id['XXRPZUSD'][0]['symbol']# id → symbol (get symbol by id)

$var_dump($exchange->load_markets());$dashcny1 =$exchange->markets['DASH/CNY'];// get market structure by symbol$dashcny2 =$exchange->market('DASH/CNY');// same result in a slightly different way$dashcnyId =$exchange->market_id('DASH/CNY');// get market id by symbol$symbols =$exchange->symbols;// get an array of symbols$symbols2 =array_keys($exchange->markets);// same as previous linevar_dump($exchange->id,$symbols);// print all symbols$currencies =$exchange->currencies;// an associative array of currencies$okcoin ='\\ccxt\\okcoin';$okcoin =new$okcoin();$okcoin->load_markets();$okcoin->markets['BTC/USD'];// symbol → market (get market by symbol)$okcoin->markets_by_id['btc_usd'][0];// id → market (get market by id)$okcoin->markets['BTC/USD']['id'];// symbol → id (get id by symbol)$okcoin->markets_by_id['btc_usd'][0]['symbol'];// id → symbol (get symbol by id)

There is a bit of term ambiguity across various exchanges that may cause confusion among newcoming traders. Some exchanges call markets aspairs, whereas other exchanges call symbols asproducts. In terms of the ccxt library, each exchange contains one or more trading markets. Each market has an id and a symbol. Most symbols are pairs of base currency and quote currency.

Exchanges → Markets → Symbols → Currencies

Historically various symbolic names have been used to designate same trading pairs. Some cryptocurrencies (like Dash) even changed their names more than once during their ongoing lifetime. For consistency across exchanges the ccxt library will perform the following known substitutions for symbols and currencies:

• XBT → BTC:XBT is newer butBTC is more common among exchanges and sounds more like bitcoin (read more).
• BCC → BCH: The Bitcoin Cash fork is often called with two different symbolic names:BCC andBCH. The nameBCC is ambiguous for Bitcoin Cash, it is confused with BitConnect. The ccxt library will convertBCC toBCH where it is appropriate (some exchanges and aggregators confuse them).
• DRK → DASH:DASH was Darkcoin then became Dash (read more).
• BCHABC → BCH: On November 15 2018 Bitcoin Cash forked the second time, so, now there isBCH (for BCH ABC) andBSV (for BCH SV).
• BCHSV → BSV: This is a common substitution mapping for the Bitcoin Cash SV fork (some exchanges call itBSV, others call itBCHSV, we use the former).
• DSH → DASH: Try not to confuse symbols and currencies. TheDSH (Dashcoin) is not the same asDASH (Dash). Some exchanges haveDASH labelled inconsistently asDSH, the ccxt library does a correction for that as well (DSH → DASH), but only on certain exchanges that have these two currencies confused, whereas most exchanges have them both correct. Just remember thatDASH/BTC is not the same asDSH/BTC.
• XRB →NANO:NANO is the newer code for RaiBlocks, thus, CCXT unified API will replace the olderXRB withNANO where needed.https://hackernoon.com/nano-rebrand-announcement-9101528a7b76
• USD →USDT: Some exchanges, like Bitfinex, HitBTC and a few other name the currency asUSD in their listings, but those markets are actually tradingUSDT. The confusion can come from a 3-letter limitation on symbol names or may be due to other reasons. In cases where the traded currency is actuallyUSDT and is notUSD – the CCXT library will performUSD → USDT conversion. Note, however, that some exchanges have bothUSD andUSDT symbols, for example, Kraken has aUSDT/USD trading pair.

Each exchange has an associative array of substitutions for cryptocurrency symbolic codes in theexchange.commonCurrencies property, like:

'commonCurrencies' : {    'XBT': 'BTC',    'OPTIMISM': 'OP',    // ... etc}

where key represents actual name how exchange engine refers to that coin, and the value represents what you want to refer to it with through ccxt.

Sometimes the user may notice exotic symbol names with mixed-case words and spaces in the code. The logic behind having these names is explained by the rules for resolving conflicts in naming and currency-coding when one or more currencies have the same symbolic code with different exchanges:

• First, we gather all info available from the exchanges themselves about the currency codes in question. They usually have a description of their coin listings somewhere in their API or their docs, knowledgebases or elsewhere on their websites.
• When we identify each particular cryptocurrency standing behind the currency code, we look them up onCoinMarketCap.
• The currency that has the greatest market capitalization of all wins the currency code and keeps it. For example, HOT often stand for eitherHolo orHydro Protocol. In this caseHolo retains the codeHOT, andHydro Protocol will have its name as its code, literally,Hydro Protocol. So, there may be trading pairs with symbols likeHOT/USD (forHolo) andHydro Protocol/USD – those are two different markets.
• If market cap of a particular coin is unknown or is not enough to determine the winner, we also take trading volumes and other factors into consideration.
• When the winner is determined all other competing currencies get their code names properly remapped and substituted within conflicting exchanges via.commonCurrencies.Note, it should be defined before '.loadMarkets()' happens!
• Unfortunately this is a work in progress, because new currencies get listed daily and new exchanges are added from time to time, so, in general this is a never-ending process of self-correction in a quickly changing environment, practically, in"live mode". We are thankful for all reported conflicts and mismatches you may find.

Is it possible for symbols to change?

In short, yes, sometimes, but rarely. Symbolic mappings can be changed if that is absolutely required and cannot be avoided. However, all previous symbolic changes were related to resolving conflicts or forks. So far, there was no precedent of a market cap of one coin overtaking another coin with the same symbolic code in CCXT.

Can we rely on always listing the same crypto with the same symbol?

More or less ) First, this library is a work in progress, and it is trying to adapt to the everchanging reality, so there may be conflicts that we will fix by changing some mappings in the future. Ultimately, the license says "no warranties, use at your own risk". However, we don't change symbolic mappings randomly all over the place, because we understand the consequences and we'd want to rely on the library as well and we don't like to break the backward-compatibility at all.

If it so happens that a symbol of a major token is forked or has to be changed, then the control is still in the users' hands. Theexchange.commonCurrencies property can beoverrided upon initialization or later, just like any other exchange property. If a significant token is involved, we usually post instructions on how to retain the old behavior by adding a couple of lines to the constructor params.

It depends on which exchange you are using, but some of them have a reversed (inconsistent) pairing ofbase andquote. They actually have base and quote misplaced (switched/reversed sides). In that case you'll see a difference of parsedbase andquote currency values with the unparsedinfo in the market substructure.

For those exchanges the ccxt will do a correction, switching and normalizing sides of base and quote currencies when parsing exchange replies. This logic is financially and terminologically correct. If you want less confusion, remember the following rule:base is always before the slash, quote is always after the slash in any symbol and with any market.

base currency ↓             BTC / USDT             ETH / BTC            DASH / ETH                    ↑ quote currency

We currently load spot markets with the unifiedBASE/QUOTE symbol schema into the.markets mapping, indexed by symbol. This would cause a naming conflict for futures and other derivatives that have the same symbol as their spot market counterparts. To accomodate both types of markets in the.markets we require the symbols between 'future' and 'spot' markets to be distinct, as well as the symbols between 'linear' and 'inverse' contracts to be distinct.

Please, check this announcement:Unified contract naming conventions

CCXT supports the following types of derivative contracts:

• future – for expiring futures contracts that have a delivery/settlement date
• swap – for perpetual swap futures that don't have a delivery date
• option – for option contracts (https://en.wikipedia.org/wiki/Option_contract)

A future market symbol consists of the underlying currency, the quoting currency, the settlement currency and an arbitrary identifier. Most often the identifier is the settlement date of the future contract inYYMMDD format:

//// base asset or currency// ↓// ↓  quote asset or currency// ↓  ↓// ↓  ↓    settlement asset or currency// ↓  ↓    ↓// ↓  ↓    ↓     identifier (settlement date)// ↓  ↓    ↓     ↓// ↓  ↓    ↓     ↓'BTC/USDT:BTC-211225'// BTC/USDT futures contract settled in BTC (inverse) on 2021-12-25'BTC/USDT:USDT-211225'// BTC/USDT futures contract settled in USDT (linear, vanilla) on 2021-12-25'ETH/USDT:ETH-210625'// ETH/USDT futures contract settled in ETH (inverse) on 2021-06-25'ETH/USDT:USDT-210625'// ETH/USDT futures contract settled in USDT (linear, vanilla) on 2021-06-25

// base asset or currency// ↓// ↓  quote asset or currency// ↓  ↓// ↓  ↓    settlement asset or currency// ↓  ↓    ↓// ↓  ↓    ↓'BTC/USDT:BTC'// BTC/USDT inverse perpetual swap contract funded in BTC'BTC/USDT:USDT'// BTC/USDT linear perpetual swap contract funded in USDT'ETH/USDT:ETH'// ETH/USDT inverse perpetual swap contract funded in ETH'ETH/USDT:USDT'// ETH/USDT linear perpetual swap contract funded in USDT

//// base asset or currency// ↓// ↓  quote asset or currency// ↓  ↓// ↓  ↓    settlement asset or currency// ↓  ↓    ↓// ↓  ↓    ↓       identifier (settlement date)// ↓  ↓    ↓       ↓// ↓  ↓    ↓       ↓   strike price// ↓  ↓    ↓       ↓   ↓// ↓  ↓    ↓       ↓   ↓   type, put (P) or call (C)// ↓  ↓    ↓       ↓   ↓   ↓'BTC/USDT:BTC-211225-60000-P'// BTC/USDT put option contract strike price 60000 USDT settled in BTC (inverse) on 2021-12-25'ETH/USDT:USDT-211225-40000-C'// BTC/USDT call option contract strike price 40000 USDT settled in USDT (linear, vanilla) on 2021-12-25'ETH/USDT:ETH-210625-5000-P'// ETH/USDT put option contract strike price 5000 USDT settled in ETH (inverse) on 2021-06-25'ETH/USDT:USDT-210625-5000-C'// ETH/USDT call option contract strike price 5000 USDT settled in USDT (linear, vanilla) on 2021-06-25

TheloadMarkets () / load_markets () is also a dirty method with a side effect of saving the array of markets on the exchange instance. You only need to call it once per exchange. All subsequent calls to the same method will return the locally saved (cached) array of markets.

When exchange markets are loaded, you can then access market information any time via themarkets property. This property contains an associative array of markets indexed by symbol. If you need to force reload the list of markets after you have them loaded already, pass the reload = true flag to the same method again.

(async()=>{letkraken=newccxt.kraken({verbose:true})// log HTTP requestsawaitkraken.loadMarkets()// request marketsconsole.log(kraken.id,kraken.markets)// output a full list of all loaded marketsconsole.log(Object.keys(kraken.markets))// output a short list of market symbolsconsole.log(kraken.markets['BTC/USD'])// output single market detailsawaitkraken.loadMarkets()// return a locally cached version, no reloadletreloadedMarkets=awaitkraken.loadMarkets(true)// force HTTP reload = trueconsole.log(reloadedMarkets['ETH/BTC'])})()

poloniex=ccxt.poloniex({'verbose':True})# log HTTP requestspoloniex.load_markets()# request marketsprint(poloniex.id,poloniex.markets)# output a full list of all loaded marketsprint(list(poloniex.markets.keys()))# output a short list of market symbolsprint(poloniex.markets['BTC/ETH'])# output single market detailspoloniex.load_markets()# return a locally cached version, no reloadreloadedMarkets=poloniex.load_markets(True)# force HTTP reload = Trueprint(reloadedMarkets['ETH/ZEC'])

$bitfinex =new \ccxt\bitfinex(array('verbose' =>true));// log HTTP requests$bitfinex.load_markets();// request marketsvar_dump($bitfinex->id,$bitfinex->markets);// output a full list of all loaded marketsvar_dump(array_keys ($bitfinex->markets));// output a short list of market symbolsvar_dump($bitfinex->markets['XRP/USD']);// output single market details$bitfinex->load_markets();// return a locally cached version, no reload$reloadedMarkets =$bitfinex->load_markets(true);// force HTTP reload = truevar_dump($bitfinex->markets['XRP/BTC']);

• API Methods / Endpoints
• Implicit API Methods
• Public/Private API
• Synchronous vs Asynchronous Calls
• Passing Parameters To API Methods

Each exchange offers a set of API methods. Each method of the API is called anendpoint. Endpoints are HTTP URLs for querying various types of information. All endpoints return JSON in response to client requests.

Usually, there is an endpoint for getting a list of markets from an exchange, an endpoint for retrieving an order book for a particular market, an endpoint for retrieving trade history, endpoints for placing and canceling orders, for money deposit and withdrawal, etc... Basically every kind of action you could perform within a particular exchange has a separate endpoint URL offered by the API.

Because the set of methods differs from exchange to exchange, the ccxt library implements the following:

• a public and private API for all possible URLs and methods
• a unified API supporting a subset of common methods

The endpoint URLs are predefined in theapi property for each exchange. You don't have to override it, unless you are implementing a new exchange API (at least you should know what you're doing).

Most of exchange-specific API methods are implicit, meaning that they aren't defined explicitly anywhere in code. The library implements a declarative approach for defining implicit (non-unified) exchanges' API methods.

Each method of the API usually has its own endpoint. The library defines all endpoints for each particular exchange in the.api property. Upon exchange construction an implicitmagic method (akapartial function orclosure) will be created insidedefineRestApi()/define_rest_api() on the exchange instance for each endpoint from the list of.api endpoints. This is performed for all exchanges universally. Each generated method will be accessible in bothcamelCase andunder_score notations.

The endpoints definition is afull list of ALL API URLs exposed by an exchange. This list gets converted to callable methods upon exchange instantiation. Each URL in the API endpoint list gets a corresponding callable method. This is done automatically for all exchanges, therefore the ccxt library supportsall possible URLs offered by crypto exchanges.

Each implicit method gets a unique name which is constructed from the.api definition. For example, a private HTTPS PUThttps://api.exchange.com/order/{id}/cancel endpoint will have a corresponding exchange method named.privatePutOrderIdCancel()/.private_put_order_id_cancel(). A public HTTPS GEThttps://api.exchange.com/market/ticker/{pair} endpoint would result in the corresponding method named.publicGetTickerPair()/.public_get_ticker_pair(), and so on.

An implicit method takes a dictionary of parameters, sends the request to the exchange and returns an exchange-specific JSON result from the APIas is, unparsed. To pass a parameter, add it to the dictionary explicitly under a key equal to the parameter's name. For the examples above, this would look like.privatePutOrderIdCancel ({ id: '41987a2b-...' }) and.publicGetTickerPair ({ pair: 'BTC/USD' }).

The recommended way of working with exchanges is not using exchange-specific implicit methods but using the unified ccxt methods instead. The exchange-specific methods should be used as a fallback in cases when a corresponding unified method isn't available (yet).

To get a list of all available methods with an exchange instance, including implicit methods and unified methods you can simply do the following:

console.log (new ccxt.kraken ())   // JavaScriptprint(dir(ccxt.kraken()))           # Pythonvar_dump (new \ccxt\kraken ()); // PHP

API URLs are often grouped into two sets of methods called apublic API for market data and aprivate API for trading and account access. These groups of API methods are usually prefixed with a word 'public' or 'private'.

A public API is used to access market data and does not require any authentication whatsoever. Most exchanges provide market data openly to all (under their rate limit). With the ccxt library anyone can access market data out of the box without having to register with the exchanges and without setting up account keys and passwords.

Public APIs include the following:

• instruments/trading pairs
• price feeds (exchange rates)
• order books (L1, L2, L3...)
• trade history (closed orders, transactions, executions)
• tickers (spot / 24h price)
• OHLCV series for charting
• other public endpoints

The private API is mostly used for trading and for accessing account-specific private data, therefore it requires authentication. You have to get the private API keys from the exchanges. It often means registering with an exchange website and creating the API keys for your account. Most exchanges require personal information or identification. Some exchanges will only allow trading after completing the KYC verification.Private APIs allow the following:

• manage personal account info
• query account balances
• trade by making market and limit orders
• create deposit addresses and fund accounts
• request withdrawal of fiat and crypto funds
• query personal open / closed orders
• query positions in margin/leverage trading
• get ledger history
• transfer funds between accounts
• use merchant services

Some exchanges offer the same logic under different names. For example, a public API is also often calledmarket data,basic,market,mapi,api,price, etc... All of them mean a set of methods for accessing data available to public. A private API is also often calledtrading,trade,tapi,exchange,account, etc...

A few exchanges also expose a merchant API which allows you to create invoices and accept crypto and fiat payments from your clients. This kind of API is often calledmerchant,wallet,payment,ecapi (for e-commerce).

To get a list of all available methods with an exchange instance, you can simply do the following:

console.log (new ccxt.kraken ())   // JavaScriptprint(dir(ccxt.kraken()))           # Pythonvar_dump (new \ccxt\kraken ()); // PHP

contract only and margin only

• methods in this documentation that are documented ascontract only ormargin only are only intended to be used for contract trading and margin trading respectively. They may work when trading in other types of markets but will most likely return irrelevant information.

In the JavaScript version of CCXT all methods are asynchronous and returnPromises that resolve with a decoded JSON object. In CCXT we use the modernasync/await syntax to work with Promises. If you're not familiar with that syntax, you can read more about ithere.

// JavaScript(async()=>{letpairs=awaitkraken.publicGetSymbolsDetails()letmarketIds=Object.keys(pairs['result'])letmarketId=marketIds[0]letticker=awaitkraken.publicGetTicker({pair:marketId})console.log(kraken.id,marketId,ticker)})()

The ccxt library supports asynchronous concurrency mode in Python 3.5+ with async/await syntax. The asynchronous Python version uses pureasyncio withaiohttp. In async mode you have all the same properties and methods, but most methods are decorated with an async keyword. If you want to use async mode, you should link against theccxt.async_support subpackage, like in the following example:

# Pythonimportasyncioimportccxt.async_supportasccxtasyncdefprint_poloniex_ethbtc_ticker():poloniex=ccxt.poloniex()print(awaitpoloniex.fetch_ticker('ETH/BTC'))awaitpolonix.close()# close the exchange instance when you don't need it anymoreasyncio.run(print_poloniex_ethbtc_ticker())

CCXT support PHP 8+ versions. The library has both synchronous and asynchronous versions. To use synchronous version, use\ccxt namespace (i.e.new ccxt\binance()) and to use asynchronous version, use\ccxt\async namespace (i.e.new ccxt\async\binance()). Asynchronous version usesReactPHP library in the background. In async mode you have all the same properties and methods, but any networking API method should be decorated with the\React\Async\await keyword and your script should be in a ReactPHP wrapper:

// PHP<?phpinclude'vendor/autoload.php';usefunctionReact\Async\await;$okx =new \ccxt\async\okx();while (true) {$result =await($okx->fetch_ticker('ETH/BTC'));var_dump($result);}

See further examples in theexamples/php directory; look for filenames that include theasync word. Also, make sure you have installed the required dependencies usingcomposer require recoil/recoil clue/buzz-react react/event-loop recoil/react react/http. Lastly,this article provides a good introduction to the methods used here. While syntactically the change is simple (i.e., just using ayield keyword before relevant methods), concurrency has significant implications for the overall design of your code.

All public and private API methods return raw decoded JSON objects in response from the exchanges, as is, untouched. The unified API returns JSON-decoded objects in a common format and structured uniformly across all exchanges.

The set of all possible API endpoints differs from exchange to exchange. Most of methods accept a single associative array (or a Python dict) of key-value parameters. The params are passed as follows:

bitso.publicGetTicker ({ book: 'eth_mxn' })                 // JavaScriptccxt.zaif().public_get_ticker_pair ({ 'pair': 'btc_jpy' })  # Python$luno->public_get_ticker (array ('pair' => 'XBTIDR'));      // PHP

The unified methods of exchanges might expect and will accept variousparams which affect their functionality, like:

params= {'type':'margin','isIsolated':'TRUE'}# --------------┑# params will go as the last argument to the unified method       |#                                                                 vbinance.create_order('BTC/USDT','limit','buy',amount,price,params)

An exchange will not accept the params from a different exchange, they're not interchangeable. The list of accepted parameters is defined by each specific exchange.

To find which parameters can be passed to a unified method:

• either open theexchange-specific implementation file and search for the desired function (i.e.createOrder) to inspect and find out the details ofparams usage
• or go to the exchange's API docs and read the list of parameters for your specific function or endpoint (i.e.order)

For a full list of accepted method parameters for each exchange, please consultAPI docs.

An exchange method name is a concatenated string consisting of type (public or private), HTTP method (GET, POST, PUT, DELETE) and endpoint URL path like in the following examples:

The ccxt library supports both camelcase notation (preferred in JavaScript) and underscore notation (preferred in Python and PHP), therefore all methods can be called in either notation or coding style in any language. Both of these notations work in JavaScript, Python and PHP:

exchange.methodName ()  // camelcase pseudocodeexchange.method_name()  // underscore pseudocode

To get a list of all available methods with an exchange instance, you can simply do the following:

console.log (new ccxt.kraken ())   // JavaScriptprint(dir(ccxt.hitbtc()))           # Pythonvar_dump (new \ccxt\okcoin ()); // PHP

• Overriding Unified API Params
• Pagination
• Automatic Pagination

The unified ccxt API is a subset of methods common among the exchanges. It currently contains the following methods:

• fetchMarkets (): Fetches a list of all available markets from an exchange and returns an array of markets (objects with properties such assymbol,base,quote etc.). Some exchanges do not have means for obtaining a list of markets via their online API. For those, the list of markets is hardcoded.
• fetchCurrencies (): Fetches all available currencies an exchange and returns an associative dictionary of currencies (objects with properties such ascode,name, etc.). Some exchanges do not have means for obtaining currencies via their online API. For those, the currencies will be extracted from market pairs or hardcoded.
• loadMarkets ([reload]): Returns the list of markets as an object indexed by symbol and caches it with the exchange instance. Returns cached markets if loaded already, unless thereload = true flag is forced.
• fetchOrderBook (symbol, limit = undefined, params = {}): Fetch L2/L3 order book for a particular market trading symbol.
• fetchStatus (params = {}): Returns information regarding the exchange status from either the info hardcoded in the exchange instance or the API, if available.
• fetchL2OrderBook (symbol, limit = undefined, params): Level 2 (price-aggregated) order book for a particular symbol.
• fetchTrades (symbol, since, limit, params): Fetch recent trades for a particular trading symbol.
• fetchTicker (symbol): Fetch latest ticker data by trading symbol.
• fetchBalance (): Fetch Balance.
• createOrder (symbol, type, side, amount, price, params)
• createOrders(orders, params)
• createLimitBuyOrder (symbol, amount, price, param)
• createLimitSellOrder (symbol, amount, price, param)
• createMarketBuyOrder (symbol, amount, param)
• createMarketSellOrder (symbol, amount, param)
• cancelOrder (id, symbol, params)
• fetchOrder (id, symbol, params)
• fetchOrders (symbol, since, limit, params)
• fetchOpenOrders (symbol, since, limit, params)
• fetchCanceledOrders (symbol, since, limit, params)
• fetchClosedOrders (symbol, since, limit, params)
• fetchMyTrades (symbol, since, limit, params)
• fetchOpenInterest (symbol, params)
• fetchVolatilityHistory (code, params)
• fetchUnderlyingAssets ()
• fetchSettlementHistory (symbol, since, limit, params)
• fetchLiquidations (symbol, since, limit, params)
• fetchMyLiquidations (symbol, since, limit, params)
• fetchGreeks (symbol, params)
• fetchAllGreeks (symbols, params)
• fetchCrossBorrowRate (code, params)
• fetchCrossBorrowRates (params)
• fetchIsolatedBorrowRate (symbol, params)
• fetchIsolatedBorrowRates (params)
• fetchOption (symbol, params)
• fetchOptionChain (code, params)
• fetchConvertQuote (fromCode, toCode, amount, params)
• createConvertTrade (id, fromCode, toCode, amount, params)
• fetchFundingRate (symbol, params)
• fetchFundingRates (symbols, params)
• fetchFundingRateHistory (symbol, since, limit, params)
• fetchFundingRateInterval (symbol, params)
• fetchFundingRateIntervals (symbols, params)
• fetchLongShortRatio (symbol, params)
• ...

TODO: better formatting

Note, that most of methods of the unified API accept an optionalparams argument. It is an associative array (a dictionary, empty by default) containing the params you want to override. The contents ofparams are exchange-specific, consult the exchanges' API documentation for supported fields and values. Use theparams dictionary if you need to pass a custom setting or an optional parameter to your unified query.

(async()=>{constparams={'foo':'bar',// exchange-specific overrides in unified queries'Hello':'World!',// see their docs for more details on parameter names}// the overrides go into the last argument to the unified call ↓ HEREconstresult=awaitexchange.fetchOrderBook(symbol,length,params)})()

params= {'foo':'bar',# exchange-specific overrides in unified queries'Hello':'World!',# see their docs for more details on parameter names}# overrides go in the last argument to the unified call ↓ HEREresult=exchange.fetch_order_book(symbol,length,params)

$params = array ('foo' =>'bar',// exchange-specific overrides in unified queries'Hello' =>'World!',// see their docs for more details on parameter names}// overrides go into the last argument to the unified call ↓ HERE$result =$exchange->fetch_order_book ($symbol,$length,$params);

Most of unified methods will return either a single object or a plain array (a list) of objects (trades, orders, transactions and so on). However, very few exchanges (if any at all) will return all orders, all trades, all ohlcv candles or all transactions at once. Most often their APIslimit output to a certain number of most recent objects.YOU CANNOT GET ALL OBJECTS SINCE THE BEGINNING OF TIME TO THE PRESENT MOMENT IN JUST ONE CALL. Practically, very few exchanges will tolerate or allow that.

To fetch historical orders or trades, the user will need to traverse the data in portions or "pages" of objects. Pagination often implies"fetching portions of data one by one" in a loop.

In most cases users arerequired to use at least some type of pagination in order to get the expected results consistently. If the user does not apply any pagination, most methods will return the exchanges' default, which may start from the beginning of history or may be a subset of most recent objects. The default behaviour (without pagination) is exchange-specific! The means of pagination are often used with the following methods in particular:

• fetchTrades()
• fetchOHLCV()
• fetchOrders()
• fetchCanceledOrders()
• fetchClosedOrder()
• fetchClosedOrders()
• fetchOpenOrder()
• fetchOpenOrders()
• fetchMyTrades()
• fetchTransactions()
• fetchDeposit()
• fetchDeposits()
• fetchWithdrawals()

With methods returning lists of objects, exchanges may offer one or more types of pagination. CCXT unifiesdate-based pagination by default, with timestampsin milliseconds throughout the entire library.

Warning: this is an experimental feature and might produce unexpected/incorrect results in some instances.

Recently, CCXT introduced a way to paginate through several results automatically by just providing thepaginate flag insideparams, lifting this work from the userland. Most leading exchanges support it, and more will be added in the future, but the easiest way to check it is to look in the method's documentation and search for thepagination parameter. As always there are exceptions, and some endpoints might not provide a way to paginate either through a timestamp or a cursor, and in those cases, there's nothing CCXT can do about it.

Right now, we have three different ways of paginating:

• dynamic/time-based: uses theuntil andsince parameters to paginate through dynamic results like (trades, orders, transactions, etc). Since we don't know a priori how many entries are available to be fetched, it will perform one request at a time until we reach the end of the data or the maximum amount of pagination calls (configurable through an option)
• deterministic: when we can pre-compute the boundaries of each page, it will perform the requests concurrently for maximum performance. This applies to OHLCV, Funding Rates, and Open Interest and also respects thepaginationCalls option.
• cursor-based: when the exchange provides a cursor inside the response, we extract the cursor and perform the subsequent request until the end of the data or reach the maximum number of pagination calls.

The user cannot select the pagination method used, it will depend from implementation to implementation, considering the exchange API's features.

We can't perform an infinite amount of requests, and some of them might throw an error for different reasons, thus, we have some options that allow the user to control these variables and other pagination specificities.

All the options below, should be provided insideparams, you can check the examples below

• paginate: (boolean) indicates that the user wants to paginate through different pages to get more data. Default isfalse.
• paginationCalls: (integer) allows the user to control the maximum amount of requests to paginate the data. Due to the rate limits, this value should not be too high. Default is 10.
• maxRetries: (integer) how many times should the pagination mechanism retry upon getting an error. Default is 3
• paginationDirection: (string) Only applies to the dynamic pagination and it can be eitherforward (start the pagination from some time in the past and paginate forward) orbackward (start from the most recent time and paginate backward). Ifforward is selected then asince parameter must also be provided. Default isbackward.
• maxEntriesPerRequest: (integer): The max amount of entries per request so that we can maximize the data retrieved per call. It varies from endpoint to endpoint and CCXT will populate this value for you, but you can override it if needed.

trades=awaitbinance.fetch_trades("BTC/USDT",params= {"paginate":True})# dynamic/time-basedohlcv=awaitbinance.fetch_ohlcv("BTC/USDT",params= {"paginate":True,"paginationCalls":5})# deterministic-pagination will perform 5 requeststrades=awaitbinance.fetch_trades("BTC/USDT",since=1664812416000,params= {"paginate":True,"paginationDirection":"forward"})# dynamic/time-based pagination starting from 1664812416000ledger=awaitbybit.fetch_ledger(params= {"paginate":True})# bybit returns a cursor so the pagination will be cursor-basedfunding_rates=awaitbinance.fetch_funding_rate_history("BTC/USDT:USDT",params= {"paginate":True,"maxEntriesPerRequest":50})# customizes the number of entries per request

All unified timestamps throughout the CCXT library are integersin milliseconds unless explicitly stated otherwise.

Below is the set of methods for working with UTC dates and timestamps and for converting between them:

exchange.parse8601('2018-01-01T00:00:00Z')==1514764800000// integer in milliseconds, Z = UTCexchange.iso8601(1514764800000)=='2018-01-01T00:00:00Z'// from milliseconds to iso8601 stringexchange.seconds()// integer UTC timestamp in secondsexchange.milliseconds()// integer UTC timestamp in milliseconds

This is the type of pagination currently used throughout the CCXT Unified API. The user supplies asince timestampin milliseconds (!) and a number tolimit results. To traverse the objects of interest page by page, the user runs the following (below is pseudocode, it may require overriding some exchange-specific params, depending on the exchange in question):

if(exchange.has['fetchTrades']){letsince=exchange.milliseconds()-86400000// -1 day from now// alternatively, fetch from a certain starting datetime// let since = exchange.parse8601 ('2018-01-01T00:00:00Z')letallTrades=[]while(since<exchange.milliseconds()){constsymbol=undefined// change for your symbolconstlimit=20// change for your limitconsttrades=awaitexchange.fetchTrades(symbol,since,limit)if(trades.length){since=trades[trades.length-1]['timestamp']+1allTrades=allTrades.concat(trades)}else{break}}}

ifexchange.has['fetchOrders']:since=exchange.milliseconds ()-86400000# -1 day from now# alternatively, fetch from a certain starting datetime# since = exchange.parse8601('2018-01-01T00:00:00Z')all_orders= []whilesince<exchange.milliseconds ():symbol=None# change for your symbollimit=20# change for your limitorders=awaitexchange.fetch_orders(symbol,since,limit)iflen(orders):since=orders[len(orders)-1]['timestamp']+1all_orders+=orderselse:break

if ($exchange->has['fetchMyTrades']) {$since = exchange->milliseconds () -86400000;// -1 day from now// alternatively, fetch from a certain starting datetime// $since = $exchange->parse8601 ('2018-01-01T00:00:00Z');$all_trades =array ();while (since < exchange->milliseconds ()) {$symbol =null;// change for your symbol$limit =20;// change for your limit$trades =$exchange->fetchMyTrades ($symbol,$since,$limit);if (count($trades)) {$since =$trades[count($trades) -1]['timestamp'] +1;$all_trades =array_merge ($all_trades,$trades);        }else {break;        }    }}

The user supplies afrom_id of the object, from where the query should continue returning results, and a number tolimit results. This is the default with some exchanges, however, this type is not unified (yet). To paginate objects based on their ids, the user would run the following:

if(exchange.has['fetchTrades']){letfrom_id='abc123'// all ids are stringsletallTrades=[]while(true){constsymbol=undefined// change for your symbolconstsince=undefinedconstlimit=20// change for your limitconstparams={'from_id':from_id,// exchange-specific non-unified parameter name}consttrades=awaitexchange.fetchTrades(symbol,since,limit,params)if(trades.length){from_id=trades[trades.length-1]['id']allTrades.push(trades)}else{break}}}

ifexchange.has['fetchOrders']:from_id='abc123'# all ids are stringsall_orders= []whileTrue:symbol=None# change for your symbolsince=Nonelimit=20# change for your limitparams= {'from_id':from_id,# exchange-specific non-unified parameter name        }orders=awaitexchange.fetch_orders(symbol,since,limit,params)iflen(orders):from_id=orders[len(orders)-1]['id']all_orders+=orderselse:break

if ($exchange->has['fetchMyTrades']) {$from_id ='abc123'// all ids are strings$all_trades =array ();while (true) {$symbol =null;// change for your symbol$since =null;$limit =20;// change for your limit$params =array ('from_id' =>$from_id,// exchange-specific non-unified parameter name        );$trades =$exchange->fetchMyTrades ($symbol,$since,$limit,$params);if (count($trades)) {$from_id =$trades[count($trades) -1]['id'];$all_trades =array_merge ($all_trades,$trades);        }else {break;        }    }}

The user supplies a page number or aninitial "cursor" value. The exchange returns a page of results and thenext "cursor" value, to proceed from. Most of exchanges that implement this type of pagination will either return the next cursor within the response itself or will return the next cursor values within HTTP response headers.

See an example implementation here:https://github.com/ccxt/ccxt/blob/master/examples/py/coinbasepro-fetch-my-trades-pagination.py

Upon each iteration of the loop the user has to take the next cursor and put it into the overrided params for the next query (on the following iteration):

if(exchange.has['fetchTrades']){letpage=0// exchange-specific type and valueletallTrades=[]while(true){constsymbol=undefined// change for your symbolconstsince=undefinedconstlimit=20// change for your limitconstparams={'page':page,// exchange-specific non-unified parameter name}consttrades=awaitexchange.fetchTrades(symbol,since,limit,params)if(trades.length){// not thread-safu and exchange-specific !last_json_response=exchange.parseJson(exchange.last_http_response)page=last_json_response['cursor']allTrades.push(trades)}else{break}}}

ifexchange.has['fetchOrders']:cursor=0# exchange-specific type and valueall_orders= []whileTrue:symbol=None# change for your symbolsince=Nonelimit=20# change for your limitparams= {'cursor':cursor,# exchange-specific non-unified parameter name        }orders=awaitexchange.fetch_orders(symbol,since,limit,params)iflen(orders):# not thread-safu and exchange-specific !cursor=exchange.last_response_headers['CB-AFTER']all_orders+=orderselse:break

if ($exchange->has['fetchMyTrades']) {$start ='0'// exchange-specific type and value$all_trades =array ();while (true) {$symbol =null;// change for your symbol$since =null;$limit =20;// change for your limit$params =array ('start' =>$start,// exchange-specific non-unified parameter name        );$trades =$exchange->fetchMyTrades ($symbol,$since,$limit,$params);if (count($trades)) {// not thread-safu and exchange-specific !$last_json_response =$exchange->parse_json ($exchange->last_http_response);$start =$last_json_response['next'];$all_trades =array_merge ($all_trades,$trades);        }else {break;        }    }}

• Order Book
• Price Tickers
• OHLCV Candlestick Charts
• Public Trades
• Exchange Time
• Exchange Status
• Borrow Rates
• Borrow Rate History
• Leverage Tiers
• Funding Rate
• Funding Rate History
• Open Interest History
• Volatility History
• Underlying Assets
• Liquidations
• Greeks
• OptionChain

Exchanges expose information on open orders with bid (buy) and ask (sell) prices, volumes and other data. Usually there is a separate endpoint for querying current state (stack frame) of theorder book for a particular market. An order book is also often calledmarket depth. The order book information is used in the trading decision making process.

To get data on order books, you can use

• fetchOrderBook () // for a single markets order books
• fetchOrderBooks ( symbols ) // for multiple markets order books
• fetchOrderBooks () // for the order books of all markets

asyncfetchOrderBook(symbol,limit=undefined,params={})

Parameters

• symbol (String)required Unified CCXT symbol (e.g."BTC/USDT")
• limit (Integer) The number of orders to return in the order book (e.g.10)
• params (Dictionary) Extra parameters specific to the exchange API endpoint (e.g.{"endTime": 1645807945000})

Returns

• Anorder book structure

asyncfetchOrderBooks(symbols=undefined,limit=undefined,params={})

Parameters

• symbols ([String]) Unified CCXT symbols (e.g.["BTC/USDT", "ETH/USDT"])
• limit (Integer) The number of orders to return in the order book (e.g.10)
• params (Dictionary) Extra parameters specific to the exchange API endpoint (e.g.{"endTime": 1645807945000})

Returns

• A dictionary oforder book structures indexed by market symbols

delay=2000// milliseconds = seconds * 1000(async()=>{for(symbolinexchange.markets){console.log(awaitexchange.fetchOrderBook(symbol))awaitnewPromise(resolve=>setTimeout(resolve,delay))// rate limit}})()

importtimedelay=2# secondsforsymbolinexchange.markets:print (exchange.fetch_order_book (symbol))time.sleep (delay)# rate limit

$delay =2000000;// microseconds = seconds * 1000000foreach ($exchange->marketsas$symbol =>$market) {var_dump ($exchange->fetch_order_book ($symbol));usleep ($delay);// rate limit}

{'bids':[[price,amount],// [ float, float ][price,amount],        ...],'asks':[[price,amount],[price,amount],        ...],'symbol':'ETH/BTC',// a unified market symbol'timestamp':1499280391811,// Unix Timestamp in milliseconds (seconds * 1000)'datetime':'2017-07-05T18:47:14.692Z',// ISO8601 datetime string with milliseconds'nonce':1499280391811,// an increasing unique identifier of the orderbook snapshot}

The timestamp and datetime may be missing (undefined/None/null) if the exchange in question does not provide a corresponding value in the API response.

Prices and amounts are floats. The bids array is sorted by price in descending order. The best (highest) bid price is the first element and the worst (lowest) bid price is the last element. The asks array is sorted by price in ascending order. The best (lowest) ask price is the first element and the worst (highest) ask price is the last element. Bid/ask arrays can be empty if there are no corresponding orders in the order book of an exchange.

Exchanges may return the stack of orders in various levels of details for analysis. It is either in full detail containing each and every order, or it is aggregated having slightly less detail where orders are grouped and merged by price and volume. Having greater detail requires more traffic and bandwidth and is slower in general but gives a benefit of higher precision. Having less detail is usually faster, but may not be enough in some very specific cases.

• Theorderbook['timestamp'] is the time when the exchange generated this orderbook response (before replying it back to you). This may be missing (undefined/None/null), as documented in the Manual, not all exchanges provide a timestamp there. If it is defined, then it is the UTC timestampin milliseconds since 1 Jan 1970 00:00:00.
• Some exchanges may index orders in the orderbook by order ids, in that case the order id may be returned as the third element of bids and asks:[ price, amount, id ]. This is often the case with L3 orderbooks without aggregation. The orderid, if shown in the orderbook, refers to the orderbook and does not necessarily correspond to the actual order id from the exchanges' database as seen by the owner or by the others. The order id is anid of the row inside the orderbook, but not necessarily the true-id of the order (though, they may be equal as well, depending on the exchange in question).
• In some cases the exchanges may supply L2 aggregated orderbooks with order counts for each aggregated level, in that case the order count may be returned as the third element of bids and asks:[ price, amount, count ]. Thecount tells how many orders are aggregated on each price level in bids and asks.
• Also, some exchanges may return the order timestamp as the third element of bids and asks:[ price, amount, timestamp ]. Thetimestamp tells when the order was placed on the orderbook.

Some exchanges accept a dictionary of extra parameters to thefetchOrderBook () / fetch_order_book () function.All extraparams are exchange-specific (non-unified). You will need to consult exchanges docs if you want to override a particular param, like the depth of the order book. You can get a limited count of returned orders or a desired level of aggregation (akamarket depth) by specifying an limit argument and exchange-specific extraparams like so:

(asyncfunctiontest(){constccxt=require('ccxt')constexchange=newccxt.bitfinex()constlimit=5constorders=awaitexchange.fetchOrderBook('BTC/USD',limit,{// this parameter is exchange-specific, all extra params have unique names per exchange'group':1,// 1 = orders are grouped by price, 0 = orders are separate})})()

importccxt# return up to ten bidasks on each side of the order book stacklimit=10ccxt.cex().fetch_order_book('BTC/USD',limit)

// instantiate the exchange by id$exchange ='\\ccxt\\kraken';$exchange =new$exchange ();// up to ten orders on each side, for example$limit =20;var_dump ($exchange->fetch_order_book ('BTC/USD',$limit));

The levels of detail or levels of order book aggregation are often number-labelled like L1, L2, L3...

• L1: less detail for quickly obtaining very basic info, namely, the market price only. It appears to look like just one order in the order book.
• L2: most common level of aggregation where order volumes are grouped by price. If two orders have the same price, they appear as one single order for a volume equal to their total sum. This is most likely the level of aggregation you need for the majority of purposes.
• L3: most detailed level with no aggregation where each order is separate from other orders. This LOD naturally contains duplicates in the output. So, if two orders have equal prices they arenot merged together and it's up to the exchange's matching engine to decide on their priority in the stack. You don't really need L3 detail for successful trading. In fact, you most probably don't need it at all. Therefore some exchanges don't support it and always return aggregated order books.

If you want to get an L2 order book, whatever the exchange returns, use thefetchL2OrderBook(symbol, limit, params) orfetch_l2_order_book(symbol, limit, params) unified method for that.

Thelimit argument does not guarantee that the number of bids or asks will always be equal tolimit. It designates the upper boundary or the maximum, so at some moment in time there may be less thanlimit bids or asks. This is the case when the exchange does not have enough orders on the orderbook. However, if the underlying exchange API does not support alimit parameter for the orderbook endpoint at all, then thelimit argument will be ignored. CCXT does not trimbids andasks if the exchange returns more than you request.

In order to get current best price (query market price) and calculate bidask spread take first elements from bid and ask, like so:

letorderbook=awaitexchange.fetchOrderBook(exchange.symbols[0])letbid=orderbook.bids.length ?orderbook.bids[0][0] :undefinedletask=orderbook.asks.length ?orderbook.asks[0][0] :undefinedletspread=(bid&&ask) ?ask-bid :undefinedconsole.log(exchange.id,'market price',{ bid, ask, spread})

orderbook=exchange.fetch_order_book (exchange.symbols[0])bid=orderbook['bids'][0][0]iflen (orderbook['bids'])>0elseNoneask=orderbook['asks'][0][0]iflen (orderbook['asks'])>0elseNonespread= (ask-bid)if (bidandask)elseNoneprint (exchange.id,'market price', {'bid':bid,'ask':ask,'spread':spread })

$orderbook =$exchange->fetch_order_book ($exchange->symbols[0]);$bid =count ($orderbook['bids']) ?$orderbook['bids'][0][0] :null;$ask =count ($orderbook['asks']) ?$orderbook['asks'][0][0] :null;$spread = ($bid &&$ask) ?$ask -$bid :null;$result =array ('bid' =>$bid,'ask' =>$ask,'spread' =>$spread);var_dump ($exchange->id,'market price',$result);

A price ticker contains statistics for a particular market/symbol for some period of time in recent past, usually last 24 hours. The methods for fetching tickers are described below.

// one tickerfetchTicker(symbol,params={})// examplefetchTicker('ETH/BTC')fetchTicker('BTC/USDT')

// multiple tickersfetchTickers(symbols=undefined,params={})// for all tickers at once// for examplefetchTickers()// all symbolsfetchTickers(['ETH/BTC','BTC/USDT'])// an array of specific symbols