Quickstart - Pulsarpay Started Kit

Prerequisites

Node.js 18 or higher
A Pulsarpay agent key (ag_live_...)

Don’t have an agent key yet? Register your agent first — the key is returned only once at registration.

Install the SDK

npm install pulsarpay-sdk

pnpm add pulsarpay-sdk

yarn add pulsarpay-sdk

Initialize the client

import { PulsarpayClient } from "Pulsarpay-sdk";

const client = new PulsarpayClient({
  agentKey: process.env.PULSARPAY_AGENT_KEY!,  //no required for register agent
});

Optional configuration:

const client = new PulsarpayClient({
  agentKey: "ag_live_...",  // required
  baseUrl: "https://...",   // defaults to https://www.pulsarpay.io
  timeout: 15_000,          // defaults to 30000ms
});

Register an agent

Run this once during onboarding. Save the returned apiKey immediately — it is not retrievable afterward.

const result = await client.agents.register({
  name: "my-inference-agent",
  email: "dev@mycompany.com",
  website: "https://mycompany.com",
});

console.log(result.apiKey);   // ag_live_... (save this!)
console.log(result.enabled);  // false — contact hello@pulsarpay.io for activation

Core operations

Create a charge

Debit a user’s balance. An idempotency key is auto-generated if you don’t provide one.Each currency has a separate balance. The charge is deducted from the user’s balance in the specified currency — the user must have sufficient funds in that currency.

const charge = await client.payments.createCharge(
  {
    amount: 0.5,
    currency: "USD",  // "USD" or "USDC"
    description: "AI Inference - 1000 tokens",
  },
  {
    userKey: "pp_live_7698774c...",
    // idempotencyKey: "uuid-v4-optional",
  }
);

console.log(charge.chargeId); // cmnnfoagf0003jk04suqxf3k9
console.log(charge.reused);   // true if idempotency key was reused

Check charge status

Poll a charge by ID. Status is one of PENDING, SUCCESS, FAILED, or EXPIRED.

const charge = await client.payments.getCharge("cmn3tney00001l104hudm7fgy");

console.log(charge.status);   // "PENDING" | "SUCCESS" | "FAILED"
console.log(charge.amount);   // 0.5
console.log(charge.currency); // "USD" | "USDC"

List charges

Retrieve paginated charge records for auditing and reconciliation.

const result = await client.payments.listCharges({ page: 1, limit: 20 });

console.log(result.pagination.total);      // 142
console.log(result.pagination.totalPages); // 8

for (const charge of result.data) {
  console.log(charge.id, charge.status, charge.amount);
}

View earnings

Each currency has its own independent balance. The response returns one entry per currency.

const { earnings } = await client.payments.getEarnings();

for (const entry of earnings) {
  console.log(entry.currency);       // "USD" | "USDC"
  console.log(entry.totalEarned);    // 8.5
  console.log(entry.totalCharges);   // 3
  console.log(entry.currentBalance); // 8.5
}

Withdraw funds

Withdraw to a Solana wallet (USDC) or a PayPal account (USD). Minimum withdrawal is 1.00. A 3% platform fee is deducted from the gross amount.

// USD → PayPal
const payout = await client.payments.withdraw({
  amount: 10.00,
  currency: "USD",
  walletAddress: "your-paypal-id@example.com",
});

// USDC → Solana wallet
const payout = await client.payments.withdraw({
  amount: 10.00,
  currency: "USDC",
  walletAddress: "8ixbQzsFc9FkxegG7aumq3h1XCGDkRSN23xeLTnZiyHr",
});

console.log(payout.success);                  // true
console.log(payout.payoutId);                 // cmnpeptvy0005l404gq5zy7nx
console.log(payout.breakdown.netAmount);      // 9.70
console.log(payout.breakdown.network);        // "PAYPAL" | "SOL"

Error handling

The SDK provides specific error classes for each failure scenario.

import {
  PulsarpayInsufficientFundsError,
  PulsarpayUnauthorizedError,
  PulsarpayBadRequestError,
  PulsarpayNotFoundError,
  PulsarpayConflictError,
  PulsarpayNetworkError,
  PulsarpayError,
} from "Pulsarpay-sdk";

try {
  await client.payments.createCharge(data, options);
} catch (err) {
  if (err instanceof PulsarpayInsufficientFundsError) {
    console.error("User has no funds:", err.message);
  } else if (err instanceof PulsarpayUnauthorizedError) {
    console.error("Invalid agent or user key:", err.message);
  } else if (err instanceof PulsarpayBadRequestError) {
    console.error("Validation error:", err.message);
  } else if (err instanceof PulsarpayNetworkError) {
    console.error("Network/timeout error:", err.message);
  } else if (err instanceof PulsarpayError) {
    console.error(`Unexpected error [${err.statusCode}]:`, err.message);
  }
}

Error class	Status
`PulsarpayBadRequestError`	400
`PulsarpayUnauthorizedError`	401
`PulsarpayInsufficientFundsError`	402
`PulsarpayNotFoundError`	404
`PulsarpayConflictError`	409
`PulsarpayNetworkError`	Network / timeout

Next steps

API reference

Full endpoint documentation with request and response schemas.

Create charges

Detailed options for charge creation and idempotency.

Earnings

Track net earnings and transaction history.

Withdraw

Transfer USDC to a Solana wallet or USD to a PayPal account.

​Prerequisites

​Install the SDK

​Initialize the client

​Register an agent

​Core operations

​Error handling

​Next steps

API reference

Create charges

Earnings

Withdraw

Prerequisites

Install the SDK

Initialize the client

Register an agent

Core operations

Error handling

Next steps