Skip to content

NFTfi-Genesis/nftfi.js

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

53 Commits
cjs
cjs
 
 
examples
examples
 
 
src
src
 
 
README.md
README.md
 
 
RELEASE.md
RELEASE.md
 
 
package.json
package.json
 
 
yarn.lock
yarn.lock
 
 

Repository files navigation

NFTfi.js

A JavaScript SDK for interacting with the NFTfi Protocol.

NFTfi is a smart contract platform for P2P (Peer-2-Peer) loans using NFTs as collateral. P2P loans are directly between a Borrower and Lender — the Borrower uses an NFT as collateral to borrow ETH or DAI, and the Lender provides liquidity. The NFT is then held in an escrow contract until the loan is repaid. If the Borrower fails to repay in time, the Lender can claim the NFT.

Please note that this SDK is in closed beta, and is constantly under development. USE AT YOUR OWN RISK.

Table of Contents

Install

yarn install

Getting Started

Before starting, ensure you have an NFTfi API key. If you don't, please reach out to our team. This key is essential for initializing the SDK.

For beginners, we advise testing with the SDK on the Sepolia network. This gives you an understanding of its functionalities. Once comfortable, switch to the Mainnet.

When the SDK is set to the Sepolia network, it interacts with the dApp at https://sepolia-integration.nftfi.com. For a Mainnet setup, the SDK will interact with https://app.nftfi.com.

When initializing, the NFTfi SDK links to the account interacting with the NFTfi protocol (if authenticated). The SDK can compute the account address from the private key, web3 provider, or the ethereum.account.address field.

We recommend that you don't hardcode your credentials into NFTfi.init(...), instead you could use environment vars, or a more secure mechanism.

Initialization Examples

1) With a Private Key.

import NFTfi from '@nftfi/js';

const nftfi = await NFTfi.init({
  config: {
    api: { key: <nftfi-sdk-api-key> }
  },
  ethereum: {
    account: { privateKey: <ethereum-account-private-key> },
    provider: { url: <ethereum-provider-url> }
  }
});

2) With a Web3 Provider.

import NFTfi from '@nftfi/js';

const nftfi = await NFTfi.init({
  config: {
    api: { key: <nftfi-sdk-api-key> }
  },
  ethereum: {
    account: { address: <your-wallet-address> },
    web3: { provider: <web3-ethereum-provider> }
  }
});

3) Without a Private Key or Web3 Provider.

Note: This setup won't be able to make offers or initiate loans since they require signatures.

import NFTfi from '@nftfi/js';

const nftfi = await NFTfi.init({
  config: {
    api: { key: <nftfi-sdk-api-key> }
  },
  ethereum: {
    account: { address: <your-wallet-address> },
    provider: { url: <web3-ethereum-provider-url> }
  }
});

4) Without a Private Key, Web3 Provider, or Provider URL.

Note: This setup restricts functionality needing blockchain interactions.

import NFTfi from '@nftfi/js';

const nftfi = await NFTfi.init({
  config: {
    api: { key: <nftfi-sdk-api-key> }
  },
  ethereum: {
    account: { address: <your-wallet-address> },
    chain: { id: <chain-id> }
  }
});

Once the SDK is initialised, you can use all the methods documented below.

SDK Reference

Bundles

Class for working with bundles.

Kind: global class

bundles.mint() ⇒ Object

Mint a new bundle.

Kind: instance method of Bundles
Returns: Object - An object containing information about the minted bundle.
Example

// Mint a new v1.1 bundle.
// NOTE: v1 bundles have been deprecated, therefore this method wont mint a v1 bundle anymore.
const bundle = await nftfi.bundles.mint();

bundles.add(options) ⇒ Object

Adds elements to a bundle.

Kind: instance method of Bundles
Returns: Object - An object containing information about the updated bundle.

Param Type Description
options Object An object containing options for the add operation.
options.bundle.id string The ID of the bundle to which elements will be added.
options.nftfi.contract.name string Name of the contract used for adding elements to the bundle.
options.elements Array.<Object> An array of objects representing the elements to be added.
options.elements[].token Object An object containing information about the token associated with the element.
options.elements[].token.address string The address of the token contract associated with the element.
options.elements[].token.ids Array.<string> An array of token IDs associated with the element.

Example

// Add elements to a v1.1 bundle.
// NOTE: v1 bundles have been deprecated. You can migrate your v1 bundle to a v1.1 bundle using `bundles.migrate()`, then add elements afterwards.
const bundle = await nftfi.bundles.add({
  bundle: { id: '42' },
  elements: [
    { token: { address: '0xabc', ids: ['1', '2'] } },
    { token: { address: '0xdef', ids: ['3'] } }
  ],
  nftfi: {
    contract: {
      name: 'v1-1.bundler'
    }
  }
});

bundles.remove(options) ⇒ Object

Removes elements from a bundle.

Kind: instance method of Bundles
Returns: Object - An object containing information about the updated bundle.

Param Type Description
options Object An object containing options for the remove operation.
options.bundle.id string The ID of the bundle from which elements will be removed.
options.nftfi.contract.name string Name of the contract used for removing elements from the bundle.
options.elements Array.<Object> An array of objects representing the elements to be removed.
options.elements[].token Object An object containing information about the token associated with the element.
options.elements[].token.address string The address of the token contract associated with the element.
options.elements[].token.ids Array.<string> An array of token IDs associated with the element.

Example

// Remove elements from a v1.1 bundle.
const bundle = await nftfi.bundles.remove({
  bundle: { id: '42' },
  elements: [
    {
      token: {
        address: '0xabc',
        ids: ['1', '2', '3']
      }
    }
  ],
  nftfi: {
    contract: {
      name: 'v1-1.bundler'
    }
  }
});

bundles.seal(options) ⇒ Object

Seals a bundle, transferring it to an immutable contract, and mints a new immutable.

