Skip to main content
lean-api-sdk is the Lean API client for Rust. It is generated from the OpenAPI spec, so every endpoint in the API reference is an async method on lean_api::Client with typed requests and responses. The crate uses the 2024 edition, so it needs a recent stable Rust. It runs on Tokio, and TLS uses rustls, so there is no OpenSSL dependency.

Install

The crate is on crates.io once 0.1.0 is published. Add it with Tokio to run it, and uuid for order IDs:
Or in Cargo.toml:
Cargo.toml
The package is lean-api-sdk and the library is lean_api.

Create a client

The examples use the same two environment variables as the quickstart:
Client::from_env reads LEAN_API_KEY, and LEAN_API_URL when it is set. The base URL defaults to https://api.lean.xyz. Keep the key in the environment and never log it; the client leaves it out of Debug output. Authentication shows how to create a key. Each method returns a Response: the result is in data and the request ID in meta.request_id.

Find a market

Pick a market whose legs include one with tradable: true. Markets and IDs explains each field. lean.get_market(id) reads one market.

Quote and preview

Check what an order would do before you place it. Neither call places or reserves anything.
CreateOrderRequest::new sets the required fields and leaves the rest unset. 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, set 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.
Prices, quantities and amounts are decimal strings exactly as the API sends them, so nothing is rounded through f64. Parse them with the decimal type your program already uses.

Read an order

If the response to create_order never arrived, look the order up by its client_order_id:
Then reconcile with lean.get_positions(&Default::default()) and lean.get_balances(). See Orders and idempotency.

Errors, timeouts and retries

A response that isn’t a success returns Error::Api, and error.api() gives you its fields: the HTTP status(), the error code(), the request_id() to quote when you report a problem, and details() with structured details such as validation issues:
Errors lists every code. Error::Transport means the request did not complete: the connection failed or it timed out. A POST that fails this way may still have reached the API. Each request times out after 30 seconds. Build the client with Client::builder() to change it:
GET requests are retried twice on connection errors, 429 and 5xx responses, with jittered backoff that follows Retry-After. Set max_read_retries(0) to turn that off. POST, PATCH and DELETE requests are never retried. After a timeout on create_order, look the order up with list_orders and its 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.reset_test_mode() 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

Client::stream keeps a WebSocket open. It reconnects with a new ticket after a drop and reads every page of orders again over REST after each reconnect:
OrdersResync replaces the order state you hold. A channel reports Stale { stale: true } from a drop until its first update on the next connection. A refused key stops the stream instead of retrying. Events queue up to StreamOptions::event_buffer, 1024 by default. Past that the stream stops reading the socket until you catch up. Call stream.close() when you are done; dropping every handle or the event receiver also stops it. See Streaming for each channel.

Types

Every request and response type is exported from lean_api by name, such as CreateOrderRequest, OrderPreview, Order and Market. Enums such as Action, TimeInForce and OrderStatus print as the API’s strings:

Methods

Method names follow the API reference. The ones used most: Changes to the crate are listed in the changelog.