@ada-harvest/sdk

Flash loan borrower SDK for ADA Harvest — borrow ADA from the vault in a single Cardano transaction.

What is a flash loan?

Borrow ADA with no collateral. The Plutus V3 smart contract enforces repayment atomically — if your transaction doesn't return principal + fee to the vault, the whole transaction is rejected by every Cardano node. No trust required.

Use cases: DEX arbitrage · protocol liquidations · collateral swaps

Install

npm install @ada-harvest/sdk lucid-cardano

Quick start

import { FlashLoanClient } from '@ada-harvest/sdk';
import { Lucid, Blockfrost } from 'lucid-cardano';

// Set up Lucid with your wallet
const lucid = await Lucid.new(
  new Blockfrost('https://cardano-mainnet.blockfrost.io/api/v0', 'mainnetXXX'),
  'Mainnet'
);
lucid.selectWalletFromSeed('your twelve word seed phrase...');

// Create client (defaults to https://api.ada-harvest.com)
const client = new FlashLoanClient();

// Fetch terms: vault UTXO, fee rate, max borrow
const terms = await client.getTerms();
console.log('Max loan:', terms.maxLoanLovelace, 'lovelace');
console.log('Fee:', terms.feeBps, 'bps');

// Build + submit in one call
const result = await client.buildAndSubmit({
  terms,
  amountLovelace: '50000000',             // 50 ADA
  borrowerAddress: await lucid.wallet.address(),
  lucid,
  buildArbitrageTx: async (tx, loanedAda) => {
    // Add your arbitrage / liquidation steps here.
    // tx is a Lucid TxBuilder. loanedAda is BigInt lovelace.
    // The SDK appends the vault repayment output after this callback.
    return tx;
  },
});

console.log('Submitted:', result.txHash);
console.log('Fee paid:', Number(result.feeLovelace) / 1_000_000, 'ADA');

API

new FlashLoanClient(apiBase?)

Creates a client. Defaults to https://api.ada-harvest.com.

client.getTerms(): Promise<FlashLoanTerms>

Returns the current vault UTXO, validator CBOR, fee rate, and borrowable cap.

client.buildTx(params): Promise<string>

Builds a signed flash loan transaction. Returns CBOR hex.

client.verify(params): Promise<{ valid: boolean; reason?: string }>

Optional pre-flight: checks your tx returns enough to the vault before broadcasting.

client.submit(params): Promise<FlashLoanSubmitResult>

Submits a signed tx CBOR. Returns { txHash, logId, amountLovelace, feeLovelace }.

client.buildAndSubmit(params): Promise<FlashLoanSubmitResult>

Combines buildTx + submit in one call.

calcFeeLovelace(amountLovelace, feeBps): bigint

Compute the fee for a given amount and fee rate.

calcRepaymentLovelace(vaultInput, amount, feeBps): bigint

Compute the minimum amount to return to the vault.

Fee

The fee rate is set daily by the AI council — currently 0.50% (50 bps). You can always read the current rate from terms.feeBps before building your tx.

Limits

| Parameter | Value | |-----------|-------| | Min loan | 10 ADA | | Max loan | 50% of vault TVL (enforced on-chain) | | Fee range | 0.05% – 1.00% (set by AI council) |

Docs

Full developer documentation: https://ada-harvest.com/flash-loan-docs

License

MIT