nCREDIT Integration

nCREDIT is the Plume Credit Vault. This page is organized around the recommended Actions API path first, then the direct contract path for advanced EVM integrations.

Outline

• Quick reference
• Supported assets
• EVM Integration:
  • Deposit
  • Deposit on behalf
  • Redeem
  • Direct onchain
• Errors and edge cases
• Implementation notes

Quick reference

Supported assets

EVM

EVM Integration

Deposit

Use the EVM Actions API when your app wants Plume Vaults to handle quote construction, vault selection, Predicate compliance checks, calldata encoding, and transaction simulation for nCREDIT. The API returns transactions that your app signs and sends with the user's EVM wallet.

The base URL is:

https://api.nest.credit/v1/actions

All amounts are raw base-unit integer strings. Do not send decimal UI amounts.

Always set complianceVersion: "v2" explicitly on mint quotes and builds. Defaults vary by vault and chain. A route without an enabled V2 deployment cannot use the V2 examples below; never retry a deposit-on-behalf request with V1.

For aggregators such as LI.FI, use the shared Deposit on behalf section for caller, original depositor, receiver, and proof lifecycle details.

Mint quote

Use the quote route before building transactions. This returns the expected raw share amount, decimals, fee fields, rate fields, and a preview of the transaction steps.

curl -X POST https://api.nest.credit/v1/actions/vaults/nest-credit-vault/mint/quote \
  -H 'content-type: application/json' \
  -d '{
  "depositAsset": "0x222365ef19f7947e5484218551b56bb3965aa7af",
  "depositAmount": "1000000",
  "chainId": 98866,
  "complianceVersion": "v2"
}'

Example response shape:

{
  "data": {
    "complianceVersion": "v2",
    "slug": "nest-credit-vault",
    "shareTokenAddress": "0xa5f78b2a0ab85429d2dfbf8b60abc70f4cec066c",
    "depositAsset": "0x222365ef19f7947e5484218551b56bb3965aa7af",
    "depositAmount": "1000000",
    "depositDecimals": 6,
    "shareAmount": "...",
    "shareDecimals": 6,
    "rate": "...",
    "rateDecimals": 6,
    "feeAmount": "0",
    "fees": {
      "ratePpm": 0,
      "flatAmount": "0",
      "maxRatePpm": 0,
      "maxFlatAmount": "0"
    },
    "steps": [
      { "label": "approve", "description": "Approve ComplianceProxy to spend the deposit asset" },
      { "label": "deposit", "description": "Deposit through ComplianceProxy" }
    ]
  }
}

steps is a preview. The actual build-tx response may omit approve if the wallet already has sufficient allowance.

Build mint transactions

Use build-tx when the user is ready to deposit. The sender is the account that calls ComplianceProxy and supplies the assets; recipient receives the minted nCREDIT shares. This example uses the same wallet for both. For a proxy depositing for a user, explicitly provide that proxy as sender and the original user as onBehalf.

curl -X POST https://api.nest.credit/v1/actions/vaults/nest-credit-vault/mint/build-tx \
  -H 'content-type: application/json' \
  -d '{
  "depositAsset": "0x222365ef19f7947e5484218551b56bb3965aa7af",
  "depositAmount": "1000000",
  "chainId": 98866,
  "complianceVersion": "v2",
  "sender": "0x00000000000000000000000000000000000000ab",
  "recipient": "0x00000000000000000000000000000000000000ab",
  "skipSimulation": false
}'

Require data.complianceVersion === "v2" and submit the returned transactions in order from sender on the requested chain. The builder obtains the attestation internally. Check the deposit transaction's complianceExpiresAt (Unix seconds) and rebuild if it will expire before inclusion; a successful deposit consumes the proof. Keep simulation enabled and enforce your approved minimum output in the executing integration.

Deposit on behalf

