lcx-liberty-sdk 1.0.2 → 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
@@ -98,6 +98,43 @@ client is not the place to publish a surface by implication.
98
98
  | `transfers()` / `transfer(id)` | a wallet's bridge transfers and their state (sent, bridging, delivered, refunded), from our own indexer |
99
99
  | `health()` | the tracker's per-chain frontier and backlog |
100
100
 
101
+ ### `lcx.multi` (several tokens at once)
102
+
103
+ | method | what it is for |
104
+ |---|---|
105
+ | `quote()` | a bundle priced: up to 8 sells into one hub token (USDC, USDT, WETH or the native coin), the hub split across up to 8 buys by basis points |
106
+ | `build()` | one transaction for the whole bundle, plus the approvals — or the single Permit2 batch signature — it needs first |
107
+ | `xquote()` | the far side of a cross-chain bundle: a corridor asset bridged, then spread across buys on the destination chain |
108
+ | `xbuild()` | the deposit for it; with `sourceQuoteId`, and a router that carries the entry, the bundle and the deposit in ONE transaction |
109
+
110
+ ```ts
111
+ const bundle = await lcx.multi.quote({
112
+ chainId: 8453,
113
+ hub: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
114
+ sells: [
115
+ { token: NATIVE, amount: "0.05" },
116
+ { token: "0x940181a94A35A4569E4529A3CDfB74e38FD98631", amount: "12" },
117
+ ],
118
+ });
119
+ // A leg the engine could not route is reported, not dropped in silence.
120
+ const failed = bundle.sells.filter((s) => s.error);
121
+
122
+ const built = await lcx.multi.build({
123
+ multiQuoteId: bundle.multiQuoteId,
124
+ recipient: taker,
125
+ pull: "allowance", // or "permit2": one batch signature covering every sell
126
+ });
127
+ // `built.tokens` says which sells still need an approval or a signature.
128
+ await wallet.sendTransaction(built.transactionRequest);
129
+ ```
130
+
131
+ The bundle settles in one transaction, so what fails is reported rather than
132
+ hidden: a leg the engine cannot route carries `error` on the quote, a sell the
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 API at
135
+ `swap-api.lcx.com` has carried the multi swap module since 23 September 2026;
136
+ on a deployment whose router does not, these four answer `not_found`.
137
+
101
138
  ### `lcx.prices`
102
139
  | method | what it is for |
103
140
  |---|---|
@@ -113,27 +150,33 @@ client is not the place to publish a surface by implication.
113
150
  | `chains.list()` | supported chains and index freshness |
114
151
  | `account.usage()` | your plan, calls used and remaining |
115
152
  | `account.plans()` | every plan and its limits |
116
- | `account.stats()` | how much liquidity the index can see |
117
153
 
118
154
  ## Contract addresses
119
155
 
120
- One router, one address on Ethereum, Base, Arbitrum and Optimism since
121
- 10 September 2026. The SDK never hardcodes them: `spender` comes from
122
- `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:
123
160
 
124
- | Contract | Address, every chain |
125
- |---|---|
126
- | Router proxy (the `spender`: swaps now, cross-chain from 12 September 2026) | `0x0000000000b1ae06c96aB73FF4360d7AeAaB56F0` |
127
- | 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` |
128
166
 
129
- A wallet that approved the earlier per-chain router is asked for one new
130
- 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.
131
169
 
132
170
  ## Notes worth knowing
133
171
 
134
- - **Amounts in, human; amounts out, raw.** You pass `"1.5"` with `decimals`; the
135
- API returns raw units, because an 18-decimal amount does not survive a JS
136
- 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.
137
180
  - **Failed requests are never billed.** A 4xx or 5xx costs nothing.
138
181
  - **Hitting your monthly limit returns 429, not an invoice.** There is no
139
182
  overage billing.
@@ -153,14 +196,6 @@ required, so `new LibertyDex()` without an `apiKey` throws with a message
153
196
  telling you where to get one. Create a free key (150k calls/month, no card) in
