OrderRouter is two things, and either works without the other

A client for the routing service, which holds live order books across roughly 60 venues and answers “what is the cheapest way to turn asset X into asset Y right now, and on which venues?” — book-walked to your actual size, fee-adjusted, and split across venues when that beats any single one.

A multi-venue execution engine for plans you build yourself. It never asks where a plan came from, so your own strategy gets the notional cap, reconciliation between hops, resting-order cleanup and the unwind plan. This half needs no service at all.

It is not an exchange. It does not extend Exchange, has no unified methods, and is constructed directly.

The whole pipeline is two calls

const venues = { mexc: new ccxt.mexc ({ apiKey: '…', secret: '…' }) };
const router = new ccxt.OrderRouter ({ venues });

const route  = await router.fetchRoute ('USDT', 'BTC', { amountIn: 20 });
const report = await router.execute (route);

The routing service

Every endpoint is public. No API key, no signup, no login. It rate-limits by client IP instead: 5 requests per second on a fixed one-second window. Every response carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset, and a 429 carries retry-after — trust those headers over any figure written down.

The client still accepts an apiKey and sends it as x-api-key when you pass one, so a deployment that fronts the service with its own authentication keeps working. With no key the header is omitted entirely rather than sent empty.

The full contract is published as OpenAPI 3.1 at docs.ccxt.com/router/openapi.yaml.

An unroutable pair is an answer, not an error

When nothing can be routed, fetchRoute returns a normal result carrying unroutableReason — it does not throw. Refusing to quote is a deliberate outcome.

Two modes for venues

Handing the router your venues says where you can trade: routes are filtered to them, and execute sends orders to those same instances. That filter costs nothing, touches no venue and cannot go stale, so it is always on.

Whether the router also reads your wallets is a separate mode, because it is a separate decision with a real price — one authenticated call per venue, holdings that go stale the moment anything moves, and a bad key on any one venue failing the whole quote.

There is deliberately nothing in between, and no expiry to tune. A router that half-knows your balances is worse than one that knows none of them.

Under trackBalances the wallets are read once and cached, the way loadMarkets caches, so a quote stays a single HTTP request however often you call it. loadBalances() primes that cache at start-up and loadBalances(true) refreshes it — but you rarely need either, because a live execute drops the cache itself. Placing an order is precisely what makes cached holdings wrong, and it is dropped before dispatch: a run that throws half way through has still moved money. A rehearsal reaches no venue and keeps the cache.

For real-time holdings, drive it yourself — watchBalance() on your own pro instances, then router.invalidateBalances(). The router never opens a socket you did not open.

What execute does before it sends anything

execute accepts a route as well as a plan, and does the rest itself: builds the plan, loads each venue's markets, and runs the safety check against that venue's real market rules. It throws on a blocking violation rather than returning it — a refusal a caller can forget to read is not a refusal.

The two advisory codes fire on essentially every real route and are not failures. Plan-level codes — empty_plan, route_unroutable, partial_fill — behave the same way.

The check is pure and public, so you can run it yourself without the throw: checkExecutionPlanSafety(plan, markets, options), with marketsOf(venues) building the markets argument.

Defaults

Guarantees that hold whatever you configure

• A plan already executed live is refused. An in-process ledger keeps the last 1024 plan identities; pass allowReexecution to override deliberately.
• An outcome_unknown step is never retried, at any setting. It may already be a live position, and re-placing it is the double-fill this class exists to prevent.
• Halt is a return value, not an exception. report.halted, haltStepIndex and haltReason say where and why a run stopped; openOrders says what was left resting and why.
• No client order id is set for you. Venues disagree on length and charset, so whatever you put in options.orderParams travels untouched.
• The cap is checked before dispatch, never after. A cap checked afterwards is an incident report.

Balances take the shape you would write

{ balances: { mexc: { USDT: 100, BTC: 0.5 } } }   // per venue
{ balances: { USDT: 100 } }                        // wherever you hold it
{ balances: 'mexc.USDT:100,mexc.BTC:0.5' }         // already rendered

Anything that cannot be rendered is refused locally, naming both accepted forms, rather than travelling to the service to be rejected there.

Errors

Over a websocket the same vocabulary applies: close code 1008 maps to BadRequest and 1013 to ExchangeNotAvailable, so there is no second set of names to learn.

Known limits

• Idempotency is in-process only. The ledger does not survive a restart, and evicts after 1024 executions. Recent duplicates are refused; duplicates are not impossible. Key idempotency at the venue yourself if you need the stronger promise.
• The re-execution check is not atomic under a same-instance race.
• Which venues honour a client order id is unmapped.
• /stream/route accepts no balances: a socket outlives the holdings it was opened with.

Reference for ccxt.OrderRouter, available in TypeScript, JavaScript, Python, PHP, C#, Go and Rust with identical behaviour.

Rust installs venues and the step hook through set_venues / set_on_step rather than constructor keys, because its Value type cannot carry them. The behaviour is the same.