Use this flow when an aggregator, router or relayer deposits assets for another user. It applies to every supported EVM NestVault route, including nOPAL and nALPHA. The vault slug, destination chain and deposit asset select the deployment; the identity mapping, API and contract flow stay the same.

LI.FI Earn can use this flow with a proxy address determined at quote time. The policy screens the actual caller and the original depositor in one V2 attestation. A successful compliance check does not replace the vault's live permissions, available liquidity or transaction simulation.

Always send "complianceVersion": "v2" explicitly in Actions mint quotes and builds. The API field is optional, but it is required for this integration. Defaults vary by vault and chain; nREAH1 and nREAH2 have V1 defaults on Plume and Ethereum while supporting explicit V2. Never omit the version or retry an on-behalf flow with V1.

The /v1 prefix in https://api.nest.credit/v1 is the API namespace. It does not select Compliance V1. Direct proof requests select V2 through the /compliance-v2 endpoint.

Resolve the vault route

Read GET https://api.nest.credit/v1/vaults/{vaultSlug} and use its data object. Do not reuse addresses from another vault or chain.

1. In nestVaults[].chainAssets[], match both the destination chainId and the assetAddress. The enclosing nestVaultAddress is the asset-specific vault, not the share-token address.
2. In complianceDeployments[], require exactly one entry with the same chainId, version: "v2" and enabled: true. Require its proxyAddress and hookAddress.
3. Resolve the deposit asset's decimals and encode depositAmount as a raw integer string. Obtain a current mint quote, fees and limits for the same route.
4. Stop if a route or deployment is absent, disabled or ambiguous. Metadata shows supported configuration; validate live contract permissions and simulate the complete destination bundle before offering the route.

The complianceVersion and complianceVersionByChain metadata fields describe defaults, not whether explicit V2 is available. Select V2 from complianceDeployments even when the default is V1.

Legacy V1-only routes remain separate. For example, the API registry on October 9, 2026 lists nOPAL on Avalanche and nTBILL on Arbitrum without an enabled V2 deployment. Refresh the registry instead of treating these examples as a permanent list. They cannot use this V2 integration until an enabled deployment is available.

Keep the three identities separate

The caller must hold the deposit assets and approve ComplianceProxy. A user's approval to the LI.FI proxy does not grant the compliance proxy allowance from that proxy. A LI.FI destination bundle must first make the assets available to the actual caller, approve the compliance proxy if needed, deposit, and deliver the shares to the intended user.

Option A Use the Actions builder

The builder obtains the V2 attestation and encodes the approval and deposit transactions internally. Do not fetch a separate transaction proof for this path.

POST https://api.nest.credit/v1/actions/vaults/{vaultSlug}/mint/build-tx
Content-Type: application/json

Set the inputs below from the selected route and actual destination identities. buildDepositOnBehalf constructs a same-chain destination deposit: LI.FI handles its own preceding bridge or swap.

import type { Address } from "viem";

async function buildDepositOnBehalf(input: {
  vaultSlug: string;
  chainId: number;
  depositAsset: Address;
  depositAmount: bigint;
  caller: Address;
  depositor: Address;
  receiver: Address;
}) {
  const response = await fetch(
    `https://api.nest.credit/v1/actions/vaults/${encodeURIComponent(input.vaultSlug)}/mint/build-tx`,
    {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        chainId: input.chainId,
        depositAsset: input.depositAsset,
        depositAmount: input.depositAmount.toString(),
        sender: input.caller,
        recipient: input.receiver,
        onBehalf: input.depositor,
        complianceVersion: "v2", // Required for every vault; never rely on defaults.
        skipSimulation: false,
      }),
    },
  );
  if (!response.ok) {
    throw new Error(`Mint build failed: ${response.status}`);
  }
  const { data } = await response.json();
  if (data.complianceVersion !== "v2" || data.chainId !== input.chainId) {
    throw new Error("Unexpected compliance version or destination chain");
  }
  const deposit = data.transactions.find(
    (transaction: { label: string }) => transaction.label === "deposit",
  );
  // Choose an inclusion buffer appropriate for your destination chain.
  const inclusionBufferSeconds = 60;
  if (
    !deposit ||
    !Number.isFinite(deposit.complianceExpiresAt) ||
    deposit.complianceExpiresAt <= Date.now() / 1000 + inclusionBufferSeconds
  ) {
    throw new Error("Rebuild with a fresh V2 proof before execution");
  }
  return data;
}

