lcx-liberty-sdk 1.7.0 → 1.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +62 -3
- package/dist/constants.d.ts +2 -1
- package/dist/constants.js +2 -1
- package/dist/errors.d.ts +7 -0
- package/dist/errors.js +15 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +8 -0
- package/dist/resources/stablecoins.d.ts +41 -0
- package/dist/resources/stablecoins.js +69 -0
- package/dist/transport.d.ts +7 -1
- package/dist/transport.js +8 -1
- package/dist/types.d.ts +132 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@ TypeScript client for the [LCX Liberty DEX](https://dex.lcx.com/business)
|
|
|
4
4
|
DEX aggregator. Best-execution routing across Ethereum, Base, Arbitrum,
|
|
5
5
|
OP Mainnet, BNB Chain, Polygon, Avalanche, Robinhood Chain, Unichain, Monad,
|
|
6
6
|
HyperEVM, Arc, World Chain, Cronos, Ink, Linea, Soneium, Plasma, MegaETH,
|
|
7
|
-
Gnosis and
|
|
7
|
+
Gnosis, Sonic and ZKsync, priced from our own pool index.
|
|
8
8
|
|
|
9
9
|
Zero dependencies. Node 18+, Deno, Bun, Workers, browser.
|
|
10
10
|
|
|
@@ -73,9 +73,61 @@ try {
|
|
|
73
73
|
Transient failures (5xx, network, 429) are retried twice with jittered backoff.
|
|
74
74
|
Client errors are never retried, because resending a bad request only spends quota.
|
|
75
75
|
|
|
76
|
+
## Stablecoins
|
|
77
|
+
|
|
78
|
+
`lcx.stablecoins` converts one stablecoin into another on the same chain,
|
|
79
|
+
under rules: both sides must be registered stablecoins, every quote is
|
|
80
|
+
measured against an anchor (par within one currency, a reference rate across
|
|
81
|
+
two), a quote past your tolerance is refused instead of filled, and buying a
|
|
82
|
+
coin that is off its peg needs `allowOffPeg`. The swap's minimum output is set
|
|
83
|
+
from your tolerance, so it reverts on chain rather than paying less. Included
|
|
84
|
+
in every plan; no fee is taken on the output.
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
import { LibertyDex, LibertyError } from "lcx-liberty-sdk";
|
|
88
|
+
|
|
89
|
+
const lcx = new LibertyDex({ apiKey: process.env.LCX_API_KEY });
|
|
90
|
+
|
|
91
|
+
// Which coins, on which chains.
|
|
92
|
+
const [ethereum] = await lcx.stablecoins.coins({ chainId: 1 });
|
|
93
|
+
|
|
94
|
+
try {
|
|
95
|
+
const { stablecoin, transaction } = await lcx.stablecoins.swap({
|
|
96
|
+
chainId: 1,
|
|
97
|
+
tokenIn: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
|
|
98
|
+
tokenOut: "0xdAC17F958D2ee523a2206206994597C13D831ec7", // USDT
|
|
99
|
+
amount: "250000",
|
|
100
|
+
maxParDeviationBps: 10, // refuse anything more than 10 bps below par
|
|
101
|
+
taker: userAddress,
|
|
102
|
+
idempotencyKey: `payout-${payoutId}`, // a retry gets the first answer back
|
|
103
|
+
});
|
|
104
|
+
console.log(stablecoin.parDeviationBps, "bps from par; at least", stablecoin.minOut);
|
|
105
|
+
await wallet.sendTransaction(transaction);
|
|
106
|
+
} catch (e) {
|
|
107
|
+
if (e instanceof LibertyError && e.code === "below_tolerance") {
|
|
108
|
+
// e.details.parDeviationBps: how far from par this size is.
|
|
109
|
+
} else if (e instanceof LibertyError && e.code === "insufficient_liquidity") {
|
|
110
|
+
// e.details.fillsUpTo, when present: the most that fills, in base units.
|
|
111
|
+
} else throw e;
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
| method | what it is for |
|
|
116
|
+
|---|---|
|
|
117
|
+
| `coins()` | every registered stablecoin by chain, with its currency (`USD`, `EUR`, `CHF`) |
|
|
118
|
+
| `quote()` | a conversion priced and measured against its anchor: `stablecoin.parDeviationBps`, `stablecoin.minOut` |
|
|
119
|
+
| `swap()` | the same, plus the transaction to sign; `idempotencyKey` goes out as the `Idempotency-Key` header |
|
|
120
|
+
|
|
121
|
+
A refusal is a `LibertyError` whose `code` is one of `StablecoinRefusalCode`
|
|
122
|
+
(`below_tolerance`, `off_peg`, `insufficient_liquidity`, `excluded_coin`,
|
|
123
|
+
`no_reference_rate`, `not_a_stablecoin`, `bad_tolerance`, `no_route`,
|
|
124
|
+
`idempotency_key_reused`); `e.refusalReason` names the rule, and the rest of
|
|
125
|
+
the body is on `e.details` (`StablecoinRefusal`). Every code is explained at
|
|
126
|
+
[dex.lcx.com/docs/stablecoin-refusals](https://dex.lcx.com/docs/stablecoin-refusals).
|
|
127
|
+
|
|
76
128
|
## The full surface
|
|
77
129
|
|
|
78
|
-
|
|
130
|
+
Eight namespaces. Nobody reads past a namespace they are not using, so the swap
|
|
79
131
|
surface stays as short as it ever was however many sit beside it.
|
|
80
132
|
|
|
81
133
|
This wraps the surfaces LCX offers publicly, and only those. Anything absent is
|
|
@@ -92,6 +144,13 @@ client is not the place to publish a surface by implication.
|
|
|
92
144
|
| `permit()` | EIP-2612 typed data for a gasless approval |
|
|
93
145
|
| `submit()` | broadcast a signed transaction, private builder path first |
|
|
94
146
|
|
|
147
|
+
### `lcx.stablecoins`
|
|
148
|
+
| method | what it is for |
|
|
149
|
+
|---|---|
|
|
150
|
+
| `coins()` | the registry: every stablecoin the API quotes, by chain |
|
|
151
|
+
| `quote()` | a stablecoin conversion, measured against par or a reference rate |
|
|
152
|
+
| `swap()` | the quote and the transaction, its minimum set from your tolerance |
|
|
153
|
+
|
|
95
154
|
### `lcx.crossChain`
|
|
96
155
|
| method | what it is for |
|
|
97
156
|
|---|---|
|
|
@@ -162,7 +221,7 @@ records:
|
|
|
162
221
|
| Contract | Chains | Address |
|
|
163
222
|
|---|---|---|
|
|
164
223
|
| Router proxy (the `spender`: swaps, cross-chain and the multi token swap) | Ethereum, Base, Arbitrum, OP Mainnet | `0x0000000000b1ae06c96aB73FF4360d7AeAaB56F0` |
|
|
165
|
-
| Router 2 (the same role) | BNB Chain, Polygon, Avalanche, Robinhood Chain, Unichain, Monad, HyperEVM, Arc, World Chain, Cronos, Ink, Linea, Soneium, Plasma, MegaETH, Gnosis, Sonic | `0x0000000000654902B6Ed6cC240cc81CB4c4a3dff` |
|
|
224
|
+
| Router 2 (the same role) | BNB Chain, Polygon, Avalanche, Robinhood Chain, Unichain, Monad, HyperEVM, Arc, World Chain, Cronos, Ink, Linea, Soneium, Plasma, MegaETH, Gnosis, Sonic, ZKsync | `0x0000000000654902B6Ed6cC240cc81CB4c4a3dff` |
|
|
166
225
|
| Fee router (deployed, reserved for integrator-fee traffic) | Ethereum, Base, Arbitrum, OP Mainnet | `0xd67aADF902d15890cb11DfB4DA3d3D90b1953Dee` |
|
|
167
226
|
|
|
168
227
|
An approval is per chain and per router: a wallet that trades on a chain of
|
package/dist/constants.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/** Version, hosts and chain constants. Imported by every resource. */
|
|
2
|
-
export declare const VERSION = "1.
|
|
2
|
+
export declare const VERSION = "1.9.0";
|
|
3
3
|
/**
|
|
4
4
|
* The API, where every call needs a key. Get a free one (150k calls/month, no
|
|
5
5
|
* card) at https://dex.lcx.com/dashboard.
|
|
@@ -41,6 +41,7 @@ export declare const CHAINS: {
|
|
|
41
41
|
readonly megaeth: 4326;
|
|
42
42
|
readonly gnosis: 100;
|
|
43
43
|
readonly sonic: 146;
|
|
44
|
+
readonly zksync: 324;
|
|
44
45
|
};
|
|
45
46
|
/** The zero address, which every endpoint treats as the chain's native asset. */
|
|
46
47
|
export declare const NATIVE = "0x0000000000000000000000000000000000000000";
|
package/dist/constants.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/** Version, hosts and chain constants. Imported by every resource. */
|
|
2
|
-
export const VERSION = "1.
|
|
2
|
+
export const VERSION = "1.9.0";
|
|
3
3
|
/**
|
|
4
4
|
* The API, where every call needs a key. Get a free one (150k calls/month, no
|
|
5
5
|
* card) at https://dex.lcx.com/dashboard.
|
|
@@ -41,6 +41,7 @@ export const CHAINS = {
|
|
|
41
41
|
megaeth: 4326,
|
|
42
42
|
gnosis: 100,
|
|
43
43
|
sonic: 146,
|
|
44
|
+
zksync: 324,
|
|
44
45
|
};
|
|
45
46
|
/** The zero address, which every endpoint treats as the chain's native asset. */
|
|
46
47
|
export const NATIVE = "0x0000000000000000000000000000000000000000";
|
package/dist/errors.d.ts
CHANGED
|
@@ -24,4 +24,11 @@ export declare class LibertyError extends Error {
|
|
|
24
24
|
get isRateLimited(): boolean;
|
|
25
25
|
/** The pair or size could not be routed — a smaller amount may work. */
|
|
26
26
|
get isNoLiquidity(): boolean;
|
|
27
|
+
/**
|
|
28
|
+
* The rule a Stablecoin API refusal names (`below_tolerance`, `off_peg`,
|
|
29
|
+
* `below_floor`, `no_route`), or undefined. The other fields of the refusal
|
|
30
|
+
* (`parDeviationBps`, `fillsUpTo`, ...) are on `details`, typed as
|
|
31
|
+
* `StablecoinRefusal`.
|
|
32
|
+
*/
|
|
33
|
+
get refusalReason(): string | undefined;
|
|
27
34
|
}
|
package/dist/errors.js
CHANGED
|
@@ -35,6 +35,11 @@ export class LibertyError extends Error {
|
|
|
35
35
|
"unknown_plan",
|
|
36
36
|
"INVALID_API_KEY",
|
|
37
37
|
"bad_email",
|
|
38
|
+
// The Stablecoin API's request-shape refusals.
|
|
39
|
+
"bad_tolerance",
|
|
40
|
+
"not_a_stablecoin",
|
|
41
|
+
"excluded_coin",
|
|
42
|
+
"idempotency_key_reused",
|
|
38
43
|
];
|
|
39
44
|
if (clientCodes.includes(this.code))
|
|
40
45
|
return true;
|
|
@@ -48,4 +53,14 @@ export class LibertyError extends Error {
|
|
|
48
53
|
get isNoLiquidity() {
|
|
49
54
|
return this.code === "no_route" || this.code === "insufficient_liquidity";
|
|
50
55
|
}
|
|
56
|
+
/**
|
|
57
|
+
* The rule a Stablecoin API refusal names (`below_tolerance`, `off_peg`,
|
|
58
|
+
* `below_floor`, `no_route`), or undefined. The other fields of the refusal
|
|
59
|
+
* (`parDeviationBps`, `fillsUpTo`, ...) are on `details`, typed as
|
|
60
|
+
* `StablecoinRefusal`.
|
|
61
|
+
*/
|
|
62
|
+
get refusalReason() {
|
|
63
|
+
const d = this.details;
|
|
64
|
+
return typeof d?.refusalReason === "string" ? d.refusalReason : undefined;
|
|
65
|
+
}
|
|
51
66
|
}
|
package/dist/index.d.ts
CHANGED
|
@@ -2,12 +2,18 @@ import { AccountResource, ChainsResource } from "./resources/account.js";
|
|
|
2
2
|
import { CrossChainResource } from "./resources/crosschain.js";
|
|
3
3
|
import { MultiResource } from "./resources/multi.js";
|
|
4
4
|
import { PricesResource } from "./resources/prices.js";
|
|
5
|
+
import { StablecoinsResource } from "./resources/stablecoins.js";
|
|
5
6
|
import { SwapResource } from "./resources/swap.js";
|
|
6
7
|
import { TokensResource } from "./resources/tokens.js";
|
|
7
8
|
import type { LibertyOptions } from "./types.js";
|
|
8
9
|
export declare class LibertyDex {
|
|
9
10
|
/** Price, build, sign and send a same-chain swap. */
|
|
10
11
|
readonly swap: SwapResource;
|
|
12
|
+
/**
|
|
13
|
+
* The Stablecoin API: one stablecoin into another, measured against par,
|
|
14
|
+
* with your tolerance enforced on chain. `/v1/stablecoins/*`.
|
|
15
|
+
*/
|
|
16
|
+
readonly stablecoins: StablecoinsResource;
|
|
11
17
|
/** Quote across chains, and follow a transfer to the far side. */
|
|
12
18
|
readonly crossChain: CrossChainResource;
|
|
13
19
|
/** Several tokens in and several out, as one transaction: `/v1/multi/*`. */
|
|
@@ -27,6 +33,7 @@ export { LibertyError } from "./errors.js";
|
|
|
27
33
|
export { Transport } from "./transport.js";
|
|
28
34
|
export * from "./types.js";
|
|
29
35
|
export { SwapResource, type SubmitResult } from "./resources/swap.js";
|
|
36
|
+
export { StablecoinsResource } from "./resources/stablecoins.js";
|
|
30
37
|
export { CrossChainResource } from "./resources/crosschain.js";
|
|
31
38
|
export { MultiResource } from "./resources/multi.js";
|
|
32
39
|
export { TokensResource } from "./resources/tokens.js";
|
package/dist/index.js
CHANGED
|
@@ -47,11 +47,17 @@ import { AccountResource, ChainsResource } from "./resources/account.js";
|
|
|
47
47
|
import { CrossChainResource } from "./resources/crosschain.js";
|
|
48
48
|
import { MultiResource } from "./resources/multi.js";
|
|
49
49
|
import { PricesResource } from "./resources/prices.js";
|
|
50
|
+
import { StablecoinsResource } from "./resources/stablecoins.js";
|
|
50
51
|
import { SwapResource } from "./resources/swap.js";
|
|
51
52
|
import { TokensResource } from "./resources/tokens.js";
|
|
52
53
|
export class LibertyDex {
|
|
53
54
|
/** Price, build, sign and send a same-chain swap. */
|
|
54
55
|
swap;
|
|
56
|
+
/**
|
|
57
|
+
* The Stablecoin API: one stablecoin into another, measured against par,
|
|
58
|
+
* with your tolerance enforced on chain. `/v1/stablecoins/*`.
|
|
59
|
+
*/
|
|
60
|
+
stablecoins;
|
|
55
61
|
/** Quote across chains, and follow a transfer to the far side. */
|
|
56
62
|
crossChain;
|
|
57
63
|
/** Several tokens in and several out, as one transaction: `/v1/multi/*`. */
|
|
@@ -67,6 +73,7 @@ export class LibertyDex {
|
|
|
67
73
|
constructor(options = {}) {
|
|
68
74
|
const t = new Transport(options);
|
|
69
75
|
this.swap = new SwapResource(t);
|
|
76
|
+
this.stablecoins = new StablecoinsResource(t);
|
|
70
77
|
this.crossChain = new CrossChainResource(t);
|
|
71
78
|
this.multi = new MultiResource(t);
|
|
72
79
|
this.tokens = new TokensResource(t);
|
|
@@ -80,6 +87,7 @@ export { LibertyError } from "./errors.js";
|
|
|
80
87
|
export { Transport } from "./transport.js";
|
|
81
88
|
export * from "./types.js";
|
|
82
89
|
export { SwapResource } from "./resources/swap.js";
|
|
90
|
+
export { StablecoinsResource } from "./resources/stablecoins.js";
|
|
83
91
|
export { CrossChainResource } from "./resources/crosschain.js";
|
|
84
92
|
export { MultiResource } from "./resources/multi.js";
|
|
85
93
|
export { TokensResource } from "./resources/tokens.js";
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import type { Transport } from "../transport.js";
|
|
2
|
+
import type { StablecoinChain, StablecoinCurrency, StablecoinQuote, StablecoinQuoteParams, StablecoinReferenceRate, StablecoinSwap, StablecoinSwapParams } from "../types.js";
|
|
3
|
+
export declare class StablecoinsResource {
|
|
4
|
+
private readonly t;
|
|
5
|
+
constructor(t: Transport);
|
|
6
|
+
/**
|
|
7
|
+
* Every registered stablecoin, by chain, with its currency. Pass `chainId`
|
|
8
|
+
* for one chain. The registry changes when the API deploys, not per call,
|
|
9
|
+
* so an hour's cache is safe.
|
|
10
|
+
*/
|
|
11
|
+
coins(params?: {
|
|
12
|
+
chainId?: number;
|
|
13
|
+
}): Promise<StablecoinChain[]>;
|
|
14
|
+
/**
|
|
15
|
+
* The rate each non-dollar currency's peg is measured against, by currency
|
|
16
|
+
* (`EUR`, `CHF`): Chainlink's feeds on Ethereum, refreshed by the API every
|
|
17
|
+
* few minutes. A currency the API could not read, or read too old, is absent.
|
|
18
|
+
* A euro coin's distance from its peg is `priceUsd / references.EUR.usd - 1`.
|
|
19
|
+
*/
|
|
20
|
+
referenceRates(): Promise<Partial<Record<StablecoinCurrency, StablecoinReferenceRate>>>;
|
|
21
|
+
/**
|
|
22
|
+
* A conversion, priced and measured against its anchor. Read-only.
|
|
23
|
+
*
|
|
24
|
+
* `stablecoin.parDeviationBps` is the distance from the anchor (positive
|
|
25
|
+
* pays more), and `stablecoin.minOut` the least a swap would deliver.
|
|
26
|
+
* Throws `LibertyError` with `below_tolerance`, `off_peg`,
|
|
27
|
+
* `insufficient_liquidity` (`details.fillsUpTo`), `not_a_stablecoin` and
|
|
28
|
+
* the other codes of `StablecoinRefusalCode`.
|
|
29
|
+
*/
|
|
30
|
+
quote(params: StablecoinQuoteParams): Promise<StablecoinQuote>;
|
|
31
|
+
/**
|
|
32
|
+
* The quote and a transaction to sign, in one call. The transaction's
|
|
33
|
+
* minimum output is `stablecoin.minOut`: if the market moves past it, the
|
|
34
|
+
* swap reverts on chain rather than paying less.
|
|
35
|
+
*
|
|
36
|
+
* `idempotencyKey` goes out as the `Idempotency-Key` header. With one, a
|
|
37
|
+
* retry (this client's own, on a 5xx or a timeout, or yours) returns the
|
|
38
|
+
* first answer instead of building a second transaction.
|
|
39
|
+
*/
|
|
40
|
+
swap(params: StablecoinSwapParams): Promise<StablecoinSwap>;
|
|
41
|
+
}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Stablecoin API: one stablecoin into another, under rules.
|
|
3
|
+
*
|
|
4
|
+
* The same engine and router as `lcx.swap`, with a rule set around it: both
|
|
5
|
+
* sides must be registered stablecoins, every quote is measured against an
|
|
6
|
+
* anchor (par within one currency, a reference rate across two), a quote past
|
|
7
|
+
* your tolerance is refused instead of filled, and buying an off-peg coin
|
|
8
|
+
* needs `allowOffPeg`. Refusals are `LibertyError`s whose `details` carry the
|
|
9
|
+
* fields of `StablecoinRefusal`.
|
|
10
|
+
*/
|
|
11
|
+
import { LibertyError } from "../errors.js";
|
|
12
|
+
/** What the API accepts as an `Idempotency-Key`: 1 to 128 visible ASCII characters. */
|
|
13
|
+
const IDEMPOTENCY_KEY = /^[\x21-\x7e]{1,128}$/;
|
|
14
|
+
export class StablecoinsResource {
|
|
15
|
+
t;
|
|
16
|
+
constructor(t) {
|
|
17
|
+
this.t = t;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Every registered stablecoin, by chain, with its currency. Pass `chainId`
|
|
21
|
+
* for one chain. The registry changes when the API deploys, not per call,
|
|
22
|
+
* so an hour's cache is safe.
|
|
23
|
+
*/
|
|
24
|
+
async coins(params = {}) {
|
|
25
|
+
const d = await this.t.request("GET", "/v1/stablecoins/coins", undefined, { chainId: params.chainId });
|
|
26
|
+
return d.chains;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* The rate each non-dollar currency's peg is measured against, by currency
|
|
30
|
+
* (`EUR`, `CHF`): Chainlink's feeds on Ethereum, refreshed by the API every
|
|
31
|
+
* few minutes. A currency the API could not read, or read too old, is absent.
|
|
32
|
+
* A euro coin's distance from its peg is `priceUsd / references.EUR.usd - 1`.
|
|
33
|
+
*/
|
|
34
|
+
async referenceRates() {
|
|
35
|
+
// The references ride with the registry; one chain keeps the answer small.
|
|
36
|
+
const d = await this.t.request("GET", "/v1/stablecoins/coins", undefined, { chainId: 1 });
|
|
37
|
+
return d.references ?? {};
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* A conversion, priced and measured against its anchor. Read-only.
|
|
41
|
+
*
|
|
42
|
+
* `stablecoin.parDeviationBps` is the distance from the anchor (positive
|
|
43
|
+
* pays more), and `stablecoin.minOut` the least a swap would deliver.
|
|
44
|
+
* Throws `LibertyError` with `below_tolerance`, `off_peg`,
|
|
45
|
+
* `insufficient_liquidity` (`details.fillsUpTo`), `not_a_stablecoin` and
|
|
46
|
+
* the other codes of `StablecoinRefusalCode`.
|
|
47
|
+
*/
|
|
48
|
+
quote(params) {
|
|
49
|
+
return this.t.request("POST", "/v1/stablecoins/quote", params);
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* The quote and a transaction to sign, in one call. The transaction's
|
|
53
|
+
* minimum output is `stablecoin.minOut`: if the market moves past it, the
|
|
54
|
+
* swap reverts on chain rather than paying less.
|
|
55
|
+
*
|
|
56
|
+
* `idempotencyKey` goes out as the `Idempotency-Key` header. With one, a
|
|
57
|
+
* retry (this client's own, on a 5xx or a timeout, or yours) returns the
|
|
58
|
+
* first answer instead of building a second transaction.
|
|
59
|
+
*/
|
|
60
|
+
// `async` so a bad key rejects rather than throws, like `swap.submit`.
|
|
61
|
+
async swap(params) {
|
|
62
|
+
const { idempotencyKey, ...body } = params;
|
|
63
|
+
if (idempotencyKey !== undefined && !IDEMPOTENCY_KEY.test(idempotencyKey)) {
|
|
64
|
+
// Caught here rather than spending a round trip to be told the same thing.
|
|
65
|
+
throw new LibertyError("bad_request", "idempotencyKey must be 1 to 128 visible ASCII characters", 400);
|
|
66
|
+
}
|
|
67
|
+
return this.t.request("POST", "/v1/stablecoins/swap", body, undefined, idempotencyKey === undefined ? undefined : { "idempotency-key": idempotencyKey });
|
|
68
|
+
}
|
|
69
|
+
}
|
package/dist/transport.d.ts
CHANGED
|
@@ -6,5 +6,11 @@ export declare class Transport {
|
|
|
6
6
|
private readonly maxRetries;
|
|
7
7
|
private readonly fetchImpl;
|
|
8
8
|
constructor(options?: LibertyOptions);
|
|
9
|
-
|
|
9
|
+
/**
|
|
10
|
+
* `extraHeaders` is for a header an endpoint documents, such as
|
|
11
|
+
* `Idempotency-Key` on `/v1/stablecoins/swap`. It cannot replace the
|
|
12
|
+
* transport's own: the content type, the SDK marker and the key are set
|
|
13
|
+
* after it.
|
|
14
|
+
*/
|
|
15
|
+
request<T>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, string | number | undefined>, extraHeaders?: Record<string, string>): Promise<T>;
|
|
10
16
|
}
|
package/dist/transport.js
CHANGED
|
@@ -32,13 +32,20 @@ export class Transport {
|
|
|
32
32
|
throw new Error("No fetch available. Use Node 18+, or pass one via `new LibertyDex({ fetch })`.");
|
|
33
33
|
}
|
|
34
34
|
}
|
|
35
|
-
|
|
35
|
+
/**
|
|
36
|
+
* `extraHeaders` is for a header an endpoint documents, such as
|
|
37
|
+
* `Idempotency-Key` on `/v1/stablecoins/swap`. It cannot replace the
|
|
38
|
+
* transport's own: the content type, the SDK marker and the key are set
|
|
39
|
+
* after it.
|
|
40
|
+
*/
|
|
41
|
+
async request(method, path, body, query, extraHeaders) {
|
|
36
42
|
const url = new URL(this.baseUrl + path);
|
|
37
43
|
for (const [k, v] of Object.entries(query ?? {})) {
|
|
38
44
|
if (v !== undefined)
|
|
39
45
|
url.searchParams.set(k, String(v));
|
|
40
46
|
}
|
|
41
47
|
const headers = {
|
|
48
|
+
...extraHeaders,
|
|
42
49
|
"content-type": "application/json",
|
|
43
50
|
// Lets us see which SDK versions are in the wild, which is what makes a
|
|
44
51
|
// breaking change safe to plan.
|
package/dist/types.d.ts
CHANGED
|
@@ -604,3 +604,135 @@ export interface MultiXBuild {
|
|
|
604
604
|
}>;
|
|
605
605
|
etaSecs?: number | null;
|
|
606
606
|
}
|
|
607
|
+
/** The currency a registered stablecoin is pegged to. */
|
|
608
|
+
export type StablecoinCurrency = "USD" | "EUR" | "CHF";
|
|
609
|
+
/** One coin in the Stablecoin API's registry. */
|
|
610
|
+
export interface StablecoinCoin {
|
|
611
|
+
/** Checksummed. Send it as `tokenIn` / `tokenOut`. */
|
|
612
|
+
address: string;
|
|
613
|
+
/** Null when the index holds no metadata for the contract; still quoted. */
|
|
614
|
+
symbol: string | null;
|
|
615
|
+
decimals: number | null;
|
|
616
|
+
currency: StablecoinCurrency;
|
|
617
|
+
}
|
|
618
|
+
/**
|
|
619
|
+
* The independent rate a non-dollar currency is measured against
|
|
620
|
+
* (`GET /v1/stablecoins/coins` -> `data.references`): Chainlink's EUR/USD and
|
|
621
|
+
* CHF/USD feeds on Ethereum, read by the API from its own node.
|
|
622
|
+
*/
|
|
623
|
+
export interface StablecoinReferenceRate {
|
|
624
|
+
/** US dollars per one unit of the currency: 1.0990 for EUR. */
|
|
625
|
+
usd: number;
|
|
626
|
+
/** Where it comes from, e.g. "Chainlink EUR/USD on Ethereum". */
|
|
627
|
+
source: string;
|
|
628
|
+
/** Unix seconds of the feed's last update. */
|
|
629
|
+
updatedAt: number;
|
|
630
|
+
}
|
|
631
|
+
/** One chain's registered stablecoins: `GET /v1/stablecoins/coins`. */
|
|
632
|
+
export interface StablecoinChain {
|
|
633
|
+
chainId: number;
|
|
634
|
+
chain: string;
|
|
635
|
+
/**
|
|
636
|
+
* The chain has passed LCX's benchmark gate. Informational: the API quotes
|
|
637
|
+
* every listed chain under the same rules either way.
|
|
638
|
+
*/
|
|
639
|
+
named: boolean;
|
|
640
|
+
coins: StablecoinCoin[];
|
|
641
|
+
}
|
|
642
|
+
/**
|
|
643
|
+
* A stablecoin conversion: both tokens must be registered stablecoins on
|
|
644
|
+
* `chainId`. Exactly one of `amountIn` (base units) / `amount` (human units).
|
|
645
|
+
*/
|
|
646
|
+
export type StablecoinQuoteParams = SellAmount & {
|
|
647
|
+
chainId: number;
|
|
648
|
+
tokenIn: string;
|
|
649
|
+
tokenOut: string;
|
|
650
|
+
/** Optional and best left out, as on `swap.quote()`. */
|
|
651
|
+
decimals?: number;
|
|
652
|
+
/**
|
|
653
|
+
* How far below the anchor (par, or a reference rate across currencies) you
|
|
654
|
+
* accept, in bps. Default 50; above 0 and at most 100; may be fractional.
|
|
655
|
+
* A quote further below is refused with `below_tolerance`.
|
|
656
|
+
*/
|
|
657
|
+
maxParDeviationBps?: number;
|
|
658
|
+
/** The bound against the quote itself. Default 30. */
|
|
659
|
+
slippageBps?: number;
|
|
660
|
+
/**
|
|
661
|
+
* Buy a coin that trades more than 1% from its peg anyway. Default false:
|
|
662
|
+
* such a quote is refused with `off_peg`.
|
|
663
|
+
*/
|
|
664
|
+
allowOffPeg?: boolean;
|
|
665
|
+
/** Your integration (an address or a registered slug), as on `/v1/quote`. */
|
|
666
|
+
integrator?: string;
|
|
667
|
+
};
|
|
668
|
+
export type StablecoinSwapParams = StablecoinQuoteParams & {
|
|
669
|
+
/** Address that sends the transaction and receives the output. Required. */
|
|
670
|
+
taker: string;
|
|
671
|
+
/** Seconds until the on-chain deadline. Default 300, at most 3600. */
|
|
672
|
+
deadlineSecs?: number;
|
|
673
|
+
/**
|
|
674
|
+
* Sent as the `Idempotency-Key` header, never in the body: the same key
|
|
675
|
+
* with the same request within 24 hours returns the first answer; with a
|
|
676
|
+
* different request it is refused (`idempotency_key_reused`). 1 to 128
|
|
677
|
+
* visible ASCII characters.
|
|
678
|
+
*/
|
|
679
|
+
idempotencyKey?: string;
|
|
680
|
+
};
|
|
681
|
+
/** The rule set's verdict on a quote: `data.stablecoin`. */
|
|
682
|
+
export interface StablecoinVerdict {
|
|
683
|
+
/** "USD par", "EUR par", "CHF par", or e.g. "USD/EUR reference rate". */
|
|
684
|
+
anchor: string;
|
|
685
|
+
currencyIn: StablecoinCurrency;
|
|
686
|
+
currencyOut: StablecoinCurrency;
|
|
687
|
+
/** Distance from the anchor in bps; positive pays MORE than the anchor. */
|
|
688
|
+
parDeviationBps: number;
|
|
689
|
+
/** The tolerance this quote was judged by. */
|
|
690
|
+
maxParDeviationBps: number;
|
|
691
|
+
/**
|
|
692
|
+
* The least the swap may deliver, in base units of tokenOut: the tighter of
|
|
693
|
+
* the slippage bound and the tolerance. Read this, not
|
|
694
|
+
* `quote.output.minimumAmount`.
|
|
695
|
+
*/
|
|
696
|
+
minOut: string;
|
|
697
|
+
/** `minOut` as a slippage figure; send it to `swap.build()` to keep that floor. */
|
|
698
|
+
slippageBps: number;
|
|
699
|
+
/** False when `allowOffPeg` was set. */
|
|
700
|
+
offPegChecked: boolean;
|
|
701
|
+
/** The chain has passed LCX's benchmark gate. */
|
|
702
|
+
named: boolean;
|
|
703
|
+
}
|
|
704
|
+
export interface StablecoinQuote {
|
|
705
|
+
/** The `/v1/quote` answer, field for field. */
|
|
706
|
+
quote: Quote;
|
|
707
|
+
stablecoin: StablecoinVerdict;
|
|
708
|
+
}
|
|
709
|
+
/** Ready for `sendTransaction`; its minimum output is `stablecoin.minOut`. */
|
|
710
|
+
export interface StablecoinTransaction {
|
|
711
|
+
to: string;
|
|
712
|
+
data: string;
|
|
713
|
+
value: string;
|
|
714
|
+
gas?: string;
|
|
715
|
+
chainId?: number;
|
|
716
|
+
[key: string]: unknown;
|
|
717
|
+
}
|
|
718
|
+
export interface StablecoinSwap extends StablecoinQuote {
|
|
719
|
+
transaction: StablecoinTransaction;
|
|
720
|
+
}
|
|
721
|
+
/** Every code a Stablecoin API call is refused with, beyond the swap API's own. */
|
|
722
|
+
export type StablecoinRefusalCode = "below_tolerance" | "off_peg" | "insufficient_liquidity" | "excluded_coin" | "no_reference_rate" | "not_a_stablecoin" | "bad_tolerance" | "no_route" | "idempotency_key_reused";
|
|
723
|
+
/**
|
|
724
|
+
* The body of a refusal, on `LibertyError.details`. Which optional fields are
|
|
725
|
+
* present depends on the code: `below_tolerance` carries both deviations,
|
|
726
|
+
* `off_peg` the deviation, and `insufficient_liquidity`
|
|
727
|
+
* (`refusalReason: "below_floor"`) carries `fillsUpTo` when some size fills.
|
|
728
|
+
*/
|
|
729
|
+
export interface StablecoinRefusal {
|
|
730
|
+
success: false;
|
|
731
|
+
code: StablecoinRefusalCode | (string & {});
|
|
732
|
+
message: string;
|
|
733
|
+
refusalReason?: string;
|
|
734
|
+
parDeviationBps?: number;
|
|
735
|
+
maxParDeviationBps?: number;
|
|
736
|
+
/** The largest amount that fills, in base units of tokenIn. */
|
|
737
|
+
fillsUpTo?: string;
|
|
738
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "lcx-liberty-sdk",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.9.0",
|
|
4
4
|
"description": "TypeScript SDK for the LCX Liberty DEX aggregator. Best-execution routing across Ethereum, Base, Arbitrum, OP Mainnet, BNB Chain, Polygon, Avalanche, Robinhood Chain, Unichain, Monad, HyperEVM and Arc.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"module": "./dist/index.js",
|