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 +62 -31
- package/dist/constants.d.ts +18 -13
- package/dist/constants.js +18 -13
- package/dist/index.d.ts +4 -0
- package/dist/index.js +6 -2
- package/dist/resources/multi.d.ts +56 -0
- package/dist/resources/multi.js +81 -0
- package/dist/transport.js +6 -6
- package/dist/types.d.ts +242 -11
- package/package.json +2 -2
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
|
|
5
|
-
|
|
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
|
-
|
|
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
|
-
|
|
121
|
-
|
|
122
|
-
`
|
|
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 |
|
|
125
|
-
|
|
126
|
-
| Router proxy (the `spender`: swaps
|
|
127
|
-
|
|
|
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
|
-
|
|
130
|
-
|
|
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
|
|
135
|
-
|
|
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`.
|
|
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
|
|
package/dist/constants.d.ts
CHANGED
|
@@ -1,28 +1,33 @@
|
|
|
1
1
|
/** Version, hosts and chain constants. Imported by every resource. */
|
|
2
|
-
export declare const VERSION = "1.
|
|
2
|
+
export declare const VERSION = "1.2.0";
|
|
3
3
|
/**
|
|
4
|
-
* The
|
|
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
|
|
16
|
-
*
|
|
17
|
-
*
|
|
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
|
-
/**
|
|
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.
|
|
2
|
+
export const VERSION = "1.2.0";
|
|
3
3
|
/**
|
|
4
|
-
* The
|
|
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
|
|
16
|
-
*
|
|
17
|
-
*
|
|
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
|
-
/**
|
|
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
|
|
21
|
-
//
|
|
22
|
-
//
|
|
23
|
-
//
|
|
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
|
|
26
|
-
"dashboard
|
|
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
|
-
|
|
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
|
-
/**
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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
|
|
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
|
|
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
|
-
/**
|
|
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
|
|
4
|
-
"description": "TypeScript SDK for the LCX Liberty DEX aggregator. Best-execution routing across Ethereum, Base, Arbitrum and
|
|
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",
|