Before execution, validate the returned asset, amount, deposit target and decoded arguments against the approved route and all three identities. Require the deposit target to match the selected V2 proxyAddress. Execute returned calls in order from sender on chainId. Approval may be absent if allowance is already sufficient. A contract caller must execute the calls itself; do not ask the end user's EOA to send them directly when the proof names a proxy.

The builder simulates by default. A proxy that is not yet deployed or funded may require simulation of the full LI.FI bundle, including its deployment and funding, instead of an isolated mint. If skipSimulation: true is necessary for construction, independently simulate that full bundle before submission; it does not waive compliance or change which account supplies assets.

For amount quotes, use POST /actions/vaults/{vaultSlug}/mint/quote with depositAsset, depositAmount, chainId and complianceVersion: "v2". The quote schema does not accept onBehalf; a quote does not prove eligibility for the caller/depositor pair. Use Option B's purpose=preview for that pair.

Omit destinationChainId for this destination-side deposit. The Actions API's own cross-chain composer route is a separate integration; do not use it to identify an arbitrary LI.FI execution proxy.

Option B Build the contract call directly

Request a V2 proof

GET https://api.nest.credit/v1/user/{actualCaller}/compliance-v2
    ?vault={vaultSlug}
    &chainId={destinationChainId}
    &flow=deposit
    &onBehalf={originalUser}
    &purpose=transaction

Send the URL on one line with URL-encoded query values. Use purpose=preview while quoting to check eligibility without receiving a usable proof. Request purpose=transaction immediately before destination execution.

For an arbitrary LI.FI proxy, omit composerAddress. That parameter selects a registered protocol composer and its deployment; it is not a generic caller override.

The response is wrapped in { "data": ... }. Require isCompliant === true, a non-null attestation and non-null complianceData. Check sender, normalized onBehalf, chainId, complianceProxyAddress, hookAddress and payload against the intended request and current deployment.

The signed policy payload is deposit(bytes32) containing the original depositor. It is not the final transaction calldata. The attestation targets the Predicate hook, while the transaction targets the compliance proxy. Forward complianceData unchanged: it already contains abi.encode(Attestation), not a V1 Predicate message or two concatenated proofs.

Encode the destination deposit

The on-behalf ABI has a different argument order from the direct-wallet deposit function:

function depositOnBehalf(
    address vault,
    address depositAsset,
    uint256 assets,
    address receiver,
    bytes32 depositor,
    bytes complianceData
) external returns (uint256 shares);

This example receives the route resolved above. It fetches a proof and builds calldata without sending a transaction.

import {
  encodeFunctionData,
  padHex,
  parseAbi,
  type Address,
  type Hex,
} from "viem";

