Liquidium SDK

https://liquidium-inc.github.io/liquidium-sdk
Admin
SDK documentation for @liquidium/client, a TypeScript library for building integrations with the...
Tokens:25,906
Snippets:919
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Installation and Running the Instant Loans Flow Example

Source: https://liquidium-inc.github.io/liquidium-sdk/examples/instant-loans-flow

Commands to install dependencies, copy the environment file, and run the example for the instant loans flow.

```bash
pnpm install

cp examples/instant-loans-flow/.env.example examples/instant-loans-flow/.env

pnpm --filter @liquidium/example-instant-loans-flow dev

```

--------------------------------

### Install and Run Example

Source: https://liquidium-inc.github.io/liquidium-sdk/examples/contract-interaction-flow

Commands to install dependencies and run the contract interaction flow example.

```bash
pnpm install  

pnpm --filter @liquidium/example-contract-interaction-flow dev  

```

--------------------------------

### Install and Run Example

Source: https://liquidium-inc.github.io/liquidium-sdk/examples/deposit-address-flow

Commands to install dependencies and run the deposit address flow example.

```bash
pnpm install  

pnpm --filter @liquidium/example-deposit-address-flow dev  
```

--------------------------------

### Local development setup

Source: https://liquidium-inc.github.io/liquidium-sdk/getting-started/installation

Clone the repository, install dependencies, and build the project for local development.

```bash
git clone https://github.com/Liquidium-Inc/liquidium-sdk.git  

cd liquidium-sdk  

pnpm install  

pnpm run build  

pnpm run typecheck  

pnpm run test  

```

--------------------------------

### Installation and Development Commands

Source: https://liquidium-inc.github.io/liquidium-sdk/examples/vite-react-dynamic

Commands to install dependencies, copy environment variables, and run the development server for the Vite React Dynamic example.

```bash
pnpm install

cp examples/vite-react-dynamic/.env.example examples/vite-react-dynamic/.env

pnpm --filter @liquidium/example-vite-react-dynamic dev

```

--------------------------------

### Install the client package

Source: https://liquidium-inc.github.io/liquidium-sdk/getting-started/installation

Install the Liquidium client package using npm.

```bash
npm install @liquidium/client  

```

--------------------------------

### Instant Loan Creation and Retrieval

Source: https://liquidium-inc.github.io/liquidium-sdk/getting-started/quick-start

This code snippet demonstrates how to create an instant loan, get its reference, and then retrieve the loan details using the reference. It includes fetching pool data, calculating LTV, creating the loan, and logging the reference and deposit target. Finally, it retrieves the loan again to show its status and repayment details.

```typescript
import { LiquidiumClient, type Pool, type SupplyTarget } from "@liquidium/client";  

const client = new LiquidiumClient();  

const [pools, prices] = await Promise.all([
  client.market.listPools(),  
  client.market.getAssetPrices(),  
]);  

const collateralPool = requirePool(pools, "BTC");  
const borrowPool = requirePool(pools, "USDC");  

const collateralAmount = 50_000n;  
const borrowAmount = 9_000_000n;  

const ltv = client.quote.calculateLtv(  
  {
    collateralPoolId: collateralPool.id,  
    borrowPoolId: borrowPool.id,  
    collateralAmount,
    borrowAmount,
  },
  pools,
  prices
);

if (ltv.validationErrors.length > 0) {  
  throw new Error(ltv.validationErrors.map((error) => error.message).join(" "));  
}

const loan = await client.instantLoans.create({
  collateralPoolId: collateralPool.id,  
  borrowPoolId: borrowPool.id,  
  collateralAsset: "BTC",  
  borrowAsset: "USDC",  
  collateralAmount,
  borrowAmount,
  ltvMaxBps: ltv.maxAllowedLtvBps,  
  depositWindowSeconds: 3_600n,  
  borrowDestination: {
    type: "External",
    address: "0x2222222222222222222222222222222222222222",
  },
  refundDestination: {
    type: "External",
    address: "bc1qrefunddestination",
  },
});

console.log("Save this loan reference:", loan.ref);
console.log("Send collateral to:", formatSupplyTarget(loan.depositTarget));

const restoredLoan = await client.instantLoans.get({ ref: loan.ref });

console.log("Loan status:", restoredLoan.status);
console.log("Repay amount:", restoredLoan.repayment.amount.toString());
console.log("Repay target:", formatSupplyTarget(restoredLoan.repayment.target));

function requirePool(pools: Pool[], asset: string): Pool {
  const pool = pools.find((candidatePool) => candidatePool.asset === asset);

  if (!pool) {
    throw new Error(`Missing ${asset} pool.`);
  }

  if (pool.frozen) {
    throw new Error(`${asset} pool is frozen.`);
  }

  return pool;
}

function formatSupplyTarget(target: SupplyTarget): string {
  if (target.type === "nativeAddress") {
    return target.address;
  }

  return target.account;
}
```

