Developer Guide

npm install @velumdotcash/api

import { VelumClient } from "@velumdotcash/api";

const client = new VelumClient({
apiKey: process.env.VELUM_API_KEY!,
// baseUrl defaults to "https://velum.cash/api"
});

// Create a payment link
const paylink = await client.paylinks.create({
recipientUtxoPubkey: "21888242871839...",
recipientEncryptionKey: "base64encodedkey...",
token: "USDC",
amountLamports: "1000000", // 1 USDC
memo: "Order #12345",
});

// Redirect your user to paylink.url
console.log(paylink.url); // https://velum.cash/pay/clx1234...

const paylink = await client.paylinks.get("clx1234567890");
console.log(paylink.token, paylink.amountLamports);

await client.transactions.log({
type: "deposit",
token: "USDC",
amountLamports: "1000000",
signature: "5xK9m...",
status: "confirmed",
paylinkId: "clx1234567890",
});

const history = await client.transactions.list({
type: "deposit",
token: "USDC",
limit: 20,
});

import { VelumClient, VelumApiError } from "@velumdotcash/api";

try {
await client.paylinks.get("nonexistent");
} catch (err) {
if (err instanceof VelumApiError) {
  console.error(err.code);    // "NOT_FOUND"
  console.error(err.message); // "Paylink not found"
  console.error(err.status);  // 404
}
}

npm install @velumdotcash/sdk

import { PrivacyCash } from "@velumdotcash/sdk";

// 1. Sign a deterministic message with the user's wallet
const message = new TextEncoder().encode(
`Welcome to Velum\n\nWallet: ${publicKey.toBase58()}`
);
const signature = await wallet.signMessage(message);

// 2. Initialize the SDK
const sdk = new PrivacyCash({
RPC_url: "https://api.mainnet-beta.solana.com",
publicKey: publicKey,
signature: signature,
transactionSigner: async (tx) => {
  return await wallet.signTransaction(tx);
},
});

// 3. Get the shielded public keys (use these in payment links)
const encryptionPubkey = sdk.getAsymmetricPublicKey();
const utxoPubkey = await sdk.getShieldedPublicKey();

// Deposit SOL
const result = await sdk.deposit({ lamports: 10_000_000 }); // 0.01 SOL
console.log(result.tx); // transaction signature

// Deposit to a third-party recipient (paylink flow)
await sdk.deposit({
lamports: 10_000_000,
recipientUtxoPublicKey: paylink.recipientUtxoPubkey,
recipientEncryptionKey: Buffer.from(paylink.recipientEncryptionKey, "base64"),
});

// Deposit USDC
await sdk.depositUSDC({ base_units: 1_000_000 }); // 1 USDC

// Deposit any SPL token
await sdk.depositSPL({
base_units: 1_000_000,
mintAddress: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB", // USDT
});

// Withdraw SOL to any address
const result = await sdk.withdraw({
lamports: 10_000_000,
recipientAddress: "Destination...",
});

// Withdraw USDC
await sdk.withdrawUSDC({
base_units: 1_000_000,
recipientAddress: "Destination...",
});

// Withdraw any SPL token
await sdk.withdrawSPL({
base_units: 1_000_000,
mintAddress: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
recipientAddress: "Destination...",
});

const solBalance = await sdk.getPrivateBalance();
console.log(solBalance.lamports);

const usdcBalance = await sdk.getPrivateBalanceUSDC();
console.log(usdcBalance.base_units);

// Any SPL token
const usdtBalance = await sdk.getPrivateBalanceSpl("Es9vMF...");
console.log(usdtBalance.base_units);

// Your backend creates the payment link
import { VelumClient } from "@velumdotcash/api";

const client = new VelumClient({ apiKey: process.env.VELUM_API_KEY! });

app.post("/checkout", async (req, res) => {
const paylink = await client.paylinks.create({
  recipientUtxoPubkey: req.body.utxoPubkey,
  recipientEncryptionKey: req.body.encryptionKey,
  token: "USDC",
  amountLamports: req.body.amount,
});

res.json({ paymentUrl: paylink.url });
});

// Your frontend uses the SDK to execute the payment
import { PrivacyCash } from "@velumdotcash/sdk";

async function payLink(paylinkId: string) {
const res = await fetch(`https://velum.cash/api/v1/paylinks/${paylinkId}`, {
  headers: { "x-api-key": apiKey },
});
const paylink = await res.json();

await sdk.deposit({
  lamports: Number(paylink.amountLamports),
  recipientUtxoPublicKey: paylink.recipientUtxoPubkey,
  recipientEncryptionKey: Buffer.from(paylink.recipientEncryptionKey, "base64"),
});
}