async function encodeDepositOnBehalf(input: {
  vaultSlug: string;
  chainId: number;
  vault: Address;
  depositAsset: Address;
  assets: bigint;
  complianceProxy: Address;
  hook: Address;
  caller: Address;
  depositor: Address;
  receiver: Address;
}) {
  const representedUser = padHex(input.depositor, { size: 32 });
  const payload = encodeFunctionData({
    abi: parseAbi(["function deposit(bytes32)"]),
    functionName: "deposit",
    args: [representedUser],
  });
  const query = new URLSearchParams({
    vault: input.vaultSlug,
    chainId: String(input.chainId),
    flow: "deposit",
    onBehalf: input.depositor,
    purpose: "transaction",
  });
  const response = await fetch(
    `https://api.nest.credit/v1/user/${input.caller}/compliance-v2?${query}`,
  );
  if (!response.ok)
    throw new Error(`Compliance request failed: ${response.status}`);
  const { data: proof } = await response.json();
  const sameHex = (actual: unknown, expected: Hex) =>
    typeof actual === "string" &&
    actual.toLowerCase() === expected.toLowerCase();
  if (
    proof.isCompliant !== true ||
    !proof.attestation ||
    !proof.complianceData ||
    proof.chainId !== input.chainId ||
    !sameHex(proof.sender, input.caller) ||
    !sameHex(proof.onBehalf, representedUser) ||
    !sameHex(proof.complianceProxyAddress, input.complianceProxy) ||
    !sameHex(proof.hookAddress, input.hook) ||
    !sameHex(proof.payload, payload)
  ) {
    throw new Error("Missing or mismatched V2 authorization");
  }
  const inclusionBufferSeconds = 60; // Adapt to signing and inclusion latency.
  if (
    !Number.isFinite(proof.attestation.expiration) ||
    proof.attestation.expiration <= Date.now() / 1000 + inclusionBufferSeconds
  ) {
    throw new Error("Rebuild with a fresh V2 proof before execution");
  }
  const data = encodeFunctionData({
    abi: parseAbi([
      "function depositOnBehalf(address vault,address depositAsset,uint256 assets,address receiver,bytes32 depositor,bytes complianceData) returns (uint256 shares)",
    ]),
    functionName: "depositOnBehalf",
    args: [
      input.vault,
      input.depositAsset,
      input.assets,
      input.receiver,
      representedUser,
      proof.complianceData,
    ],
  });
  return { to: input.complianceProxy, data, value: 0n };
}

Check the caller's ERC-20 allowance to the selected compliance proxy and include any needed approval before the deposit. Handle tokens that require resetting a nonzero allowance to zero. ComplianceProxy pulls the assets from its msg.sender, approves the asset-specific NestVault internally and mints shares to receiver.

The proof authorizes the caller/depositor pair and operation. It does not bind the amount or receiver and does not enforce a minimum share output. Preserve those constraints in the executing integration and simulate them with the full bundle. Neither deposit nor depositOnBehalf accepts a minimum-share parameter.

Expiry, retries and failures

• Preview: returns eligibility and routing with attestation and complianceData set to null. It may warm a short-lived server cache; do not treat that cache as an execution guarantee.
• Transaction: returns a one-time proof. Its attestation.expiration, or the builder transaction's complianceExpiresAt, is Unix time in seconds. Leave enough time for signing and inclusion; no fixed lifetime is guaranteed.
• Bridge delays: obtain or refresh the proof near destination execution. If the bundle embeds a proof that expires in transit, rebuild the destination call. A failed or expired proof must never trigger a V1 fallback.
• Consumption and retries: successful on-chain authorization consumes the proof. Confirm the original transaction's status before retrying an uncertain submission; obtain fresh authorization for a new execution. Do not share a transaction proof among competing bundles.
• Rejection: isCompliant: false is not executable. A missing V2 deployment (404 on the compliance endpoint), invalid route, disabled deposits or failed simulation blocks that route. For rate limits (429) and retryable service failures, respect Retry-After when present and use bounded retries without bypassing compliance.

Before enabling a LI.FI route, simulate the exact proxy's complete destination bundle and verify the minted shares reach the intended receiver with the approved minimum output. Route configuration alone does not establish that this particular bundle can execute.

References

• V2 compliance API
• Mint transaction builder
• Vault integration guides
• Core OpenAPI and Actions OpenAPI
• ComplianceProxy implementation

Redeem

Redeem quote

Use the redeem quote route before submitting a redemption. This quotes the redemption asset amount and validates the selected asset for this vault.

curl -X POST https://api.nest.credit/v1/actions/vaults/nest-credit-vault/redeem/quote \
  -H 'content-type: application/json' \
  -d '{
  "redemptionAsset": "0x222365ef19f7947e5484218551b56bb3965aa7af",
  "shareAmount": "1000000",
  "chainId": 98866
}'

