Integrators

This guide describes how to integrate Credit Vaults into Web3 applications using both the Pareto REST API and smart contracts. It is intended for technical audiences familiar with Web3 and frontend frameworks.

Smart contract instantiation

To interact with on-chain vaults, tokens, and queue contracts, a Web3 contract instance must be created using the ABI and contract address:

const contract = new web3.eth.Contract(abi, address);

This pattern is required for calling methods such as depositAA, requestWithdraw, approve. Refer to the Web3.js documentation for full syntax details.

API access

All API routes below belong to the public Pareto API at https://api.pareto.credit. Refer to the API chapter for a complete overview.

1. Required vault data

These steps outline the minimum data required to render a vault and enable interactions.

1

Load Vault Entity

Use either:

• GET /v1/vaults/{_id} — by ID

• GET /v1/vaults?address=0x... — by address

Only vaults with visibility: PUBLIC should be displayed to users.

2

Retrieve Signatures

Each vault contains a signatures array of the form:

interface VaultSignature {
  _id: string;
  entity: "ALL" | "LENDER" | "MANAGER";
}

Filter all entries where entity === 'LENDER'and use the _id values to load them. This returns the full signature definitions required to enable future user interactions.

GET /v1/signatures?_id=signatureId1,signatureId2

3

Retrieve underlying Token

Retrieve token information with:

GET /v1/tokens/{vault.tokenId}

4

Fetch latest Vault Block

Fetch up-to-date vault metrics. This includes share price, APRs, TVL, and queue configuration.

GET /v1/vault-latest-block?vaultId={vault._id}

2. Required wallet access data

Defines the required checks and data fetches needed immediately after wallet connection to verify access and authorization for vault operations.

1

Check wallet access

To verify if a wallet is allowed to interact with the vault, instantiate the contract using the cdoEpoch ABI and address retrieved from the vault JSON:

const cdoEpochContract = new web3.eth.Contract(
  vault.cdoEpoch.abi,
  vault.cdoEpoch.address
);
const isAllowed = await cdoEpochContract.methods
  .isWalletAllowed(walletAddress)
  .call();

If isAllowed is false, initiate a KYC flow using Keyring Connect SDK. Only after KYC is completed, it's possible to proceed with next steps.

2

Signature Validation

Check if the required signatures have been signed:

GET /v1/signatures/{signatureId}/check?walletAddress=0x...123

otherwise

const hash = await web3.eth.personal.sign(
  atob(walletMessage),
  walletAddress,
  ""
);

Submit the signed hash:

POST /v1/signatures/{signatureId}/sign

3

Retrieve Wallet Position

Retrieve the wallet position to track users' deposits, claims, and balances.

GET /v1/vaults/{vaultId}/position?walletAddress={walletAddress}

3. Deposit flow

Outlines the required contract state and transactions to successfully execute a deposit into a vault.

1

Verify allowance and balance

Instantiate the token contract using the vault token ABI and address:

const tokenContract = new web3.eth.Contract(token.abi, token.address);
const allowance = await tokenContract.methods
  .allowance(walletAddress, spenderAddress)
  .call({ from: walletAddress });
const balance = await tokenContract.methods
  .balanceOf(walletAddress)
  .call({ from: walletAddress });

Spender can be found in:

• vault.cdoEpoch.address if NETTING

• vault.depositQueue.address if RUNNING

2

Approve token spending

Make sure the amount respects the token's decimals (6 for USDC, USDT, 18 for the majority of ERC-20 tokens).

await tokenContract.methods
  .approve(spenderAddress, amount)
  .send({ from: walletAddress });

3

Submit Deposit Transaction

// during NETTING period
await cdoEpochContract.methods.depositAA(amount).send({ from: walletAddress });
// during cycle RUNNING
await depositQueueContract.methods
  .requestDeposit(amount)
  .send({ from: walletAddress });

4. Withdraw flow

Describes how to prepare, calculate, and submit a withdrawal request from a vault, depending on its current status and configuration.

1

Fetch user balance and max withdrawable amount

const vaultTokenContract = new web3.eth.Contract(
  vaultToken.abi,
  vaultToken.address
);
const balance = await vaultTokenContract.methods
  .balanceOf(walletAddress)
  .call({ from: walletAddress });
const maxWithdrawable = await cdoEpochContract.methods
  .maxWithdrawable(walletAddress, vault.address)
  .call({ from: walletAddress });

2

Check allowance

The allowance must be verified only when the vault is in RUNNING state and uses the withdrawQueue. In this case, the withdrawQueue contract address should be used as spender.

const spender = vault.cdoEpoch.withdrawQueue.address;
const allowance = await tokenContract.methods
  .allowance(walletAddress, spender)
  .call({ from: walletAddress });

3

Compute the LP tokens required

const percentage = 1000000 / maxWithdrawable;
const lpAmount = LPDeposited * percentage;

4

Submit withdrawal request

Track requests in the block.requests array

// during NETTING period
await vaultContract.methods
  .requestWithdraw(lpAmount, vault.address)
  .send({ from: walletAddress });
// during cycle RUNNING
await withdrawQueueContract.methods
  .requestWithdraw(lpAmount)
  .send({ from: walletAddress });

Managing requests

All deposit requests (during the RUNNING state), and all withdrawals (instant or standard) are tracked under the requests array of the vaultBlock object. Each entry in this array represents a user-initiated interaction awaiting processing.

Request schema

interface VaultBlockRequest {
  type: "DEPOSIT" | "WITHDRAW" | "REDEEM";
  amount: iBigInt;
  block: Block;
  isInstant?: boolean;
  requestedOn: string;
  walletId: string;
  walletAddress: string;
  status:
    | "PENDING"
    | "PROCESSED"
    | "CLAIMABLE"
    | "INSTANT_CLAIMABLE"
    | "CLAIMED";
  epochNumber?: number;
}

where

• type: Indicates if it's a DEPOSIT, WITHDRAW, or REDEEM.

• status: Tracks the lifecycle of the request (e.g., PENDING, CLAIMABLE, etc.).

• isInstant: Only present for withdrawals that qualify as "instant".

• block: Indicates the vault block in which the request was recorded.

Requests are retrieved from the latest vault block:

GET /v1/vault-latest-block?vaultId={vaultId}

Deposit requests

• Cancel the request if status === 'PENDING'

await cdoEpochContract.methods
  .deleteRequest(request.epochNumber)
  .send({ from: walletAddress });

• Claim the request if status === 'CLAIMED'

await cdoEpochContract.methods
  .claimDepositRequest(request.epochNumber)
  .send({ from: walletAddress });

Redeem requests

Handled via the main vault contract vault.cdoEpoch

• If status === 'CLAIMED':

await cdoEpochContract.methods
  .claimWithdrawRequest(request.epochNumber)
  .send({ from: walletAddress });

• If request.isInstant === true:

await cdoEpochContract.methods
  .claimInstantWithdrawRequest(request.epochNumber)
  .send({ from: walletAddress });

Withdraw requests

Handled via the queue contract vault.cdoEpoch.withdrawQueue

• If status === 'CLAIMED'

await withdrawQueueContract.methods
  .claimWithdrawRequest(request.epochNumber)
  .send({ from: walletAddress });