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.
@@ -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
@@ -0,0 +1,7 @@
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 {};
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
+ }