### SDK Installation

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/start-here

Instructions for installing the Lombard SDK and its peer dependencies.

```APIDOC
## SDK Installation

### Description
Install the Lombard SDK and its required peer dependencies using npm.

### Method
`npm install`

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
npm install @lombard.finance/sdk

npm install viem@^2.23.15 axios@^1 bignumber.js@^9 @bitcoinerlab/secp256k1@1.2.0 bitcoinjs-lib@6.1.5
```

### Response
#### Success Response (200)
Installation completes successfully.

#### Response Example
N/A
```

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

### Install Lombard SDK and Dependencies

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/start-here

Commands to install the core Lombard SDK package and its required peer dependencies including viem, axios, and bitcoinjs-lib.

```bash
npm install @lombard.finance/sdk
npm install viem@^2.23.15 axios@^1 bignumber.js@^9 @bitcoinerlab/secp256k1@1.2.0 bitcoinjs-lib@6.1.5
```

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

### Using the SDK (Full Object)

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/start-here

Demonstrates how to use the full Lombard SDK object for accessing all capabilities.

```APIDOC
## Using the SDK (Full SDK Object)

### Description
Initialize the Lombard SDK with a configuration object to get a full SDK instance. This instance provides access to all SDK functionalities, including chain actions and data API calls.

### Method
`createLombardSDK`

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **config** (object) - Required - The configuration object created using `createConfig`.

### Request Example
```typescript
import { createLombardSDK, Chain, AssetId } from '@lombard.finance/sdk';
import { config } from './lib/lombard';

const sdk = createLombardSDK(config);

// Chain actions
const stake = sdk.chain.btc.stake({
  destChain: Chain.ETHEREUM,
  assetOut: AssetId.LBTC,
});

// Data API
const deposits = await sdk.api.deposits('0x1234...');
```

### Response
#### Success Response (200)
A fully initialized Lombard SDK object.

#### Response Example
```json
{
  "sdkInstance": "[SDK Instance Object]"
}
```
```

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

### SDK Configuration

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/start-here

Guide on how to configure the Lombard SDK for use in your application.

```APIDOC
## SDK Configuration

### Description
Configure the Lombard SDK by creating a configuration object that can be reused throughout your application. This involves specifying the environment, partner details, and wallet providers.

### Method
`createConfig`

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
```typescript
interface CreateConfigOptions {
  env: Env;
  providers?: ProviderGetters;
  partner?: PartnerConfig;
  modules?: readonly AnyModule[];
}
```

- **env** (Env) - Required - Environment (prod, testnet, dev)
- **providers** (ProviderGetters) - Optional - Wallet provider functions
- **partner** (PartnerConfig) - Optional - Partner configuration
- **modules** (AnyModule[]) - Optional - Custom modules

### Request Example
```typescript
import { createConfig, Env } from '@lombard.finance/sdk';

export const config = createConfig({
  env: Env.testnet,
  partner: {
    partnerId: 'test',  // See Partners guide for production setup
  },
  providers: {
    evm: () => window.ethereum,
  },
});
```

### Response
#### Success Response (200)
A configuration object is created.

#### Response Example
```json
{
  "config": "[Configuration Object]"
}
```
```

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

### First API Calls (Data API)

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/start-here

An overview of how to make data-fetching calls using the `sdk.api.*` methods.

```APIDOC
## First API Calls (Data API)

### Description
Access data-fetching methods through the `sdk.api.*` interface to retrieve information from the Lombard Finance API. Examples include fetching deposit data.

### Method
`sdk.api.*` (e.g., `sdk.api.deposits`)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
Parameters depend on the specific API method called (e.g., an address for `deposits`).

### Request Example
```typescript
// Assuming 'sdk' is initialized as shown in the 'Full SDK Object' example
const deposits = await sdk.api.deposits('0x1234...');
```

### Response
#### Success Response (200)
Returns the requested data from the API.

#### Response Example
```json
{
  "data": "[API Response Data]"
}
```
```

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

### Using the SDK (Modular Factories)

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/start-here

Illustrates how to use modular factories for a more tree-shakeable approach to using the Lombard SDK.

```APIDOC
## Using the SDK (Modular Factories)

### Description
Utilize modular factories to import only the necessary SDK modules. This approach is recommended for production builds to optimize tree-shaking and reduce bundle size.

### Method
Factory functions (e.g., `btcStake`)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **config** (object) - Required - The configuration object created using `createConfig`.
- **options** (object) - Required - Module-specific options.

