API Reference

Complete reference for the Velum REST API. Integrate private payments into your application.

Base URL

plaintext

https://velum.cash/api

Access Modes

Velum exposes two access modes for its API:

Mode	Auth	Rate Limits	Use Case
Public (`/api/paylinks`)	None (IP-based rate limiting)	10 creates/min, 60 gets/min	Web app frontend
Authenticated (`/api/v1/...`)	API key via `x-api-key` header	Per-key configurable	Server-side integrations

Authentication

Authenticated v1 endpoints require an API key in the x-api-key header:

Request Header

bash

x-api-key: pk_live_your_api_key_here

Paylink Endpoints

Create Payment Link

plaintext

POST /v1/paylinks

Request Body:

Field	Type	Required	Description
`recipientUtxoPubkey`	string	Yes	BN254 curve point for UTXO ownership
`recipientEncryptionKey`	string	Yes	X25519 public key for note encryption
`token`	string	No	`"SOL"`, `"USDC"`, `"USDT"`, or `"ANY"` (default)
`amountLamports`	string	No	Fixed amount in base units (omit = sender decides)
`memo`	string	No	Private memo, max 140 characters
`expiresAt`	string	No	ISO 8601 expiration timestamp

Example Request:

cURL

bash

curl -X POST https://velum.cash/api/v1/paylinks \
-H "Content-Type: application/json" \
-H "x-api-key: pk_live_your_api_key" \
-d '{
  "recipientUtxoPubkey": "21888242871839...",
  "recipientEncryptionKey": "base64encodedkey...",
  "token": "USDC",
  "amountLamports": "1000000"
}'

Response:

Response 201 Created

json

{
"id": "clx1234567890",
"url": "https://velum.cash/pay/clx1234567890"
}

Get Payment Link

plaintext

GET /v1/paylinks/:id

Response:

Response 200 OK

json

{
"id": "clx1234567890",
"recipientUtxoPubkey": "21888242871839...",
"recipientEncryptionKey": "base64encodedkey...",
"token": "USDC",
"amountLamports": "1000000",
"memo": null,
"createdAt": "2026-01-20T10:30:00.000Z"
}

Transaction Endpoints

Log Transaction

Record a deposit or withdrawal transaction.

plaintext

POST /v1/transactions

Request Body:

Field	Type	Required	Description
`type`	string	Yes	`"deposit"` or `"withdraw"`
`token`	string	Yes	Token symbol (e.g., `"SOL"`, `"USDC"`)
`amountLamports`	string	Yes	Amount in base units
`signature`	string	Yes	Solana transaction signature
`status`	string	No	`"pending"`, `"confirmed"`, or `"failed"`
`utxoPubkey`	string	No	Associated UTXO public key
`paylinkId`	string	No	Associated payment link ID

Response:

Response 201 Created

json

{
"id": "clx9876543210",
"signature": "5xK9m...",
"status": "confirmed",
"createdAt": "2026-01-20T12:00:00.000Z"
}

List Transactions

plaintext

GET /v1/transactions

Query Parameters:

Parameter	Type	Description
`utxoPubkey`	string	Filter by UTXO public key
`type`	string	Filter by `"deposit"` or `"withdraw"`
`token`	string	Filter by token symbol
`limit`	number	Results per page (default 50)
`offset`	number	Pagination offset

Response:

Response 200 OK

json

{
"transactions": [
  {
    "id": "clx9876543210",
    "type": "deposit",
    "token": "USDC",
    "amountLamports": "1000000",
    "signature": "5xK9m...",
    "status": "confirmed",
    "utxoPubkey": "21888...",
    "paylinkId": "clx1234567890",
    "paylinkMemo": "Order #12345",
    "createdAt": "2026-01-20T12:00:00.000Z"
  }
],
"total": 42,
"limit": 50,
"offset": 0
}

Update Transaction Status

plaintext

PATCH /v1/transactions/:signature

Request Body:

json

{ "status": "confirmed" }

Response:

Response 200 OK

json

{
"signature": "5xK9m...",
"status": "confirmed",
"updatedAt": "2026-01-20T12:05:00.000Z"
}

Error Handling

All errors follow a consistent format:

Error Response

json