--------------------------------

### Supply Flow Example

Source: https://liquidium-inc.github.io/liquidium-sdk/guides/contract-interaction-flow

Example of a supply flow using the SDK, which involves approving and depositing ERC-20 funds.

```javascript
const supplyFlow = await client.lending.supply({
  mechanism: "contractInteraction",
  profileId,
  poolId,
  action: "deposit",
  walletAdapter,
  account: evmAddress,
  amount,
});

console.log("Deposit txid", supplyFlow.txid);

```

--------------------------------

### get

Source: https://liquidium-inc.github.io/liquidium-sdk/api-reference/generated/classes/InstantLoansModule

Resolves the canonical canister state for a loan using its loan ID or a short reference. References are decoded locally, and then the corresponding loan ID is retrieved from the instant-loans canister.

```typescript
get(request: InstantLoanGetRequest): Promise<InstantLoan>
```

--------------------------------

### findByAddress

Source: https://liquidium-inc.github.io/liquidium-sdk/api-reference/generated/classes/InstantLoansModule

Finds candidate loans associated with a given address using the Liquidium SDK API. This method returns only discovery candidates; to get the full canister state, call `get(...)`. Candidates are useful for recovery scenarios where a user might know a borrow or refund address but not the specific loan reference.

```typescript
findByAddress(address: string): Promise<InstantLoanCandidate[]>
```

--------------------------------

### Deposit Address Flow Example

Source: https://liquidium-inc.github.io/liquidium-sdk/guides/deposit-address-flow

This code snippet demonstrates how to initiate a supply flow and handle the deposit target, whether it's a native address or an ICRC account. It also shows when to call `submit` if a transaction ID is required.

```javascript
const supplyFlow = await client.lending.supply({
  profileId,
  poolId,
  action: "deposit",
});

if (supplyFlow.target.type === "nativeAddress") {
  console.log("Send funds to", supplyFlow.target.address);
} else {
  console.log("Send funds to", supplyFlow.target.account);
}

```

--------------------------------

### Error.captureStackTrace Example 2

Source: https://liquidium-inc.github.io/liquidium-sdk/api-reference/generated/classes/LiquidiumError

Shows how to use the constructorOpt argument to omit frames from the stack trace, hiding implementation details.

```typescript
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.  
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;
  
  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

--------------------------------

### Create client with defaults

Source: https://liquidium-inc.github.io/liquidium-sdk/getting-started/configuration

Instantiate the LiquidiumClient with default settings for Liquidium mainnet.

```typescript
import { LiquidiumClient } from "@liquidium/client";  

const client = new LiquidiumClient();  
```

--------------------------------

### create

Source: https://liquidium-inc.github.io/liquidium-sdk/api-reference/generated/classes/InstantLoansModule

Creates a profileless instant loan. It returns the canonical canister state along with deposit and repayment targets for the generated lending profile. Before creation, it's recommended to choose collateral and borrow pools, convert UI amounts to base units using pool decimals, and calculate the Loan-to-Value (LTV) ratio using `client.quote.calculateLtv(...)` to prevent invalid LTV inputs. The `borrowDestination` parameter specifies where the borrowed asset will be sent, and `refundDestination` is for collateral refunds or withdrawals. `depositWindowSeconds` controls the user-facing collateral deposit timeout, which the SDK maps to the canister's internal `ltv_timer_s`.

```typescript
create(request: CreateInstantLoanRequest): Promise<InstantLoan>
```

--------------------------------

### Constructor

Source: https://liquidium-inc.github.io/liquidium-sdk/api-reference/generated/classes/InstantLoansModule

Initializes a new instance of the InstantLoansModule. It requires canister context, an API client, and instances of LendingModule and PositionsModule.

```typescript
new InstantLoansModule(
  canisterContext: CanisterContext,
  apiClient: ApiClient | undefined,
  lending: LendingModule,
  positions: PositionsModule
): InstantLoansModule
```

--------------------------------

### Error.captureStackTrace Example 1

Source: https://liquidium-inc.github.io/liquidium-sdk/api-reference/generated/classes/LiquidiumError

Demonstrates the basic usage of Error.captureStackTrace to add a stack property to an object.

```typescript
const myObject = {};