### Request Example
```typescript
import { btcStake, Chain, AssetId } from '@lombard.finance/sdk';
import { config } from './lib/lombard';

const stake = btcStake(config, {
  destChain: Chain.ETHEREUM,
  assetOut: AssetId.LBTC,
});
```

### Response
#### Success Response (200)
Returns the specific module function (e.g., `btcStake` function).

#### Response Example
```json
{
  "moduleFunction": "[Function Object]"
}
```
```

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

### Initialize and Use SDK

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/start-here

Demonstrates two usage patterns: the full SDK object for comprehensive access to chain actions and data APIs, and modular factories for tree-shaking optimization.

```typescript
// Full SDK Approach
import { createLombardSDK, Chain, AssetId } from '@lombard.finance/sdk';
import { config } from './lib/lombard';

const sdk = createLombardSDK(config);
const stake = sdk.chain.btc.stake({ destChain: Chain.ETHEREUM, assetOut: AssetId.LBTC });
const deposits = await sdk.api.deposits('0x1234...');

// Modular Factory Approach
import { btcStake } from '@lombard.finance/sdk';

const stakeModular = btcStake(config, {
  destChain: Chain.ETHEREUM,
  assetOut: AssetId.LBTC,
});
```

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

### Configure Lombard SDK

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/start-here

Initializes the SDK configuration object with environment settings and wallet providers. This configuration should be exported from a central file for reuse across the application.

```typescript
import { createConfig, Env } from '@lombard.finance/sdk';

export const config = createConfig({
  env: Env.testnet,
  partner: {
    partnerId: 'test',
  },
  providers: {
    evm: () => window.ethereum,
  },
});
```

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

### Define SDK Configuration Options

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/start-here

TypeScript interface definition for the configuration object, outlining required environment settings and optional providers, partner details, and modules.

```typescript
interface CreateConfigOptions {
  env: Env;
  providers?: ProviderGetters;
  partner?: PartnerConfig;
  modules?: readonly AnyModule[];
}
```

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

### Access Event Constants

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/concepts/event-handling

Provides examples of importing event constants for various SDK actions and the internal structure of event constant objects.

```typescript
import {
  StakeEvent,
  DepositEvent,
  UnstakeEvent,
  DeployEvent,
  RedeemEvent,
  BridgeEvent,
} from '@lombard.finance/sdk';

const StakeEvent = {
  Progress: 'progress',
  StatusChange: 'status-change',
  Completed: 'completed',
  Failed: 'failed',
  Error: 'error',
};
```

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

### Setup Solana Provider for SDK

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/capabilities/non-evm/solana-deposit

Configures the Lombard SDK to use a Solana provider. This is a necessary step for interacting with Solana-based functionalities. The `solana` key in the `providers` object should be set to a function that returns the Solana Web3 provider (e.g., `window.solana`).

```typescript
import { createLombardSDK, Env } from '@lombard.finance/sdk';

const sdk = await createLombardSDK({
  env: Env.stage,
  providers: {
    solana: () => window.solana,
  },
});
```

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

### Prepare Deposit with Referral Code (TypeScript)

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/capabilities/bitcoin/btc-deposit-and-deploy

This code snippet extends the basic BTC deposit and deploy functionality by including a referral code during the preparation phase. This allows for tracking and attributing deposits to specific partners. It uses the same Lombard SDK setup as the basic usage.

```tsx
await depositAndDeploy.prepare({
  amount: '0.1',
  recipient: '0x1234567890abcdef1234567890abcdef12345678',
  referralCode: 'PARTNER123',
});

```

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

### GET /api/exchangeRatio

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/data-api/api-methods

Fetches the current exchange ratios for all supported tokens.

```APIDOC
## GET /api/exchangeRatio

### Description
Fetches the current exchange ratios for all supported tokens.

### Method
GET

### Endpoint
/api/exchangeRatio

### Parameters
None

### Request Example
```javascript
// Assuming 'sdk' is an initialized Lombard SDK instance
const ratios = await sdk.api.exchangeRatio();
```

### Response
#### Success Response (200)
- **ratios** (object) - An object where keys are token symbols and values contain exchange rate information.

```json
{
  "LBTC": {
    "tokenBTCRatio": "0.998",
    "BTCTokenRatio": "1.002"
  },
  "ETH": {
    "tokenBTCRatio": "0.05",
    "BTCTokenRatio": "20.0"
  }
  // ... other tokens
}
```
```

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

### GET /api/unstakes

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/data-api/api-methods

Fetches all unstakes for a given address, with options to filter the results.

```APIDOC
## GET /api/unstakes

