@plumenetwork/nest-sdk

SDK for typed Nest API and CMS-backed metadata access.

The core SDK exposes product-oriented imperative methods. TanStack Query option factories are available from the @plumenetwork/nest-sdk/tanstack-query entrypoint. The SDK does not export React hooks, providers, or raw OpenAPI/Payload clients. Apps own React Query providers, cache policy, polling, readiness checks, retries, and app-specific hooks.

Exports

• @plumenetwork/nest-sdk: createNestSdk, generated OpenAPI types, convenient response aliases, config types, and TransactionType
• @plumenetwork/nest-sdk/tanstack-query: createNestQuerySdk, createNestSdkQueryOptions, and query option types. This entrypoint requires @tanstack/react-query.
• @plumenetwork/nest-sdk/types: shared config and response helper types

Setup

Install the SDK:

pnpm add @plumenetwork/nest-sdk

Create one configured SDK instance in the consuming app.

import { createNestSdk } from "@plumenetwork/nest-sdk";

export const nestSdk = createNestSdk({
  baseUrl: "https://api.nest.credit/v1",
});

baseUrl is required. metaBaseUrl is optional and defaults to https://cms.nest.credit; pass it only when the consuming app uses a custom CMS deployment.

TanStack Query Setup

Install the optional peer dependency when using query option helpers:

pnpm add @plumenetwork/nest-sdk @tanstack/react-query

Create a query-enabled SDK instance from the TanStack entrypoint:

import { createNestQuerySdk } from "@plumenetwork/nest-sdk/tanstack-query";

export const nestSdk = createNestQuerySdk({
  baseUrl: "https://api.nest.credit/v1",
});

If an app already owns a core SDK instance, compose query options separately:

import { createNestSdk } from "@plumenetwork/nest-sdk";
import { createNestSdkQueryOptions } from "@plumenetwork/nest-sdk/tanstack-query";

export const nestSdk = createNestSdk({ baseUrl, metaBaseUrl });
export const nestQueryOptions = createNestSdkQueryOptions(nestSdk);

Core SDK Surface

• nestSdk.mint: mint quotes and transaction builders
• nestSdk.redeem: redeem quotes, redeem transaction builders, and redeem update builders
• nestSdk.claim: pending claim checks and claim transaction builders
• nestSdk.autoClaim: auto-claim status and transaction builders
• nestSdk.vaults: imperative vault data helpers
• nestSdk.assets: imperative asset data helpers
• nestSdk.metadata: imperative CMS-backed vault metadata helpers
• nestSdk.portfolio: imperative portfolio transaction history helpers
• nestSdk.solana: imperative Solana status helpers

TanStack Query SDK Surface

createNestQuerySdk returns the full core SDK surface plus:

• nestSdk.queryOptions.solana: Solana status query option factories
• nestSdk.queryOptions: API-shaped TanStack Query option factories

Product Methods

Product methods use normalized SDK field names and map API-specific fields internally. Raw amount values are strings. EVM transaction builders accept optional skipSimulation; it defaults to false when omitted. Solana transaction builders accept optional feePayer for sponsored transactions. Examples use the nALPHA vault slug, nest-alpha-vault.

Mint

const mintQuote = await nestSdk.mint.quote({
  slug: "nest-alpha-vault",
  depositAsset: "0x...",
  depositAmount: "1000000",
  chainId: 98866,
});

const evmMintTx = await nestSdk.mint.buildTx({
  network: "evm",
  slug: "nest-alpha-vault",
  depositAsset: "0x...",
  depositAmount: "1000000",
  chainId: 98866,
  recipient: "0x...",
});

const solanaMintTx = await nestSdk.mint.buildTx({
  network: "solana",
  slug: "nest-basis-vault",
  depositAsset: "USDC",
  depositAmount: "1000000",
  recipient: "CFagSTMBFiMaD4YKHr7mMcKTzpi35DqiBKbDA35BvZgr",
  feePayer: "Gp2nANpTLh9sdNaay1DnZtHGQmWRS2jfqzMB1xttEST5",
});

Standard Redemption

Use redeem.quote and redeem.buildTx to request a standard redemption. If a pending redemption needs to be changed before fulfillment, use redeem.buildUpdateTx. Claim helpers are separate and apply when a pending redemption is claimable. On Solana, standard redemption uses the async redemption flow.

EVM Request

const redeemQuote = await nestSdk.redeem.quote({
  slug: "nest-alpha-vault",
  redemptionAsset: "0x...",
  shareAmount: "1000000",
  chainId: 98866,
});

const evmRedeemTx = await nestSdk.redeem.buildTx({
  network: "evm",
  slug: "nest-alpha-vault",
  redemptionAsset: "0x...",
  shareAmount: "1000000",
  chainId: 98866,
  user: "0x...",
});

EVM Update Existing Request

const evmUpdateRedeemTx = await nestSdk.redeem.buildUpdateTx({
  network: "evm",
  slug: "nest-alpha-vault",
  redemptionAsset: "0x...",
  chainId: 98866,
  user: "0x...",
  newShareAmount: "2000000",
});

Solana Async Request

const solanaAsyncRedeemRequestTx = await nestSdk.redeem.buildTx({
  network: "solana",
  slug: "nest-basis-vault",
  redemptionAsset: "USDC",
  shareAmount: "1000000",
  user: "CFagSTMBFiMaD4YKHr7mMcKTzpi35DqiBKbDA35BvZgr",
  feePayer: "Gp2nANpTLh9sdNaay1DnZtHGQmWRS2jfqzMB1xttEST5",
});

