Skip to main content

Flash Loans SDK

The DeepBookV3 SDK provides flash loan functions that let you borrow and return pool assets within a single programmable transaction block (PTB). Because the borrow and repayment happen atomically in the same transaction, you never hold an uncollateralized position across transactions. See Flash Loans for more details on the underlying contract API.

What is a flash loan?​

A flash loan lets you borrow an asset from a DeepBook pool without upfront collateral, as long as you return exactly what you borrowed within the same PTB. DeepBook charges no fee on flash loans. If the repayment step fails, the entire transaction reverts and no funds leave the pool. This makes flash loans safe for the protocol and useful for arbitrage, liquidations, and other multi-step trading strategies.

Setup​

Flash loan functions live on the DeepBook client extension. Create a SuiGrpcClient and extend it with deepbook().

import { deepbook } from '@mysten/deepbook-v3';
import { SuiGrpcClient } from '@mysten/sui/grpc';

const client = new SuiGrpcClient({
	network: 'testnet',
	baseUrl: 'https://fullnode.testnet.sui.io:443',
}).$extend(
	deepbook({
		address: '<YOUR_ADDRESS>',
	}),
);

Reach the functions on this page through client.deepbook.flashLoans. Each one returns a callback that accepts a Transaction object, making it compatible with PTB composition. The example later on this page runs inside the DeepBookMarketMaker class from the DeepBookV3 SDK overview, where the same extended client is this.client.

Flash loan functions​

The DeepBookV3 SDK provides the following flash loan related functions.

borrowBaseAsset​

Use borrowBaseAsset to borrow a base asset from the pool identified by the poolKey value you provide. The call returns a function that takes a Transaction object. The borrow returns a FlashLoan hot potato (struct with no abilities), which must be returned back to the pool by the end of the call.. The borrow returns a FlashLoan hot potato (struct with no abilities), which must be returned back to the pool by the end of the call.

Parameters

  • poolKey: String that identifies the pool to which to return the base asset. The SDK comes with default pools; you can provide a PoolMap during construction to override this behavior.
  • borrowAmount: Number that represents the amount to borrow from the pool.
borrowBaseAsset(poolKey: string, borrowAmount: number);

returnBaseAsset​

Use returnBaseAsset to return the base asset to the pool identified by the poolKey value you provide. The call returns a function that takes a Transaction object.

Parameters

  • poolKey: String that identifies the pool to which to return the base asset.
  • borrowAmount: Number that represents the amount to borrow from the pool.
  • baseCoinInput: Coin object representing the base asset to be returned.
  • flashLoan: Flash loan object representing the loan to be settled.

returnBaseAsset splits exactly borrowAmount off baseCoinInput and returns the remainder to you.

returnBaseAsset(
  poolKey: string,
  borrowAmount: number,
  baseCoinInput: TransactionObjectArgument,
  flashLoan: TransactionObjectArgument,
);

borrowQuoteAsset​

Use borrowQuoteAsset to borrow a quote asset from the pool identified by the poolKey value you provide. The call returns a function that takes a Transaction object.

Parameters

  • poolKey: String that identifies the pool from which to borrow.
  • borrowAmount: Number that represents the amount to borrow from the pool.
borrowQuoteAsset(poolKey: string, borrowAmount: number);

returnQuoteAsset​

Use returnQuoteAsset to return a quote asset to the pool identified by the poolKey you provide. The call returns a function that takes a Transaction object.

Parameters

  • poolKey: String that identifies the pool from which to borrow.
  • borrowAmount: Number that represents the amount to borrow from the pool.
  • quoteCoinInput: Coin object representing the quote asset to be returned.
  • flashLoan: Flash loan object representing the loan to be settled.
returnQuoteAsset(
  poolKey: string,
  borrowAmount: number,
  quoteCoinInput: TransactionObjectArgument,
  flashLoan: TransactionObjectArgument,
);

How flash loan transactions work​

Every flash loan follows the same pattern inside a single PTB:

  1. Call borrowBaseAsset or borrowQuoteAsset to receive a coin and a FlashLoan hot potato.
  2. Use the borrowed coin in one or more trading steps within the same transaction.
  3. Call returnBaseAsset or returnQuoteAsset, passing the FlashLoan and a coin holding at least the original borrow amount. The function splits the exact borrow amount off for the pool and hands you back the remainder.
  4. Transfer the remainder and any other assets to your address.

The transaction reverts automatically if step 3 does not satisfy the repayment requirement. You never need to write explicit error handling for underpayment.

Flash loan example​

The following example demonstrates flash loan usage in DeepBookMarketMaker class.

// Example of a flash loan transaction
// Borrow 1 DEEP from DEEP_SUI pool
// Swap 0.5 DBUSDC for SUI in SUI_DBUSDC pool, pay with deep borrowed
// Swap SUI back to DEEP
// Return 1 DEEP to DEEP_SUI pool
flashLoanExample = async (tx: Transaction) => {
  const borrowAmount = 1;
  const [deepCoin, flashLoan] = tx.add(this.client.deepbook.flashLoans.borrowBaseAsset('DEEP_SUI', borrowAmount));

  // Execute trade using borrowed DEEP
  const [baseOut, quoteOut, deepOut] = tx.add(
    this.client.deepbook.deepBook.swapExactQuoteForBase({
      poolKey: 'SUI_DBUSDC',
      amount: 0.5,
      deepAmount: 1,
      minOut: 0,
      deepCoin: deepCoin,
    }),
  );

  tx.transferObjects([baseOut, quoteOut, deepOut], this.getActiveAddress());

  // Execute second trade to get back DEEP for repayment
  const [baseOut2, quoteOut2, deepOut2] = tx.add(
    this.client.deepbook.deepBook.swapExactQuoteForBase({
      poolKey: 'DEEP_SUI',
      amount: 10,
      deepAmount: 0,
      minOut: 0,
    }),
  );

  tx.transferObjects([quoteOut2, deepOut2], this.getActiveAddress());

  // Return borrowed DEEP
  const loanRemain = tx.add(
    this.client.deepbook.flashLoans.returnBaseAsset('DEEP_SUI', borrowAmount, baseOut2, flashLoan),
  );
  
  // Send the remaining coin to user's address
  tx.transferObjects([loanRemain], this.getActiveAddress());
};

Frequently asked questions​

What happens if I do not repay the flash loan?​

The entire PTB reverts. Because borrow and repayment are steps in the same atomic transaction, a failed repayment means no assets leave the pool and no state changes are committed onchain.

Can I use both base and quote flash loans in the same transaction?​

Yes. You can compose multiple borrow and return calls within a single PTB as long as each FlashLoan is settled before the transaction ends. Each one has to go back to the pool it came from, in the asset it was borrowed in.

Do flash loans incur fees?​

No. DeepBook charges nothing for a flash loan. The contract requires the returned coin to hold exactly the borrowed amount, and returning more aborts with EIncorrectQuantityReturned just as returning less does. That is why returnBaseAsset splits the borrow amount off the coin you pass and gives you the remainder back, which is loanRemain in the preceding example.