### Description
Fetches all unstakes for a given address, with options to filter the results.

### Method
GET

### Endpoint
/api/unstakes

### Parameters
#### Query Parameters
- **address** (string) - Required - The address to fetch unstakes for.
- **show_redeems** (boolean) - Optional - Whether to include redeem transactions. Defaults to true.
- **show_unstakes** (boolean) - Optional - Whether to include unstake transactions. Defaults to true.
- **to_native** (boolean) - Optional - Whether to filter for native unstakes. Defaults to false.

### Request Example
```javascript
// Assuming 'sdk' is an initialized Lombard SDK instance
// Fetch all unstakes
const unstakes = await sdk.api.unstakes('0x1234...');

// Fetch unstakes with specific filters
const filteredUnstakes = await sdk.api.unstakes('0x1234...', {
  show_redeems: false,
  to_native: true
});
```

### Response
#### Success Response (200)
- **unstakes** (Unstake[]) - An array of unstake objects.

```json
// Example Unstake object structure
{
  "isNative": false,
  "txHash": "0xabc123...",
  "fromChainId": 1,
  "toChainId": 56,
  "blockHeight": 12345678,
  "blockTime": 1678886400,
  "fromAddress": "0x789ghi...",
  "toAddress": "0xdef456...",
  "amount": "500000000000000000",
  "payoutTxHash": null,
  "payoutTxIndex": null,
  "payoutTxStatus": "PENDING",
  "sanctioned": false,
  "notarizationStatus": "PENDING",
  "sessionState": "ACTIVE",
  "claimTxHash": null
}
```
```

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

### GET /api/points

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/data-api/api-methods

Fetches Lux points for a given address, optionally for a specific season.

```APIDOC
## GET /api/points

### Description
Fetches Lux points for a given address, optionally for a specific season.

### Method
GET

### Endpoint
/api/points

### Parameters
#### Query Parameters
- **address** (string) - Required - The address to fetch points for.
- **season** (number) - Optional - The specific season number to fetch points for. If not provided, points for the current season are returned.

### Request Example
```javascript
// Assuming 'sdk' is an initialized Lombard SDK instance
// Fetch points for the current season
const currentSeasonPoints = await sdk.api.points('0x1234...');

// Fetch points for a specific season (e.g., season 1)
const season1Points = await sdk.api.points('0x1234...', 1);
```

### Response
#### Success Response (200)
- **points** (object) - An object containing point data. Structure may vary based on whether a season is specified.

```json
// Example response for current season
{
  "totalPoints": "1500",
  "holdingPoints": "1000",
  "tradingPoints": "500",
  "season": 3
}

// Example response for a specific season
{
  "totalPoints": "1200",
  "holdingPoints": "800",
  "tradingPoints": "400"
}
```
```

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

### GET /sdk/referrals/lookupReferrer

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/concepts/referral-system

Retrieves the referral status and associated referrer code for a given address.

```APIDOC
## GET sdk.referrals.lookupReferrer

### Description
Checks if a specific address has an associated referrer.

### Method
GET

### Endpoint
sdk.referrals.lookupReferrer({ address: string })

### Parameters
#### Query Parameters
- **address** (string) - Required - The address to check for referral attribution.

### Response
#### Success Response (200)
- **hasDepositAddress** (boolean) - Indicates if the address has a valid deposit association.
- **referrer** (string) - The referral code associated with the address, if any.

### Response Example
{
  "hasDepositAddress": true,
  "referrer": "PARTNER123"
}
```

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

### Initialize Lombard SDK

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/data-api/api-methods

Demonstrates how to import and initialize the Lombard SDK using a configuration object.

```typescript
import { createLombardSDK } from '@lombard.finance/sdk';
import { config } from './lib/lombard';

const sdk = createLombardSDK(config);
```

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

### Configure Lombard SDK Provider

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/capabilities/non-evm/starknet-unstake

Shows how to set up the Lombard SDK configuration, including environment selection and provider injection for Starknet.

```tsx
import { createConfig, Env } from '@lombard.finance/sdk';

const config = createConfig({
  env: Env.testnet,
  providers: {
    starknet: () => window.starknet,
  },
});
```

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

### Deploy LBTC to DeFi Protocols using Lombard SDK

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/capabilities/evm/evm-deploy

Demonstrates how to initialize the Lombard SDK, configure a deployment to a specific protocol, and execute the transaction. Requires the @lombard.finance/sdk package and a valid configuration object.

```tsx
import { createLombardSDK, Chain, AssetId, DeployProtocol } from '@lombard.finance/sdk';
import { config } from './lib/lombard';

