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/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";
|
package/dist/errors.d.ts
ADDED
|
@@ -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
|
+
}
|
package/dist/index.d.ts
ADDED
|
@@ -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
|
+
}
|