Kind: instance method of Bundles
Returns: Object - A promise that resolves to an object containing information about the newly minted immutable object.

Param Type Description
options Object An object containing options for the seal operation.
options.bundle.id string The ID of the bundle to be sealed.
options.nftfi.contract.name string Name of the contract used for sealing the bundle.

Example

// Seal a v1.1 bundle and mint a new v1.1 immutable.
// NOTE: v1 bundles have been deprecated. You can migrate your v1 bundle to a v1.1 bundle using `bundles.migrate()`, then seal afterwards.
const immutable = await nftfi.bundles.seal({
  bundle: { id: '42' },
  nftfi: {
    contract: {
      name: 'v1-1.bundler'
    }
  }
});

bundles.empty(options) ⇒ Object

Empties a bundle, transferring its contents to your account.

Kind: instance method of Bundles
Returns: Object - An object containing the status of the empty operation.

Param Type Description
options Object An object containing options for the empty operation.
options.bundle.id string The ID of the bundle to be emptied.
options.nftfi.contract.name string Name of the contract used for emptying the bundle.

Example

// NOTE: v1 bundles are deprecated, after emptying one it will be destroyed and you will not be able to use it anymore.
// Approve the migration contract to handle your v1 bundle.
const approvalResult = await nftfi.erc721.setApprovalForAll({
  token: { address: nftfi.config.bundler.v1.address },
  nftfi: { contract: { name: 'v1.bundler.migrate' } }
});
// Empty the v1 bundle and transfer its contents to your account.
const response = await nftfi.bundles.empty({
  bundle: { id: '42' },
  nftfi: {
    contract: {
      name: 'v1.bundler'
    }
  }
});

Example

// Empty a v1.1 bundle and transfer its contents to your account.
const response = await nftfi.bundles.empty({
  bundle: { id: '42' },
  nftfi: {
    contract: {
      name: 'v1-1.bundler'
    }
  }
});

bundles.elements(options) ⇒ Object

Retrieves the elements in a bundle.

Kind: instance method of Bundles
Returns: Object - An object containing information about the bundle and its elements.

Param Type Description
options Object An object containing options for retrieving the elements.
options.bundle.id string The ID of the bundle whose elements are to be retrieved.
options.nftfi.contract Object An object containing information about the contract.
options.nftfi.contract.name string Name of the contract used for retrieving the elements.

Example

// Get the elements of a bundle.
const elements = await nftfi.bundles.elements({
  bundle: { id: '42' },
  nftfi: {
    contract: {
      name: 'v1-1.bundler'
    }
  }
});

bundles.migrate(options) ⇒ Object

Migrates a bundle from one bundler contract to another.

Kind: instance method of Bundles
Returns: Object - An object containing information about the migrated bundle.

Param Type Description
options Object An object containing options for migrating the bundle.
options.bundle.id string The ID of the bundle to be migrated.
options.from.nftfi.contract.name string Name of the source contract.
options.to.nftfi.contract.name string Name of the destination contract.

Example

// Approve the v1 bundler contract with the v1 migration contract.
const approvalResult = await nftfi.erc721.setApprovalForAll({
  token: { address: nftfi.config.bundler.v1.address },
  nftfi: { contract: { name: 'v1.bundler.migrate' } }
});
// Migrate a bundle from v1 bundle to v1.1 bundle.
const migrateResult = await nftfi.bundles.migrate({
  bundle: { id: '42' },
  from: {
    nftfi: {
      contract: {
        name: 'v1.bundler'
      }
    }
  },
  to: {
    nftfi: {
      contract: {
        name: 'v1-1.bundler'
      }
    }
  }
});

bundles.getImmutable(options) ⇒ Object

Retrieves an immutable of a bundle.

Kind: instance method of Bundles
Returns: Object - An object containing information about a bundle.

Param Type Description
options Object An object containing options for the getImmutable operation.
options.bundle.id string The ID of the bundle object.
options.nftfi.contract Object An object containing information about the contract used to facilitate the bundle.
options.nftfi.contract.name string Name of the contract used to facilitate the bundle: v1-1.bundler.

Example

// Get an immutable of a v1-1 bundle.
const bundle = await nftfi.bundles.getImmutable({
  bundle: { id: '42' },
  nftfi: {
    contract: {
      name: 'v1-1.bundler'
    }
  }
});

Erc20

Class for working with ERC20 tokens.

Kind: global class

erc20.allowance(options) ⇒ number

Returns the ERC20 allowance, for v1 & v2 NFTfi contracts, for your account (by default), or a specified account.

Kind: instance method of Erc20
Returns: number - The user account's token allowance for that contract, in base units (eg. 1000000000000000000 wei)

Param Type Description
options object Hashmap of config options for this method
[options.account.address] object The account address to get the allowance of (optional)
options.token.address string The ERC20 token address
options.nftfi.contract.name string The name of the contract NFTfi contract (eg. v2-3.loan.fixed, v2-3.loan.fixed.collection)

Example

const balance = await nftfi.erc20.allowance({
 token: { address: '0x00000000' },
 nftfi: { contract: { name: 'v2-3.loan.fixed' } }
});

erc20.approve(options) ⇒ boolean

Approves your account's ERC20 spending amount, if not already approved, for v1 & v2 NFTfi contracts.

Kind: instance method of Erc20
Returns: boolean - Boolean value indicating whether the operation succeeded

Param Type Description
options object Hashmap of config options for this method
options.token.address string The ERC20 token address
options.nftfi.contract.name string The name of the contract NFTfi contract (eg. v2-3.loan.fixed, v2-3.loan.fixed.collection)
options.amount number The token amount to approve, in base units (eg. 1000000000000000000 wei)

Example

const results = await nftfi.erc20.approve({
  amount: 1000000000000000000,
  token: { address: '0x00000000' },
  nftfi: { contract: { name: 'v2-3.loan.fixed' } }
});