const sdk = createLombardSDK(config);

const deploy = sdk.chain.evm.deploy({
  sourceChain: Chain.ETHEREUM,
  assetIn: AssetId.LBTC,
  deploy: {
    protocol: DeployProtocol.Veda,
  },
});

await deploy.prepare({
  amount: '0.1',
});

const result = await deploy.execute();
```

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

### Switch Environments Dynamically

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/start-here/testing-and-sandbox

Demonstrates how to switch between production and testnet environments at runtime using environment variables. This pattern ensures the correct partnerId and environment settings are applied based on the deployment context.

```tsx
import { createConfig, Env } from '@lombard.finance/sdk';

const env = process.env.LOMBARD_ENV === 'production' ? Env.prod : Env.testnet;

const config = createConfig({
  env,
  partner: {
    partnerId: env === Env.prod ? 'YOUR_PARTNER_ID' : 'test',
  },
  providers: {
    evm: () => window.ethereum,
  },
});
```

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

### GET /api/deposits

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/data-api/api-methods

Fetches all deposits for a given address. The response includes detailed information about each deposit transaction.

```APIDOC
## GET /api/deposits

### Description
Fetches all deposits for a given address. The response includes detailed information about each deposit transaction.

### Method
GET

### Endpoint
/api/deposits

### Parameters
#### Query Parameters
- **address** (string) - Required - The address to fetch deposits for.

### Request Example
```javascript
// Assuming 'sdk' is an initialized Lombard SDK instance
const deposits = await sdk.api.deposits('0x1234...');
```

### Response
#### Success Response (200)
- **deposits** (Deposit[]) - An array of deposit objects.

```json
// Example Deposit object structure
{
  "isNative": true,
  "txHash": "0xabc123...",
  "eventIndex": 0,
  "amount": "1000000000000000000",
  "tokenAmount": null,
  "depositAddress": "0xdef456...",
  "fromAddress": "0x789ghi...",
  "toAddress": null,
  "toChainId": 1,
  "fromChainId": 1,
  "blockHeight": 12345678,
  "blockTime": 1678886400,
  "notarizationStatus": "PROCESSED",
  "sessionState": "COMPLETED",
  "claimTxHash": null,
  "isClaimed": false,
  "sanctioned": false
}
```
```

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

### Monitor Withdrawal Events

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/capabilities/evm/evm-withdraw

Provides examples of how to listen to status changes, progress updates, and completion events during the withdrawal process.

```typescript
withdraw.on('status-change', (status) => {
  // status: 'IDLE' | 'NEEDS_APPROVAL' | 'READY' | 'COMPLETED'
});

withdraw.on('progress', (progress) => {
  // progress.status: current status
  // progress.steps.approval: 'IDLE' | 'PENDING' | 'COMPLETE'
  // progress.steps.queueing: 'IDLE' | 'PENDING' | 'COMPLETE'
});

withdraw.on('completed', () => {
  // Withdrawal successfully queued
});
```

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

### Initialize and Execute BTC Deposit

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/capabilities/bitcoin/btc-deposit

Demonstrates the full lifecycle of a BTC deposit using the Lombard SDK. This includes initializing the SDK, configuring the deposit parameters, authorizing the transaction, and generating a destination address.

```tsx
import { createLombardSDK, Chain, AssetId } from '@lombard.finance/sdk';
import { config } from './lib/lombard';

const sdk = createLombardSDK(config);

const deposit = sdk.chain.btc.deposit({
  destChain: Chain.KATANA,
  assetOut: AssetId.BTCb,
});

await deposit.prepare({
  amount: '0.1',
  recipient: '0x1234567890abcdef1234567890abcdef12345678',
});

await deposit.authorize();

const depositAddress = await deposit.generateDepositAddress();
```

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

### Initialize and execute BTC stake

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/capabilities/bitcoin/btc-stake

Demonstrates the basic workflow for staking BTC, including SDK initialization, preparing the transaction with recipient details, authorizing the action, and generating a deposit address.

```typescript
import { createLombardSDK, Chain, AssetId } from '@lombard.finance/sdk';
import { config } from './lib/lombard';

const sdk = createLombardSDK(config);

const stake = sdk.chain.btc.stake({
  destChain: Chain.ETHEREUM,
  assetOut: AssetId.LBTC,
});

