lcx-liberty-sdk 1.0.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 +171 -0
- package/dist/constants.d.ts +28 -0
- package/dist/constants.js +28 -0
- package/dist/errors.d.ts +27 -0
- package/dist/errors.js +51 -0
- package/dist/index.d.ts +31 -0
- package/dist/index.js +84 -0
- package/dist/resources/account.d.ts +48 -0
- package/dist/resources/account.js +30 -0
- package/dist/resources/crosschain.d.ts +36 -0
- package/dist/resources/crosschain.js +59 -0
- package/dist/resources/prices.d.ts +78 -0
- package/dist/resources/prices.js +52 -0
- package/dist/resources/swap.d.ts +76 -0
- package/dist/resources/swap.js +61 -0
- package/dist/resources/tokens.d.ts +44 -0
- package/dist/resources/tokens.js +29 -0
- package/dist/transport.d.ts +10 -0
- package/dist/transport.js +107 -0
- package/dist/types.d.ts +349 -0
- package/dist/types.js +7 -0
- package/package.json +51 -0
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,349 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Wire types, shared across resources.
|
|
3
|
+
*
|
|
4
|
+
* These mirror the `/v1` responses exactly. Where the API omits a field
|
|
5
|
+
* rather than sending null, the type says optional, not `| null`.
|
|
6
|
+
*/
|
|
7
|
+
export interface QuoteParams {
|
|
8
|
+
chainId: number;
|
|
9
|
+
/** Sell token. Use `NATIVE` for the chain's native asset. */
|
|
10
|
+
tokenIn: string;
|
|
11
|
+
tokenOut: string;
|
|
12
|
+
/** Human amount, e.g. "1.5" — not raw units. */
|
|
13
|
+
amount: string;
|
|
14
|
+
/** Decimals of `tokenIn`. */
|
|
15
|
+
decimals: number;
|
|
16
|
+
/** Defaults to 50 (0.5%). */
|
|
17
|
+
slippageBps?: number;
|
|
18
|
+
/**
|
|
19
|
+
* Destination chain, for a CROSS-CHAIN quote. Omit (or set equal to
|
|
20
|
+
* `chainId`) for the same-chain quote, byte for byte as before. When it
|
|
21
|
+
* differs, `tokenOut` is an address on `toChainId`, `recipient` is required,
|
|
22
|
+
* and the answer is a `CrossChainQuote` — see `crossChainQuote()`, which
|
|
23
|
+
* types both.
|
|
24
|
+
*/
|
|
25
|
+
toChainId?: number;
|
|
26
|
+
/**
|
|
27
|
+
* Who receives on `toChainId`. REQUIRED with `toChainId` (the bridge
|
|
28
|
+
* deposit is built for it, and on the ETH corridor it decides whether ETH
|
|
29
|
+
* or WETH lands); ignored on a same-chain quote, which takes the recipient
|
|
30
|
+
* at `build()`.
|
|
31
|
+
*/
|
|
32
|
+
recipient?: string;
|
|
33
|
+
}
|
|
34
|
+
export interface SwapParams extends QuoteParams {
|
|
35
|
+
/** Address that sends the transaction and receives the output. */
|
|
36
|
+
taker: string;
|
|
37
|
+
deadlineSecs?: number;
|
|
38
|
+
}
|
|
39
|
+
export interface Hop {
|
|
40
|
+
pool: string;
|
|
41
|
+
dex: string;
|
|
42
|
+
family: string;
|
|
43
|
+
tokenIn: string;
|
|
44
|
+
tokenOut: string;
|
|
45
|
+
}
|
|
46
|
+
export interface Route {
|
|
47
|
+
amountIn: string;
|
|
48
|
+
amountOut: string;
|
|
49
|
+
hops: Hop[];
|
|
50
|
+
}
|
|
51
|
+
export interface Quote {
|
|
52
|
+
quoteId: string;
|
|
53
|
+
chainId: number;
|
|
54
|
+
input: {
|
|
55
|
+
token: string;
|
|
56
|
+
amount: string;
|
|
57
|
+
};
|
|
58
|
+
output: {
|
|
59
|
+
token: string;
|
|
60
|
+
amount: string;
|
|
61
|
+
minimumAmount: string;
|
|
62
|
+
};
|
|
63
|
+
/** Percent, e.g. 0.185. */
|
|
64
|
+
priceImpactPct: number;
|
|
65
|
+
gasEstimateWei: string;
|
|
66
|
+
gasFeeUSD: number;
|
|
67
|
+
/** The block this was derived from — record it to prove which state a price came from. */
|
|
68
|
+
blockNumber: number;
|
|
69
|
+
createdAt: number;
|
|
70
|
+
expiresAt: number;
|
|
71
|
+
slippageBps: number;
|
|
72
|
+
routes: Route[];
|
|
73
|
+
venues: string[];
|
|
74
|
+
spender: string | null;
|
|
75
|
+
stale: boolean;
|
|
76
|
+
}
|
|
77
|
+
/** Flat and ready for `sendTransaction`. */
|
|
78
|
+
export interface Transaction {
|
|
79
|
+
to: string;
|
|
80
|
+
data: string;
|
|
81
|
+
value: string;
|
|
82
|
+
chainId?: number;
|
|
83
|
+
deadline?: string;
|
|
84
|
+
minAmountOut?: string;
|
|
85
|
+
}
|
|
86
|
+
export interface SwapResult {
|
|
87
|
+
quote: Quote;
|
|
88
|
+
transaction: Transaction;
|
|
89
|
+
}
|
|
90
|
+
export interface Token {
|
|
91
|
+
address: string;
|
|
92
|
+
symbol: string;
|
|
93
|
+
name: string;
|
|
94
|
+
decimals: number;
|
|
95
|
+
chainId: number;
|
|
96
|
+
/**
|
|
97
|
+
* Image URL, or null once the backend has verified that no logo exists —
|
|
98
|
+
* render your own fallback immediately rather than paying a guaranteed 404.
|
|
99
|
+
* Unchecked tokens carry a best-guess URL that may 404.
|
|
100
|
+
*/
|
|
101
|
+
logo?: string | null;
|
|
102
|
+
/**
|
|
103
|
+
* Where a verified logo came from. Null while unchecked and when none
|
|
104
|
+
* exists. ATTRIBUTION: rows whose `logoSource` is "geckoterminal" carry
|
|
105
|
+
* CoinGecko-licensed data — if you render them, place a hyperlinked
|
|
106
|
+
* "Powered by GeckoTerminal" (https://www.geckoterminal.com) near them, and
|
|
107
|
+
* do not redistribute them through your own API. Keyed API responses omit
|
|
108
|
+
* GeckoTerminal-sourced logos (served as null) because that license does
|
|
109
|
+
* not extend to commercial redistribution.
|
|
110
|
+
*/
|
|
111
|
+
logoSource?: "trustwallet" | "geckoterminal" | null;
|
|
112
|
+
}
|
|
113
|
+
export interface Allowance {
|
|
114
|
+
token: string;
|
|
115
|
+
taker?: string;
|
|
116
|
+
spender: string | null;
|
|
117
|
+
/** Raw units, or null when approval does not apply (native asset). */
|
|
118
|
+
allowance: string | null;
|
|
119
|
+
/** Always a boolean: false for the native asset and where the router is not
|
|
120
|
+
* deployed on that chain, with `reason` saying which. */
|
|
121
|
+
required: boolean;
|
|
122
|
+
permit2?: string;
|
|
123
|
+
reason?: string;
|
|
124
|
+
}
|
|
125
|
+
export interface PermitTypedData {
|
|
126
|
+
types: Record<string, {
|
|
127
|
+
name: string;
|
|
128
|
+
type: string;
|
|
129
|
+
}[]>;
|
|
130
|
+
primaryType: string;
|
|
131
|
+
domain: Record<string, unknown>;
|
|
132
|
+
message: Record<string, unknown>;
|
|
133
|
+
}
|
|
134
|
+
export interface ChainStatus {
|
|
135
|
+
chainId: number;
|
|
136
|
+
key: string;
|
|
137
|
+
name: string;
|
|
138
|
+
nativeSymbol: string;
|
|
139
|
+
available: boolean;
|
|
140
|
+
ageSeconds: number | null;
|
|
141
|
+
}
|
|
142
|
+
export interface Usage {
|
|
143
|
+
plan: string;
|
|
144
|
+
planLabel: string;
|
|
145
|
+
rateLimit: {
|
|
146
|
+
perSecond: number;
|
|
147
|
+
perMinute: number;
|
|
148
|
+
};
|
|
149
|
+
monthlyCalls: number | null;
|
|
150
|
+
callsUsed: number | null;
|
|
151
|
+
callsRemaining: number | null;
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* Who stands behind the bridge leg. `issuer` — the token's issuer mints on the
|
|
155
|
+
* destination (CCTP); `canonical` — the rollup's own bridge; `relayer_backed`
|
|
156
|
+
* — a relayer fronts the funds (Across). Carried on every quote, not optimised
|
|
157
|
+
* for: ranking is on net output, so read this if you care who holds the funds
|
|
158
|
+
* in the middle.
|
|
159
|
+
*/
|
|
160
|
+
export type TrustTier = "issuer" | "canonical" | "relayer_backed";
|
|
161
|
+
export type CrossChainShape = "DIRECT" | "SWAP_BRIDGE" | "BRIDGE_SWAP" | "SWAP_BRIDGE_SWAP";
|
|
162
|
+
export interface BridgeFee {
|
|
163
|
+
name: string;
|
|
164
|
+
/** Base units of `token`. */
|
|
165
|
+
amount: string;
|
|
166
|
+
token: string;
|
|
167
|
+
/** Null when unknown — never 0. */
|
|
168
|
+
amountUsd: number | null;
|
|
169
|
+
}
|
|
170
|
+
export interface BridgeLeg {
|
|
171
|
+
kind: "bridge";
|
|
172
|
+
/** "across" | "cctp" | … */
|
|
173
|
+
adapter: string;
|
|
174
|
+
/** "USDC" | "ETH" */
|
|
175
|
+
corridor: string;
|
|
176
|
+
fromChainId: number;
|
|
177
|
+
toChainId: number;
|
|
178
|
+
tokenIn: string;
|
|
179
|
+
tokenOut: string;
|
|
180
|
+
amountIn: string;
|
|
181
|
+
out: string;
|
|
182
|
+
minOut: string;
|
|
183
|
+
etaSec: number | null;
|
|
184
|
+
trustTier: TrustTier;
|
|
185
|
+
fees: BridgeFee[];
|
|
186
|
+
maxAmount?: string | null;
|
|
187
|
+
approvalTarget?: string | null;
|
|
188
|
+
gasFeeUSD?: number | null;
|
|
189
|
+
expiresAt?: number;
|
|
190
|
+
}
|
|
191
|
+
export interface SwapLeg {
|
|
192
|
+
kind: "swap";
|
|
193
|
+
chainId: number;
|
|
194
|
+
tokenIn: string;
|
|
195
|
+
tokenOut: string;
|
|
196
|
+
amountIn: string;
|
|
197
|
+
out: string;
|
|
198
|
+
minOut: string;
|
|
199
|
+
slippageBps?: number;
|
|
200
|
+
gasEstimateWei?: string | null;
|
|
201
|
+
gasFeeUSD?: number | null;
|
|
202
|
+
spender?: string | null;
|
|
203
|
+
etaSec?: number | null;
|
|
204
|
+
expiresAt?: number;
|
|
205
|
+
/** The same-chain SOR route object for this leg. */
|
|
206
|
+
route?: {
|
|
207
|
+
routes?: Route[];
|
|
208
|
+
venues?: string[];
|
|
209
|
+
stale?: boolean;
|
|
210
|
+
} | null;
|
|
211
|
+
}
|
|
212
|
+
export type CrossChainLeg = BridgeLeg | SwapLeg;
|
|
213
|
+
/**
|
|
214
|
+
* A cross-chain quote (`toChainId` set and different from `chainId`).
|
|
215
|
+
*
|
|
216
|
+
* Two fields are the contract and must not be modified by a client:
|
|
217
|
+
* `endToEndMinOut` is what the last leg is guaranteed to deliver or revert
|
|
218
|
+
* (every leg is sized at the previous leg's floor), and `approval.amount` is
|
|
219
|
+
* the EXACT input the deposit pulls — approve that, not the maximum.
|
|
220
|
+
*
|
|
221
|
+
* `expiresAt` is 25 seconds after `createdAt`, not the same-chain 120: a
|
|
222
|
+
* bridge quote is an offer for that long. Re-quote rather than hold one.
|
|
223
|
+
*
|
|
224
|
+
* Stage S1 is quote-only: `build()` on a cross-chain `quoteId` returns
|
|
225
|
+
* `cross_chain_build_unsupported` until execution ships.
|
|
226
|
+
*/
|
|
227
|
+
export interface CrossChainQuote {
|
|
228
|
+
quoteId: string;
|
|
229
|
+
type: "CROSS_CHAIN";
|
|
230
|
+
shape: CrossChainShape;
|
|
231
|
+
fromChainId: number;
|
|
232
|
+
toChainId: number;
|
|
233
|
+
tokenIn: string;
|
|
234
|
+
tokenOut: string;
|
|
235
|
+
amountIn: string;
|
|
236
|
+
recipient: string;
|
|
237
|
+
slippageBps: number;
|
|
238
|
+
legs: CrossChainLeg[];
|
|
239
|
+
endToEndOut: string;
|
|
240
|
+
endToEndMinOut: string;
|
|
241
|
+
etaSec: number | null;
|
|
242
|
+
trustTier: TrustTier;
|
|
243
|
+
/** Null for a native-coin input — nothing to approve. */
|
|
244
|
+
approval: {
|
|
245
|
+
target: string;
|
|
246
|
+
amount: string;
|
|
247
|
+
} | null;
|
|
248
|
+
gasFeeUSD: number | null;
|
|
249
|
+
createdAt: number;
|
|
250
|
+
expiresAt: number;
|
|
251
|
+
/** The ranking key: the floor less the gas the route is known to cost. */
|
|
252
|
+
netOut?: string;
|
|
253
|
+
gasAccounted?: boolean;
|
|
254
|
+
}
|
|
255
|
+
/** One corridor × adapter that was enumerated and refused, with the stage and reason. */
|
|
256
|
+
export interface RejectedCrossRoute {
|
|
257
|
+
shape: CrossChainShape | string;
|
|
258
|
+
corridor: string;
|
|
259
|
+
adapter: string | null;
|
|
260
|
+
stage: string;
|
|
261
|
+
reason: string;
|
|
262
|
+
}
|
|
263
|
+
export interface CrossChainQuoteResult {
|
|
264
|
+
/** The best route by net output. */
|
|
265
|
+
quote: CrossChainQuote;
|
|
266
|
+
/** The rest, ranked best-first. */
|
|
267
|
+
alternatives: CrossChainQuote[];
|
|
268
|
+
/** Why the others were not offered — "no route" is never silent. */
|
|
269
|
+
rejected: RejectedCrossRoute[];
|
|
270
|
+
}
|
|
271
|
+
export interface CrossChainQuoteParams extends QuoteParams {
|
|
272
|
+
toChainId: number;
|
|
273
|
+
recipient: string;
|
|
274
|
+
}
|
|
275
|
+
/**
|
|
276
|
+
* The tracker's state machine:
|
|
277
|
+
* QUOTED → SUBMITTED → SRC_CONFIRMED → BRIDGE_PENDING → BRIDGE_COMPLETE
|
|
278
|
+
* → DST_EXECUTED | DST_FALLBACK → DONE
|
|
279
|
+
* REFUND_PENDING → REFUNDED AWAITING_ACTION NEEDS_ATTENTION
|
|
280
|
+
* `DST_FALLBACK` is a SUCCESS: the corridor asset reached the recipient on the
|
|
281
|
+
* destination because the destination swap could not run. Open union so a
|
|
282
|
+
* state added later still types.
|
|
283
|
+
*/
|
|
284
|
+
export type BridgeTransferState = "QUOTED" | "SUBMITTED" | "SRC_CONFIRMED" | "BRIDGE_PENDING" | "BRIDGE_COMPLETE" | "DST_EXECUTED" | "DST_FALLBACK" | "DONE" | "REFUND_PENDING" | "REFUNDED" | "AWAITING_ACTION" | "NEEDS_ATTENTION" | (string & {});
|
|
285
|
+
export interface BridgeTransferTimestamps {
|
|
286
|
+
quotedAt?: number | null;
|
|
287
|
+
submittedAt?: number | null;
|
|
288
|
+
srcConfirmedAt?: number | null;
|
|
289
|
+
bridgePendingAt?: number | null;
|
|
290
|
+
bridgeCompleteAt?: number | null;
|
|
291
|
+
dstExecutedAt?: number | null;
|
|
292
|
+
dstFallbackAt?: number | null;
|
|
293
|
+
refundPendingAt?: number | null;
|
|
294
|
+
refundedAt?: number | null;
|
|
295
|
+
awaitingActionAt?: number | null;
|
|
296
|
+
needsAttentionAt?: number | null;
|
|
297
|
+
doneAt?: number | null;
|
|
298
|
+
}
|
|
299
|
+
/**
|
|
300
|
+
* One tracked bridge transfer. Nullable where the tracker has seen only one
|
|
301
|
+
* side so far — a fill observed on the destination before its deposit has no
|
|
302
|
+
* `srcTxHash`, `tokenIn` or `amountIn` yet.
|
|
303
|
+
*/
|
|
304
|
+
export interface BridgeTransfer {
|
|
305
|
+
transferId: string;
|
|
306
|
+
adapter: string;
|
|
307
|
+
state: BridgeTransferState;
|
|
308
|
+
srcChainId: number;
|
|
309
|
+
dstChainId: number;
|
|
310
|
+
sender: string | null;
|
|
311
|
+
recipient: string | null;
|
|
312
|
+
finalRecipient: string | null;
|
|
313
|
+
tokenIn: string | null;
|
|
314
|
+
tokenOut: string | null;
|
|
315
|
+
amountIn: string | null;
|
|
316
|
+
amountOut: string | null;
|
|
317
|
+
srcTxHash: string | null;
|
|
318
|
+
dstTxHash: string | null;
|
|
319
|
+
refundTxHash: string | null;
|
|
320
|
+
/** True when the corridor asset was delivered instead of the intended token. */
|
|
321
|
+
fallback: boolean;
|
|
322
|
+
pendingAction: string | null;
|
|
323
|
+
attentionReason: string | null;
|
|
324
|
+
timestamps: BridgeTransferTimestamps;
|
|
325
|
+
updatedAt: number;
|
|
326
|
+
/** Initiated through Liberty, vs. merely observed for this wallet. */
|
|
327
|
+
ours: boolean;
|
|
328
|
+
}
|
|
329
|
+
export interface BridgeTransferPage {
|
|
330
|
+
wallet: string;
|
|
331
|
+
transfers: BridgeTransfer[];
|
|
332
|
+
/** Pass back as `cursor` for the next page; null at the end. */
|
|
333
|
+
nextCursor: string | null;
|
|
334
|
+
}
|
|
335
|
+
export interface LibertyOptions {
|
|
336
|
+
/** Omit to use the anonymous tier — fine for evaluation, rate limited. */
|
|
337
|
+
apiKey?: string;
|
|
338
|
+
baseUrl?: string;
|
|
339
|
+
/** Per request, milliseconds. Default 20000. */
|
|
340
|
+
timeoutMs?: number;
|
|
341
|
+
/**
|
|
342
|
+
* Retries for transient failures. Default 2.
|
|
343
|
+
*
|
|
344
|
+
* Only 5xx, network errors and 429 are retried. A 4xx is never retried —
|
|
345
|
+
* sending the same bad request again just spends the caller's quota.
|
|
346
|
+
*/
|
|
347
|
+
maxRetries?: number;
|
|
348
|
+
fetch?: typeof globalThis.fetch;
|
|
349
|
+
}
|
package/dist/types.js
ADDED
package/package.json
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "lcx-liberty-sdk",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "TypeScript SDK for the LCX Liberty DEX aggregator. Best-execution routing across Ethereum, Base, Arbitrum and OP Mainnet.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./dist/index.js",
|
|
7
|
+
"module": "./dist/index.js",
|
|
8
|
+
"types": "./dist/index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"types": "./dist/index.d.ts",
|
|
12
|
+
"import": "./dist/index.js"
|
|
13
|
+
}
|
|
14
|
+
},
|
|
15
|
+
"files": [
|
|
16
|
+
"dist",
|
|
17
|
+
"README.md"
|
|
18
|
+
],
|
|
19
|
+
"sideEffects": false,
|
|
20
|
+
"engines": {
|
|
21
|
+
"node": ">=18"
|
|
22
|
+
},
|
|
23
|
+
"scripts": {
|
|
24
|
+
"build": "tsc -p tsconfig.json",
|
|
25
|
+
"test": "node --test test/*.test.mjs",
|
|
26
|
+
"prepublishOnly": "npm run build && npm test"
|
|
27
|
+
},
|
|
28
|
+
"keywords": [
|
|
29
|
+
"dex",
|
|
30
|
+
"aggregator",
|
|
31
|
+
"swap",
|
|
32
|
+
"defi",
|
|
33
|
+
"ethereum",
|
|
34
|
+
"base",
|
|
35
|
+
"arbitrum",
|
|
36
|
+
"optimism",
|
|
37
|
+
"lcx"
|
|
38
|
+
],
|
|
39
|
+
"license": "MIT",
|
|
40
|
+
"devDependencies": {
|
|
41
|
+
"typescript": "^5.6.0"
|
|
42
|
+
},
|
|
43
|
+
"publishConfig": {
|
|
44
|
+
"access": "public"
|
|
45
|
+
},
|
|
46
|
+
"homepage": "https://dex.lcx.com/business",
|
|
47
|
+
"bugs": {
|
|
48
|
+
"email": "support@lcx.com"
|
|
49
|
+
},
|
|
50
|
+
"author": "LCX"
|
|
51
|
+
}
|