> For the complete documentation index, see [llms.txt](https://fija.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fija.gitbook.io/docs/overview/the-partner-api/interface-documentation.md). # Interface Documentation ### 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 ```solidity function asset() public view returns (address) ``` Returns the address of the underlying input token to invest in the strategy. #### totalAssets ```solidity function totalAssets() public view returns (uint256) ``` Returns the total amount of underlying input tokens held by the vault. #### totalSupply ```solidity **function** totalSupply() **public** view returns (uint256) ``` Returns the total fija token supply. #### balanceOf ```solidity function balanceOf(address owner) public view returns (uint256) ``` Returns the amount of fija tokens the owner currently has. #### convertToShares, convertToTokens , previewDeposit ```solidity 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** ```solidity 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 \ ```solidity 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 ```solidity DEPOSIT: 0 WITHDRAW: 1 REDEEM: 2 ``` #### d**eposit** ```solidity 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. \ #### redeem ```solidity 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. \ #### withdraw ```solidity 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. \ #### addAddressToWhitelist ```solidity 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. \ #### removeAddressFromWhitelist ```solidity 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. \ #### isWhitelisted ```solidity function isWhitelisted(address addr) public view returns (bool) ``` Returns true if address is whitelisted. False otherwise. #### reseller ```solidity function reseller() public view returns (address) ``` Returns the address of the reseller of this Vault. ### - Events #### Deposit event ```solidity 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 ```solidity 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 ```solidity event WhitelistedAddressAdded( address addr ) ``` #### WhitelistedAddressRemoved event ```solidity 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: ```html ``` #### 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 }` as a header #### Retrieving vault data ```html GET /v1/vaults/ ``` Returns all vaults assigned to a certain reseller. * Response format ```json { "success": true, "data": [ { "id": uuid, "name": string, "description": string, "Strategy": string, "fijaToken": string }, { "id": uuid, .... } ] } ``` ```html GET /v1/vaults/{vaultID} ``` Returns detailed data about a specific vault. Fails if the {vault ID} is not assigned to the reseller. * Response format ```json { "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 } ] } ``` \ #### Retrieving vault performance ```html 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 ```json { "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 } ] } ``` \ ```html GET /v1/vaults/{vaultID}/performance/{timestamp} ``` Returns vault performance at a certain timestamp. Timestamp is in ISO-8601 format. * Response format ```json { "success": true, "data": [ "time": string, "supply": string, "assets": string, "tokenPrice": string, "apy": string ] } ``` \ #### Retrieving vault performance range ```html 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 ```json { "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 ] } ``` \ #### Retrieving strategy data \ ```html GET /v1/strategies/ ``` Returns all strategies assigned to a certain reseller. * Response format ```json { "success": true, "data": [ { "id": uuid, "name": string, "strategyToken": string }, { "id": uuid, .... } ] } ``` ```html GET /v1/strategies/{strategyId} ``` Returns detailed data about a specific strategy. Fails if the {strategy ID} is not assigned to the reseller. * Response format ```json { "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 \ ```html 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 ```json { "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 ] } ] } ``` ```html GET /v1/strategies/{strategyID}/performance/{timestamp} ``` Returns strategy performance at a certain timestamp. Timestamp is in ISO-8601 format. * Response format ```json { "success": true, "data": [ { "time": string, "supply": string, "assets": string, "tokenPrice": string, "apy": string } ] } ``` #### Retrieving strategy performance range \ ```html 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 * ```json { "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 ], .... ] } ```
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://fija.gitbook.io/docs/overview/the-partner-api/interface-documentation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.