await stake.prepare({
  amount: '0.1',
  recipient: '0x1234567890abcdef1234567890abcdef12345678',
});

await stake.authorize();

const depositAddress = await stake.generateDepositAddress();
```

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

### GET /api/depositAddress

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/data-api/api-methods

Retrieves an existing BTC deposit address for a recipient on a specified chain, with optional parameters for partner ID and token.

```APIDOC
## GET /api/depositAddress

### Description
Retrieves an existing BTC deposit address for a recipient on a specified chain, with optional parameters for partner ID and token.

### Method
GET

### Endpoint
/api/depositAddress

### Parameters
#### Query Parameters
- **recipientAddress** (string) - Required - The address that will receive the deposited funds.
- **chainId** (number) - Required - The chain ID where the deposit will be made (e.g., ChainId.ethereum).
- **options** (object) - Optional - An object containing additional options.
  - **partnerId** (string) - Optional - Your unique partner identifier.
  - **token** (string) - Optional - The specific token for which to get a deposit address (e.g., 'LBTC').

### Request Example
```javascript
import { ChainId } from '@lombard.finance/sdk';

// Assuming 'sdk' is an initialized Lombard SDK instance

try {
  // Get a standard BTC deposit address for Ethereum chain
  const btcAddress = await sdk.api.depositAddress(
    '0x1234567890abcdef1234567890abcdef12345678',
    ChainId.ethereum
  );
  console.log('BTC Deposit Address:', btcAddress);

  // Get a deposit address with partner ID and specific token
  const specificBtcAddress = await sdk.api.depositAddress(
    '0x1234...',
    ChainId.ethereum,
    {
      partnerId: 'YOUR_PARTNER_ID',
      token: 'LBTC'
    }
  );
  console.log('Specific BTC Deposit Address:', specificBtcAddress);

} catch (error) {
  console.error('Error fetching deposit address:', error.message);
  // Handle cases where no existing deposit address is found or other errors
}
```

### Response
#### Success Response (200)
- **btcAddress** (string) - The BTC deposit address.

#### Error Response (e.g., 404)
- **message** (string) - Description of the error, e.g., 'No existing deposit address found'.

```json
// Example success response
"bc1qxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

// Example error response
{
  "message": "No existing deposit address found"
}
```
```

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

### Get BTC Deposit Address

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/data-api/api-methods

Retrieves or generates a BTC deposit address for a specific recipient on a target chain, with optional partner and token parameters.

```typescript
import { ChainId } from '@lombard.finance/sdk';

try {
  const btcAddress = await sdk.api.depositAddress(
    '0x1234567890abcdef1234567890abcdef12345678',
    ChainId.ethereum
  );
} catch (error) {}

const btcAddressWithOptions = await sdk.api.depositAddress(
  '0x1234...',
  ChainId.ethereum,
  {
    partnerId: 'YOUR_PARTNER_ID',
    token: 'LBTC'
  }
);
```

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

### Prepare Deposit with Referral Code

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/capabilities/bitcoin/btc-deposit

Shows how to include an optional referral code during the deposit preparation phase to ensure proper attribution.

```tsx
await deposit.prepare({
  amount: '0.1',
  recipient: '0x1234567890abcdef1234567890abcdef12345678',
  referralCode: 'PARTNER123',
});
```

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

### Initialize SDK and Prepare Solana Deposit

Source: https://docs.lombard.finance/build/the-lombard-sdk/user-guides/capabilities/non-evm/solana-deposit

Initializes the Lombard SDK with a Solana provider and prepares a BTC deposit to Solana. It requires the destination chain, output asset, source chain, deposit amount, and recipient Solana address. The SDK instance is created with environment and partner configurations, and a Solana provider is registered.

```typescript
import { createLombardSDK, Chain, AssetId, Env } from '@lombard.finance/sdk';

const sdk = await createLombardSDK({
  env: Env.stage,
  partner: { partnerId: 'test' },
  providers: {
    solana: () => window.solana,
  },
});

const deposit = sdk.chain.btc.deposit({
  destChain: Chain.SOLANA_DEVNET,
  assetOut: AssetId.BTCb,
  sourceChain: Chain.BITCOIN_SIGNET,
});

await deposit.prepare({
  amount: '0.01',
  recipient: 'SoLaNaWaLLeTaDdReSs1234567890abcdef12345678',
});

const depositAddress = await deposit.generateDepositAddress();
// depositAddress: 'bc1q...'
```