{
"error": {
  "code": "VALIDATION_ERROR",
  "message": "Invalid token specified",
  "details": {
    "issues": [{ "path": ["token"], "message": "Invalid enum value" }]
  }
}
}

Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request parameters
`UNAUTHORIZED`	401	Missing or invalid API key
`NOT_FOUND`	404	Resource not found
`EXPIRED`	410	Payment link has expired
`RATE_LIMITED`	429	Too many requests
`CONFLICT`	409	Duplicate resource
`INTERNAL_ERROR`	500	Server error

Rate Limits

Public endpoints (no auth, IP-based):

Create paylink: 10 requests / 60 seconds
Get paylink: 60 requests / 60 seconds

Authenticated v1 endpoints (per API key):

Configurable per key, default 100 requests / 60 seconds

Rate limit headers are included in authenticated responses:

plaintext

X-RateLimit-Remaining: 95

SDKs & Libraries

`@velumdotcash/api` — REST Client

Lightweight TypeScript client for the v1 API (zero runtime dependencies):

bash

npm install @velumdotcash/api

Usage

typescript

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

const client = new VelumClient({ apiKey: "pk_live_..." });

const paylink = await client.paylinks.create({
recipientUtxoPubkey: "21888242871839...",
recipientEncryptionKey: "base64key...",
token: "USDC",
amountLamports: "1000000",
});

console.log(paylink.url);

`@velumdotcash/sdk` — ZK Crypto SDK

Full TypeScript SDK for client-side ZK operations (deposit, withdraw, proof generation):

bash

npm install @velumdotcash/sdk

See the Developer Guide for detailed usage.

API Reference

Complete reference for the Velum REST API. Integrate private payments into your application.

Base URL

plaintext

https://velum.cash/api

Access Modes

Velum exposes two access modes for its API:

Mode	Auth	Rate Limits	Use Case
Public (`/api/paylinks`)	None (IP-based rate limiting)	10 creates/min, 60 gets/min	Web app frontend
Authenticated (`/api/v1/...`)	API key via `x-api-key` header	Per-key configurable	Server-side integrations

Authentication

Authenticated v1 endpoints require an API key in the x-api-key header:

Request Header

bash

x-api-key: pk_live_your_api_key_here

Paylink Endpoints

Create Payment Link

plaintext

POST /v1/paylinks

Request Body:

Field	Type	Required	Description
`recipientUtxoPubkey`	string	Yes	BN254 curve point for UTXO ownership
`recipientEncryptionKey`	string	Yes	X25519 public key for note encryption
`token`	string	No	`"SOL"`, `"USDC"`, `"USDT"`, or `"ANY"` (default)
`amountLamports`	string	No	Fixed amount in base units (omit = sender decides)
`memo`	string	No	Private memo, max 140 characters
`expiresAt`	string	No	ISO 8601 expiration timestamp

Example Request:

cURL

bash

curl -X POST https://velum.cash/api/v1/paylinks \
-H "Content-Type: application/json" \
-H "x-api-key: pk_live_your_api_key" \
-d '{
  "recipientUtxoPubkey": "21888242871839...",
  "recipientEncryptionKey": "base64encodedkey...",
  "token": "USDC",
  "amountLamports": "1000000"
}'

Response:

Response 201 Created

json

{
"id": "clx1234567890",
"url": "https://velum.cash/pay/clx1234567890"
}

Get Payment Link

plaintext

GET /v1/paylinks/:id

Response:

Response 200 OK

json

{
"id": "clx1234567890",
"recipientUtxoPubkey": "21888242871839...",
"recipientEncryptionKey": "base64encodedkey...",
"token": "USDC",
"amountLamports": "1000000",
"memo": null,
"createdAt": "2026-01-20T10:30:00.000Z"
}

Transaction Endpoints

Log Transaction

Record a deposit or withdrawal transaction.

plaintext

POST /v1/transactions

Request Body:

Field	Type	Required	Description
`type`	string	Yes	`"deposit"` or `"withdraw"`
`token`	string	Yes	Token symbol (e.g., `"SOL"`, `"USDC"`)
`amountLamports`	string	Yes	Amount in base units
`signature`	string	Yes	Solana transaction signature
`status`	string	No	`"pending"`, `"confirmed"`, or `"failed"`
`utxoPubkey`	string	No	Associated UTXO public key
`paylinkId`	string	No	Associated payment link ID