For this guide, treat the NestVault redemption flow as the supported redemption path. If an integration receives an unsupported route value, surface it as an integration error instead of trying to fall back to a different contract flow.

Build redemption transactions

Use this route to submit a redemption request on the same EVM chain.

curl -X POST https://api.nest.credit/v1/actions/vaults/nest-credit-vault/redeem/build-tx \
  -H 'content-type: application/json' \
  -d '{
  "redemptionAsset": "0x222365ef19f7947e5484218551b56bb3965aa7af",
  "shareAmount": "1000000",
  "chainId": 98866,
  "user": "0x00000000000000000000000000000000000000ab"
}'

NestVault redemptions return:

• approve, if the selected NestVault does not already have sufficient share-token allowance.
• requestRedeem, to submit the asynchronous redemption request.

After the request becomes claimable, use the claim routes below.

Pending, update, and claim

For NestVault-backed redemptions:

curl -X POST https://api.nest.credit/v1/actions/vaults/nest-credit-vault/claim/pending \
  -H 'content-type: application/json' \
  -d '{
    "redemptionAsset": "0x222365ef19f7947e5484218551b56bb3965aa7af",
    "chainId": 98866,
    "user": "0x00000000000000000000000000000000000000ab"
  }'

curl -X POST https://api.nest.credit/v1/actions/vaults/nest-credit-vault/claim/build-tx \
  -H 'content-type: application/json' \
  -d '{
    "redemptionAsset": "0x222365ef19f7947e5484218551b56bb3965aa7af",
    "chainId": 98866,
    "user": "0x00000000000000000000000000000000000000ab"
  }'

claim/build-tx builds a transaction to claim all currently claimable shares for the selected NestVault and user.

The update routes are for reducing an existing pending redemption:

POST /vaults/nest-credit-vault/update-redeem/pending
POST /vaults/nest-credit-vault/update-redeem/build-tx

newShareAmount is the final pending share amount, not the delta to remove.

Instant redemption

When instant liquidity is available for the selected asset, use:

POST /vaults/nest-credit-vault/instant-redeem/quote
POST /vaults/nest-credit-vault/instant-redeem/liquidity
POST /vaults/nest-credit-vault/instant-redeem/build-tx

The instant-redeem request body uses redemptionAsset, shareAmount, chainId, and user. receiver is optional and defaults to user.

Direct onchain

Use direct contracts only when your integration needs lower-level control than the Actions API provides. This path requires you to handle the full flow yourself:

This section covers:

• Main contracts
• Direct mint outline
• Direct redeem outline

For a direct integration, you handle:

• Validate the selected chain, vault slug, and asset.
• Resolve the enabled Compliance V2 deployment and obtain a fresh transaction attestation for the actual caller.
• Read the correct NestVault for the asset.
• Quote shares or redemption assets.
• Apply any app-level slippage or UX checks.
• Submit ERC-20 approvals.
• Submit deposit, redeem, update, instant-redeem, or claim calls.
• Track asynchronous redemption state.

Main nCREDIT contracts

For accountants, roles, and other shared protocol contracts, use the Smart Contracts page as the source of truth.

Direct mint outline

V2 uses ComplianceProxy with an opaque complianceData proof. Resolve its proxy and hook from the selected vault's enabled complianceDeployments for the destination chain; do not reuse a shared V1 address.

1. Read the NestVault for the selected deposit asset and chain.
2. Call previewDeposit(depositAmount) on that NestVault to estimate shares after fees. Enforce the approved minimum output in your integration; deposit and depositOnBehalfdo not take a minimum-share argument.
3. Request /user/{sender}/compliance-v2 with the vault slug, chain ID, flow=deposit, and purpose=transaction immediately before execution.
4. The actual caller approves the returned complianceProxyAddress to spend its deposit asset balance.
5. Call ComplianceProxy.deposit(depositAsset, depositAmount, recipient, nestVault, complianceData) from that caller for a direct wallet deposit. For a represented user, include onBehalf in the proof request and call depositOnBehalf as described in the Deposit on behalf section above.