erc20.approveMax(options) ⇒ boolean

Approves your account's ERC20 maximum amount, if not already approved, for v1 & v2 NFTfi contracts.

Kind: instance method of Erc20
Returns: boolean - Boolean value indicating whether the operation succeeded

Param Type Description
options object Hashmap of config options for this method
options.token.address string The ERC20 token address
options.nftfi.contract.name string The name of the contract NFTfi contract (eg. v2-3.loan.fixed, v2-3.loan.fixed.collection)

Example

const results = await nftfi.erc20.approveMax({
  token: { address: '0x00000000' },
  nftfi: { contract: { name: 'v2-3.loan.fixed' } }
});

erc20.balanceOf(options) ⇒ number

Returns the balance of a given ERC20 token for your account (by default), or a specified account.

Kind: instance method of Erc20
Returns: number - The user account's token balance, in base units (eg. 1000000000000000000 wei)

Param Type Description
options object Options
[options.account.address] object The account address to get the balance of (optional)
options.token.address string The ERC20 token address

Example

const balance = await nftfi.erc20.balanceOf({
  token: { address: '0x00000000' }
});

Erc721

Class for working with ERC721 non-fungible tokens.

Kind: global class

erc721.ownerOf(options) ⇒ string

Returns the owner of the specified NFT.

Kind: instance method of Erc721
Returns: string - The NFT's owner address

Param Type Description
options object Options
options.token.address string The ERC721 token address
options.token.id string The ERC721 token ID

Example

const address = await nftfi.nft.erc721.ownerOf({
  token: {
   address: '0x00000000',
   id: '0'
  }
});

erc721.setApprovalForAll(options) ⇒ boolean

Sets the approval of a given NFTfi contract. The NFTfi contract is allowed to transfer all tokens of the sender on their behalf.

Kind: instance method of Erc721
Returns: boolean - Boolean value indicating whether the operation succeeded

Param Type Description
options object Options
options.token.address string The ERC721 token address
options.nftfi.contract.name string The name of the NFTfi contract (eg. v2-3.loan.fixed, v2-3.loan.fixed.collection)

Example

const address = await nftfi.nft.erc721.setApprovalForAll({
  token: {
   address: '0x00000000'
  },
  nftfi: { contract: { name: 'v2-3.loan.fixed' } }
});

erc721.isApprovedForAll(options) ⇒ boolean

Returns the approval of a given NFTfi contract. The NFTfi contract is allowed to transfer all tokens of the sender on their behalf.

Kind: instance method of Erc721
Returns: boolean - Boolean value indicating whether permission has been granted or not

Param Type Description
options object Options
options.account.address object The account address to get the approval of (optional)
options.token.address string The ERC721 token address
options.nftfi.contract.name string The name of the NFTfi contract (eg. v2-3.loan.fixed, v2-3.loan.fixed.collection)

Example

const address = await nftfi.nft.erc721.isApprovedForAll({
  token: {
   address: '0x00000000'
  },
  nftfi: { contract: { name: 'v2-3.loan.fixed' } }
});

Immutables

Class for working with immutables.

Kind: global class

immutables.unseal(options) ⇒ Object

Unseals an immutable bundle.

Kind: instance method of Immutables
Returns: Object - An object containing information about the bundle that was released from the immutable.

Param Type Description
options Object An object containing options for the unseal operation.
options.immutable.id string The ID of the immutable bundle to unseal.
options.nftfi.contract Object An object containing information about the contract used to facilitate the bundle.
options.nftfi.contract.name string Name of the contract used to facilitate the bundle: v1.immutable.bundle (deprecated), v1-1.immutable.bundle.

Example

// Unseal a v1.1 immutable bundle.
// NOTE: v1 immutables have been deprecated. You must call `nftfi.immutables.empty()` instead, or you can migrate your v1 immutable to a v1.1 immutable using `nftfi.immutables.migrate()`, then unseal it.
const bundle = await nftfi.immutables.unseal({
  immutable: { id: '42' },
  nftfi: {
    contract: {
      name: 'v1-1.immutable.bundle'
    }
  }
});

immutables.getBundle(options) ⇒ Object

Retrieves a bundle of an immutable.

Kind: instance method of Immutables
Returns: Object - An object containing information about an bundle.

Param Type Description
options Object An object containing options for the getBundle operation.
options.immutable.id string The ID of the immutable object.
options.nftfi.contract Object An object containing information about the contract used to facilitate the bundle.
options.nftfi.contract.name string Name of the contract used to facilitate the bundle: v1.immutable.bundle (deprecated), v1-1.immutable.bundle.

Example

// Get a bundle of a v1 immutable.
const bundle = await nftfi.immutables.getBundle({
  immutable: { id: '42' },
  nftfi: {
    contract: {
      name: 'v1.immutable.bundle'
    }
  }
});

Example

// Get a bundle of a v1.1 immutable.
const bundle = await nftfi.immutables.getBundle({
  immutable: { id: '42' },
  nftfi: {
    contract: {
      name: 'v1-1.immutable.bundle'
    }
  }
});

immutables.empty(options) ⇒ Object

Empties an immutable according to the specified contract.

Kind: instance method of Immutables
Returns: Object - An object containing the success status of the empty operation.

Param Type Description
options Object An object containing options for the empty operation.
options.immutable.id string The ID of the immutable object to be emptied.
options.nftfi.contract.name string Name of the contract used for emptying the immutable object: v1.immutable.bundle, v1-1.immutable.bundle.

Example