Response:

Response 201 Created

json

{
"id": "clx9876543210",
"signature": "5xK9m...",
"status": "confirmed",
"createdAt": "2026-01-20T12:00:00.000Z"
}

List Transactions

plaintext

GET /v1/transactions

Query Parameters:

Parameter	Type	Description
`utxoPubkey`	string	Filter by UTXO public key
`type`	string	Filter by `"deposit"` or `"withdraw"`
`token`	string	Filter by token symbol
`limit`	number	Results per page (default 50)
`offset`	number	Pagination offset

Response:

Response 200 OK

json

{
"transactions": [
  {
    "id": "clx9876543210",
    "type": "deposit",
    "token": "USDC",
    "amountLamports": "1000000",
    "signature": "5xK9m...",
    "status": "confirmed",
    "utxoPubkey": "21888...",
    "paylinkId": "clx1234567890",
    "paylinkMemo": "Order #12345",
    "createdAt": "2026-01-20T12:00:00.000Z"
  }
],
"total": 42,
"limit": 50,
"offset": 0
}

Update Transaction Status

plaintext

PATCH /v1/transactions/:signature

Request Body:

json

{ "status": "confirmed" }

Response:

Response 200 OK

json

{
"signature": "5xK9m...",
"status": "confirmed",
"updatedAt": "2026-01-20T12:05:00.000Z"
}

Error Handling

All errors follow a consistent format:

Error Response

json

{
"error": {
  "code": "VALIDATION_ERROR",
  "message": "Invalid token specified",
  "details": {
    "issues": [{ "path": ["token"], "message": "Invalid enum value" }]
  }
}
}

Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request parameters
`UNAUTHORIZED`	401	Missing or invalid API key
`NOT_FOUND`	404	Resource not found
`EXPIRED`	410	Payment link has expired
`RATE_LIMITED`	429	Too many requests
`CONFLICT`	409	Duplicate resource
`INTERNAL_ERROR`	500	Server error

Rate Limits

Public endpoints (no auth, IP-based):

Create paylink: 10 requests / 60 seconds
Get paylink: 60 requests / 60 seconds

Authenticated v1 endpoints (per API key):

Configurable per key, default 100 requests / 60 seconds

Rate limit headers are included in authenticated responses:

plaintext

X-RateLimit-Remaining: 95

SDKs & Libraries

`@velumdotcash/api` — REST Client

Lightweight TypeScript client for the v1 API (zero runtime dependencies):

bash

npm install @velumdotcash/api

Usage

typescript

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

const client = new VelumClient({ apiKey: "pk_live_..." });

const paylink = await client.paylinks.create({
recipientUtxoPubkey: "21888242871839...",
recipientEncryptionKey: "base64key...",
token: "USDC",
amountLamports: "1000000",
});

console.log(paylink.url);

`@velumdotcash/sdk` — ZK Crypto SDK

Full TypeScript SDK for client-side ZK operations (deposit, withdraw, proof generation):

bash

npm install @velumdotcash/sdk

See the Developer Guide for detailed usage.

API Reference

Base URL

Access Modes

Authentication

Paylink Endpoints

Create Payment Link

Get Payment Link

Transaction Endpoints

Log Transaction

List Transactions

Update Transaction Status

Error Handling

Error Codes

Rate Limits

SDKs & Libraries

@velumdotcash/api — REST Client

@velumdotcash/sdk — ZK Crypto SDK

API Reference

Base URL

Access Modes

Authentication

Paylink Endpoints

Create Payment Link

Get Payment Link

Transaction Endpoints

Log Transaction

List Transactions

Update Transaction Status

Error Handling

Error Codes

Rate Limits

SDKs & Libraries

@velumdotcash/api — REST Client

@velumdotcash/sdk — ZK Crypto SDK

`@velumdotcash/api` — REST Client

`@velumdotcash/sdk` — ZK Crypto SDK

`@velumdotcash/api` — REST Client

`@velumdotcash/sdk` — ZK Crypto SDK