Huma Permissionless SDK

This is an NPM Package that helps build deposit and withdrawal instructions for the various modes + lockups on Huma 2.0 (Permissionless), and check token prices, target APY, and balances.

Current supported features

• Deposit into classic or maxi mode (PST and mPST respectively)
• Withdraw from classic or maxi mode (redeem PST and mPST tokens)
• Check the current price of PST and mPST tokens
• Check the target APY for classic or maxi mode
• Check both locked and unlocked balances for a specific owner and mode
• Optionally specify a lockup on these tokens, in most cases you'll want to use the default NO_COMMIT option.

Depositing

An example Node script integration in /examples/deposit.ts is provided in this repo. For those integrating with react, an example repo using vite and @solana/web3.js is available at https://github.com/00labs/permissionless-sdk-example.

1. Create a PermissionlessClient

import {
  PermissionlessClient,
  SolanaChainEnum,
} from "@huma-finance/permissionless-sdk";

new PermissionlessClient(connection, SolanaChainEnum.MAINNET);

2. Build a deposit instruction for either PST (DepositMode.CLASSIC) or mPST (DepositMode.MAXI) (note that token amounts should be denoted in smallest units). At least 1 USDC must be deposited.

import {
  DepositMode
} from "@huma-finance/permissionless-sdk";

const tx = await client.buildDepositTx(
    publicKey,
    new BN(1000000), /* Deposit 1 USDC */
    DepositMode.CLASSIC /* Will receive PST */
);

3. The deposit transaction is intended to only handle the instructions for depositing and creating relevant Huma accounts. It should be up to the implementation to optimize the transaction with the correct blockhashes, compute unit limits, priority fees, etc.

Redeeming

An example Node script integration in /examples/addRedemptionRequest.ts is provided in this repo.

1. Create a PermissionlessClient (same as depositing)

import {
  PermissionlessClient,
  SolanaChainEnum,
} from "@huma-finance/permissionless-sdk";

new PermissionlessClient(connection, SolanaChainEnum.MAINNET);

2. Build a withdrawal instruction for either PST (DepositMode.CLASSIC) or mPST (DepositMode.MAXI). At least 1 USDC worth of tokens must be withdrawn. Note that the withdrawal creates a redemption request and is not an instant redemption - withdrawals are typically processed within a few days, with a 7 day SLA at the latest.

import {
  DepositMode
} from "@huma-finance/permissionless-sdk";

const tx = await client.buildWithdrawTx(
    publicKey,
    new BN(1000000), /* Withdraw 1 USDC worth of tokens */
    DepositMode.CLASSIC /* Will redeem PST */
);

3. The withdrawal transaction is intended to only handle the instructions for creating a redemption request. It should be up to the implementation to optimize the transaction with the correct blockhashes, compute unit limits, priority fees, etc.

4. Once a transaction hash is submitted and confirmed on-chain, you can optionally manually sync it with our Huma services if you want to reflect the correct pending redemption amounts in the UI. Otherwise, our services will automatically pick up the transaction.

// Sync the redemption request to Huma's services
const syncResponse = await client.syncRedemptionRequest(
  key.publicKey,
  txHash
);
console.log("Sync response:", syncResponse);

// Fetch the updated balances after syncing
const balances = await client.getBalances(key.publicKey, DepositMode.CLASSIC);
console.log("Balances after syncing:", balances);

Checking Token Price

An example Node script integration in /examples/tokenPrice.ts is provided in this repo.

1. Create a PermissionlessClient (same as depositing)

import {
  PermissionlessClient,
  SolanaChainEnum,
} from "@huma-finance/permissionless-sdk";

new PermissionlessClient(connection, SolanaChainEnum.MAINNET);

2. Get the current price of PST or mPST tokens denominated in the underlying mint (USDC)

import {
  DepositMode
} from "@huma-finance/permissionless-sdk";

const price = await client.getModeTokenPrice(DepositMode.CLASSIC);
console.log(price.toString()); // Price in smallest units of underlying mint

3. The price is returned as a BN representing the price in the smallest units of the underlying mint. For example, if the price is 1.234567 USDC, it will be returned as 1234567 (since USDC has 6 decimals).

Checking Target APY

An example Node script integration in /examples/getModeTargetAPY.ts is provided in this repo.

1. Create a PermissionlessClient (same as depositing)

import {
  PermissionlessClient,
  SolanaChainEnum,
} from "@huma-finance/permissionless-sdk";

new PermissionlessClient(connection, SolanaChainEnum.MAINNET);

2. Get the target APY for either PST (DepositMode.CLASSIC) or mPST (DepositMode.MAXI)

import {
  DepositMode
} from "@huma-finance/permissionless-sdk";

const apy = await client.getModeTargetApy(DepositMode.CLASSIC);
console.log(apy); // APY in basis points (e.g., 500 = 5.00%)

3. The APY is returned as a number representing the target APY in basis points. For example, if the target APY is 5.00%, it will be returned as 500.

Checking Balances

An example Node script integration in /examples/getBalance.ts is provided in this repo.

1. Create a PermissionlessClient (same as depositing)

import {
  PermissionlessClient,
  SolanaChainEnum,
} from "@huma-finance/permissionless-sdk";

new PermissionlessClient(connection, SolanaChainEnum.MAINNET);

2. Get both unlocked and locked balances for a specific owner and mode

import {
  DepositMode
} from "@huma-finance/permissionless-sdk";

const balances = await client.getBalances(
    publicKey,
    DepositMode.CLASSIC
);
console.log(balances.lockedBalance.toString()); // Locked balance in smallest units
console.log(balances.unlockedBalance.toString()); // Unlocked balance in smallest units

3. The balances are returned as BNs representing the amount of tokens in the smallest units of the underlying mint. For example, if the locked balance is 1.5 PST, it will be returned as 1500000 (since PST has 6 decimals). The unlocked balance is calculated as the total token balance minus the locked balance, and will return 0 if the result would be negative.

Note: This endpoint is subject to rate limitations. You should only fetch when necessary.