Solana Async Update Existing Request

const solanaAsyncRedeemUpdateTx = await nestSdk.redeem.buildUpdateTx({
  network: "solana",
  slug: "nest-basis-vault",
  redemptionAsset: "USDC",
  user: "CFagSTMBFiMaD4YKHr7mMcKTzpi35DqiBKbDA35BvZgr",
  newShareAmount: "2000000",
  feePayer: "Gp2nANpTLh9sdNaay1DnZtHGQmWRS2jfqzMB1xttEST5",
});

Instant Redemption

EVM instant redemption supports quote, liquidity, and transaction builders. Solana instant redemption supports transaction builders.

const instantRedeemQuote = await nestSdk.instantRedeem.quote({
  slug: "nest-alpha-vault",
  redemptionAsset: "0x...",
  shareAmount: "1000000",
  chainId: 98866,
});

const instantRedeemLiquidity = await nestSdk.instantRedeem.liquidity({
  slug: "nest-alpha-vault",
  redemptionAsset: "0x...",
  chainId: 98866,
});

const evmInstantRedeemTx = await nestSdk.instantRedeem.buildTx({
  network: "evm",
  slug: "nest-alpha-vault",
  redemptionAsset: "0x...",
  shareAmount: "1000000",
  chainId: 98866,
  user: "0x...",
});

const solanaInstantRedeemTx = await nestSdk.instantRedeem.buildTx({
  network: "solana",
  slug: "nest-basis-vault",
  redemptionAsset: "USDC",
  shareAmount: "1000000",
  user: "CFagSTMBFiMaD4YKHr7mMcKTzpi35DqiBKbDA35BvZgr",
  feePayer: "Gp2nANpTLh9sdNaay1DnZtHGQmWRS2jfqzMB1xttEST5",
});

Claim And Auto-Claim

const pendingClaim = await nestSdk.claim.pending({
  slug: "nest-alpha-vault",
  redemptionAsset: "0x...",
  chainId: 98866,
  user: "0x...",
});

const claimTx = await nestSdk.claim.buildTx({
  slug: "nest-alpha-vault",
  redemptionAsset: "0x...",
  chainId: 98866,
  user: "0x...",
});

const autoClaimStatus = await nestSdk.autoClaim.status({
  chainId: 98866,
  user: "0x...",
});

const autoClaimTx = await nestSdk.autoClaim.buildTx({
  chainId: 98866,
  user: "0x...",
  enabled: true,
});

Query Options

queryOptions is available from createNestQuerySdk or createNestSdkQueryOptions. It returns normalized product data, matching the imperative methods. The SDK unwraps API transport responses internally, so consumers should not read query.data?.data.

Apps pass these factories to TanStack Query and own cache policy: staleTime, refetchInterval, placeholderData, select, retries, and QueryClient defaults.

Action query factories accept flat partial inputs and set enabled to false until required inputs are present. Apps should pass undefined for inputs that are not ready instead of adding duplicate enabled guards.

import { useQuery } from "@tanstack/react-query";

import { nestSdk } from "@/lib/nestSdk";

export function VaultOverview({ slug }: { slug: string }) {
  const vaultQuery = useQuery({
    ...nestSdk.queryOptions.vaults.detailsBySlug(slug),
    enabled: Boolean(slug),
  });

  return <div>{vaultQuery.data?.name}</div>;
}

const mintQuoteQuery = useQuery({
  ...nestSdk.queryOptions.actions.mint.quote({
    slug,
    depositAsset,
    depositAmount,
    chainId,
  }),
});

const mintQuote = mintQuoteQuery.data;

Vault list helpers use the API default status filter unless a status is provided:

const activeVaults = await nestSdk.vaults.list();
const allVaults = await nestSdk.vaults.list({ status: "all" });

Use status: "all" when historical portfolio views need vault definitions beyond the active vault list.

Imperative Data Helpers

Use imperative helpers when a React Query call site is not the right fit.

const stats = await nestSdk.vaults.stats();
const price = await nestSdk.vaults.price("nest-alpha-vault");
const assetApy = await nestSdk.assets.apy("usdc");
const vaultMeta = await nestSdk.metadata.vaultBySlug("nest-alpha-vault");

const history = await nestSdk.portfolio.transactionHistory({
  address: "0x...",
  slug: "nest-alpha-vault",
  limit: 20,
});

Types

This package re-exports generated OpenAPI types and convenient aliases.

• paths, components
• Vault, VaultDetails, VaultDetailsLite
• VaultTransaction, VaultPriceHistory, VaultPerformanceHistory
• VaultsMeta, AssetsMeta, CategoriesMeta
• Address, NestSdkConfig
• TransactionType
• EvmActionTransaction

Code Generation

OpenAPI types are generated from Nest API schemas and committed under src/generated. The merge step combines the vault and actions schemas and fails if either schema defines a duplicate path method or component key.

Run codegen from the repo root:

pnpm --filter @plumenetwork/nest-sdk codegen

When the Nest API schema changes, regenerate types here before updating downstream consumers. The codegen step also syncs generated CMS metadata types from packages/payload-config/src/payload-types.ts.

Package builds are deterministic and offline: pnpm --filter @plumenetwork/nest-sdk build consumes the generated files already present in src/generated and src/payload-types.ts.