Direct wallet deposit outline for Plume:

import { encodeFunctionData, parseAbi, parseUnits, toFunctionSelector } from "viem";

const chainId = 98866;
const sender = "0x00000000000000000000000000000000000000ab";
const recipient = sender;
const depositAsset = "0x222365ef19f7947e5484218551b56bb3965aa7af";
const depositAmount = parseUnits("1", 6);
const nestVault = "0xec593cf6d9f6e03339914928a82da064956fabee";
// Resolve these from fresh vault metadata for the selected chain.
const complianceProxy = "0xb65b65cff0ca1f3cc12fe58a13110e43dfa999f1";
const hookAddress = "0xac002355fe37c73e9e53be8296d4a75eecc257ef";
const query = new URLSearchParams({
  vault: "nest-credit-vault", chainId: String(chainId),
  flow: "deposit", purpose: "transaction",
});
const response = await fetch(
  `https://api.nest.credit/v1/user/${sender}/compliance-v2?${query}`,
);
if (!response.ok) throw new Error(`Compliance request failed: ${response.status}`);
const { data: proof } = await response.json();
if (proof.isCompliant !== true || !proof.attestation || !proof.complianceData ||
    proof.chainId !== chainId || proof.sender.toLowerCase() !== sender.toLowerCase() ||
    proof.onBehalf !== null || proof.payload !== toFunctionSelector("deposit()") ||
    proof.complianceProxyAddress.toLowerCase() !== complianceProxy.toLowerCase() ||
    proof.hookAddress.toLowerCase() !== hookAddress.toLowerCase()) {
  throw new Error("Missing or mismatched V2 authorization");
}
// Choose a buffer that covers signing and inclusion on this chain.
if (!Number.isFinite(proof.attestation.expiration) ||
    proof.attestation.expiration <= Math.floor(Date.now() / 1000) + 60) {
  throw new Error("Rebuild with a fresh proof before execution");
}
// sender must hold the assets and approve complianceProxy before the deposit.
const data = encodeFunctionData({
  abi: parseAbi(["function deposit(address,uint256,address,address,bytes) returns (uint256)"]),
  functionName: "deposit",
  args: [depositAsset, depositAmount, recipient, nestVault, proof.complianceData],
});
const transaction = { to: complianceProxy, data, value: 0n };
// Simulate and execute from sender on chainId. Do not reuse a spent proof.

For LI.FI and other aggregators, follow the vault-independent Deposit on behalf section. It includes the depositOnBehalf ABI, dual screening, expiry handling, and explicit V2 Actions API requests.

Legacy V1 routes require their configured NestVaultPredicateProxy and V1 Predicate message. A V2 attestation cannot be used with that interface. Such routes are outside this V2 deposit-on-behalf integration; do not silently fall back.

Direct redeem outline

For nCREDIT redemptions, use the selected NestVault for the redemption asset:

1. Approve the NestVault to spend nCREDIT shares, if allowance is insufficient.
2. Call NestVault.requestRedeem(shareAmount, user, user).
3. Wait until shares become claimable.
4. Call NestVault.redeem(claimableShares, user, user) to claim the redemption asset.

If you need to reduce a pending redemption before it is claimable, call NestVault.updateRedeem(newShareAmount, user, user).

Errors and edge cases

Implementation notes

• Treat every API amount as a raw integer amount.
• Use the API's returned depositDecimals, shareDecimals, and redemptionDecimals when rendering UI values.
• Execute returned EVM transactions in order.
• Never assume approve is present. Render and execute the returned transactions[].
• Do not reuse quotes indefinitely. Re-quote close to the time the user signs.
• For direct contract integrations, prefer the registry and Smart Contracts page over copying addresses from old integration examples.