@leanxyz/api-sdk is the Lean API client for
TypeScript and JavaScript. It is generated from the
OpenAPI spec, so every endpoint in the
API reference is a method with typed requests and
responses.
The package is ESM only and needs Node.js 22 or later. It has no dependencies and uses the
platform fetch and WebSocket.
Install
Create a client
The examples use the same two environment variables as the quickstart:baseUrl defaults to https://api.lean.xyz. Keep the key in the environment and never log it.
Authentication shows how to create a key.
Each method returns the whole response: the result is in data and the request ID in
meta.requestId.
Find a market
legs include one with tradable: true. Markets and IDs explains
each field. lean.getMarket(id) reads one market.
Quote and preview
Check what an order would do before you place it. Neither call places or reserves anything.expires_at. A blocking warning means the order would be refused. See
Preview.
Place an order
This buys 25 USD of the outcome at once and cancels whatever can’t fill:notional is the dollars to spend, in place of quantity. Polymarket takes ioc buys by dollar
amount only, so size an immediate buy with notional when it should fill there. To buy a number of
shares instead, send quantity and limit_price. See
Buying a dollar amount.
Save client_order_id before you send the order, and reuse it on every retry of the same order.
Sending it again returns the original order, never a second one.
Read an order
createOrder never arrived, look the order up by its client_order_id:
lean.getPositions() and lean.getBalances(). See
Orders and idempotency.
Errors, timeouts and retries
A response that isn’t a success throwsLeanApiError. It has the HTTP status, the error code,
the requestId to quote when you report a problem, and the whole error response in body:
timeoutMs on the client to change it, or pass
{ signal } as the last argument of any method to cancel a request yourself. A request that times
out or is canceled rejects with the error fetch raises, not a LeanApiError.
The client never retries a request. After a timeout on createOrder, look the order up with
listOrders({ client_order_id }) before you send it again, and resend only with the same
client_order_id and body.
Test mode
The key decides the mode, as it does for every call. With alean_sk_test_ key, orders and fills
are simulated and no money moves. Switch to a live key by changing LEAN_API_KEY; the code stays the
same.
Every successful response has data.livemode, which is false for a test key. Check it where
your program would act on money:
lean.resetTestMode() clears the simulated orders, positions,
withdrawals, transfers, stop losses and limit chases and returns test balances to the starting
amount. See Test mode and live mode.
Stream updates
@leanxyz/api-sdk/stream keeps a WebSocket open. It reconnects with a new ticket after a drop and
reads the orders again over REST after each reconnect:
stream.close() when you are done. See Streaming for each channel.
Types
Every request and response type is exported by name, such asCreateOrderRequest,
PreviewOrderResponse and GetOrderResponse:
Methods
Method names follow the API reference. The ones used most:
Releases of the package are listed in the changelog.