Skip to main content
@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

Pick a market whose 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.
Quote again after 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.
An accepted response is not a fill. Read status and filled_quantity, and confirm them by reading the order back.

Read an order

If the response to createOrder never arrived, look the order up by its client_order_id:
Then reconcile with lean.getPositions() and lean.getBalances(). See Orders and idempotency.

Errors, timeouts and retries

A response that isn’t a success throws LeanApiError. It has the HTTP status, the error code, the requestId to quote when you report a problem, and the whole error response in body:
Errors lists every code. Each request times out after 30 seconds. Set 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 a lean_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:
To start over with a test key, 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:
Call stream.close() when you are done. See Streaming for each channel.

Types

Every request and response type is exported by name, such as CreateOrderRequest, PreviewOrderResponse and GetOrderResponse:

Methods

Method names follow the API reference. The ones used most: Releases of the package are listed in the changelog.