cexy (Rust)
The official Rust SDK for the CEXY.io REST and WebSocket API.
- Typed models generated from the public OpenAPI spec (cexy-api-spec).
- Safe by default: retries with backoff, order placement designed to avoid duplicate orders (via
client_order_id), a client-side rate limiter, and no HTTP redirects followed. - A WebSocket client with heartbeat, reconnect and a live order book that applies the sync rules for you.
- Async on tokio, with reqwest and tokio-tungstenite over rustls (the
ringprovider and thewebpki-rootsMozilla root store, for REST and WebSocket alike). No OpenSSL, no system trust store, no C toolchain needed to build. - Rust 1.94 or newer.
Status: 0.x, pre-release. The API is not yet frozen. It stays 0.x until the exchange ships HMAC request signing, which will change how credentials are sent.
Install
[]
= "=0.1.0-dev.16"
= { = "1", = ["macros", "rt-multi-thread"] }
Cargo never picks a pre-release (a version with -dev.N) on its own: name it explicitly. The
exact requirement above (=0.1.0-dev.16) is the safest way; move it by hand for each new pre-release.
Quick start: public data
use ;
async
Quick start: your account
use ;
# async
Placing and cancelling need a key with the trade scope; everything else needs read.
Cancel-all
Cancel-all also cancels stop orders that have not triggered yet (pending_trigger) and releases their
reservations. One cancel_all call handles at most 500 orders. Every order it handled is in exactly one of
cancelled, already_closed (it closed on its own first: not a failure) and failed (the reason is
in failures; INVALID_STATE means the order was taken off the book and cannot be cancelled yet; the server cancels a pending order at once). has_more means there are
more. An unknown symbol is a NotFound error, and the server allows 30 cancel-all calls a minute.
cancel_all_until_done repeats the call until nothing is left: while has_more is set or a failure code is
SERVICE_UNAVAILABLE, MARKET_UNAVAILABLE or CONCURRENT_MODIFICATION. INVALID_STATE is returned,
not retried. A market that stays down returns only when the time budget ends. Each round is exactly one HTTP request (the loop does its own retrying, so it
never sends more than max_rounds requests). It backs off 1, 2, 4, 8, then 15 s after rounds without
progress or with a retryable error (a 503, a network failure), waits a 429's Retry-After exactly,
stops after max_rounds (default 20) or before a wait would reach time_budget (default 120 s; that
wait is not taken, and last_error_code says why), and merges the rounds by order id. A
non-retryable error returns Error::CancelAllInterrupted with the summary so far. The target is
explicit:
# async
Held incoming transfers
Balance::held_incoming lists incoming internal transfers still held, each a HeldIncoming with
transfer_id, amount and available_at. Their sum is already included in locked, so never
add it to locked or total again. There are at most 100 entries, soonest available_at first
(millisecond precision), with no sender identity. An entry disappears once the transfer is
released (the amount moves to available) or cancelled by the exchange. It is always a Vec
(empty when none, including from servers that predate the field).
Batch orders
Place up to 20 orders in one market with one request, or cancel up to 50:
# async
- Each order is placed (or cancelled) on its own: the batch is not atomic, and one refusal does
not stop the rest. Each result's
outcomeisPlaced(orCancelled),Failedwitherror,RecoveredorUnknown(below). The counts on the result are computed from the results. - Every order carries a
client_order_id; one (a UUID) is generated for each order without one. Your own ids must be 1 to 64 characters ofA-Z a-z 0-9 _ - . :, distinct within the batch, and unique per account across all markets. - Retries: the request body is built once; a retry after a timeout resends it unchanged, and the
server refuses every id it already placed, so nothing is placed twice. Such an order comes back as
Recoveredwith itsorder_idandstatus. A recovered order counts as placed unless its status isrejected, even if it endedcancelledwith nothing filled: readstatusbefore acting. Arejectedstatus means the server refused it for funds and its id is spent: do not place it again under that id.Unknownmeans its state could not be read; it was not placed again (look it up withorder_by_client_id). A cancel that a retry finds already closed is looked up and comes back asRecoveredwith its current status. - An item error that names an order (
MARKET_UNAVAILABLEwithdetails.order_id: the market stopped while matching) means the order exists: it comes backRecoveredwith its status, on any attempt. An itemINTERNALis looked up once by its id (Recovered, orUnknown). Reconcile everyUnknownitem withorder_by_client_idbefore placing it again. - A 400, 403 or 404 for the whole batch is returned at once, and a 429 is waited out and resent.
Such a refusal means the server placed nothing in that attempt; an earlier attempt whose
answer was lost may still have placed orders. A batch larger than the key's whole budget is a 400
with a number in
details["limit"]: send fewer at a time. The SDK never splits a batch. - When the call fails after its request is built (retries run out, a refusal after a lost
answer, a timeout, or a 200 that is unreadable or does not match the orders sent), the error is
Error::BatchPlacewith everyclient_order_idsent, in request order, andmaybe_placed(false only when every attempt was a definite refusal). Look those ids up, or send the same orders again with the same ids, before placing anything anew. - Supply and save your own
client_order_ids before the call if you need to reconcile (cexy::new_client_order_id()makes one). It is the only protection when the future is dropped, for example bytokio::time::timeout: a dropped call returns nothing.
Market buys by total
A market buy can name a budget, quote_quantity, instead of a quantity: "spend at most this
much of the quote asset".
# async
- The taker fee is inside the budget:
filled_quote_quantity + fee_paid <= quote_quantity, always. A stop-market buy by total reserves exactly the budget. - The budget must be at least the market's
min_notional. It may have at most the market's price decimals. More decimals are refused with 400PRECISION_EXCEEDED, never rounded. Trailing zeros are fine. - How it ends:
filled, with nostatus_reason, when the budget was used (what is left cannot buy one lot at the last fill price). The last WebSocket frame is thenorder.filled. Otherwise it endscancelledwith astatus_reason, for exampleInsufficient liquidity to fill the remainder(fills, but the book ran out) orBudget exhausted(no fill; the budget cannot buy one lot). - After a server restart mid-order, a budget order can end
cancelledwithInterrupted; the unfilled remainder was cancelled. Its fills stand and the rest is released: treat it like any partial fill. - Reading one:
quantityandremaining_quantityare0for a budget order. Progress isfilled_quote_quantity + fee_paidagainstquote_quantity. Never divide byquantity. - A budget bounds the money spent, not the price paid. On a thin book a market buy can fill far from the last price.
Amounts
Every amount is an exact decimal string (Amount::new("0.00150000")?), in responses and requests.
Floats cannot hold most decimals exactly. Amount::new accepts only plain decimals (no exponents, no
spaces), and the SDK checks every amount field again before sending (Error::InvalidAmount). Do
arithmetic with a decimal crate such as rust_decimal:
#
Errors
Every API failure is Error::Api(ApiError) with status, code, message, details, fields,
request_id, retryable and retry_after. Branch on code, never on message. Match the category
with err.is(ErrorCategory::…):
| Category | When |
|---|---|
Authentication |
401: missing or invalid credentials |
Forbidden |
403: the key lacks a scope (FORBIDDEN), or the route is session-only (API_KEY_NOT_ALLOWED); also matches 451 |
JurisdictionBlocked |
451: JURISDICTION_BLOCKED (not available in the caller's jurisdiction) |
Validation |
400: see fields |
NotFound |
404 |
Conflict |
409: ALREADY_EXISTS, IDEMPOTENCY_KEY_CONFLICT, CONCURRENT_MODIFICATION |
Unprocessable |
422: INSUFFICIENT_FUNDS, MARKET_UNAVAILABLE, ... |
RateLimited |
429, with retry_after |
Server |
5xx |
UnexpectedRedirect |
3xx: code UNEXPECTED_REDIRECT, set by the SDK (see Security) |
| (none) | a code this SDK version does not know yet: check code |
Local problems are Error::Config, Error::InvalidAmount, Error::Connection (with timeout for
the per-attempt timeout), Error::OrderStateUnknown and Error::CancelAllInterrupted. ErrorCode
is an open enum: codes added to the API later arrive as ErrorCode::Other(String), so keep a
wildcard arm.
# async
Retries and idempotency
- Timeout per attempt:
ClientOptions::timeout(default 10 s). Retries:max_retries(default 3;Some(0)turns them off), exponential backoff with full jitter, capped at 10 s. - Retried: connection errors, timeouts and responses with
retryable: true(and 409CONCURRENT_MODIFICATION). A 4xx is never retried except 429 and 409CONCURRENT_MODIFICATION, whatever its body says. - After a 429 with a wait hint, the client-side rate limiter holds every other request of the client for that wait (at most 120 s), not only the retried one. A key that keeps sending through its own limit counts against its IP's failed-key limit (120 a minute) and can lock out every other key on that IP. Market makers: run the cancel/risk key from its own egress IP; a separate key on the same IP is not isolated.
- A 429 waits at least
Retry-After/details.retry_after_seconds. - Batches and order budgets. A batch of N orders or cancel entries takes N tokens from the
client's limiter, as the server counts it. A market maker's key also has an order budget of 50
placements a second (per key and per account); cancels never count against it. A 429 whose
details["limit"]is"order_actions"holds only placements (place_order,place_orders) for its wait: reads and cancels keep going. SetClientOptions::order_actions_per_secondtoSome(50.0)to keep placements under that budget locally instead of being refused (off by default). - GETs retry freely.
- Orders: safety rests on
client_order_id, not onIdempotency-Key(the server does not honour that header on orders, order cancels or cancel-all, so the SDK sends it only on pool join and exit).place_orderalways sends aclient_order_id(a UUID if you do not set one); it is unique per account and a repeat is refused before any funds move. After an ambiguous failure (connection error, timeout, 5xx) the SDK first looks the order up by that id. If the order exists it is returned withrecovered: true; only if it does not exist is it sent again, with the same id. If even the lookup fails, or the order was accepted but its response could not be decoded, you getError::OrderStateUnknownwith theclient_order_id: checkorder_by_client_idbefore placing the order again. - Cancels:
cancel_orderretries connection errors; if a retry getsINVALID_STATE, the first attempt most likely cancelled the order, so the SDK fetches and returns it. Check the returnedstatus: it is usuallycancelled, but can befilledif the order traded before the cancel landed. Cancel-all is naturally repeatable and is retried the same way (a retry reports only what it cancelled); it sends noIdempotency-Key.cancel_all_until_donedoes its own retrying instead (one request per round, see above). - Server waits are bounded. A
Retry-After(ordetails.retry_after_seconds) up to 120 s (MAX_SERVER_WAIT) is honoured; a longer one is not waited: the call fails at once with the rate-limit error, whoseretry_afterstill says what the server asked. Unreadable values are ignored, andX-RateLimit-*headers never make the client-side limiter wait longer than 120 s. - Pool join and exit send a generated
Idempotency-Key, reused on every retry; the server honours it there, so they execute once. A 409CONCURRENT_MODIFICATION(the same key still in flight) is retried with the same key. Set it yourself withCallOptions::idempotency_key. ClientOptions::on_retrylets you log retries.
Per-call overrides: client.with_options(CallOptions { timeout: Some(..), max_retries: Some(..), idempotency_key: Some(..) })
returns a client that shares everything else with the original.
Pagination
Histories use opaque cursors. Each listing returns one Page (items, has_more, next_cursor), and
an all_… method returns a stream that fetches pages lazily:
# async
Futures data (read only)
client.futures() reads futures market data (public, no key needed) and the account's own futures
data (an API key with the read scope; requests are signed like every private call). Nothing here
places orders or moves funds. Coins are the provider's names, such as "BTC" or "kPEPE"; prices
and sizes are decimal strings.
# async
- Every market-data answer has
as_ofandstale; for books and trades,staleis the health of the live feed, not the data's age. When nothing usable is cached the API answers 503SERVICE_UNAVAILABLEwith Retry-After, which the normal retry policy waits out. - Without a futures account, the account reads answer
has_account: false(andall_fills/all_fundingyield nothing). fills(cursor)andfunding(cursor)return one page. The cursor is opaque: passnext_cursorback exactly as given. A page can be short, even empty, and still have anext_cursor: keep paging until it isNone.all_fills/all_fundingdo this for you. When the provider is busy (an empty page whosenext_cursoris the cursor just sent, or a 503 withdetails.reasonfutures_data_unavailable, also on the first request), they wait (the server's Retry-After, elsedetails.retry_after_seconds, as given; else the retry backoff) and ask again, at most 3 times (with_max_busy_retrieschanges it; the client'smax_retriesdoes not), then end withError::PagingStalled(codePAGING_STALLED, retryable; after a 503, itssource()is thatApiError). A page with rows that repeats the cursor just sent ends them withError::PagingCursorRepeated(not retryable). Either way, the rows before the error are not the whole history.
Rate limits
The client has a token-bucket limiter: 100 requests a minute without a key (the server allows
120 a minute per IP for anonymous calls) and 300 a minute with an API key (the server allows 600 a
minute per key). Cancel-all is limited separately to 30 a minute per account. It adapts downwards to
X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset (seconds until the window resets),
and pauses after a 429. Change it with requests_per_minute, or turn it off with disable_rate_limit.
The limiter belongs to one Client; clones share it, so clone the client rather than creating new ones.
WebSocket
# async
Everything the client reports arrives, in order, on the event channel from ws.events(). Read it
continuously: when its buffer (event_buffer, default 10 000) is full, new events are dropped and
counted in ws.dropped_events(). Live order books keep updating either way (book.snapshot()).
What the client does for you:
- Sends
{"op":"ping"}every 30 s (ping_interval; above 60 s is a configuration error: the server closes connections whose client is silent for 90 s) and accepts the server's unsolicited pongs. No frame from the server for 75 s (liveness_timeout; the client's own pings do not count) means a dead connection and a reconnect. - Reconnects with exponential backoff and full jitter, then re-authenticates and re-subscribes everything.
- Correlates every request with its acknowledgement by
id:authreturns onauthenticated(and fails on anerrorwith its id, or on timeout),subscribeonsubscribed,unsubscribeonunsubscribed,pingonpong. - Collects a subscribe's refusals: the server sends one
errorframe (with the request id) per refused channel before itssubscribedack, and no ack when it refused them all.subscribereturns the accepted channels inaddedand the refused ones with their errors inrejected, and fails only when every channel sent was refused (no answer at all withinack_timeoutis aTIMEOUTerror; those channels stay held). Refused channels are not held and not retried. When the automatic re-subscription after a reconnect or re-auth is refused, a private channel refused asUNAUTHENTICATEDwaits for the next auth; any other refusal drops it (reported asWsEvent::Error). - Guards locally: at most 100 subscriptions (extras are returned in
refused) and 200 messages a minute. - Warns once (
WsEvent::Warning) if the server speaks anotherprotocol_version, and ignores unknown event types.
Order-book rules (applied by ws.order_book; follow them if you build your own):
- Subscribe to
orderbook:{symbol}first, then take the REST snapshot (itssequenceis S). - Drop updates with
sequence <= S. - Every update carries the complete top 50 of both sides (
"full": true) and replaces the previous state. There are no deltas. Never merge REST levels deeper than 50 into WebSocket state. - A sequence gap marks the book stale until the next update, which heals it. There is no forced resync.
- Sequences reset when the server restarts: take a fresh snapshot after every reconnect.
- An
errorframeCONCURRENT_MODIFICATIONwith a nullidmeans messages were dropped: resync every book and channel (the client emitsWsEvent::Resync).
While a snapshot is missing (for example, the REST call keeps failing), LiveOrderBook keeps at most
the newest 256 updates to replay; older ones are dropped (book.dropped_updates(), with one
WsEvent::Warning). Nothing is lost, since every update is a complete top 50.
Private channels (orders, balances, deposits, withdrawals, account, futures.account) need
ws.auth(token) with a session access token (it returns the user_id from authenticated),
or ws.auth_key() with an API key (see
Request signing). If the session is revoked, the client emits WsEvent::AuthLost;
public channels keep working.
The server ends private subscriptions, without any frame, when auth succeeds as another user,
when an auth fails (any error signs the connection out), or when this connection's own session
is revoked (session.revoked with current: true). The client emits WsEvent::AuthChanged
(AuthChange: reason UserChanged, AuthFailed or SessionRevoked, plus the dropped
channels) and re-subscribes those channels itself: at once for another user, after the next
successful auth otherwise, followed by WsEvent::Resync(ResyncReason::Reauth) (refetch private
state).
The server can also sign a connection out by itself: signed_out (a planned server frame; this
SDK already handles it). Reason expired gives WsEvent::AuthChanged with TokenExpired, reason
revoked gives SessionRevoked plus WsEvent::AuthLost, and any other reason gives SignedOut
with the raw value in code. Call auth again with the fresh token on every token refresh; that
keeps the private subscriptions.
Missed private events. Every private frame carries a per-connection sequence. When numbers are
skipped (after a short reorder window, WsOptions::reorder_window, default 250 ms), the client emits
WsEvent::SequenceGap and WsEvent::Resync(ResyncReason::SequenceGap): refetch that channel's
state over REST. balances.resync, deposits.resync and withdrawals.resync (the last two
planned) emit Resync with BalancesResync, DepositsResync or WithdrawalsResync.
Dead-man switch
cancel_all_after(symbol, timeout) and cancel_all_after_markets(timeout) arm a server-side timer: if you do
not arm again in time, the exchange cancels every open order in that scope. Duration::ZERO disarms that
scope only. The server checks the range (5 s to 10 min); the SDK refuses a non-zero timeout that is not a whole
number of milliseconds, so it can never turn into a disarm.
# async
A fired switch is cleared: arm again before quoting. The per-market and all-markets switches are separate.
Arming is retried after connection errors; if the switch must be off after a retried arm, disarm once more.
Nothing reads the switch, and the returned deadline is on the server's clock (do not compare it with yours).
DEAD_MAN_NOT_ARMED on place_order (409, not retried) means stop quoting.
Futures channels
Public: futures.mids, futures.orderbook:{coin}, futures.trades:{coin},
futures.candles:{coin}:{interval} and futures.status. Private: futures.account (positions and
open orders, in full, on subscribe and on change). Build the names with cexy::FuturesChannel: the
coin is sent exactly as given (case-sensitive, as futures().markets() lists it, 1 to 20 ASCII
letters or digits) and the interval is one of 1m 5m 15m 1h 4h 1d; anything else is an
Error::Config and nothing is sent.
# async
- Events are
WsEvent::Eventwithtypefutures.mids,futures.orderbook.update,futures.trades.new,futures.candle.update,futures.status,futures.positions,futures.ordersorfutures.resync; decodedatawithFuturesMids,FuturesBookUpdate,FuturesTradesUpdate,FuturesCandleUpdate,FuturesStatus,FuturesPositionsUpdateorFuturesOrdersUpdate. Book levels are{price, size}objects; books, mids, positions and orders are full replacements. futures.resyncarrives as its event, thenWsEvent::ChannelResync(channel): refetch that channel over REST. Onfutures.accountthe client also sendsunsubscribethensubscribefor it (the server's updates stopped); if that subscribe is refused (for exampleNOT_FOUND, no futures account) the channel is dropped and the error is reported (WsEvent::Error).futures.accountsubscribed beforeauth/auth_keysucceeds is held (SubscribeResult::pending,ws.pending_channels()) and subscribed once it does; a sign-out ends it like the other private channels.- A refused futures subscribe (
RATE_LIMITED,NOT_FOUND,VALIDATION_FAILED,SERVICE_UNAVAILABLE) is inSubscribeResult::rejectedlike any refused channel (below), and is not retried: back off yourself, usingWsError::retry_afterwhen the frame has one (details.retry_after_seconds;WsError::channelandWsError::detailscarry the rest). - Public futures sequences are not gap-checked (frames are full replacements, or lost for trades and
candles);
futures.accountis checked like the other private channels and restarts after a re-subscribe.
Request signing
Every private request is signed (AuthScheme::Hmac, the default since 0.1.0-dev.8). The API is
switching off the old mode that sent the secret in X-API-Secret, and refuses it with
SIGNATURE_REQUIRED:
use ;
# async
The secret never leaves your process: every private request is signed
(X-API-Key, X-API-Timestamp, X-API-Nonce, X-API-Signature), every retry with a fresh
timestamp and nonce. A key issued before signing existed fails with KEY_NOT_SIGNABLE: create a new
API key. ws.auth_key().await authenticates a WebSocket with the same key.
The signed timestamp must be at most 30 s behind and 5 s ahead of the server clock: keep the system
clock synchronised (NTP). After SIGNATURE_EXPIRED the client adopts the server clock (at most 1 h
away) and resends once. For a few seconds after the API's replay-protection store restarts, it may
answer 503 SERVICE_UNAVAILABLE (nonce_store_warming); reads are retried after Retry-After.
Live balances
# async
live_balances subscribes balances, takes a REST snapshot and applies newer balance.updated
events (only when their sequence is greater than the one it holds; a total of 0 removes the row).
It refetches by itself on a missed event, balances.resync, CONCURRENT_MODIFICATION, a reconnect
or an account change, at most every min_snapshot_interval (default 2 s; Duration::ZERO: none),
and never because a balance's own sequence skipped values. At the start and after every account change it checks that the
REST key's account (account().id()) is the WebSocket's authenticated user: otherwise nothing is
merged (BalancesEvent::AccountMismatch, and last_error() has code ACCOUNT_MISMATCH). With your
own snapshot source, also pass its owner (owner_id or account_id); without one,
live_balances fails with a CONFIG error.
Security
- API keys cannot withdraw or transfer funds, whatever their scopes.
- Use a read-only key unless you need to trade, and restrict keys to your IPs (
allowed_ips). - Credentials are sent only on private endpoints and never in URLs: the key id and a signature
(
X-API-Key,X-API-Timestamp,X-API-Nonce,X-API-Signature). The secret itself is never sent. - The SDK never follows HTTP redirects, so credentials and orders are never re-sent to another URL.
A 3xx response becomes an API error with code
UNEXPECTED_REDIRECT(categoryUnexpectedRedirect); it is not retried. The WebSocket handshake does not follow redirects either. - The SDK always builds its own HTTP client, and there is no option to pass your own
reqwest::Client: redirects cannot be disabled on a client the SDK did not create, so a caller's client could leak the credentials. UseClientOptions(timeout, retries, rate limit, User-Agent) to tune it. - Only
https://base URLs andwss://WebSocket URLs are accepted.allow_insecurepermitshttp:///ws://solely forlocalhost,127.0.0.1or::1(local test servers). - The SDK redacts the secret from
Debug/Displayoutput and error messages, including values the server echoes back inApiError::details(at any depth, object keys included),fieldsandrequest_id. - WebSocket URLs must not carry credentials (
user:pass@), a query string or a fragment. - Live tests (
tests/live.rs: public REST reads and one unauthenticated WebSocket connection) run only withCEXY_LIVE_TESTS=1, never in CI. - Keep keys in environment variables or a secret manager, not in code.
Report vulnerabilities as described in SECURITY.md.
Trading risk
- Orders are real and irreversible once filled. Test your code with a read-only key and small amounts first, and add your own limits (maximum order size, allowed markets) before automating trades.
- Retries and the
client_order_idlookup are designed to avoid duplicate orders, but when a failure is ambiguous and even the lookup fails you getError::OrderStateUnknown: check the order before placing it again. - Markets move between reading data and placing an order; prices and balances you read may be stale.
- This SDK is provided under the MIT licence, without warranty. Nothing in it is investment advice.
For tool builders
OperationId::ALL and OperationId::info() describe the 52 operations (method, path, auth and scope).
The crate also exports every model type, the error types, the Authenticator trait (HMAC signing will
plug in here) and ClientOptions::user_agent_suffix to identify your tool.
Development
&& &&
CEXY_LIVE_TESTS=1
Tests read the shared conformance cases from a cexy-api-spec checkout next to this repo
(override with CEXY_API_SPEC; CEXY_REQUIRE_SPEC=1 fails instead of skipping when it is missing).
License
MIT, see LICENSE.