// NOTE: v1 immutables have been deprecated. If you empty it you will also burn the bundle after the NFTs have been transferred back into your account. You could optionally migrate your v1 immutable to a v1.1 immutable using `nftfi.immutables.migrate()`, then empty it.
// Approve the migration contract to handle your v1 immutable.
const approvalResult = await nftfi.erc721.setApprovalForAll({
  token: { address: nftfi.config.immutable.v1.address },
  nftfi: { contract: { name: 'v1.bundler.migrate' } }
});
// Empty the v1 immutable and transfer its contents to your account.
const result = await nftfi.immutables.empty({
  immutable: { id: '42' },
  nftfi: {
    contract: {
      name: 'v1.immutable.bundle'
    }
  }
});

Example

// Empty an v1.1 immutable and transfer its contents to your account.
const result = await nftfi.immutables.empty({
  immutable: { id: '42' },
  nftfi: {
    contract: {
      name: 'v1-1.immutable.bundle'
    }
  }
});

immutables.migrate(options) ⇒ Object

Migrates an immutable from one contract to another.

Kind: instance method of Immutables
Returns: Object - An object containing information about the migrated immutable object.

Param Type Description
options Object An object containing options for the migration operation.
options.immutable.id string The ID of the immutable object to be migrated.
options.from.nftfi.contract.name string Name of the source immutable contract.
options.to.nftfi.contract.name string Name of the destination immutable contract.

Example

// Approve the v1 immutable contract with the v1 migration contract.
const approvalResult = await nftfi.erc721.setApprovalForAll({
  token: {
    address: nftfi.config.immutable.v1.address
  },
  nftfi: { contract: { name: 'v1.bundler.migrate' } }
});
// Migrate an immutable from a v1 contract to a v1.1 contract.
const migrateResult = await nftfi.immutables.migrate({
  immutable: { id: '42' },
  from: {
    nftfi: {
      contract: {
        name: 'v1.immutable.bundle'
      }
    }
  },
  to: {
    nftfi: {
      contract: {
        name: 'v1-1.immutable.bundle'
      }
    }
  }
});

Listings

Class for working with listings.

Kind: global class

listings.get([options]) ⇒ Array.<object>

Gets all current listings.

Kind: instance method of Listings
Returns: Array.<object> - Array of listings hashmaps

Param Type Description
[options] object Hashmap of config options for this method
[options.filters.nftAddresses] Array.<string> NFT contract addresses (optional)
[options.pagination.page] number Pagination page (optional)
[options.pagination.limit] number Pagination limit (optional)

Example

// get listings without specifying pagination or filters
const listings = await nftfi.listings.get();

Example

// get the first `page` of listings, filtered by `nftAddresses`
const listings = await nftfi.listings.get({
  filters: {
    nftAddresses: ['0x11111111', '0x22222222']
  },
  pagination: {
    page: 1,
    limit: 20
  }
});

Loans

Class for working with loans.

Kind: global class

loans.get(options) ⇒ Array.<object>

Gets loans by specific filters.

Kind: instance method of Loans
Returns: Array.<object> - Array of listing objects

Param Type Description
options object Hashmap of config options for this method
options.filters object Hashmap of filter options for this method
options.filters.status string Loan status: active, defaulted, repaid or liquidated
[options.filters.borrower.address] string Address of the borrower
[options.filters.lender.address] string Address of the lender
[options.filters.nft.addresses] string Array of NFT addresses being used as collateral
[options.sort] object Hashmap of config sorting options for this method
[options.sort.by] string Field to sort by repayment, interest, apr, duration, dueDate, nftName
[options.sort.direction] string Sort direction: asc or desc
[options.pagination] object Hashmap of pagination options for this method
[options.pagination.page] number Page number
[options.pagination.limit] number Number of results per page

Example

// Get `active` loans where your account is the `lender`
const { data: { results } } = await nftfi.loans.get({
  filters: {
    lender: {
      address: nftfi.account.getAddress()
    },
    status: 'active'
  }
});

Example

// Get `defaulted` loans that your account is either `lender` or `borrower`
const { data: { results } } = await nftfi.loans.get({
  filters: {
    lender: {
      address: nftfi.account.getAddress()
    },
    borrower: {
      address: nftfi.account.getAddress()
    },
    status: 'defaulted'
  },
  pagination: {
   page: 1,
   limit: 10
  }
});

Example

// Get `repaid` loans that used one of the specified `nft addresses`
const { data: { results } } = await nftfi.loans.get({
  filters: {
    nft: {
      addresses: ['0x0', '0x1']
    },
    status: 'repaid'
  },
 sort: {
   by: 'repayment',
   direction: 'desc'
 },
});

loans.begin(options) ⇒ object

Begin a loan. Called by the borrower when accepting a lender's offer.

Kind: instance method of Loans
Returns: object - Response object

