Interface Documentation

Technical Description of our API.

Pre-requisites for interacting with the fija system

• fija and reseller agree on the specific vaults and strategies that will be offered to the reseller’s customers.

• fija deploys the agreed vaults on the respective blockchains.

• fija initialises the reseller in the back-end API.

• fija shares the reseller’s API key via a secured channel.

Retrieving the vault and strategy data from the API

• Reseller queries the /vault endpoint in the fija API to retrieve the vault and strategy descriptions, legal documentation, current performance and other relevant meta data.

• Reseller queries the /vault endpoint to retrieve the chain ID and the vault addresses of the smart contracts.

• The /vault endpoint will also signal if the vault is a single transaction vault, or a two-transaction vault. two-transaction vaults will require an additional execution fee — see deposit section below.

Whitelisting users to the vault

• The reseller interacts directly with the vault to whitelist wallets, using the addAddressToWhitelist() functions available in the smart contract.

• Only whitelisted wallets are allowed to deposit or withdraw funds from the vault.

Depositing funds to the vault

• The user’s wallet interacts directly with the smart contract to deposit funds to the vault.

• The convertToTokens() function is used to determine the amount of fija tokens that will be received in return for a certain amount of assets.

• The deposit() function is used to deposit assets to the vault, and the corresponding amount of fija tokens will be returned to the receivers wallet.

• The deposit function is a payable method, and takes 2 parameters as an input. The table below explains how the parameters are used for specific circumstances.

Deposit token	2Txn vault (***)	Value of txn	Asset parameter	Receiver parameter
ERC20	N	0	Amount of ERC20 to be invested in fija vault	wallet receiving fija tokens (**)
ERC20	Y	Execution fee (*)	Amount of ERC20 to be invested in fija vault	wallet receiving fija tokens (**)
Native ETH	N	Amount of ETH to be invested in vault	Amount of wei to be invested in fija vault (should equal value of txn)	wallet receiving fija tokens (**)
Native ETH	Y	Amount of ETH to be invested in vault + Execution fee (*)	Amount of wei to be invested in fija vault	wallet receiving fija tokens (**)

Notes:

(*) The execution fee to calculated as follows

Output of getExecutionFee() method * gas price

The execution fee will be taken from the calling wallet. It is suggested to take a small margin on top of the calculated value (5-10%) — but remember that any excess will not be returned.

(**) The receiving wallet should be whitelisted

(***) the /vaults/{id} endpoint is specifying whether a vault is a 2 transaction vault or not

Monitoring vault and strategy performance

• The value of the tokens can be queried directly from the vault contract using the convertToAsset() function available in the vault

• For historical data and reporting purposes the fija API offers the vaults/{vaultID}/performance/ endpoint listing the weekly, monthly and lifetime APY of the respective vaults

Withdrawing funds from the vault

• The user’s wallet interacts directly with the smart contract to withdraw funds from the vault

• The convertToAssets() function is used to determine the amount of assets that will be received in return for a certain amount of fija tokens

• The redeem() function is used to return fija tokens to the vault, and the corresponding amount of assets will be returned to the user’s wallet.

• The redeem() function is a payable method, and for 2 transaction vaults an execution fee needs to be delivered for the method to succeed.

  • The /vaults/{id} endpoint is specifying whether a vault is a 2 transaction vault or not

  • The execution fee to calculated as follows

    Output of getExecutionFee() method * gas price

Smart Contract - Vault

The fija Vault contract offers the main interface to interact with the fija Finance DeFi system.

A fija Vault has an underlying asset that can be deposited in the vault. When assets are deposited strategy tokens will be returned in return. Only whitelisted addresses are able to deposit funds or receive fija tokens.

Each fija Vault implements exactly one investment strategy, and any assets deposited to the vault will be invested according to that strategy.

Each vault is assigned to a reseller address. Resellers are able to whitelist addresses of the vault.

The fija vault is an implementation of a yield bearing vault as defined in ERC-4626

- Methods

asset

function asset() public view returns (address)

Returns the address of the underlying input token to invest in the strategy.

totalAssets

function totalAssets() public view returns (uint256)

Returns the total amount of underlying input tokens held by the vault.

totalSupply

**function** totalSupply() **public** view returns (uint256)

Returns the total fija token supply.

balanceOf

function balanceOf(address owner) public view returns (uint256)

Returns the amount of fija tokens the owner currently has.

convertToShares, convertToTokens , previewDeposit

function convertToShares(uint256 assets) public view returns (uint256 tokens)
function convertToTokens(uint256 assets) public view returns (uint256 tokens)
function previewDeposit(uint256 assets) public view returns (uint256)

Returns the amount of fija tokens that would be exchanged by the vault for the amount of assets provided.

