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, anduuid for
order IDs:
Cargo.toml:
Cargo.toml
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
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.
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
create_order never arrived, look the order up by its client_order_id:
lean.get_positions(&Default::default()) and lean.get_balances(). See
Orders and idempotency.
Errors, timeouts and retries
A response that isn’t a success returnsError::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:
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:
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 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.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 fromlean_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.