Error.captureStackTrace(myObject);

myObject.stack;  // Similar to `new Error().stack`
```

--------------------------------

### Create client with custom configuration

Source: https://liquidium-inc.github.io/liquidium-sdk/getting-started/configuration

Instantiate the LiquidiumClient with custom transports, headers, canister IDs, or EVM read support.

```typescript
const client = new LiquidiumClient({  
  apiBaseUrl: "https://app.liquidium.fi/api/sdk",  
  headers: {  
    "x-client-name": "my-app",  
  },  
  evmRpcUrl: import.meta.env.VITE_EVM_RPC_URL,  
});  
```

--------------------------------

### getConfig

Source: https://liquidium-inc.github.io/liquidium-sdk/api-reference/generated/classes/InstantLoansModule

Retrieves the active configuration of the instant-loans canister through a direct query.

```typescript
getConfig(): Promise<InstantLoanConfig>
```

--------------------------------

### listAccessList

Source: https://liquidium-inc.github.io/liquidium-sdk/api-reference/generated/classes/InstantLoansModule

Returns a list of principals that are authorized to perform protected update callbacks.

```typescript
listAccessList(): Promise<string[]>
```

--------------------------------

### Restore State using Reference

Source: https://liquidium-inc.github.io/liquidium-sdk/guides/instant-loans

Use the user-facing reference for refreshes, status pages, and support links.

```javascript
const loan = await client.instantLoans.get({ ref: savedReference });
```

--------------------------------

### listEvents

Source: https://liquidium-inc.github.io/liquidium-sdk/api-reference/generated/classes/InstantLoansModule

Retrieves a page of canister events via a direct query, ordered by ascending event ID.

```typescript
listEvents(request: InstantLoanListEventsRequest): Promise<InstantLoanEvent[]>
```

--------------------------------

### Generate API Reference

Source: https://liquidium-inc.github.io/liquidium-sdk/api-reference

Command to generate API reference files using pnpm.

```bash
pnpm docs:api
```

--------------------------------

### Restore State using Address Recovery

Source: https://liquidium-inc.github.io/liquidium-sdk/guides/instant-loans

Use address recovery only when the user lost the reference. Candidates are lightweight. Load canonical state with `client.instantLoans.get(...)` before you show transfer targets or repayment amounts.

```javascript
const candidates = await client.instantLoans.findByAddress(address);
```

--------------------------------

### getEvent

Source: https://liquidium-inc.github.io/liquidium-sdk/api-reference/generated/classes/InstantLoansModule

Fetches a specific canister event by its ID via a direct query.

```typescript
getEvent(eventId: bigint): Promise<InstantLoanEvent | null>
```

--------------------------------

### Restore State using Loan ID

Source: https://liquidium-inc.github.io/liquidium-sdk/guides/instant-loans

Use the numeric loan ID when your backend stores it.

```javascript
const loan = await client.instantLoans.get({ loanId });
```

--------------------------------

### countWarmedProfiles

Source: https://liquidium-inc.github.io/liquidium-sdk/api-reference/generated/classes/InstantLoansModule

Retrieves the current number of warmed profiles in the pool by directly querying the canister.

```typescript
countWarmedProfiles(): Promise<bigint>
```

--------------------------------

### Reload state

Source: https://liquidium-inc.github.io/liquidium-sdk/concepts/instant-loan-lifecycle

Reload state with the following code snippet.

```javascript
const loan = await client.instantLoans.get({ ref });  
```
Tokens:
Raw