> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inkwell.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Guide

> Technical guide for integrating Leviathan Embedded Lending into your protocol using the SDK.

> **CONFIDENTIAL & PROPRIETARY © 2026 Inkwell Finance, Inc. All Rights Reserved.**
>
> This document is for informational purposes only and does not constitute legal, tax, or investment advice, nor an offer to sell or a solicitation to buy any security or other financial instrument. Any examples, structures, or flows described here are design intent only and may change.

## Overview

This guide walks through the technical steps for integrating Leviathan Embedded Lending into your protocol. The integration is SDK-driven — your frontend calls the `@leviathan/sdk/embedded` package, which handles all communication with Leviathan's on-chain programs.

<Note>
  **Prerequisites**

  Before starting integration, your protocol must complete the [onboarding process](/leviathan/embedded/protocol-onboarding). Onboarding establishes your protocol's whitelist, approved functions, and revenue split configuration on-chain.
</Note>

## SDK Installation

Install the Leviathan SDK:

```bash theme={null}
pnpm add @leviathan/sdk
```

The SDK requires `@solana/web3.js` as a peer dependency:

```bash theme={null}
pnpm add @solana/web3.js
```

## Core Client

The `EmbeddedLendingClient` is your primary integration surface:

```typescript theme={null}
import { EmbeddedLendingClient } from "@leviathan/sdk/embedded";
import { Connection, PublicKey } from "@solana/web3.js";

const connection = new Connection("https://api.mainnet-beta.solana.com");
const protocolId = new PublicKey("your-protocol-whitelist-pda");

const client = new EmbeddedLendingClient({
  connection,
  protocolId,
});
```

The `protocolId` is the on-chain address of your protocol's whitelist configuration, created during onboarding.

## Key Operations

### Check Credit Line Eligibility

Before offering lending features, check whether a user qualifies:

```typescript theme={null}
const userWallet = new PublicKey("user-wallet-address");

const eligibility = await client.checkEligibility(userWallet);

if (eligibility.eligible) {
  // User qualifies — show lending UI
  console.log(`Credit limit: \${eligibility.creditLimit}`);
  console.log(`Rate tier: \${eligibility.rateTier}`);
} else {
  // User does not qualify — hide or disable lending features
  console.log(`Reason: \${eligibility.reason}`);
}
```

Eligibility is determined by the user's on-chain credit score from `leviathan-score`. Users with insufficient history or low scores may not qualify.

### Create Agreement

Before a user can borrow, they must accept the lending agreement:

```typescript theme={null}
const agreement = await client.createAgreement({
  borrower: userWallet,
  creditLimit: eligibility.creditLimit,
  rateBps: eligibility.rateBps,
  termDays: 180,
  agreementHash: "sha256-of-legal-document",
});

// User signs the agreement transaction
const signedTx = await walletAdapter.signTransaction(agreement.transaction);
await connection.sendRawTransaction(signedTx.serialize());
```

The agreement links the legal terms (hashed) with the on-chain credit line parameters. Both parties can verify that the on-chain state matches the signed document.

### Originate a Loan

When a user draws on their credit line:

```typescript theme={null}
const loan = await client.originateLoan({
  borrower: userWallet,
  amount: 10_000_000, // in smallest units
  purpose: "margin-trade", // protocol-defined purpose tag
});

// User signs the loan origination transaction
const signedTx = await walletAdapter.signTransaction(loan.transaction);
await connection.sendRawTransaction(signedTx.serialize());

console.log(`Loan PDA: \${loan.loanPda}`);
console.log(`Capital available for use within protocol`);
```

Once originated, capital is deployed into a policy-gated environment scoped to your protocol's approved function set.

### Validate Capital Usage

Before executing an action with borrowed capital, validate that it conforms to the protocol's function gate:

```typescript theme={null}
const validation = await client.validateAction({
  loanPda: loan.loanPda,
  targetProgram: new PublicKey("target-contract"),
  functionSelector: "swap",
  amount: 5_000_000,
});

if (validation.permitted) {
  // Proceed with the action
} else {
  // Action would be rejected — do not submit
  console.log(`Blocked: \${validation.reason}`);
}
```

This client-side check mirrors the on-chain enforcement — use it to prevent users from submitting transactions that would be rejected, improving UX.

### Query Loan State

Monitor a user's active loan:

```typescript theme={null}
const state = await client.getLoanState(loan.loanPda);

console.log(`Outstanding: \${state.outstandingBalance}`);
console.log(`Repaid: \${state.totalRepaid}`);
console.log(`Repayment cap: \${state.repaymentCap}`);
console.log(`Health: \${state.healthFactor}`);
console.log(`Status: \${state.status}`);
```

### Manage Splitters

Query the revenue split configuration for a loan:

```typescript theme={null}
const splitter = await client.getSplitterConfig(loan.loanPda);

console.log(`Repayment share: \${splitter.repaymentPct}%`);
console.log(`Borrower share: \${splitter.borrowerPct}%`);
console.log(`Protocol share: \${splitter.protocolPct}%`);
console.log(`Total routed: \${splitter.totalRouted}`);
```

## Integration Pattern

The recommended integration pattern follows this flow:

```
┌──────────────────────────────────────────────────────┐
│                 Protocol Frontend                     │
│                                                      │
│  1. Check eligibility ──► Show/hide lending UI       │
│  2. Create agreement  ──► User accepts terms         │
│  3. Originate loan    ──► Capital available           │
│  4. Validate actions  ──► Client-side gate check     │
│  5. Execute actions   ──► On-chain policy enforced   │
│  6. Query state       ──► Show repayment progress    │
│                                                      │
│  SDK handles: PDA derivation, tx construction,       │
│  account lookups, policy checks                      │
│                                                      │
│  On-chain handles: Credit scoring, policy            │
│  enforcement, revenue splitting, loan lifecycle      │
└──────────────────────────────────────────────────────┘
```

Your protocol frontend is responsible for:

* Calling the SDK at the right points in your user flow
* Presenting lending options within your existing UI
* Handling wallet signing via your existing wallet adapter
* Displaying loan state and repayment progress

Leviathan's on-chain programs handle:

* Credit assessment and eligibility
* Policy enforcement and function gating
* Revenue split execution
* Loan lifecycle state transitions

## Requirements

### Protocol Requirements

* **Whitelisted** — your protocol must be registered through the onboarding process
* **Verifiable revenue** — user activity within your protocol must generate verifiable on-chain revenue
* **Contract stability** — your protocol's contract addresses and function signatures should be stable (changes require whitelist updates)

### Technical Requirements

* **Solana wallet integration** — your frontend must support Solana wallet signing
* **SDK compatibility** — TypeScript/JavaScript frontend with `@solana/web3.js` support
* **RPC access** — reliable Solana RPC endpoint for transaction submission and account queries

## Error Handling

The SDK provides typed errors for common failure modes:

| Error                  | Meaning                                          |
| ---------------------- | ------------------------------------------------ |
| `NotEligible`          | User does not meet credit criteria               |
| `CreditLineExhausted`  | User has reached their borrowing limit           |
| `FunctionNotPermitted` | Action targets a non-approved function           |
| `LoanNotActive`        | Attempting to use capital from a non-active loan |
| `PolicyViolation`      | Transaction violates protocol policy constraints |

Handle these in your UI to provide clear feedback to users.

## Next Steps

<CardGroup cols={2}>
  <Card title="Protocol Onboarding" icon="handshake" href="/leviathan/embedded/protocol-onboarding">
    Complete the onboarding process to start integrating
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/leviathan/embedded/architecture">
    Understand the on-chain modules powering Embedded
  </Card>
</CardGroup>