convertToAssets, previewRedeem, previewWithdraw

function convertToAssets(uint256 tokens) public view returns (uint256 assets)
function previewRedeem(uint256 tokens) public view returns (uint256)
function previewWithdraw(uint256 assets) public view returns (uint256 tokens)

The first 2 methods return the amount of assets that would be exchanged by the vault for the amount of fija tokens provided. The last method returns the amount of tokens that would be burned to receive the expected amount of assets.

getExecutionGasLimit

<aside> 💡 This method is only available for 2 transaction vaults.

</aside>

		function getExecutionGasLimit(TxType txType) public returns (uint256)

This functions return the amount of gas units needed to execute the 2nd transaction for a specific activity.

The parameter txType specifies the action to be taken

	DEPOSIT: 0
  WITHDRAW: 1
  REDEEM: 2

deposit

function deposit(uint256 assets, address receiver) public payable returns (uint256 tokens)

This function deposits assets of underlying tokens into the vault and grants ownership of fija tokens to receiver.

<aside> 👉 msgSender and receiver should be whitelisted, otherwise the call will fail. assets are taken from the msgSender wallet.

</aside>

redeem

function redeem(uint256 tokens, address receiver, address owner) public payable returns (uint256 assets)

This function redeems a specific number of fija tokens from owner and send assets of underlying token from the vault to receiver.

<aside> 👉 Owner, receiver as well as msgSender should be whitelisted, otherwise the call will fail. msgSender can either be the owner, receiver or the reseller, if not the call will fail.

</aside>

withdraw

function withdraw(uint256 assets, address receiver, address owner) public payable returns (uint256 assets)

This function burns fija tokens from oner and send exactly assets token from the vault to receiver.

<aside> 👉 Owner, receiver as well as msgSender should be whitelisted, otherwise the call will fail. msgSender can either be the owner, receiver or the reseller, if not the call will fail.

</aside>

addAddressToWhitelist

function addAddressToWhitelist(address addr) public returns (bool success)

Adds the specified address to the whitelist. Returns true if address was added to the list, false if the address was already in the whitelist.

<aside> 👉 Only reseller is able to add addresses to the whitelist. Call will fail if msgSender is not reseller.

</aside>

removeAddressFromWhitelist

function removeAddressFromWhitelist(address addr) public returns (bool success)

Removes the specified address from the whitelist. Returns true if address is removed, false if it wasn’t in the whitelist in the first place.

<aside> 👉 Only reseller is able to remove addresses from the whitelist. Call will fail if msgSender is not reseller.

</aside>

isWhitelisted

function isWhitelisted(address addr) public view returns (bool)

Returns true if address is whitelisted. False otherwise.

reseller

function reseller() public view returns (address)

Returns the address of the reseller of this Vault.

- Events

Deposit event

event Deposit(
address indexed sender,
address indexed owner,
uint256 assets,
uint256 tokens
)

Where sender is the user who exchanged assets for strategy tokens, and transferred those shares to owner.

Withdraw event

event Withdraw(
address indexed sender,
address indexed receiver,
address indexed owner,
uint256 assets,
uint256 tokens
)

Where sender is the user who triggered the withdrawal and exchanged strategy tokens, owned by owner, for assets. Receiver is the user who received the withdrawn assets.

WhitelistedAddressAdded event

event WhitelistedAddressAdded(
address addr
)

WhitelistedAddressRemoved event

event WhitelistedAddressRemoved(
address addr
)

Back-end API v1

The fija Back-end API is used by resellers to retrieve metadata for the vaults offered by fija.

The /vault endpoint will list the fija vaults available to the reseller. It allows the reseller to retrieve details about the vault including name, description, contract address on chain as well as 1-week, 1-month and lifetime performance

A /vault/performance endpoint is offered to retrieve more detailed performance data, e.g. value of the vault at a specific date.

Authentication for the API is achieved through a pre-shared API key unique to each reseller.

Base URL

The fija production API is available from:

<https://api.fija.finance/>

Authorization

• All API calls are done using a API key shared in advance with the reseller

• API keys can be included as a GET parameter, or alternatively as a header

  • the apiKey parameter is used for GET requests

  • for POST requests use {"authorization": Bearer <API_KEY>} as a header

Retrieving vault data

GET /v1/vaults/

Returns all vaults assigned to a certain reseller.

• Response format

  {
  	"success": true,
  	"data": [
  		{
  			"id": uuid,
  			"name": string,
  			"description": string,
  			"Strategy": string,
  			"fijaToken": string
  		},
  		{
  			"id": uuid,
  			....
  		}
  ]
  }

GET /v1/vaults/{vaultID}

