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 ADDED
@@ -0,0 +1,171 @@
1
+ # lcx-liberty-sdk
2
+
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.
6
+
7
+ Zero dependencies. Node 18+, Deno, Bun, Workers, browser.
8
+
9
+ ```bash
10
+ npm i lcx-liberty-sdk
11
+ ```
12
+
13
+ ## Swap in one call
14
+
15
+ ```ts
16
+ import { LibertyDex } from "lcx-liberty-sdk";
17
+
18
+ const lcx = new LibertyDex({ apiKey: process.env.LCX_API_KEY });
19
+
20
+ const { quote, transaction } = await lcx.swap.execute({
21
+ chainId: 1,
22
+ tokenIn: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
23
+ tokenOut: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
24
+ amount: "1",
25
+ decimals: 18,
26
+ taker: userAddress,
27
+ slippageBps: 50,
28
+ });
29
+
30
+ console.log(quote.output.amount, "USDC, floor", quote.output.minimumAmount);
31
+ await wallet.sendTransaction(transaction); // { to, data, value }
32
+ ```
33
+
34
+ ## Approval first
35
+
36
+ ```ts
37
+ const { required, spender } = await lcx.swap.allowance({
38
+ chainId: 1, token: WETH, taker: userAddress, amount: rawAmount,
39
+ });
40
+
41
+ if (required) {
42
+ try {
43
+ // Gasless where the token supports it.
44
+ const typedData = await lcx.swap.permit({ chainId: 1, token: WETH, owner: userAddress });
45
+ const signature = await wallet.signTypedData(typedData);
46
+ } catch (e) {
47
+ if (e.code === "PERMIT_UNSUPPORTED") await erc20.approve(spender, rawAmount);
48
+ else throw e;
49
+ }
50
+ }
51
+ ```
52
+
53
+ ## Errors you can branch on
54
+
55
+ Every failure is a `LibertyError` with a stable `code` and a message written for
56
+ a human, and usually worth showing verbatim.
57
+
58
+ ```ts
59
+ import { LibertyError } from "lcx-liberty-sdk";
60
+
61
+ try {
62
+ await lcx.swap.quote({ ... });
63
+ } catch (e) {
64
+ if (e instanceof LibertyError) {
65
+ if (e.isNoLiquidity) // the pair or size cannot be routed, try smaller
66
+ if (e.isRateLimited) // back off, or upgrade the plan
67
+ if (e.isClientError) // the request is wrong; retrying will not help
68
+ }
69
+ }
70
+ ```
71
+
72
+ Transient failures (5xx, network, 429) are retried twice with jittered backoff.
73
+ Client errors are never retried, because resending a bad request only spends quota.
74
+
75
+ ## The full surface
76
+
77
+ Six namespaces. Nobody reads past a namespace they are not using, so the swap
78
+ surface stays as short as it ever was however many sit beside it.
79
+
80
+ This wraps the surfaces LCX offers publicly, and only those. Anything absent is
81
+ absent on purpose: an SDK method is a promise to keep something working, so a
82
+ client is not the place to publish a surface by implication.
83
+
84
+ ### `lcx.swap` (same-chain)
85
+ | method | what it is for |
86
+ |---|---|
87
+ | `execute()` | quote + signable calldata, one call |
88
+ | `quote()` | price only, nothing executed |
89
+ | `build()` | calldata for a `quoteId` you already hold |
90
+ | `allowance()` | does this taker need to approve, and of whom |
91
+ | `permit()` | EIP-2612 typed data for a gasless approval |
92
+ | `submit()` | broadcast a signed transaction, private builder path first |
93
+
94
+ ### `lcx.crossChain`
95
+ | method | what it is for |
96
+ |---|---|
97
+ | `quote()` | `tokenIn` on one chain to `tokenOut` on another, as legs: bridge + swap(s), one end-to-end floor, trust tier and ETA. Quote-only at this stage |
98
+ | `transfers()` / `transfer(id)` | a wallet's bridge transfers and their state (sent, bridging, delivered, refunded), from our own indexer |
99
+ | `health()` | the tracker's per-chain frontier and backlog |
100
+
101
+ ### `lcx.prices`
102
+ | method | what it is for |
103
+ |---|---|
104
+ | `get()` | USD price from real pool depth |
105
+ | `batch()` | up to 250 tokens in one round trip |
106
+ | `history()` | one token's close on one past day |
107
+
108
+ ### `lcx.tokens` · `lcx.chains` · `lcx.account`
109
+ | method | what it is for |
110
+ |---|---|
111
+ | `tokens.list()` | resolve a ticker to an address |
112
+ | `tokens.page()` | the same, with `hasMore` / `nextOffset` for walking past page one |
113
+ | `chains.list()` | supported chains and index freshness |
114
+ | `account.usage()` | your plan, calls used and remaining |
115
+ | `account.plans()` | every plan and its limits |
116
+ | `account.stats()` | how much liquidity the index can see |
117
+
118
+ ## Notes worth knowing
119
+
120
+ - **Amounts in, human; amounts out, raw.** You pass `"1.5"` with `decimals`; the
121
+ API returns raw units, because an 18-decimal amount does not survive a JS
122
+ number.
123
+ - **Failed requests are never billed.** A 4xx or 5xx costs nothing.
124
+ - **Hitting your monthly limit returns 429, not an invoice.** There is no
125
+ overage billing.
126
+ - **Quotes carry `blockNumber` and `expiresAt`** so you can prove which chain
127
+ state a price came from.
128
+ - **Approval is client-side.** We return the `spender`; you send the approve.
129
+ - **Cross-chain quotes are offers for 25 seconds** (`expiresAt`), need a
130
+ `recipient`, and carry two fields you must pass through untouched:
131
+ `endToEndMinOut` (the guarantee) and `approval.amount` (exact, so approve
132
+ that, never the maximum). `build()` on a cross-chain `quoteId` returns
133
+ `cross_chain_build_unsupported` until execution ships.
134
+
135
+ ## API key
136
+
137
+ The SDK talks to `swap-api.lcx.com`, the commercial API, where a key is
138
+ required, so `new LibertyDex()` without an `apiKey` throws with a message
139
+ telling you where to get one. Create a free key (150k calls/month, no card) in
140
+ the [developer dashboard](https://dex.lcx.com/dashboard).
141
+
142
+ To try the API before you have a key, point the client at the public product
143
+ surface, which serves reads on an anonymous, rate-limited tier:
144
+
145
+ ```ts
146
+ import { LibertyDex, PUBLIC_BASE_URL } from "lcx-liberty-sdk";
147
+ const lcx = new LibertyDex({ baseUrl: PUBLIC_BASE_URL }); // no key, evaluation only
148
+ ```
149
+
150
+ Never put the key in a browser bundle: it is a server-side credential. In a
151
+ web app, call the SDK from your backend and forward the result.
152
+
153
+ ## Data sources, licensing and attribution
154
+
155
+ Every price with `source: "index"`, which is every token our own index can
156
+ price, comes from our own pool depth and carries no third-party strings.
157
+
158
+ A small amount of gap-fill data is licensed from CoinGecko's GeckoTerminal:
159
+ USD prices labeled `source: "external"` and token logos labeled
160
+ `logoSource: "geckoterminal"`. Their terms do not allow us to redistribute
161
+ that data through a commercial API, so **keyed (API-key) responses omit those
162
+ fields**: an oracle-unpriceable token answers `usd: null`, and a
163
+ GeckoTerminal-logoed token serves `logo: null`. Anonymous evaluation calls may
164
+ still receive them; if you render such a figure or logo, place a hyperlinked
165
+ "Powered by GeckoTerminal" (https://www.geckoterminal.com) near it, and do not
166
+ re-serve or redistribute that data through your own API. The license that
167
+ lets it reach you does not extend past your screen.
168
+
169
+ ## License
170
+
171
+ MIT
@@ -0,0 +1,28 @@
1
+ /** Version, hosts and chain constants. Imported by every resource. */
2
+ export declare const VERSION = "1.0.0";
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.
12
+ */
13
+ export declare const DEFAULT_BASE_URL = "https://swap-api.lcx.com";
14
+ /**
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.
18
+ */
19
+ export declare const PUBLIC_BASE_URL = "https://dex-api.lcx.com";
20
+ /** Chains the aggregator indexes. */
21
+ export declare const CHAINS: {
22
+ readonly ethereum: 1;
23
+ readonly optimism: 10;
24
+ readonly base: 8453;
25
+ readonly arbitrum: 42161;
26
+ };
27
+ /** The zero address, which every endpoint treats as the chain's native asset. */
28
+ export declare const NATIVE = "0x0000000000000000000000000000000000000000";
@@ -0,0 +1,28 @@
1
+ /** Version, hosts and chain constants. Imported by every resource. */
2
+ export const VERSION = "1.0.0";
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.
12
+ */
13
+ export const DEFAULT_BASE_URL = "https://swap-api.lcx.com";
14
+ /**
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.
18
+ */
19
+ export const PUBLIC_BASE_URL = "https://dex-api.lcx.com";
20
+ /** Chains the aggregator indexes. */
21
+ export const CHAINS = {
22
+ ethereum: 1,
23
+ optimism: 10,
24
+ base: 8453,
25
+ arbitrum: 42161,
26
+ };
27
+ /** The zero address, which every endpoint treats as the chain's native asset. */
28
+ export const NATIVE = "0x0000000000000000000000000000000000000000";
@@ -0,0 +1,27 @@
1
+ /** The one error type the SDK throws. */
2
+ /**
3
+ * A failure the API described.
4
+ *
5
+ * `code` is stable and meant to be switched on; `message` is written for a human
6
+ * and is usually worth surfacing verbatim — "this pair is indexed, but our
7
+ * liquidity is too thin at this size" tells a user what to do, where "request
8
+ * failed" does not.
9
+ */
10
+ export declare class LibertyError extends Error {
11
+ readonly code: string;
12
+ readonly status: number;
13
+ readonly details?: unknown;
14
+ constructor(code: string, message: string, status: number, details?: unknown);
15
+ /**
16
+ * Retrying will not help: the request itself is wrong.
17
+ *
18
+ * Classified by CODE as well as status. An API can answer a bad request with
19
+ * 200 and `success: false`, and a client that trusted the status alone would
20
+ * retry it — spending the caller's quota to get the same answer.
21
+ */
22
+ get isClientError(): boolean;
23
+ /** Back off and retry, or upgrade the plan. */
24
+ get isRateLimited(): boolean;
25
+ /** The pair or size could not be routed — a smaller amount may work. */
26
+ get isNoLiquidity(): boolean;
27
+ }
package/dist/errors.js ADDED
@@ -0,0 +1,51 @@
1
+ /** The one error type the SDK throws. */
2
+ /**
3
+ * A failure the API described.
4
+ *
5
+ * `code` is stable and meant to be switched on; `message` is written for a human
6
+ * and is usually worth surfacing verbatim — "this pair is indexed, but our
7
+ * liquidity is too thin at this size" tells a user what to do, where "request
8
+ * failed" does not.
9
+ */
10
+ export class LibertyError extends Error {
11
+ code;
12
+ status;
13
+ details;
14
+ constructor(code, message, status, details) {
15
+ super(message);
16
+ this.name = "LibertyError";
17
+ this.code = code;
18
+ this.status = status;
19
+ this.details = details;
20
+ }
21
+ /**
22
+ * Retrying will not help: the request itself is wrong.
23
+ *
24
+ * Classified by CODE as well as status. An API can answer a bad request with
25
+ * 200 and `success: false`, and a client that trusted the status alone would
26
+ * retry it — spending the caller's quota to get the same answer.
27
+ */
28
+ get isClientError() {
29
+ const clientCodes = [
30
+ "unknown_chain",
31
+ "bad_request",
32
+ "bad_token",
33
+ "bad_recipient",
34
+ "bad_address",
35
+ "unknown_plan",
36
+ "INVALID_API_KEY",
37
+ "bad_email",
38
+ ];
39
+ if (clientCodes.includes(this.code))
40
+ return true;
41
+ return this.status >= 400 && this.status < 500 && !this.isRateLimited;
42
+ }
43
+ /** Back off and retry, or upgrade the plan. */
44
+ get isRateLimited() {
45
+ return this.code === "RATE_LIMITED" || this.code === "QUOTA_EXCEEDED";
46
+ }
47
+ /** The pair or size could not be routed — a smaller amount may work. */
48
+ get isNoLiquidity() {
49
+ return this.code === "no_route" || this.code === "insufficient_liquidity";
50
+ }
51
+ }
@@ -0,0 +1,31 @@
1
+ import { AccountResource, ChainsResource } from "./resources/account.js";
2
+ import { CrossChainResource } from "./resources/crosschain.js";
3
+ import { PricesResource } from "./resources/prices.js";
4
+ import { SwapResource } from "./resources/swap.js";
5
+ import { TokensResource } from "./resources/tokens.js";
6
+ import type { LibertyOptions } from "./types.js";
7
+ export declare class LibertyDex {
8
+ /** Price, build, sign and send a same-chain swap. */
9
+ readonly swap: SwapResource;
10
+ /** Quote across chains, and follow a transfer to the far side. */
11
+ readonly crossChain: CrossChainResource;
12
+ /** The token registry, and what we vouch for. */
13
+ readonly tokens: TokensResource;
14
+ /** USD prices: one token, a batch, or a past day. */
15
+ readonly prices: PricesResource;
16
+ /** Supported chains and index freshness. */
17
+ readonly chains: ChainsResource;
18
+ /** Your key: plan, quota, and the index behind it. */
19
+ readonly account: AccountResource;
20
+ constructor(options?: LibertyOptions);
21
+ }
22
+ export { CHAINS, NATIVE, PUBLIC_BASE_URL, VERSION } from "./constants.js";
23
+ export { LibertyError } from "./errors.js";
24
+ export { Transport } from "./transport.js";
25
+ export * from "./types.js";
26
+ export { SwapResource, type SubmitResult } from "./resources/swap.js";
27
+ export { CrossChainResource } from "./resources/crosschain.js";
28
+ export { TokensResource } from "./resources/tokens.js";
29
+ export { PricesResource, MAX_TOKENS_PER_BATCH, type PriceBatch, type PriceSource, type HistoricPrice, } from "./resources/prices.js";
30
+ export { AccountResource, ChainsResource, type Plan, type Stats, } from "./resources/account.js";
31
+ export default LibertyDex;
package/dist/index.js ADDED
@@ -0,0 +1,84 @@
1
+ /**
2
+ * LCX Liberty DEX SDK — the aggregator, as a typed client.
3
+ *
4
+ * ```ts
5
+ * const lcx = new LibertyDex({ apiKey: process.env.LCX_API_KEY });
6
+ *
7
+ * const { transaction } = await lcx.swap.execute({
8
+ * chainId: 1,
9
+ * tokenIn: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
10
+ * tokenOut: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
11
+ * amount: "1",
12
+ * decimals: 18,
13
+ * taker: userAddress,
14
+ * });
15
+ * await wallet.sendTransaction(transaction);
16
+ * ```
17
+ *
18
+ * ## Why this is namespaced
19
+ *
20
+ * A method per endpoint on one object gets worse with every endpoint added,
21
+ * which is what an earlier version of this file objected to. Namespaces do not
22
+ * have that problem: `lcx.swap.*` is exactly as short to read however many
23
+ * namespaces sit beside it, because nobody reads past one they are not using.
24
+ * That is what makes it safe to cover the API broadly instead of picking a
25
+ * subset and leaving integrators to hand-roll `fetch` for the rest.
26
+ *
27
+ * ## Scope
28
+ *
29
+ * This wraps the surfaces LCX offers publicly, and only those. Endpoints that
30
+ * exist for our own applications are deliberately not wrapped: an SDK method is
31
+ * a promise to keep something working, and a typed client is how an endpoint
32
+ * becomes an API whether or not anyone meant it to. What is missing here is
33
+ * missing on purpose.
34
+ *
35
+ * ## Design
36
+ *
37
+ * Zero dependencies, `fetch`-based, works in Node 18+, Deno, Bun, Cloudflare
38
+ * Workers and the browser. A dependency in an SDK becomes a dependency in every
39
+ * customer's build, and a swap client has no business dragging one in.
40
+ *
41
+ * Each namespace is one file under `resources/`, holding its own types and
42
+ * taking the shared `Transport`. Adding a product surface is adding a file and
43
+ * one line below — no existing namespace changes, and consumers tree-shake what
44
+ * they do not import.
45
+ */
46
+ import { Transport } from "./transport.js";
47
+ import { AccountResource, ChainsResource } from "./resources/account.js";
48
+ import { CrossChainResource } from "./resources/crosschain.js";
49
+ import { PricesResource } from "./resources/prices.js";
50
+ import { SwapResource } from "./resources/swap.js";
51
+ import { TokensResource } from "./resources/tokens.js";
52
+ export class LibertyDex {
53
+ /** Price, build, sign and send a same-chain swap. */
54
+ swap;
55
+ /** Quote across chains, and follow a transfer to the far side. */
56
+ crossChain;
57
+ /** The token registry, and what we vouch for. */
58
+ tokens;
59
+ /** USD prices: one token, a batch, or a past day. */
60
+ prices;
61
+ /** Supported chains and index freshness. */
62
+ chains;
63
+ /** Your key: plan, quota, and the index behind it. */
64
+ account;
65
+ constructor(options = {}) {
66
+ const t = new Transport(options);
67
+ this.swap = new SwapResource(t);
68
+ this.crossChain = new CrossChainResource(t);
69
+ this.tokens = new TokensResource(t);
70
+ this.prices = new PricesResource(t);
71
+ this.chains = new ChainsResource(t);
72
+ this.account = new AccountResource(t);
73
+ }
74
+ }
75
+ export { CHAINS, NATIVE, PUBLIC_BASE_URL, VERSION } from "./constants.js";
76
+ export { LibertyError } from "./errors.js";
77
+ export { Transport } from "./transport.js";
78
+ export * from "./types.js";
79
+ export { SwapResource } from "./resources/swap.js";
80
+ export { CrossChainResource } from "./resources/crosschain.js";
81
+ export { TokensResource } from "./resources/tokens.js";
82
+ export { PricesResource, MAX_TOKENS_PER_BATCH, } from "./resources/prices.js";
83
+ export { AccountResource, ChainsResource, } from "./resources/account.js";
84
+ export default LibertyDex;
@@ -0,0 +1,48 @@
1
+ /** Your key: what it may do, what it has spent, and the index behind it. */
2
+ import type { Transport } from "../transport.js";
3
+ import type { ChainStatus, Usage } from "../types.js";
4
+ export interface Plan {
5
+ code: string;
6
+ label: string;
7
+ custom: boolean;
8
+ usdMonthly: number;
9
+ /** Monthly-equivalent price when billed annually. */
10
+ usdAnnualPerMonth: number;
11
+ annualSavingPct: number;
12
+ monthlyCalls: number;
13
+ maxApps: number;
14
+ retentionDays: number;
15
+ /** Requests per second, and per minute. Both are enforced. */
16
+ rps: number;
17
+ rpm: number;
18
+ }
19
+ /**
20
+ * Index size and engine health.
21
+ *
22
+ * Shape is deliberately loose: this is an operational view we extend as the
23
+ * engine grows, so it is the one response not worth pinning field by field.
24
+ * `pools`, `tokens`, `venues` and `chains` are stable enough to build on.
25
+ */
26
+ export interface Stats {
27
+ chains: number;
28
+ pools: number;
29
+ tokens: number;
30
+ venues: number;
31
+ [key: string]: unknown;
32
+ }
33
+ export declare class AccountResource {
34
+ private readonly t;
35
+ constructor(t: Transport);
36
+ /** Your plan, calls used and remaining. Free, and answers even at your limit. */
37
+ usage(): Promise<Usage>;
38
+ /** Every plan and its limits. Public — no key needed. */
39
+ plans(): Promise<Plan[]>;
40
+ /** How much liquidity the index can see right now. */
41
+ stats(): Promise<Stats>;
42
+ }
43
+ export declare class ChainsResource {
44
+ private readonly t;
45
+ constructor(t: Transport);
46
+ /** Supported chains and how fresh each index is. Free — never counts against quota. */
47
+ list(): Promise<ChainStatus[]>;
48
+ }
@@ -0,0 +1,30 @@
1
+ export class AccountResource {
2
+ t;
3
+ constructor(t) {
4
+ this.t = t;
5
+ }
6
+ /** Your plan, calls used and remaining. Free, and answers even at your limit. */
7
+ usage() {
8
+ return this.t.request("GET", "/v1/usage");
9
+ }
10
+ /** Every plan and its limits. Public — no key needed. */
11
+ async plans() {
12
+ const d = await this.t.request("GET", "/v1/plans");
13
+ return d.plans;
14
+ }
15
+ /** How much liquidity the index can see right now. */
16
+ stats() {
17
+ return this.t.request("GET", "/v1/stats");
18
+ }
19
+ }
20
+ export class ChainsResource {
21
+ t;
22
+ constructor(t) {
23
+ this.t = t;
24
+ }
25
+ /** Supported chains and how fresh each index is. Free — never counts against quota. */
26
+ async list() {
27
+ const d = await this.t.request("GET", "/v1/chains");
28
+ return d.chains;
29
+ }
30
+ }
@@ -0,0 +1,36 @@
1
+ import type { Transport } from "../transport.js";
2
+ import type { BridgeTransfer, BridgeTransferPage, CrossChainQuoteParams, CrossChainQuoteResult } from "../types.js";
3
+ export declare class CrossChainResource {
4
+ private readonly t;
5
+ constructor(t: Transport);
6
+ /**
7
+ * A CROSS-CHAIN quote: `tokenIn` on `chainId` → `tokenOut` on `toChainId`,
8
+ * priced as swap → bridge → swap through our own aggregator on both chains
9
+ * and a bridge in the middle. Read-only.
10
+ *
11
+ * Same endpoint as `swap.quote()`, typed for the cross-chain answer: the best
12
+ * route, the ranked alternatives (choose on `trustTier` and `etaSec` if
13
+ * net output is not your only criterion) and every corridor × adapter that
14
+ * was refused. Throws `LibertyError` with `cross_chain_disabled`,
15
+ * `no_cross_route` (read `details.rejected`), `cross_chain_upstream`
16
+ * (retryable), or `bad_recipient`.
17
+ */
18
+ quote(params: CrossChainQuoteParams): Promise<CrossChainQuoteResult>;
19
+ /**
20
+ * Every transfer a wallet sent or received, newest first, paged by `cursor`.
21
+ *
22
+ * The state machine and the meaning of each state are on `BridgeTransfer`.
23
+ * Poll while a transfer's state is one of QUOTED, SUBMITTED, SRC_CONFIRMED,
24
+ * BRIDGE_PENDING, BRIDGE_COMPLETE, REFUND_PENDING or AWAITING_ACTION;
25
+ * everything else has settled or is waiting on a person.
26
+ */
27
+ transfers(params: {
28
+ wallet: string;
29
+ limit?: number;
30
+ cursor?: string | null;
31
+ }): Promise<BridgeTransferPage>;
32
+ /** One transfer by its transfer id. */
33
+ transfer(id: string): Promise<BridgeTransfer>;
34
+ /** The tracker's health: per-chain frontier, worker backlog, reconciliation. */
35
+ health(): Promise<Record<string, unknown>>;
36
+ }
@@ -0,0 +1,59 @@
1
+ /** Cross-chain swapping, and the tracker that follows a transfer to the far side. */
2
+ import { LibertyError } from "../errors.js";
3
+ export class CrossChainResource {
4
+ t;
5
+ constructor(t) {
6
+ this.t = t;
7
+ }
8
+ /**
9
+ * A CROSS-CHAIN quote: `tokenIn` on `chainId` → `tokenOut` on `toChainId`,
10
+ * priced as swap → bridge → swap through our own aggregator on both chains
11
+ * and a bridge in the middle. Read-only.
12
+ *
13
+ * Same endpoint as `swap.quote()`, typed for the cross-chain answer: the best
14
+ * route, the ranked alternatives (choose on `trustTier` and `etaSec` if
15
+ * net output is not your only criterion) and every corridor × adapter that
16
+ * was refused. Throws `LibertyError` with `cross_chain_disabled`,
17
+ * `no_cross_route` (read `details.rejected`), `cross_chain_upstream`
18
+ * (retryable), or `bad_recipient`.
19
+ */
20
+ async quote(params) {
21
+ if (params.toChainId === params.chainId) {
22
+ throw new LibertyError("bad_request", "toChainId equals chainId — use swap.quote() for a same-chain price", 400);
23
+ }
24
+ const d = await this.t.request("POST", "/v1/quote", params);
25
+ if (!d?.quote || d.quote.type !== "CROSS_CHAIN") {
26
+ // An older deployment that ignores `toChainId` answers with a same-chain
27
+ // quote. That is a different price for a different trade; refuse it.
28
+ throw new LibertyError("cross_chain_disabled", "This deployment did not return a cross-chain quote", 200, d);
29
+ }
30
+ return {
31
+ quote: d.quote,
32
+ alternatives: d.alternatives ?? [],
33
+ rejected: d.rejected ?? [],
34
+ };
35
+ }
36
+ /**
37
+ * Every transfer a wallet sent or received, newest first, paged by `cursor`.
38
+ *
39
+ * The state machine and the meaning of each state are on `BridgeTransfer`.
40
+ * Poll while a transfer's state is one of QUOTED, SUBMITTED, SRC_CONFIRMED,
41
+ * BRIDGE_PENDING, BRIDGE_COMPLETE, REFUND_PENDING or AWAITING_ACTION;
42
+ * everything else has settled or is waiting on a person.
43
+ */
44
+ transfers(params) {
45
+ return this.t.request("GET", "/v1/bridge/transfers", undefined, {
46
+ wallet: params.wallet,
47
+ limit: params.limit,
48
+ cursor: params.cursor ?? undefined,
49
+ });
50
+ }
51
+ /** One transfer by its transfer id. */
52
+ transfer(id) {
53
+ return this.t.request("GET", `/v1/bridge/transfers/${encodeURIComponent(id)}`);
54
+ }
55
+ /** The tracker's health: per-chain frontier, worker backlog, reconciliation. */
56
+ health() {
57
+ return this.t.request("GET", "/v1/bridge/health");
58
+ }
59
+ }
@@ -0,0 +1,78 @@
1
+ import type { Transport } from "../transport.js";
2
+ /** Where a figure came from. `index` is our own pool depth. */
3
+ export type PriceSource = "index" | "external";
4
+ /**
5
+ * A batch answer.
6
+ *
7
+ * ⚠️ EVERY MAP IS SPARSE, AND KEYED BY THE CALLER'S OWN SPELLING.
8
+ *
9
+ * A token the API could not price is OMITTED rather than returned as 0, because
10
+ * a zero reads as "worthless" and poisons any arithmetic done on it. So a key
11
+ * present in the request may be absent from `prices`, and the maps beside it are
12
+ * keyed exactly as the caller wrote the address, not normalised.
13
+ */
14
+ export interface PriceBatch {
15
+ /** USD per whole token, for the tokens that could be priced. */
16
+ prices: Record<string, number>;
17
+ sources: Record<string, PriceSource>;
18
+ /** 24-hour move as a RATIO: 0.0123 is +1.23%, not 1.23. */
19
+ change24h: Record<string, number | null>;
20
+ /** Unix seconds, for `external` entries only. */
21
+ fetchedAt: Record<string, number>;
22
+ /** Reference block per `index` entry. */
23
+ asOfBlocks: Record<string, number>;
24
+ ageSeconds: Record<string, number>;
25
+ /** Chain-wide: the index is behind and prices should be treated as stale. */
26
+ stale: boolean;
27
+ staleByToken: Record<string, boolean>;
28
+ }
29
+ export interface HistoricPrice {
30
+ chainId: number;
31
+ /** yyyy-mm-dd, as asked for. */
32
+ day: string;
33
+ token: string;
34
+ usd: number;
35
+ }
36
+ /** The server refuses more than this per call. */
37
+ export declare const MAX_TOKENS_PER_BATCH = 250;
38
+ export declare class PricesResource {
39
+ private readonly t;
40
+ constructor(t: Transport);
41
+ /**
42
+ * USD price from real pool depth, not a mid-market feed.
43
+ *
44
+ * Null when nobody can price the token — never 0, which would read as
45
+ * "worthless". Guard for null before doing arithmetic. (Keyed calls answer
46
+ * from our own index only; the anonymous tier may also serve a
47
+ * CoinGecko-licensed gap-fill figure, labeled `source: "external"` on the
48
+ * wire, which requires GeckoTerminal attribution if rendered and may not be
49
+ * redistributed.)
50
+ */
51
+ get(params: {
52
+ chainId: number;
53
+ token: string;
54
+ }): Promise<number | null>;
55
+ /**
56
+ * Many tokens in one round trip. Prefer this over looping `get()`.
57
+ *
58
+ * Pass `decimals` positionally alongside `tokens` when you know them: without
59
+ * it the server falls back to its registry and then to 18, and a wrong guess
60
+ * is wrong by a factor of 10^(18 - decimals).
61
+ */
62
+ batch(params: {
63
+ chainId: number;
64
+ tokens: string[];
65
+ decimals?: number[];
66
+ }): Promise<PriceBatch>;
67
+ /**
68
+ * The close for one token on one past day.
69
+ *
70
+ * `day` is `yyyy-mm-dd` and is required — there is no range form. Ask for the
71
+ * days you need.
72
+ */
73
+ history(params: {
74
+ chainId: number;
75
+ token: string;
76
+ day: string;
77
+ }): Promise<HistoricPrice>;
78
+ }