lcx-liberty-sdk 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,8 +1,9 @@
1
1
  # lcx-liberty-sdk
2
2
 
3
3
  TypeScript client for the [LCX Liberty DEX](https://dex.lcx.com/business)
4
- DEX aggregator. Best-execution routing across Ethereum, Base, Arbitrum and
5
- Optimism, priced from our own pool index.
4
+ DEX aggregator. Best-execution routing across Ethereum, Base, Arbitrum,
5
+ OP Mainnet, BNB Chain, Polygon, Avalanche and Robinhood Chain, priced from our
6
+ own pool index.
6
7
 
7
8
  Zero dependencies. Node 18+, Deno, Bun, Workers, browser.
8
9
 
@@ -21,8 +22,7 @@ const { quote, transaction } = await lcx.swap.execute({
21
22
  chainId: 1,
22
23
  tokenIn: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
23
24
  tokenOut: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
24
- amount: "1",
25
- decimals: 18,
25
+ amountIn: "1000000000000000000", // 1 WETH in base units; or amount: "1"
26
26
  taker: userAddress,
27
27
  slippageBps: 50,
28
28
  });
@@ -74,7 +74,7 @@ Client errors are never retried, because resending a bad request only spends quo
74
74
 
75
75
  ## The full surface
76
76
 
77
- Six namespaces. Nobody reads past a namespace they are not using, so the swap
77
+ Seven namespaces. Nobody reads past a namespace they are not using, so the swap
78
78
  surface stays as short as it ever was however many sit beside it.
79
79
 
80
80
  This wraps the surfaces LCX offers publicly, and only those. Anything absent is
@@ -112,8 +112,8 @@ const bundle = await lcx.multi.quote({
112
112
  chainId: 8453,
113
113
  hub: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
114
114
  sells: [
115
- { token: NATIVE, amount: "0.05", decimals: 18 },
116
- { token: "0x940181a94A35A4569E4529A3CDfB74e38FD98631", amount: "12", decimals: 18 },
115
+ { token: NATIVE, amount: "0.05" },
116
+ { token: "0x940181a94A35A4569E4529A3CDfB74e38FD98631", amount: "12" },
117
117
  ],
118
118
  });
119
119
  // A leg the engine could not route is reported, not dropped in silence.
@@ -131,8 +131,8 @@ await wallet.sendTransaction(built.transactionRequest);
131
131
  The bundle settles in one transaction, so what fails is reported rather than
132
132
  hidden: a leg the engine cannot route carries `error` on the quote, a sell the
133
133
  build's guards drop is left out of the calldata and named in `skipped`, and a
134
- buy that fails refuses the build outright. The public deployment at
135
- `dex-api.lcx.com` has carried the multi swap module since 23 September 2026;
134
+ buy that fails refuses the build outright. The API at
135
+ `swap-api.lcx.com` has carried the multi swap module since 23 September 2026;
136
136
  on a deployment whose router does not, these four answer `not_found`.
137
137
 
138
138
  ### `lcx.prices`
@@ -150,27 +150,33 @@ on a deployment whose router does not, these four answer `not_found`.
150
150
  | `chains.list()` | supported chains and index freshness |
151
151
  | `account.usage()` | your plan, calls used and remaining |
152
152
  | `account.plans()` | every plan and its limits |
153
- | `account.stats()` | how much liquidity the index can see |
154
153
 
155
154
  ## Contract addresses
156
155
 
157
- One router, one address on Ethereum, Base, Arbitrum and Optimism since
158
- 10 September 2026. The SDK never hardcodes them: `spender` comes from
159
- `allowance()` / `quote()`, `to` from `build()`. For your own records:
156
+ Two routers, each at one address on every chain it serves. The SDK never
157
+ hardcodes them: `spender` comes from `allowance()` / `quote()`, `to` from
158
+ `build()`, and `chains.list()` names the router of each chain. For your own
159
+ records:
160
160
 
161
- | Contract | Address, every chain |
162
- |---|---|
163
- | Router proxy (the `spender`: swaps now, cross-chain from 12 September 2026) | `0x0000000000b1ae06c96aB73FF4360d7AeAaB56F0` |
164
- | Fee router (deployed, reserved for integrator-fee traffic) | `0xd67aADF902d15890cb11DfB4DA3d3D90b1953Dee` |
161
+ | Contract | Chains | Address |
162
+ |---|---|---|
163
+ | Router proxy (the `spender`: swaps, cross-chain and the multi token swap) | Ethereum, Base, Arbitrum, OP Mainnet | `0x0000000000b1ae06c96aB73FF4360d7AeAaB56F0` |
164
+ | Router 2 (the same role) | BNB Chain, Polygon, Avalanche, Robinhood Chain | `0x0000000000654902B6Ed6cC240cc81CB4c4a3dff` |
165
+ | Fee router (deployed, reserved for integrator-fee traffic) | Ethereum, Base, Arbitrum, OP Mainnet | `0xd67aADF902d15890cb11DfB4DA3d3D90b1953Dee` |
165
166
 
166
- A wallet that approved the earlier per-chain router is asked for one new
167
- approval on its next swap.
167
+ An approval is per chain and per router: a wallet that trades on a chain of
168
+ each set approves each router once.
168
169
 
169
170
  ## Notes worth knowing
170
171
 
171
- - **Amounts in, human; amounts out, raw.** You pass `"1.5"` with `decimals`; the
172
- API returns raw units, because an 18-decimal amount does not survive a JS
173
- number.
172
+ - **Amounts are base units, in and out.** Pass `amountIn`, an integer string
173
+ in the token's smallest unit (`"1500000"` for 1.5 USDC); responses answer the
174
+ same way, because an 18-decimal amount does not survive a JS number, and
175
+ name each side's `decimals` so you can format it. For a figure a person
176
+ typed, pass `amount: "1.5"` instead and the API scales it by the token's own
177
+ decimals. You do not send `decimals`: the API knows them, and refuses one
178
+ that disagrees with the token (`decimals_mismatch`) rather than pricing a
179
+ different trade.
174
180
  - **Failed requests are never billed.** A 4xx or 5xx costs nothing.
175
181
  - **Hitting your monthly limit returns 429, not an invoice.** There is no
176
182
  overage billing.
@@ -190,14 +196,6 @@ required, so `new LibertyDex()` without an `apiKey` throws with a message
190
196
  telling you where to get one. Create a free key (150k calls/month, no card) in
191
197
  the [developer dashboard](https://dex.lcx.com/dashboard).
192
198
 
193
- To try the API before you have a key, point the client at the public product
194
- surface, which serves reads on an anonymous, rate-limited tier:
195
-
196
- ```ts
197
- import { LibertyDex, PUBLIC_BASE_URL } from "lcx-liberty-sdk";
198
- const lcx = new LibertyDex({ baseUrl: PUBLIC_BASE_URL }); // no key, evaluation only
199
- ```
200
-
201
199
  Never put the key in a browser bundle: it is a server-side credential. In a
202
200
  web app, call the SDK from your backend and forward the result.
203
201
 
@@ -211,11 +209,7 @@ USD prices labeled `source: "external"` and token logos labeled
211
209
  `logoSource: "geckoterminal"`. Their terms do not allow us to redistribute
212
210
  that data through a commercial API, so **keyed (API-key) responses omit those
213
211
  fields**: an oracle-unpriceable token answers `usd: null`, and a
214
- GeckoTerminal-logoed token serves `logo: null`. Anonymous evaluation calls may
215
- still receive them; if you render such a figure or logo, place a hyperlinked
216
- "Powered by GeckoTerminal" (https://www.geckoterminal.com) near it, and do not
217
- re-serve or redistribute that data through your own API. The license that
218
- lets it reach you does not extend past your screen.
212
+ GeckoTerminal-logoed token serves `logo: null`.
219
213
 
220
214
  ## License
221
215
 
@@ -1,28 +1,33 @@
1
1
  /** Version, hosts and chain constants. Imported by every resource. */
2
- export declare const VERSION = "1.0.0";
2
+ export declare const VERSION = "1.2.0";
3
3
  /**
4
- * The commercial API, where a key is required.
5
- *
6
- * The SDK is a keyed developer tool, so it targets the host built for that -
7
- * `dex-api.lcx.com` is the product surface the swap UI runs on and is being
8
- * turned key-free (it will stop accepting keys), so defaulting there would
9
- * break the day that flip lands. Evaluate without a key by passing
10
- * `{ baseUrl: PUBLIC_BASE_URL }`; get a free key (150k calls/month) at the
11
- * dashboard.
4
+ * The API, where every call needs a key. Get a free one (150k calls/month, no
5
+ * card) at https://dex.lcx.com/dashboard.
12
6
  */
13
7
  export declare const DEFAULT_BASE_URL = "https://swap-api.lcx.com";
14
8
  /**
15
- * The public product surface. No key needed for read endpoints, on the
16
- * anonymous tier (a few requests per second) - enough to try the API before
17
- * you have a key. Pass it as `baseUrl` to opt in.
9
+ * @deprecated The LCX Liberty DEX website's own API, not a developer API.
10
+ * Since 29 September 2026 it refuses keyless calls from anywhere but the
11
+ * website itself. Still exported so existing imports compile; use the default
12
+ * base URL with an `apiKey`.
18
13
  */
19
14
  export declare const PUBLIC_BASE_URL = "https://dex-api.lcx.com";
20
- /** Chains the aggregator indexes. */
15
+ /**
16
+ * Chains the aggregator indexes, by the key `/v1/chains` uses for each.
17
+ *
18
+ * A convenience, not a gate: every method takes a plain `chainId`, and
19
+ * `chains.list()` is what says which of these the deployment you are calling
20
+ * serves right now and how fresh each index is.
21
+ */
21
22
  export declare const CHAINS: {
22
23
  readonly ethereum: 1;
23
24
  readonly optimism: 10;
25
+ readonly bnb: 56;
26
+ readonly polygon: 137;
27
+ readonly robinhood: 4663;
24
28
  readonly base: 8453;
25
29
  readonly arbitrum: 42161;
30
+ readonly avalanche: 43114;
26
31
  };
27
32
  /** The zero address, which every endpoint treats as the chain's native asset. */
28
33
  export declare const NATIVE = "0x0000000000000000000000000000000000000000";
package/dist/constants.js CHANGED
@@ -1,28 +1,33 @@
1
1
  /** Version, hosts and chain constants. Imported by every resource. */
2
- export const VERSION = "1.0.0";
2
+ export const VERSION = "1.2.0";
3
3
  /**
4
- * The commercial API, where a key is required.
5
- *
6
- * The SDK is a keyed developer tool, so it targets the host built for that -
7
- * `dex-api.lcx.com` is the product surface the swap UI runs on and is being
8
- * turned key-free (it will stop accepting keys), so defaulting there would
9
- * break the day that flip lands. Evaluate without a key by passing
10
- * `{ baseUrl: PUBLIC_BASE_URL }`; get a free key (150k calls/month) at the
11
- * dashboard.
4
+ * The API, where every call needs a key. Get a free one (150k calls/month, no
5
+ * card) at https://dex.lcx.com/dashboard.
12
6
  */
13
7
  export const DEFAULT_BASE_URL = "https://swap-api.lcx.com";
14
8
  /**
15
- * The public product surface. No key needed for read endpoints, on the
16
- * anonymous tier (a few requests per second) - enough to try the API before
17
- * you have a key. Pass it as `baseUrl` to opt in.
9
+ * @deprecated The LCX Liberty DEX website's own API, not a developer API.
10
+ * Since 29 September 2026 it refuses keyless calls from anywhere but the
11
+ * website itself. Still exported so existing imports compile; use the default
12
+ * base URL with an `apiKey`.
18
13
  */
19
14
  export const PUBLIC_BASE_URL = "https://dex-api.lcx.com";
20
- /** Chains the aggregator indexes. */
15
+ /**
16
+ * Chains the aggregator indexes, by the key `/v1/chains` uses for each.
17
+ *
18
+ * A convenience, not a gate: every method takes a plain `chainId`, and
19
+ * `chains.list()` is what says which of these the deployment you are calling
20
+ * serves right now and how fresh each index is.
21
+ */
21
22
  export const CHAINS = {
22
23
  ethereum: 1,
23
24
  optimism: 10,
25
+ bnb: 56,
26
+ polygon: 137,
27
+ robinhood: 4663,
24
28
  base: 8453,
25
29
  arbitrum: 42161,
30
+ avalanche: 43114,
26
31
  };
27
32
  /** The zero address, which every endpoint treats as the chain's native asset. */
28
33
  export const NATIVE = "0x0000000000000000000000000000000000000000";
package/dist/index.js CHANGED
@@ -8,8 +8,7 @@
8
8
  * chainId: 1,
9
9
  * tokenIn: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
10
10
  * tokenOut: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
11
- * amount: "1",
12
- * decimals: 18,
11
+ * amountIn: "1000000000000000000", // base units; or amount: "1"
13
12
  * taker: userAddress,
14
13
  * });
15
14
  * await wallet.sendTransaction(transaction);
@@ -14,7 +14,7 @@ export declare class MultiResource {
14
14
  * the hub, with buys, spreads one token across several. At most eight a side.
15
15
  *
16
16
  * Throws `LibertyError` with `bad_request` (shares that do not sum to 10,000,
17
- * a hub we do not settle in), `no_route`, or `quote_expired` on the build.
17
+ * a hub we do not settle in), `no_route`, or `QUOTE_EXPIRED` on the build.
18
18
  */
19
19
  quote(params: MultiQuoteParams): Promise<MultiQuote>;
20
20
  /**
@@ -18,7 +18,7 @@ export class MultiResource {
18
18
  * the hub, with buys, spreads one token across several. At most eight a side.
19
19
  *
20
20
  * Throws `LibertyError` with `bad_request` (shares that do not sum to 10,000,
21
- * a hub we do not settle in), `no_route`, or `quote_expired` on the build.
21
+ * a hub we do not settle in), `no_route`, or `QUOTE_EXPIRED` on the build.
22
22
  */
23
23
  async quote(params) {
24
24
  if (params.sells.length === 0) {
package/dist/transport.js CHANGED
@@ -17,13 +17,13 @@ export class Transport {
17
17
  constructor(options = {}) {
18
18
  this.apiKey = options.apiKey;
19
19
  this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
20
- // The commercial host answers every request with 401 without a key, so a
21
- // keyless client pointed at it is misconfigured before it makes a call.
22
- // Caught here with a message that says where a key comes from and how to
23
- // evaluate without one, rather than surfacing as a 401 on the first quote.
20
+ // The API answers every request with 401 without a key, so a keyless
21
+ // client pointed at it is misconfigured before it makes a call. Caught
22
+ // here with a message that says where a key comes from, rather than
23
+ // surfacing as a 401 on the first quote.
24
24
  if (!this.apiKey && this.baseUrl === DEFAULT_BASE_URL) {
25
- throw new LibertyError("api_key_required", "LibertyDex needs an apiKey for swap-api.lcx.com. Create a free one in the developer " +
26
- "dashboard, or pass { baseUrl: PUBLIC_BASE_URL } to evaluate on the keyless public tier.", 0);
25
+ throw new LibertyError("api_key_required", "LibertyDex needs an apiKey. Create a free one (150,000 calls a month, no card) at " +
26
+ "https://dex.lcx.com/dashboard.", 0);
27
27
  }
28
28
  this.timeoutMs = options.timeoutMs ?? 20_000;
29
29
  this.maxRetries = options.maxRetries ?? 2;
package/dist/types.d.ts CHANGED
@@ -4,15 +4,36 @@
4
4
  * These mirror the `/v1` responses exactly. Where the API omits a field
5
5
  * rather than sending null, the type says optional, not `| null`.
6
6
  */
7
- export interface QuoteParams {
7
+ /**
8
+ * How much to sell: exactly one of the two.
9
+ *
10
+ * `amountIn` is the standard form, the token's BASE units as an integer string
11
+ * (`"1500000"` for 1.5 USDC): what every response answers in, and what you
12
+ * already hold if the figure came from a balance or an earlier quote.
13
+ * `amount` is the human form (`"1.5"`), which the API scales by the token's
14
+ * own decimals.
15
+ */
16
+ export type SellAmount = {
17
+ /** Base units, an integer string. */
18
+ amountIn: string;
19
+ amount?: never;
20
+ } | {
21
+ /** Human units, e.g. "1.5". Scaled by the token's own decimals. */
22
+ amount: string;
23
+ amountIn?: never;
24
+ };
25
+ export type QuoteParams = SellAmount & {
8
26
  chainId: number;
9
27
  /** Sell token. Use `NATIVE` for the chain's native asset. */
10
28
  tokenIn: string;
11
29
  tokenOut: string;
12
- /** Human amount, e.g. "1.5" — not raw units. */
13
- amount: string;
14
- /** Decimals of `tokenIn`. */
15
- decimals: number;
30
+ /**
31
+ * Optional, and best left out: the API knows the decimals of every token it
32
+ * indexes. Needed only with `amount` for a token it holds none for
33
+ * (`decimals_required`). A value that disagrees with the token's own is
34
+ * refused with `decimals_mismatch` rather than priced as a different trade.
35
+ */
36
+ decimals?: number;
16
37
  /** Defaults to 50 (0.5%). */
17
38
  slippageBps?: number;
18
39
  /**
@@ -30,12 +51,12 @@ export interface QuoteParams {
30
51
  * at `build()`.
31
52
  */
32
53
  recipient?: string;
33
- }
34
- export interface SwapParams extends QuoteParams {
54
+ };
55
+ export type SwapParams = QuoteParams & {
35
56
  /** Address that sends the transaction and receives the output. */
36
57
  taker: string;
37
58
  deadlineSecs?: number;
38
- }
59
+ };
39
60
  export interface Hop {
40
61
  pool: string;
41
62
  dex: string;
@@ -51,14 +72,21 @@ export interface Route {
51
72
  export interface Quote {
52
73
  quoteId: string;
53
74
  chainId: number;
75
+ /**
76
+ * `amount` is base units on both sides. `decimals` is the token's own, so
77
+ * the figure can be formatted without a second lookup; null for a token the
78
+ * index holds none for, absent on a deployment older than 1.2.0's API.
79
+ */
54
80
  input: {
55
81
  token: string;
56
82
  amount: string;
83
+ decimals?: number | null;
57
84
  };
58
85
  output: {
59
86
  token: string;
60
87
  amount: string;
61
88
  minimumAmount: string;
89
+ decimals?: number | null;
62
90
  };
63
91
  /** Percent, e.g. 0.185. */
64
92
  priceImpactPct: number;
@@ -294,10 +322,10 @@ export interface CrossChainQuoteResult {
294
322
  /** Why the others were not offered — "no route" is never silent. */
295
323
  rejected: RejectedCrossRoute[];
296
324
  }
297
- export interface CrossChainQuoteParams extends QuoteParams {
325
+ export type CrossChainQuoteParams = QuoteParams & {
298
326
  toChainId: number;
299
327
  recipient: string;
300
- }
328
+ };
301
329
  /**
302
330
  * The tracker's state machine:
303
331
  * QUOTED → SUBMITTED → SRC_CONFIRMED → BRIDGE_PENDING → BRIDGE_COMPLETE
@@ -359,7 +387,7 @@ export interface BridgeTransferPage {
359
387
  nextCursor: string | null;
360
388
  }
361
389
  export interface LibertyOptions {
362
- /** Omit to use the anonymous tier — fine for evaluation, rate limited. */
390
+ /** Required. Create a free one at https://dex.lcx.com/dashboard. */
363
391
  apiKey?: string;
364
392
  baseUrl?: string;
365
393
  /** Per request, milliseconds. Default 20000. */
@@ -373,12 +401,14 @@ export interface LibertyOptions {
373
401
  maxRetries?: number;
374
402
  fetch?: typeof globalThis.fetch;
375
403
  }
376
- /** One token sold into the bundle's hub. `amount` is human units. */
377
- export interface MultiSellParam {
404
+ /**
405
+ * One token sold into the bundle's hub: `amountIn` in base units or `amount`
406
+ * in human units, as for a quote. `decimals` is optional and checked.
407
+ */
408
+ export type MultiSellParam = SellAmount & {
378
409
  token: string;
379
- amount: string;
380
- decimals: number;
381
- }
410
+ decimals?: number;
411
+ };
382
412
  /** One token bought out of the hub. `bps` is its share; the shares sum to 10000. */
383
413
  export interface MultiBuyParam {
384
414
  token: string;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "lcx-liberty-sdk",
3
- "version": "1.1.0",
4
- "description": "TypeScript SDK for the LCX Liberty DEX aggregator. Best-execution routing across Ethereum, Base, Arbitrum and OP Mainnet.",
3
+ "version": "1.2.0",
4
+ "description": "TypeScript SDK for the LCX Liberty DEX aggregator. Best-execution routing across Ethereum, Base, Arbitrum, OP Mainnet, BNB Chain, Polygon, Avalanche and Robinhood Chain.",
5
5
  "type": "module",
6
6
  "module": "./dist/index.js",
7
7
  "types": "./dist/index.d.ts",