Returns detailed data about a specific vault. Fails if the {vault ID} is not assigned to the reseller.

• Response format

  
  {
  	"success": true,
  	"data": [
  		{
  			"id": uuid,
  			"name": string,
  			"strategy": string,
  			"strategyDescriptionShort": string,
  			"strategyDescriptionLong": string,
  			"emergencyMode": boolean,
  			"maxVaultSize": string,
  			"maxTicketSize": string,
  
  			"network": string,
  			"chainID": number, 
  			"blockchainExplorerURL": string,
  			"vaultAddress": string,
  			"is2TxnVault": boolean,
  			"strategyAddress": string,
  			"createdAt": date,
  
  			"bibURL": string,
  			"consumerInformationURL": string,
  			"riskFactorsURL": string,
  			"tokenTermsURL": string,
  			"auditReportURL": string,
  			"safetyScoreURL":string,
  			"safetyScore": number,
  			
  			"strategist": string,
  			"strategistDescription": string,
  			"strategistURL": string,
  		
  			"protocols": string,
  			"protocolsDescription":: string,
  			"tokens": string,
  			"tokenDistribution": string,
  			"tokensDescription": string,
  			"fija": string,
  			"fijaDescription": string,
  	
  
  			"depositAsset": string, 
  			"depositAssetAddress": string,
  			"depositAddressDecimals": number,
  			"fijaToken": string,
  			"fijaTokenAddress": string,
  			"fijaTokenDecimals": number,
  
  			"assets": string,
  			"supply": string,
  			"tokenPrice": string,
  			"apy": string,
  			"apyNow": string,
  			"apy7days": string,
  			"apy30days": string,
  			"apy90days": string,
  			"apyLifeTime": string
  		}
  ]
  }

<aside> 💡

TokenPrice is processed with a 2-3 min delay compared to the on-chain contracts. APY data is delivered with a 30 min delay compared to on-chain contract data.

</aside>

Retrieving vault performance

GET /v1/vaults/{vaultID}/performance/

Returns current performance of the Vault, including current vault values, 1 wk values, 1 month values and lifetime values.