Param Type Description
options object Hashmap of config options for this method
options.type object Type of the offer v3.asset or v3.collection`
options.offer.nft.address string Address of the NFT being used as collateral
[options.offer.nft.id] string ID of NFT being used as collateral
[options.offer.nft.ids.from] number "from" ID of NFT id range of the offer (only when accepting a ranged offer)
[options.offer.nft.ids.to] number "to" ID of NFT id range of the offer (only when accepting a ranged offer)
options.offer.terms.loan.currency string Address of the ERC20 contract being used as principal/interest
options.offer.terms.loan.principal number Sum of money transferred from lender to borrower at the beginning of the loan
options.offer.terms.loan.repayment number Maximum amount of money that the borrower would be required to retrieve their collateral
options.offer.terms.loan.origination number Sum of money transferred to the lender at the beginning of the loan
options.offer.terms.loan.duration number Amount of time (measured in seconds) that may elapse before the lender can liquidate the loan
options.offer.terms.loan.expiry.seconds number Timestamp (in seconds) of when the signature expires
[options.borrower.address] string The address of the borrower (owner of nft)
options.offer.lender.address string Address of the lender that signed the offer
options.offer.lender.nonce string Nonce used by the lender when they signed the offer
[options.offer.nftfi.fee.bps] number Percent (measured in basis points) of the interest earned that will be taken as a fee by the contract admins when the loan is repaid
[options.offer.nftfi.contract.name] string Name of contract used to facilitate the loan: v2-3.loan.fixed, v2-3.loan.fixed.collection
options.offer.signature string ECDSA signature of the lender

Example

// Begin a loan on v3 offer
const result = await nftfi.loans.begin({
  type: 'v3.asset',
  nft: { address: '0x22222222', id: '2' },
  borrower: { address: '0x11111111' },
  lender: { address: '0x22222222' },
  terms: {
    principal: '1000000000000000000',
    repayment: '1100000000000000000',
    origination: '100000000000000000',
    interest: { prorated: true },
    duration: 31536000,
    currency: '0x00000000',
    expiry: { seconds: 1722260287 }
  },
  signature: "0x000000000"
});

loans.renegotiate(options) ⇒ object

Renegotiate a loan. Called by the borrower when accepting a lender's renegotiation offer.

Kind: instance method of Loans
Returns: object - Response object

Param Type Description
options object Hashmap of config options for this method
options.loan.id object ID of the loan being renegotiated
options.offer.terms.loan.duration string New loan duration in seconds relative to the original loan start time
options.offer.terms.loan.repayment string Maximum amount of money that the borrower would be required to retrieve their collateral
options.offer.terms.loan.interest.prorated string If the offer is pro-rata or not
options.offer.terms.loan.renegotiation.fee string Fee for renegotiating the loan
options.offer.lender.nonce string Nonce used by the lender when they signed the offer
options.offer.terms.loan.expiry.seconds string Timestamp (in seconds) of when the signature expires
options.offer.signature string ECDSA signature of the lender
options.offer.type string Type of the offer v3.asset or v3.collection`
options.offer.nftfi.contract.name string Name of contract used to facilitate the loan: v2-3.loan.fixed, v2-3.loan.fixed.collection

Example

// Renegotiate a v3 loan
const result = await nftfi.loans.renegotiate({
  loan: { id: '12' },
  offer: {
    type: 'v3.asset',
    lender: { nonce: '123456789' },
    terms: {
      loan: {
        duration: 1209600,
        repayment: '10004000000000000',
        renegotiation: { fee: '0' },
        expiry: { seconds: 3600 },
        interest: { prorated: false }
      }
    },
    signature: '0x000000000000000'
  }
});

loans.liquidate(options) ⇒ object

Liquidate defaulted loans in which your account is a participant. Can be called once a loan has finished its duration and the borrower still has not repaid.

Kind: instance method of Loans
Returns: object - Response object

Param Type Description
options object Hashmap of config options for this method
options.loan.id string The ID of the loan being liquidated
[options.nftfi.contract.name] string Name of contract used to facilitate the liquidation: v2-3.loan.fixed, v2-3.loan.fixed.collection

Example

// Liquidate a v3 loan
const result = await nftfi.loans.liquidate({
  loan: { id: 1 },
});

Example

// Liquidate a v2 loan
const result = await nftfi.loans.liquidate({
  loan: { id: 2 },
  nftfi: {
    contract: {
      name: 'v2-3.loan.fixed'
    }
  }
});

loans.repay(options) ⇒ object

Repay a loan. Can be called at any time after the loan has begun and before loan expiry.

Kind: instance method of Loans
Returns: object - Response object

Param Type Description
options object Hashmap of config options for this method
options.loan.id string The ID of the loan being repaid
[options.nftfi.contract.name] string Name of contract used to facilitate the repayment: v2-3.loan.fixed, v2-3.loan.fixed.collection

Example

// Repay a v3 loan
const result = await nftfi.loans.repay({
  loan: { id: 1 }
});

Example

// Repay a v2 loan
const result = await nftfi.loans.repay({
  loan: { id: 2 },
  nftfi: {
    contract: {
      name: 'v2-3.loan.fixed.collection'
    }
  }
});

loans.refinance(options) ⇒ object

Refinance a given loan.

Kind: instance method of Loans
Returns: object - Response object

Param Type Description
options Object The options object containing the loan and offer information.
options.loan Object The loan being refinanced.
options.offer Object The offer being used to refinance the loan.

Example

// Fetch active loans
const loans = await borrower.loans.get({
  filters: { status: 'active' }
});
const loan = loans.data.results[0];

// Get a v3 offer
const offers = await borrower.offers.get({
  filters: {
    nft: { address: loan.nft.address },
    loan: { currency: { address: { eq: loan.terms.loan.currency } } },
    type: 'v3.collection'
  }
});
const offer = offers[0];

// Mint Obligation Receipt
await nftfi.loans.mintObligationReceipt({ loan });

// Allow the contract to manage your ORs
await borrower.nft.approve({
  token: { address: nftfi.config.protocol.v3.obligationReceipt.v1.address },
  nftfi: { contract: { name: 'v3.refinance.v1' } }
});

// If the refinancing proceed is negative, also allow the contract to manage your ERC20 to pay the proceed
await borrower.erc20.approveMax({
  token: { address: borrower.config.erc20.weth.address },
  nftfi: { contract: { name: 'v3.refinance.v1' } }
});

// Refinance
const result = await borrower.loans.refinance({
  loan,
  offer: {
    ...offer,
    nft: { ...offer.nft, id: NFT_ID }
  }
});

loans.revokeOffer(options) ⇒ object

Revokes an active offer made by your account.

Kind: instance method of Loans
Returns: object - Response object