154
197
  the [developer dashboard](https://dex.lcx.com/dashboard).
155
198
 
156
- To try the API before you have a key, point the client at the public product
157
- surface, which serves reads on an anonymous, rate-limited tier:
158
-
159
- ```ts
160
- import { LibertyDex, PUBLIC_BASE_URL } from "lcx-liberty-sdk";
161
- const lcx = new LibertyDex({ baseUrl: PUBLIC_BASE_URL }); // no key, evaluation only
162
- ```
163
-
164
199
  Never put the key in a browser bundle: it is a server-side credential. In a
165
200
  web app, call the SDK from your backend and forward the result.
166
201
 
@@ -174,11 +209,7 @@ USD prices labeled `source: "external"` and token logos labeled
174
209
  `logoSource: "geckoterminal"`. Their terms do not allow us to redistribute
175
210
  that data through a commercial API, so **keyed (API-key) responses omit those
176
211
  fields**: an oracle-unpriceable token answers `usd: null`, and a
177
- GeckoTerminal-logoed token serves `logo: null`. Anonymous evaluation calls may
178
- still receive them; if you render such a figure or logo, place a hyperlinked
179
- "Powered by GeckoTerminal" (https://www.geckoterminal.com) near it, and do not
180
- re-serve or redistribute that data through your own API. The license that
181
- lets it reach you does not extend past your screen.
212
+ GeckoTerminal-logoed token serves `logo: null`.
182
213
 
183
214
  ## License
184
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.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import { AccountResource, ChainsResource } from "./resources/account.js";
2
2
  import { CrossChainResource } from "./resources/crosschain.js";
3
+ import { MultiResource } from "./resources/multi.js";
3
4
  import { PricesResource } from "./resources/prices.js";
4
5
  import { SwapResource } from "./resources/swap.js";
5
6
  import { TokensResource } from "./resources/tokens.js";
@@ -9,6 +10,8 @@ export declare class LibertyDex {
9
10
  readonly swap: SwapResource;
10
11
  /** Quote across chains, and follow a transfer to the far side. */
11
12
  readonly crossChain: CrossChainResource;
13
+ /** Several tokens in and several out, as one transaction: `/v1/multi/*`. */
14
+ readonly multi: MultiResource;
12
15
  /** The token registry, and what we vouch for. */
13
16
  readonly tokens: TokensResource;
14
17
  /** USD prices: one token, a batch, or a past day. */
@@ -25,6 +28,7 @@ export { Transport } from "./transport.js";
25
28
  export * from "./types.js";
26
29
  export { SwapResource, type SubmitResult } from "./resources/swap.js";
27
30
  export { CrossChainResource } from "./resources/crosschain.js";
31
+ export { MultiResource } from "./resources/multi.js";
28
32
  export { TokensResource } from "./resources/tokens.js";
29
33
  export { PricesResource, MAX_TOKENS_PER_BATCH, type PriceBatch, type PriceSource, type HistoricPrice, } from "./resources/prices.js";
30
34
  export { AccountResource, ChainsResource, type Plan, type Stats, } from "./resources/account.js";
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);
@@ -46,6 +45,7 @@
46
45
  import { Transport } from "./transport.js";
47
46
  import { AccountResource, ChainsResource } from "./resources/account.js";
48
47
  import { CrossChainResource } from "./resources/crosschain.js";
48
+ import { MultiResource } from "./resources/multi.js";
49
49
  import { PricesResource } from "./resources/prices.js";
50
50
  import { SwapResource } from "./resources/swap.js";
51
51
  import { TokensResource } from "./resources/tokens.js";
@@ -54,6 +54,8 @@ export class LibertyDex {
54
54
  swap;
55
55
  /** Quote across chains, and follow a transfer to the far side. */
56
56
  crossChain;
57
+ /** Several tokens in and several out, as one transaction: `/v1/multi/*`. */
58
+ multi;
57
59
  /** The token registry, and what we vouch for. */
58
60
  tokens;
59
61
  /** USD prices: one token, a batch, or a past day. */
@@ -66,6 +68,7 @@ export class LibertyDex {
66
68
  const t = new Transport(options);
67
69
  this.swap = new SwapResource(t);
68
70
  this.crossChain = new CrossChainResource(t);
71
+ this.multi = new MultiResource(t);
69
72
  this.tokens = new TokensResource(t);
70
73
  this.prices = new PricesResource(t);
71
74
  this.chains = new ChainsResource(t);
@@ -78,6 +81,7 @@ export { Transport } from "./transport.js";
78
81
  export * from "./types.js";
79
82
  export { SwapResource } from "./resources/swap.js";
80
83
  export { CrossChainResource } from "./resources/crosschain.js";
84
+ export { MultiResource } from "./resources/multi.js";
81
85
  export { TokensResource } from "./resources/tokens.js";
82
86
  export { PricesResource, MAX_TOKENS_PER_BATCH, } from "./resources/prices.js";
83
87
  export { AccountResource, ChainsResource, } from "./resources/account.js";
@@ -0,0 +1,56 @@
1
+ import type { Transport } from "../transport.js";
2
+ import type { MultiBuild, MultiBuildParams, MultiQuote, MultiQuoteParams, MultiXBuild, MultiXBuildParams, MultiXQuote, MultiXQuoteParams } from "../types.js";
3
+ export declare class MultiResource {
4
+ private readonly t;
5
+ constructor(t: Transport);
6
+ /**
7
+ * Price a bundle: every sell is routed into one hub token (USDC, USDT, WETH
8
+ * or the native coin), and the hub is split across the buys by basis points.
9
+ * Read-only, and the whole thing settles in ONE transaction, so a leg that
10
+ * cannot be routed is reported rather than silently dropped — read
11
+ * `sells[].status` before you build.
12
+ *
13
+ * Sells only (no `buys`) consolidates dust into the hub; one sell that IS
14
+ * the hub, with buys, spreads one token across several. At most eight a side.
15
+ *
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.
18
+ */
19
+ quote(params: MultiQuoteParams): Promise<MultiQuote>;
20
+ /**
21
+ * Turn an `mq_` quote into the transaction that runs the bundle, plus the
22
+ * approvals or the one Permit2 batch signature it needs first.
23
+ *
24
+ * `pull: "allowance"` asks each sell token's allowance for the router;
25
+ * `pull: "permit2"` takes one batch signature covering every token instead.
26
+ * `tokens[]` says which state each sell is in, so a wallet can collect only
27
+ * what is missing. `simulation` reports what the bundle would produce; a
28
+ * `skipped` simulation names why (an approval still missing, usually).
29
+ */
30
+ build(params: MultiBuildParams): Promise<MultiBuild>;
31
+ /**
32
+ * Price the far side of a CROSS-CHAIN bundle: a corridor asset on
33
+ * `fromChainId` is bridged and spread across `buys` on `toChainId`.
34
+ *
35
+ * Step 1 is an ordinary bundle on the source chain that consolidates into
36
+ * the corridor asset (`quote()` with no buys); `amount` here is what the
37
+ * wallet actually holds after it, not what step 1 was quoted at.
38
+ */
39
+ xquote(params: MultiXQuoteParams): Promise<MultiXQuote>;
40
+ /**
41
+ * Build the deposit for an `mqx_` quote.
42
+ *
43
+ * Without `sourceQuoteId` this is the bridge deposit alone, signed after the
44
+ * source bundle. With it — and on a network whose router carries the
45
+ * one-transaction entry — the bundle and the deposit are ONE transaction:
46
+ * the response's `transactionRequest` then goes to the router rather than to
47
+ * the bridge, and `approval` covers the sells instead of the corridor asset.
48
+ * A network without that router answers `one_tx_unavailable`; send the two
49
+ * transactions in order instead.
50
+ *
51
+ * ⚠️ One transaction is all or nothing: a sell leg that fails reverts the
52
+ * whole thing and leaves every token in the wallet. The two-transaction path
53
+ * keeps a partial fill, which is the trade-off between them.
54
+ */
55
+ xbuild(params: MultiXBuildParams): Promise<MultiXBuild>;
56
+ }
@@ -0,0 +1,81 @@
1
+ /** Several tokens in and several tokens out, as one transaction. */
2
+ import { LibertyError } from "../errors.js";
3
+ /** What every leg of a bundle settles through, and the cap on each side. */
4
+ const SIDE_CAP = 8;
5
+ export class MultiResource {
6
+ t;
7
+ constructor(t) {
8
+ this.t = t;
9
+ }
10
+ /**
11
+ * Price a bundle: every sell is routed into one hub token (USDC, USDT, WETH
12
+ * or the native coin), and the hub is split across the buys by basis points.
13
+ * Read-only, and the whole thing settles in ONE transaction, so a leg that
14
+ * cannot be routed is reported rather than silently dropped — read
15
+ * `sells[].status` before you build.
16
+ *
17
+ * Sells only (no `buys`) consolidates dust into the hub; one sell that IS
18
+ * the hub, with buys, spreads one token across several. At most eight a side.
19
+ *
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.
22
+ */
23
+ async quote(params) {
24
+ if (params.sells.length === 0) {
25
+ throw new LibertyError("bad_request", "a bundle needs at least one sell", 400);
26
+ }
27
+ if (params.sells.length > SIDE_CAP || (params.buys?.length ?? 0) > SIDE_CAP) {
28
+ throw new LibertyError("bad_request", `at most ${SIDE_CAP} tokens a side in one bundle`, 400);
29
+ }
30
+ const bps = (params.buys ?? []).reduce((n, b) => n + b.bps, 0);
31
+ if (params.buys?.length && bps !== 10_000) {
32
+ throw new LibertyError("bad_request", `the buys' bps must sum to 10000, not ${bps}`, 400);
33
+ }
34
+ return this.t.request("POST", "/v1/multi/quote", params);
35
+ }
36
+ /**
37
+ * Turn an `mq_` quote into the transaction that runs the bundle, plus the
38
+ * approvals or the one Permit2 batch signature it needs first.
39
+ *
40
+ * `pull: "allowance"` asks each sell token's allowance for the router;
41
+ * `pull: "permit2"` takes one batch signature covering every token instead.
42
+ * `tokens[]` says which state each sell is in, so a wallet can collect only
43
+ * what is missing. `simulation` reports what the bundle would produce; a
44
+ * `skipped` simulation names why (an approval still missing, usually).
45
+ */
46
+ async build(params) {
47
+ return this.t.request("POST", "/v1/multi/build", params);
48
+ }
49
+ /**
50
+ * Price the far side of a CROSS-CHAIN bundle: a corridor asset on
51
+ * `fromChainId` is bridged and spread across `buys` on `toChainId`.
52
+ *
53
+ * Step 1 is an ordinary bundle on the source chain that consolidates into
54
+ * the corridor asset (`quote()` with no buys); `amount` here is what the
55
+ * wallet actually holds after it, not what step 1 was quoted at.
56
+ */
57
+ async xquote(params) {
58
+ if (params.fromChainId === params.toChainId) {
59
+ throw new LibertyError("bad_request", "fromChainId equals toChainId — use quote() for a same-chain bundle", 400);
60
+ }
61
+ return this.t.request("POST", "/v1/multi/xquote", params);
62
+ }
63
+ /**
64
+ * Build the deposit for an `mqx_` quote.
65
+ *
66
+ * Without `sourceQuoteId` this is the bridge deposit alone, signed after the
67
+ * source bundle. With it — and on a network whose router carries the
68
+ * one-transaction entry — the bundle and the deposit are ONE transaction:
69
+ * the response's `transactionRequest` then goes to the router rather than to
70
+ * the bridge, and `approval` covers the sells instead of the corridor asset.
71
+ * A network without that router answers `one_tx_unavailable`; send the two
72
+ * transactions in order instead.
73
+ *
74
+ * ⚠️ One transaction is all or nothing: a sell leg that fails reverts the
75
+ * whole thing and leaves every token in the wallet. The two-transaction path
76
+ * keeps a partial fill, which is the trade-off between them.
77
+ */
78
+ async xbuild(params) {
79
+ return this.t.request("POST", "/v1/multi/xbuild", params);
80
+ }
81
+ }
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,3 +401,206 @@ export interface LibertyOptions {
373
401
  maxRetries?: number;
374
402
  fetch?: typeof globalThis.fetch;
375
403
  }
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 & {
409
+ token: string;
410
+ decimals?: number;
411
+ };
412
+ /** One token bought out of the hub. `bps` is its share; the shares sum to 10000. */
413
+ export interface MultiBuyParam {
414
+ token: string;
415
+ bps: number;
416
+ }
417
+ export interface MultiQuoteParams {
418
+ chainId: number;
419
+ /** The chain's USDC, USDT or WETH, or `NATIVE` for the native coin. */
420
+ hub: string;
421
+ /** 1 to 8 tokens. */
422
+ sells: MultiSellParam[];
423
+ /** 0 to 8 tokens; omit to consolidate everything into the hub. */
424
+ buys?: MultiBuyParam[];
425
+ /** Default 50 (0.5%), at most 2000. Every leg is priced at it. */
426
+ slippageBps?: number;
427
+ }
428
+ /**
429
+ * One leg of a bundle, as the quote prices it. `amountIn` is raw units of the
430
+ * leg's own input — for a buy, its share of `hubFloor`. A leg the engine could
431
+ * not route carries `error` and leaves the others untouched.
432
+ */
433
+ export interface MultiLeg {
434
+ token: string;
435
+ /** Buys only: the share this leg was sized at. */
436
+ bps?: number;
437
+ amountIn: string;
438
+ /** The single quote this leg is pinned under; null for a passthrough. */
439
+ quoteId: string | null;
440
+ /** The leg is already the hub: pulled or paid straight through, unswapped. */
441
+ passthrough: boolean;
442
+ amountOut: string | null;
443
+ minimumAmount: string | null;
444
+ usdValueIn?: number | null;
445
+ usdValueOut?: number | null;
446
+ gasFeeUSD?: number | null;
447
+ priceImpact?: number | null;
448
+ routes?: Route[];
449
+ error?: {
450
+ code: string;
451
+ message: string;
452
+ } | null;
453
+ }
454
+ /** How the bundle is laid out. Reported, never chosen by the caller. */
455
+ export type MultiMode = "consolidate" | "spread" | "hub";
456
+ export interface MultiQuote {
457
+ multiQuoteId: string;
458
+ chainId: number;
459
+ hub: string;
460
+ hubIsNative: boolean;
461
+ mode: MultiMode;
462
+ sells: MultiLeg[];
463
+ buys: MultiLeg[];
464
+ /** Raw hub units: what the sells are expected to deliver, and what they guarantee. */
465
+ hubExpected: string;
466
+ hubFloor: string;
467
+ totals: {
468
+ usdIn: number | null;
469
+ usdOut: number | null;
470
+ gasFeeUSD: number | null;
471
+ };
472
+ /** The multi router: calldata target, Permit2 spender and approval target. */
473
+ spender: string;
474
+ createdAt: number;
475
+ /** 120 seconds after the quote began. */
476
+ expiresAt: number;
477
+ }
478
+ /** How the ERC-20 sells reach the router. */
479
+ export type MultiPull = "allowance" | "permit2";
480
+ export interface MultiBuildParams {
481
+ /** An `mq_` id from `multi.quote()`. */
482
+ multiQuoteId: string;
483
+ /** Receives the hub or the buys, and sends the transaction unless `taker` is set. */
484
+ recipient: string;
485
+ taker?: string;
486
+ /** Must match the quote's if sent. */
487
+ slippageBps?: number;
488
+ pull: MultiPull;
489
+ /** Seconds from now; default 300, at most 3600. */
490
+ deadlineSecs?: number;
491
+ }
492
+ /** What stands between the wallet and the send, per ERC-20 sell. */
493
+ export interface MultiTokenState {
494
+ token: string;
495
+ state: "ready" | "signature" | "permit" | "approval";
496
+ approveTarget: string | null;
497
+ needed: string;
498
+ }
499
+ /** A sell dropped at build time, with the guard that dropped it. */
500
+ export interface MultiSkipped {
501
+ token: string;
502
+ code: string;
503
+ message: string;
504
+ }
505
+ export interface MultiBuild {
506
+ multiQuoteId: string;
507
+ router: string;
508
+ /** `multiSwap`, `multiSwapWithPermit2` or `multiSwapAndBridge`. */
509
+ entry: string;
510
+ mode: MultiMode;
511
+ transactionRequest: Transaction & {
512
+ from?: string;
513
+ };
514
+ /** The structured call, field for field `ILibertyMultiSwap`; every uint256 a decimal string. */
515
+ args: Record<string, unknown>;
516
+ /** EIP-712 typed data for the Permit2 batch, on the permit2 path. */
517
+ permit2?: Record<string, unknown> | null;
518
+ permits2612?: unknown[];
519
+ tokens: MultiTokenState[];
520
+ hubExpected: string;
521
+ hubFloor: string;
522
+ /** Sells that did not survive the build's guards; the rest still ran. */
523
+ skipped: MultiSkipped[];
524
+ simulation?: {
525
+ status: string;
526
+ why?: string;
527
+ [k: string]: unknown;
528
+ } | null;
529
+ deadline: string;
530
+ expiresAt: number;
531
+ }
532
+ export interface MultiXQuoteParams {
533
+ fromChainId: number;
534
+ toChainId: number;
535
+ /** The corridor asset on the SOURCE chain — what step 1 consolidated into. */
536
+ corridor: string;
537
+ /** Raw units of it: what the wallet holds after step 1, not what step 1 was quoted at. */
538
+ amount: string;
539
+ /** What to buy on the destination chain; shares sum to 10000. */
540
+ buys: MultiBuyParam[];
541
+ recipient: string;
542
+ slippageBps?: number;
543
+ }
544
+ export interface MultiXQuote {
545
+ /** An `mqx_` id. */
546
+ multiQuoteId: string;
547
+ fromChainId: number;
548
+ toChainId: number;
549
+ corridor: {
550
+ from: string;
551
+ to: string;
552
+ };
553
+ amount: string;
554
+ /** What the bridge delivers before the arrival message is priced in. */
555
+ delivered: string;
556
+ bridge: {
557
+ adapter: string;
558
+ etaSecs: number | null;
559
+ minimumAmount: string;
560
+ };
561
+ outputs: Array<{
562
+ token: string;
563
+ bps: number;
564
+ hubIn: string;
565
+ amount: string | null;
566
+ minimumAmount: string | null;
567
+ usdValueOut?: number | null;
568
+ priceImpactPct?: number | null;
569
+ passthrough: boolean;
570
+ }>;
571
+ expiresAt: number;
572
+ }
573
+ export interface MultiXBuildParams {
574
+ /** An `mqx_` id from `multi.xquote()`. */
575
+ multiQuoteId: string;
576
+ recipient: string;
577
+ /**
578
+ * An `mq_` id whose sells produce the corridor asset. With it, and on a
579
+ * network whose router carries the one-transaction entry, the bundle and the
580
+ * deposit are one transaction; without it this is the deposit alone.
581
+ */
582
+ sourceQuoteId?: string;
583
+ }
584
+ export interface MultiXBuild {
585
+ multiQuoteId: string;
586
+ router: string;
587
+ handler?: string;
588
+ transactionRequest: Transaction & {
589
+ from?: string;
590
+ };
591
+ /** One exact approval, for the same address the transaction goes to. */
592
+ approval: {
593
+ token: string;
594
+ target: string;
595
+ amount: string;
596
+ };
597
+ delivered?: string;
598
+ dstPayloadHash?: string;
599
+ sharesBps?: number[];
600
+ outputs: Array<{
601
+ token: string;
602
+ bps: number;
603
+ minimumAmount: string;
604
+ }>;
605
+ etaSecs?: number | null;
606
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "lcx-liberty-sdk",
3
- "version": "1.0.2",
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",