• Response format

  {
  	"success": true,
  	"data": [
  		{
  			"performanceNow": [
  				"supply": string,
  				"assets": string,
  				"tokenPrice": string, 
  				"apy": string
  			],
  			"performance7days":[
  				"supply": string,
  				"assets": string,
  				"tokenPrice": string,
  				"apy": string
  			],
  			"performance30days": [
  				"supply": string,
  				"assets": string,
  				"tokenPrice": string,
  				"apy": string
  			],
  			"performance90days": [
  				"supply": string,
  				"assets": string,
  				"tokenPrice": string,
  				"apy": string
  			],
  			"performanceLifeTime": [
  				"supply": string,
  				"assets": string,
  				"tokenPrice": string,
  				"apy": string
  			]
  			
  			"performance7daysAgo":[
  			"performance30daysAgo":[
  			"performance90daysAgo":[
  			
  			"apy7days": string,
  			"apy30days": string,
  			"apy90days": string,
  			"apyLifeTime": string
  		}
  ]
  }

<aside> 💡

Current TokenPrice is processed with a 2-3 min delay compared to the on-chain contracts. APY data is delivered with a 30 min delay compared to on-chain contract data.

</aside>

GET /v1/vaults/{vaultID}/performance/{timestamp}

Returns vault performance at a certain timestamp. Timestamp is in ISO-8601 format.

• Response format

  {
  	"success": true,
  	"data": [
  			"time": string,
  			"supply": string,
  			"assets": string,
  			"tokenPrice": string,
  			"apy": string
  	]
  }

<aside> 💡

Current TokenPrice is processed with a 2-3 min delay compared to the on-chain contracts. APY data is delivered with a 30 min delay compared to on-chain contract data.

</aside>

Retrieving vault performance range

GET /v1/vaults/{vaultID}/performanceRange?from={timestamp}&to={timestamp}

Returns vault performance for a range specified in the request.

Granularity is defined automatic:

• Date range <1 day = 5 minute interval date

• Date range 1 - 90 days = hourly data

• Date range >90 days = daily data (00:00 UTC)

Timestamps is in ISO-8601 format.

• Response format

  {
  	"success": true,
  	"data": [
  			"time": string,
  			"supply": string,
  			"assets": string,
  			"tokenPrice": string,
  			"apy": string
  	],
  	"data": [
  			"time": string,
  			"supply": string,
  			"assets": string,
  			"tokenPrice": string,
  			"apy": string
  	],
  	"data": [
  			"time": string,
  			"supply": string,
  			"assets": string,
  			"tokenPrice": string,
  			"apy": string
  	],
  	...   
  	"apy7days": string,
  	"apy30days": string,
  	"apy90days": string,
  	"apyLifeTime": string
  ]
  }

<aside> 💡

Current TokenPrice is processed with a 2-3 min delay compared to the on-chain contracts. APY data is delivered with a 30 min delay compared to on-chain contract data.

</aside>

Retrieving strategy data

<aside> 💡 Strategy data is only accessible to strategists.

</aside>

GET /v1/strategies/

Returns all strategies assigned to a certain reseller.

• Response format

  {
  	"success": true,
  	"data": [
  		{
  			"id": uuid,
  			"name": string,
  			"strategyToken": string 
  		},
  		{
  			"id": uuid,
  			....
  		}
  ]
  }

GET /v1/strategies/{strategyId}

Returns detailed data about a specific strategy. Fails if the {strategy ID} is not assigned to the reseller.

• Response format

  {
  	"success": true,
  	"data": [
  		{
  			"id": uuid,
  			"name": string,
  			"strategyDescriptionShort": string,
  			"strategyDescriptionLong": string,
  			"emergencyMode": boolean,
  			"maxVaultSize": string,
  			"maxTicketSize": string,
  
  			"network": string, 
  			"chainId": number,
  			"blockchainExplorerURL": string,
  			"strategyAddress": string,
  			"is2TxnStrategy": boolean,
  			"createdAt": date,
  
  			"auditReportURL": string,
  			"safetyScoreURL": string,
  			"safetyScore": number,
  			
  			"strategist": string,
  			"strategistDescription": string,
  			"strategistURL": string,
  			
  			"protocols": string,
  			"protocolsDescription":: string,
  			"tokens": string,
  			"tokenDistribution": string,
  			"tokensDescription": string,
  			"fija": string,
  			"fijaDescription": string,
  	
  
  			"depositAsset": string, 
  			"depositAssetAddress": string,
  			"depositAddressDecimals": number,
  			"strategyToken": string,
  			"strategyTokenAddress": string,
  			"strategyTokenDecimals": number,
  
  			"assets": string,
  			"supply": string,
  			"tokenPrice": string,
  			"apy": string,
  			"apyNow": string,
  			"apy7days": string,
  			"apy30days": string,
  			"apy90days": string,
  			"apyLifeTime": string
  		}
  ]
  }

Retrieving strategy performance

<aside> 💡 Strategy data is only accessible to strategists.

</aside>

GET /v1/strategies/{strategyID}/performance/

Returns current performance of the Strategy, including current strategy values, 1 wk values, 1 month values and lifetime values.

• Response format

  {
  	"success": true,
  	"data": [
  		{
  			"performanceNow": [
  				"supply": string,
  				"assets": string,
  				"tokenPrice": string, 
  				"apy": string
  			],
  			"performance7days":[
  				"supply": string,
  				"assets": string,
  				"tokenPrice": string,
  				"apy": string
  			],
  			"performance30days": [
  				"supply": string,
  				"assets": string,
  				"tokenPrice": string,
  				"apy": string
  			],
  			"performance90days": [
  				"supply": string,
  				"assets": string,
  				"tokenPrice": string,
  				"apy": string
  			],
  			"performanceLifeTime": [
  				"supply": string,
  				"assets": string,
  				"tokenPrice": string,
  				"apy": string
  			]
  		}
  ]
  }

GET /v1/strategies/{strategyID}/performance/{timestamp}

Returns strategy performance at a certain timestamp. Timestamp is in ISO-8601 format.

• Response format

  {
  	"success": true,
  	"data": [
  		{
  			"time": string,
  			"supply": string,
  			"assets": string,
  			"tokenPrice": string,
  			"apy": string
  		}
  ]
  }

Retrieving strategy performance range

<aside> 💡 Strategy data is only accessible to strategists.

</aside>

GET /v1/strategies/{vaultID}/performanceRange?from={timestamp}&to={timestamp}

Returns strategy performance for a range specified in the request.

Granularity is defined automatic:

• Date range <1 day = 5 minute interval date

• Date range 1 - 90 days = hourly data

• Date range >90 days = daily data (00:00 UTC)

Timestamps is in ISO-8601 format.

• Response format

• {
  	"success": true,
  	"data": [
  			"time": string,
  			"supply": string,
  			"assets": string,
  			"tokenPrice": string,
  			"apy": string
  	],
  	"data": [
  			"time": string,
  			"supply": string,
  			"assets": string,
  			"tokenPrice": string,
  			"apy": string
  	],
  	"data": [
  			"time": string,
  			"supply": string,
  			"assets": string,
  			"tokenPrice": string,
  			"apy": string
  	],
  	....
  ]
  }