Param Type Description
options object Hashmap of config options for this method
options.offer.nonce object The nonce of the offer to be deleted
[options.offer.type] string Type of the offer v3.asset or v3.collection`
[options.nftfi.contract.name] string Name of contract which the offer was created for: v2-3.loan.fixed, v2-3.loan.fixed.collection

Example

// Revoke a v3 offer
const revoked = await nftfi.loans.revoke({
  offer: {
    nonce: '1',
    type: 'v3.asset'
  }
});

Example

// Revoke a v2 offer
const revoked = await nftfi.loans.revoke({
  offer: {
    nonce: '2'
  },
  nftfi: {
    contract: {
      name: 'v2-3.loan.fixed'
    }
  }
});

loans.mintObligationReceipt(options) ⇒ object

Mints an obligation receipt for a given loan.

Kind: instance method of Loans
Returns: object - Response object

Param Type Description
options Object The options object containing the loan details and contract information.
options.loan.nftfi.id number The ID of the loan.
[options.loan.nftfi.contract.name] string Name of contract used to facilitate the loan: v2-1.loan.fixed, v2-3.loan.fixed, v2.loan.fixed.collection, v2-3.loan.fixed.collection

Example

// Mint an Obligation Receipt for a v3 loan
const response = await nftfi.loans.mintObligationReceipt({
  loan: { id: '1' }
});

Example

// Mint an Obligation Receipt for a v2 loan
const response = await nftfi.loans.mintObligationReceipt({
  loan: {
    id: '2',
    nftfi: {
      contract: {
        name: 'v2-3.loan.fixed'
      }
    }
  },
});

loans.mintPromissoryNote(options) ⇒ object

Mints an promissory note for a given loan.

Kind: instance method of Loans
Returns: object - Response object

Param Type Description
options Object The options object containing the loan details and contract information.
options.loan.nftfi.id number The ID of the loan.

Example

// Mint an Promissory Note for a v3 loan
const response = await nftfi.loans.mintObligationReceipt({
  loan: { id: '1' }
});

Offers

Class for working with offers.

Kind: global class

offers.get([options]) ⇒ Array.<object>

When called without filtering by an NFT address, lender address or borrower address, defaults to filtering by your account address as lender. When provided with filters, gets all offers by specified filters.

Kind: instance method of Offers
Returns: Array.<object> - Array of offers

Param Type Default Description
[options] object Hashmap of config options for this method
[options.filters.nft.address] string NFT contract address to filter by (optional)
[options.filters.nft.id] string NFT id of the asset to filter by (optional)
[options.filters.lender.address.eq] string Lender wallet address to filter by (optional)
[options.filters.borrower.address.eq] string Borrower wallet address to filter by (optional)
[options.filters.lender.address.ne] string Lender wallet address to exclude (optional)
[options.filters.nftfi.contract.name] string Contract name to filter by (optional)
[options.filters.nftfi.contract.name.in] Array.<string> Contract names to filter by (optional)
[options.filters.loan.apr.lte] string Max apr to filter by (optional)
[options.filters.loan.effectiveApr.lte] string Max effective apr to filter by (optional)
[options.filters.loan.duration.eq] string Loan duration to filter by (optional)
[options.filters.loan.duration.nin] Array.<number> Loan durations to exclude (optional)
[options.filters.loan.currency.address.eq] string Loan currency to filter by (optional)
[options.filters.interest.prorated] boolean Filter for flexible or fixed offers (optional)
[options.filters.type] string Filter for offers of a certain type, v3.asset or v3.collection (optional)
[options.filters.type.in] Array.<string> Filter for offers that match one of many types (optional)
[options.pagination.page] number Pagination page (optional)
[options.pagination.limit] number Pagination limit (optional)
[options.pagination.sort] string Field to sort by (optional)
[options.pagination.direction] 'asc' | 'desc' Direction to sort by (optional)
[options.validation.check] boolean true Validate offers and append error info (optional)
[options.validation.refinance] boolean false Validate offers checking if they're valid in the context of refinancing, works when offers are filtered by lender address (optional)
[options.auth.token] 'required' | 'optional' | 'none' Specify if call to fetch offers should be authed, un-authed calls will always redact offers signature. By default, auth is optional. (optional)

Example

// Get all offers made by your account
const offers = await nftfi.offers.get();

Example

// Get the first page of offers made by your account, for a given NFT
const offers = await nftfi.offers.get({
  filters: {
    nft: {
      address: "0x00000000",
      id: "42"
    }
  },
  pagination:{
    page: 1,
    limit: 10
  }
});

Example

// Get all offers made by your account, for multiple NFTs in a collection
const offers = await nftfi.offers.get({
  filters: {
    nft: {
      address: "0x00000000"
    }
  }
});

Example

// Get the first page of collection offers made by a specific lender
const offers = await nftfi.offers.get({
  filters: {
    type: 'v3.collection'
    nft: {
      address: "0x00000000",
    },
    lender:{
      address: {
        eq: "0x12345567"
      }
    },
  },
  pagination:{
    page: 1,
    limit: 10
  }
});

Example

// Get all offers made by your account, and dont perform validation checks.
const offers = await nftfi.offers.get({
  validation: {
    check: false
  }
});

offers.count(options) ⇒ Array.<object>

Counts offers matching specified filters and groups by specified grouping value.

Kind: instance method of Offers
Returns: Array.<object> - Array of response object

Param Type Description
options object Hashmap of config options for this method
[options.filters.nft.address] string NFT contract address to filter by
[options.filters.nft.id] string NFT id of the asset to filter by (optional)
[options.filters.lender.address.eq] string Lender wallet address to filter by
[options.filters.lender.address.ne] string Lender wallet address to ignore
[options.group] string Field to group by

Example

// Count offers made by lenderAddress for a given NFT grouped by currency
const results = await nftfi.offers.count({
  filters: {
    nft: {
      address: "0x11111111",
      id: "42"
    },
    lender: {
      address: {
        eq: "0x123"
      }
    }
  },
  group: "termsCurrencyAddress"
});

offers.create(options) ⇒ object

Creates a new offer on a NFT or collection.

Kind: instance method of Offers
Returns: object - Response object

Param Type Description
options object Config options for this method
options.type object Type of the offer
options.nft object NFT to place an offer on
[options.nft.ids.from] number "from" Starting ID of the NFT range (inclusive, optional). Requires options.type to be "v3.collection"
[options.nft.ids.to] number "to" Ending ID of the NFT range (inclusive, optional). Requires options.type to be "v3.collection"
options.borrower object Owner of the NFT
options.terms object Terms of the offer

Example

// Create a Flexible offer on a NFT
const offer = await nftfi.offers.create({
  type: 'v3.asset',
  nft: { address: '0x22222222', id: '2' },
  borrower: { address: '0x11111111' },
  terms: {
    principal: '1000000000000000000',
    repayment: '1100000000000000000',
    origination: '100000000000000000',
    interest: { prorated: true },
    duration: 31536000,
    currency: '0x00000000',
    expiry: { seconds: 3600 } // 1 hour
  }
});

Example

// Create a Fixed offer on a Collection of NFTs
const offer = await nftfi.offers.create({
  type: 'v3.collection',
  nft: { address: '0x22222222' },
  terms: {
    principal: '1000000000000000000',
    repayment: '1100000000000000000',
    origination: '0',
    interest: { prorated: false },
    duration: 31536000,
    currency: '0x00000000',
    expiry: { seconds: 3600 } // 1 hour
  }
});

Example

// Create a flexible offer on a Collection range of NFTs
const offer = await nftfi.offers.create({
  type: 'v3.collection',
  nft: { address: '0x22222222', ids: { from: 1, to: 10 } },
  terms: {
    principal: '1000000000000000000',
    repayment: '1100000000000000000',
    origination: '0',
    interest: { prorated: true },
    duration: 31536000,
    currency: '0x00000000',
    expiry: { seconds: 3600 } // 1 hour
  }
});

offers.delete(options) ⇒ object

Deletes an active offer made by your account.

Kind: instance method of Offers
Returns: object - Response object

Param Type Description
options object Hashmap of config options for this method
options.offer.id object The Id of the offer to be deleted

Example

// Get first avilable offer made by your account
const offers = await nftfi.offers.get();
const offerId = offers[0]['id'];
// Delete the offer by Id
const deleted = await nftfi.offers.delete({
  offer: {
    id: offerId
  }
});

offers.revoke(options) ⇒ object

Revokes an active offer made by your account.

Kind: instance method of Offers
Returns: object - Response object

Param Type Description
options object Hashmap of config options for this method
options.offer.nonce object The nonce of the offer to be deleted
[options.offer.type] string Type of offer v3.asset, v3.collection
[options.offer.contract.name] string Name of contract which the offer was created for: v2-3.loan.fixed, v2-3.loan.fixed.collection

Example

// Revoke v3 offer
const nonce = offer.lender.nonce;
const type = offer.type;
const result = await lender.offers.revoke({
  offer: { nonce, type }
});

Example

// Revoking a v2 offer
const nonce = offer.lender.nonce;
const result = await lender.offers.revoke({
  offer: { nonce },
  nftfi: { contract: { name: offer.nftfi.contract.name } }
});

offers.validate(options) ⇒ object

Validates an offer based on specified checks.

Kind: instance method of Offers
Returns: object - Response object

Param Type Description
options object Parameters for the validation.
options.offer object The offer object to validate.
[options.checks] Array.<string> An array of checks to validate against. If not provided or empty, all supported checks are performed. (optional)

Example

// Validate an offer based on specified checks
const validation = await nftfi.offers.validate({
  offer,
  checks: [
    "signature",
    "terms.principal",
    "lender.nonce"
  ]
});

Utils

Class with utility methods.

Kind: global class

utils.calcEffectiveApr ⇒ number | null

Calculates the effective APR (annual percentage rate) of a loan given its parameters

Kind: instance property of Utils
Returns: number | null - The APR in %, calculated including the origination fee

Param Type Description
principal string | bigint The loan's principal amount in base units (e.g., "1000000000000000000" wei)
repayment string | bigint The total repayment amount to be paid by the borrower, in base units (e.g., "1100000000000000000" wei)
duration string | number The duration of the loan in days
originationFee string | bigint The origination fee of the loan in base units (e.g., "10000000000000000" wei). Defaults to 0 if undefined or null.

Example

// Calculate the effective APR
const principal = "1000000000000000000";
const repayment = "1100000000000000000";
const duration = 30;
const originationFee = "10000000000000000";
const apr = calculateEffectiveApr(principal, repayment, duration, originationFee);
console.log(apr); // Outputs the APR as a percentage

utils.getNonce() ⇒ string

Gets random nonce.

Kind: instance method of Utils
Returns: string - Nonce
Example

// Get a random nonce
const nonce = nftfi.utils.getNonce();

utils.getExpiry() ⇒ number

Gets an expiry timestamp.

Kind: instance method of Utils
Returns: number - Expiry
Example

// Get an expiry timestamp into the future
const expiry = nftfi.utils.getExpiry();

utils.formatEther(wei) ⇒ string

Formats an amount of wei into a decimal string representing the amount of ether.

Kind: instance method of Utils
Returns: string - Ether denomination of the amount

Param Type Description
wei number Wei denomination of the amount

Example

// Format wei into the amount of ether
const wei = 100;
const ether = nftfi.utils.formatEther(wei);

utils.formatUnits(wei, unit) ⇒ string

Formats an amount of wei into a decimal string representing the amount of unit.

Kind: instance method of Utils
Returns: string - String representation of value formatted with unit digits

Param Type Description
wei BigNumber Wei denomination of the amount
unit string Unit denomination to format value

Example

// Format usdc wei amount into the amount of unit
const wei = '1000000';
const usdc = nftfi.utils.formatUnits(wei, 'mwei'); // 1 usdc

Example

// Format wei into the amount of unit
const wei = '1000000000000000000';
const ether = nftfi.utils.formatUnits(wei, 'ether'); // 1 ether

utils.formatWei(value, unit) ⇒ BigNumber

Formats value into a BigNumber representing the value in wei from the unit specified.

Kind: instance method of Utils
Returns: BigNumber - BigNumber representation of value parsed with unit digits

Param Type Description
value number Value
unit string Unit denomination to format from

Example

// Format usdc amount into the amount of wei
const value = 1;
const usdcWei = nftfi.utils.formatWei(value, 'mwei'); // 1000000

Example

// Format ether amount into the amount of wei
const value = 100;
const wei = nftfi.utils.formatWei(value, 'ether'); // 100000000000000000000

utils.calcRepaymentAmount(principal, apr, duration) ⇒ number

Calculates the loan repayment amount given its other parameters.

Kind: instance method of Utils
Returns: number - The result maximum repayment amount, in base units (eg. 1250000000000000000 wei)

Param Type Description
principal number The loan's principal amount, in base units (eg. 1000000000000000000 wei)
apr number The APR (yearly percentage rate)
duration number The duration of the loan denominated in days

Example

// Calculate the loan repayment amount
const principal = 1000000000000000000;
const apr = 32;
const duration = 30;
const amount = nftfi.utils.calcRepaymentAmount(principal, apr, duration);

utils.calcApr(principal, repayment, duration) ⇒ number

Calculates the loan APR (yearly percentage rate) given its other parameters

Kind: instance method of Utils
Returns: number - The result APR

Param Type Description
principal number The loan's principal amount in base units (eg. 1000000000000000000 wei)
repayment number The maximum repayment amount to be paid by the borrower, in base units (eg. 1230000000000000000 wei)
duration number The duration of the loan denominated in days

Example

// Calculate the APR
const principal = 1000000000000000000;
const repayment = 1500000000000000000;
const duration = 30;
const apr = nftfi.utils.calcApr(principal, repayment, duration);

utils.getSupportedInterface(options) ⇒ Object

Checks if a token contract supports specific interfaces (ERC1155 and ERC721).

Kind: instance method of Utils
Returns: Object - - The combined results for the various interface checks.

Param Type Description
options Object The options for performing the contract interface checks.
options.token.address address The contract address to do interface checks against.

Erc1155

Class for working with ERC1155 multi token standard.

Kind: global class

erc1155.setApprovalForAll(options) ⇒ boolean

Sets the approval of a given NFTfi contract. The NFTfi contract is allowed to transfer all tokens of the sender on their behalf.

Kind: instance method of Erc1155
Returns: boolean - Boolean value indicating whether the operation succeeded

Param Type Description
options object Options
options.token.address string The ERC1155 token address
options.nftfi.contract.name string The name of the NFTfi contract (eg. v2-3.loan.fixed, v2-3.loan.fixed.collection)

Example

const address = await nftfi.nft.erc1155.setApprovalForAll({
  token: {
   address: '0x00000000'
  },
  nftfi: { contract: { name: 'v2-3.loan.fixed' } }
});

erc1155.isApprovedForAll(options) ⇒ boolean

Returns the approval of a given NFTfi contract. The NFTfi contract is allowed to transfer all tokens of the sender on their behalf.

Kind: instance method of Erc1155
Returns: boolean - Boolean value indicating whether permission has been granted or not

Param Type Description
options object Options
options.token.address string The ERC1155 token address
options.nftfi.contract.name string The name of the NFTfi contract (eg. v2-3.loan.fixed, v2-3.loan.fixed.collection)

Example

const address = await nftfi.nft.erc1155.isApprovalForAll({
  token: {
   address: '0x00000000'
  },
  nftfi: { contract: { name: 'v2-3.loan.fixed' } }
});

erc1155.balanceOf(options) ⇒ number

Returns the balance of a given ERC1155 token

Kind: instance method of Erc1155
Returns: number - The balance of tokens owned by account.

Param Type Description
options object Options
options.token.address string The ERC1155 token address
options.token.id string The ERC1155 token id
[options.account.address] string The address of the account (If not provided, the signer account address will be used.)

Example

const balance = await nftfi.nft.erc1155.balanceOf({
  token: {
   address: '0x00000000',
   id: '0'
  }
});

Example

const balance = await nftfi.nft.erc1155.balanceOf({
  token: {
   address: '0x00000000',
   id: '0'
  },
  account: {
   address: "0x111111111"
  }
});

Examples

To experiment with common NFTfi SDK use cases, run the following scripts from the root directory:

SDK using an EOA (Externally Owned Account)

node examples/get-listings.js
node examples/make-offer-on-listing.js
node examples/make-offer-on-nft.js
node examples/make-offer-on-collection.js
node examples/get-my-offers.js
node examples/get-offers-on-listing.js
node examples/get-offers-on-collection.js
node examples/delete-my-offers.js
node examples/revoke-and-delete-my-offers.js
node examples/begin-loan.js
node examples/get-my-active-loans.js
node examples/repay-loan.js
node examples/liquidate-my-defaulted-loans.js
node examples/bundles/basics.js
node examples/bundles/get-nfts-in-bundle-listing.js

SDK using a Multisig (Gnosis Safe)

node examples/multisig/gnosis-safe/make-offer-on-listing.js
node examples/multisig/gnosis-safe/make-offer-on-nft.js
node examples/multisig/gnosis-safe/get-offers.js
node examples/multisig/gnosis-safe/delete-offers.js
node examples/multisig/gnosis-safe/get-active-loans.js
node examples/multisig/gnosis-safe/liquidate-defaulted-loans.js

About

JavaScript SDK for interacting with the NFTfi Protocol

www.nftfi.com

Resources

Readme
Activity
Custom properties

Stars

14 stars

Watchers

12 watching

Forks

15 forks
Report repository

Releases 17

v0.6.4 Latest
Dec 23, 2024
+ 16 releases

Contributors 3

  •  
  •  
  •  

Languages