lcx-liberty-sdk 1.0.2 → 1.1.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
@@ -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", decimals: 18 },
116
+ { token: "0x940181a94A35A4569E4529A3CDfB74e38FD98631", amount: "12", decimals: 18 },
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 public deployment at
135
+ `dex-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
  |---|---|
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
@@ -46,6 +46,7 @@
46
46
  import { Transport } from "./transport.js";
47
47
  import { AccountResource, ChainsResource } from "./resources/account.js";
48
48
  import { CrossChainResource } from "./resources/crosschain.js";
49
+ import { MultiResource } from "./resources/multi.js";
49
50
  import { PricesResource } from "./resources/prices.js";
50
51
  import { SwapResource } from "./resources/swap.js";
51
52
  import { TokensResource } from "./resources/tokens.js";
@@ -54,6 +55,8 @@ export class LibertyDex {
54
55
  swap;
55
56
  /** Quote across chains, and follow a transfer to the far side. */
56
57
  crossChain;
58
+ /** Several tokens in and several out, as one transaction: `/v1/multi/*`. */
59
+ multi;
57
60
  /** The token registry, and what we vouch for. */
58
61
  tokens;
59
62
  /** USD prices: one token, a batch, or a past day. */
@@ -66,6 +69,7 @@ export class LibertyDex {
66
69
  const t = new Transport(options);
67
70
  this.swap = new SwapResource(t);
68
71
  this.crossChain = new CrossChainResource(t);
72
+ this.multi = new MultiResource(t);
69
73
  this.tokens = new TokensResource(t);
70
74
  this.prices = new PricesResource(t);
71
75
  this.chains = new ChainsResource(t);
@@ -78,6 +82,7 @@ export { Transport } from "./transport.js";
78
82
  export * from "./types.js";
79
83
  export { SwapResource } from "./resources/swap.js";
80
84
  export { CrossChainResource } from "./resources/crosschain.js";
85
+ export { MultiResource } from "./resources/multi.js";
81
86
  export { TokensResource } from "./resources/tokens.js";
82
87
  export { PricesResource, MAX_TOKENS_PER_BATCH, } from "./resources/prices.js";
83
88
  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/types.d.ts CHANGED
@@ -373,3 +373,204 @@ export interface LibertyOptions {
373
373
  maxRetries?: number;
374
374
  fetch?: typeof globalThis.fetch;
375
375
  }
376
+ /** One token sold into the bundle's hub. `amount` is human units. */
377
+ export interface MultiSellParam {
378
+ token: string;
379
+ amount: string;
380
+ decimals: number;
381
+ }
382
+ /** One token bought out of the hub. `bps` is its share; the shares sum to 10000. */
383
+ export interface MultiBuyParam {
384
+ token: string;
385
+ bps: number;
386
+ }
387
+ export interface MultiQuoteParams {
388
+ chainId: number;
389
+ /** The chain's USDC, USDT or WETH, or `NATIVE` for the native coin. */
390
+ hub: string;
391
+ /** 1 to 8 tokens. */
392
+ sells: MultiSellParam[];
393
+ /** 0 to 8 tokens; omit to consolidate everything into the hub. */
394
+ buys?: MultiBuyParam[];
395
+ /** Default 50 (0.5%), at most 2000. Every leg is priced at it. */
396
+ slippageBps?: number;
397
+ }
398
+ /**
399
+ * One leg of a bundle, as the quote prices it. `amountIn` is raw units of the
400
+ * leg's own input — for a buy, its share of `hubFloor`. A leg the engine could
401
+ * not route carries `error` and leaves the others untouched.
402
+ */
403
+ export interface MultiLeg {
404
+ token: string;
405
+ /** Buys only: the share this leg was sized at. */
406
+ bps?: number;
407
+ amountIn: string;
408
+ /** The single quote this leg is pinned under; null for a passthrough. */
409
+ quoteId: string | null;
410
+ /** The leg is already the hub: pulled or paid straight through, unswapped. */
411
+ passthrough: boolean;
412
+ amountOut: string | null;
413
+ minimumAmount: string | null;
414
+ usdValueIn?: number | null;
415
+ usdValueOut?: number | null;
416
+ gasFeeUSD?: number | null;
417
+ priceImpact?: number | null;
418
+ routes?: Route[];
419
+ error?: {
420
+ code: string;
421
+ message: string;
422
+ } | null;
423
+ }
424
+ /** How the bundle is laid out. Reported, never chosen by the caller. */
425
+ export type MultiMode = "consolidate" | "spread" | "hub";
426
+ export interface MultiQuote {
427
+ multiQuoteId: string;
428
+ chainId: number;
429
+ hub: string;
430
+ hubIsNative: boolean;
431
+ mode: MultiMode;
432
+ sells: MultiLeg[];
433
+ buys: MultiLeg[];
434
+ /** Raw hub units: what the sells are expected to deliver, and what they guarantee. */
435
+ hubExpected: string;
436
+ hubFloor: string;
437
+ totals: {
438
+ usdIn: number | null;
439
+ usdOut: number | null;
440
+ gasFeeUSD: number | null;
441
+ };
442
+ /** The multi router: calldata target, Permit2 spender and approval target. */
443
+ spender: string;
444
+ createdAt: number;
445
+ /** 120 seconds after the quote began. */
446
+ expiresAt: number;
447
+ }
448
+ /** How the ERC-20 sells reach the router. */
449
+ export type MultiPull = "allowance" | "permit2";
450
+ export interface MultiBuildParams {
451
+ /** An `mq_` id from `multi.quote()`. */
452
+ multiQuoteId: string;
453
+ /** Receives the hub or the buys, and sends the transaction unless `taker` is set. */
454
+ recipient: string;
455
+ taker?: string;
456
+ /** Must match the quote's if sent. */
457
+ slippageBps?: number;
458
+ pull: MultiPull;
459
+ /** Seconds from now; default 300, at most 3600. */
460
+ deadlineSecs?: number;
461
+ }
462
+ /** What stands between the wallet and the send, per ERC-20 sell. */
463
+ export interface MultiTokenState {
464
+ token: string;
465
+ state: "ready" | "signature" | "permit" | "approval";
466
+ approveTarget: string | null;
467
+ needed: string;
468
+ }
469
+ /** A sell dropped at build time, with the guard that dropped it. */
470
+ export interface MultiSkipped {
471
+ token: string;
472
+ code: string;
473
+ message: string;
474
+ }
475
+ export interface MultiBuild {
476
+ multiQuoteId: string;
477
+ router: string;
478
+ /** `multiSwap`, `multiSwapWithPermit2` or `multiSwapAndBridge`. */
479
+ entry: string;
480
+ mode: MultiMode;
481
+ transactionRequest: Transaction & {
482
+ from?: string;
483
+ };
484
+ /** The structured call, field for field `ILibertyMultiSwap`; every uint256 a decimal string. */
485
+ args: Record<string, unknown>;
486
+ /** EIP-712 typed data for the Permit2 batch, on the permit2 path. */
487
+ permit2?: Record<string, unknown> | null;
488
+ permits2612?: unknown[];
489
+ tokens: MultiTokenState[];
490
+ hubExpected: string;
491
+ hubFloor: string;
492
+ /** Sells that did not survive the build's guards; the rest still ran. */
493
+ skipped: MultiSkipped[];
494
+ simulation?: {
495
+ status: string;
496
+ why?: string;
497
+ [k: string]: unknown;
498
+ } | null;
499
+ deadline: string;
500
+ expiresAt: number;
501
+ }
502
+ export interface MultiXQuoteParams {
503
+ fromChainId: number;
504
+ toChainId: number;
505
+ /** The corridor asset on the SOURCE chain — what step 1 consolidated into. */
506
+ corridor: string;
507
+ /** Raw units of it: what the wallet holds after step 1, not what step 1 was quoted at. */
508
+ amount: string;
509
+ /** What to buy on the destination chain; shares sum to 10000. */
510
+ buys: MultiBuyParam[];
511
+ recipient: string;
512
+ slippageBps?: number;
513
+ }
514
+ export interface MultiXQuote {
515
+ /** An `mqx_` id. */
516
+ multiQuoteId: string;
517
+ fromChainId: number;
518
+ toChainId: number;
519
+ corridor: {
520
+ from: string;
521
+ to: string;
522
+ };
523
+ amount: string;
524
+ /** What the bridge delivers before the arrival message is priced in. */
525
+ delivered: string;
526
+ bridge: {
527
+ adapter: string;
528
+ etaSecs: number | null;
529
+ minimumAmount: string;
530
+ };
531
+ outputs: Array<{
532
+ token: string;
533
+ bps: number;
534
+ hubIn: string;
535
+ amount: string | null;
536
+ minimumAmount: string | null;
537
+ usdValueOut?: number | null;
538
+ priceImpactPct?: number | null;
539
+ passthrough: boolean;
540
+ }>;
541
+ expiresAt: number;
542
+ }
543
+ export interface MultiXBuildParams {
544
+ /** An `mqx_` id from `multi.xquote()`. */
545
+ multiQuoteId: string;
546
+ recipient: string;
547
+ /**
548
+ * An `mq_` id whose sells produce the corridor asset. With it, and on a
549
+ * network whose router carries the one-transaction entry, the bundle and the
550
+ * deposit are one transaction; without it this is the deposit alone.
551
+ */
552
+ sourceQuoteId?: string;
553
+ }
554
+ export interface MultiXBuild {
555
+ multiQuoteId: string;
556
+ router: string;
557
+ handler?: string;
558
+ transactionRequest: Transaction & {
559
+ from?: string;
560
+ };
561
+ /** One exact approval, for the same address the transaction goes to. */
562
+ approval: {
563
+ token: string;
564
+ target: string;
565
+ amount: string;
566
+ };
567
+ delivered?: string;
568
+ dstPayloadHash?: string;
569
+ sharesBps?: number[];
570
+ outputs: Array<{
571
+ token: string;
572
+ bps: number;
573
+ minimumAmount: string;
574
+ }>;
575
+ etaSecs?: number | null;
576
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lcx-liberty-sdk",
3
- "version": "1.0.2",
3
+ "version": "1.1.0",
4
4
  "description": "TypeScript SDK for the LCX Liberty DEX aggregator. Best-execution routing across Ethereum, Base, Arbitrum and OP Mainnet.",
5
5
  "type": "module",
6
6
  "module": "./dist/index.js",