SDK Reference

pnpm add @wallgent/sdk

import { Wallgent } from '@wallgent/sdk';

// Production
const wg = new Wallgent('wg_live_your_key_here');

// Sandbox with custom base URL
const wg = new Wallgent('wg_test_your_key_here', {
  baseUrl: 'http://localhost:3000',
});

const wallet = await wg.wallets.create({
  name: 'Research Agent',
  agentName: 'research-bot',
  metadata: { department: 'engineering' },
});
// wallet.id: "wal_01J..."

const wallet = await wg.wallets.get('wal_01J_wallet_id');

const balance = await wg.wallets.getBalance('wal_01J_wallet_id');
// { available: "250.00", currency: "USD" }

await wg.wallets.fund('wal_01J_wallet_id', {
  amount: '1000.00',
});

const result = await wg.wallets.list();
// { data: Wallet[], cursor?: string, hasMore: boolean }

const payment = await wg.payments.send({
  fromWalletId: 'wal_01J_source',
  toWalletId: 'wal_01J_dest',
  amount: '50.00',
  description: 'Monthly SaaS subscription',
  idempotencyKey: 'pay_unique_key_123',
});
// payment.id: "txn_01J..."
// payment.state: "POSTED"

const payment = await wg.payments.get('txn_01J_transaction_id');

const payments = await wg.payments.list();

const agent = await wg.agents.create({
  name: 'Research Bot',
  permissions: ['wallets:read', 'payments:write'],
});
// agent.id: "wal_01J..."  (the wallet ID doubles as the agent ID)
// agent.apiKey: "wg_test_..."  (save this — shown once)
// agent.apiKeyId: "key_01J..."
// agent.balance: "0.00"

const result = await wg.agents.list({ limit: 50 });
// { data: AgentBudget[], cursor: string | null, hasMore: boolean }

const agent = await wg.agents.retrieve('wal_01J_agent_id');
// agent.status: "ACTIVE" | "FROZEN"
// agent.balance: "125.00"

const result = await wg.agents.adjustBudget('wal_01J_agent_id', { amount: 50 });
// { id, adjustment: 50, newBalance: "175.00", currency: "USD" }

// Claw back $25:
await wg.agents.adjustBudget('wal_01J_agent_id', { amount: -25 });

// Freeze the wallet — no outgoing payments allowed
await wg.agents.pause('wal_01J_agent_id');

// Unfreeze and allow payments again
await wg.agents.resume('wal_01J_agent_id');

const result = await wg.agents.rotateKey('wal_01J_agent_id');
// { apiKey: "wg_test_...", apiKeyId: "key_new...", revokedKeyId: "key_old..." }

const result = await wg.agents.delete('wal_01J_agent_id');
// { deleted: true, sweptAmount: "125.00" }

const result = await wg.network.payAgent({
  toAddress: 'wg_01J_recipient_address',
  amount: '25.00',
  description: 'Data processing fee',
});
// { transactionId, from, to, toAddress, amount: "25.00", fees: "0.00" }

const directory = await wg.network.searchDirectory('analytics');
// { data: [{ walletId, name, agentName, wallgentAddress }] }

for (const entry of directory.data) {
  console.log(`${entry.name} — ${entry.wallgentAddress}`);
}

const policy = await wg.policies.create('wal_01J_wallet_id', {
  name: 'Spending Guard',
  maxTransactionAmount: '100.00',
  dailySpendingLimit: '500.00',
  approvedRecipients: ['wal_vendor_a', 'wal_vendor_b'],
});

const policies = await wg.policies.list('wal_01J_wallet_id');

await wg.policies.update('pol_01J_policy_id', {
  dailySpendingLimit: '1000.00',
  enabled: true,
});

await wg.policies.delete('pol_01J_policy_id');

const webhook = await wg.webhooks.create({
  url: 'https://your-app.com/webhooks/wallgent',
  events: ['payment.completed', 'wallet.funded', 'policy.denied'],
});

const webhooks = await wg.webhooks.list();

await wg.webhooks.update('hook_01J_webhook_id', {
  enabled: false,
});

await wg.webhooks.delete('hook_01J_webhook_id');

const deposit = await wg.transfers.deposit({
  walletId: 'wal_01J...',
  amount: '1000.00',
  currency: 'USD',
  bankAccountId: 'ba_01J...',
});

const withdrawal = await wg.transfers.withdraw({
  walletId: 'wal_01J...',
  amount: '500.00',
  currency: 'USD',
  bankAccountId: 'ba_01J...',
});

const transfer = await wg.transfers.internal({
  fromWalletId: 'wal_01J_ops',
  toWalletId: 'wal_01J_savings',
  amount: '250.00',
  description: 'Move to savings',
});

const result = await wg.transfers.list({
  walletId: 'wal_01J...',
  direction: 'DEPOSIT',
  limit: 20,
});

const transfer = await wg.transfers.get('xfr_01J...');

const card = await wg.cards.create({
  walletId: 'wal_01J...',
  type: 'PERSISTENT',
  spendingLimits: [
    { amount: '500.00', interval: 'monthly' },
  ],
});

const cards = await wg.cards.list({ walletId: 'wal_01J...' });

const details = await wg.cards.getDetails('crd_01J...');
// { number: "4242...", cvc: "123", expMonth: 12, expYear: 2027 }

await wg.cards.update('crd_01J...', { status: 'INACTIVE' }); // freeze
await wg.cards.update('crd_01J...', { status: 'ACTIVE' });   // unfreeze

await wg.cards.cancel('crd_01J...');

const link = await wg.paymentLinks.create({
  walletId: 'wal_01J...',
  amount: '250.00',
  description: 'Freelance payment',
  expiresAt: '2026-03-01T00:00:00Z',
});
// link.slug: "abc123"

const links = await wg.paymentLinks.list({
  walletId: 'wal_01J...',
  status: 'ACTIVE',
});

await wg.paymentLinks.cancel('pyl_01J...');

const customer = await wg.customers.create({
  email: 'jane@acme.com',
  name: 'Jane Smith',
  companyName: 'Acme Corp',
});

const customers = await wg.customers.list();

const setup = await wg.customers.setupPaymentMethod('cus_01J...');
// setup.url: "https://checkout.stripe.com/..."

const invoice = await wg.invoices.create({
  walletId: 'wal_01J...',
  customerId: 'cus_01J...',
  lineItems: [
    { description: 'API calls (10,000)', unitPrice: '25.00' },
    { description: 'Data processing', quantity: 3, unitPrice: '15.00' },
  ],
  memo: 'Services for January 2026',
});

const invoices = await wg.invoices.list({
  walletId: 'wal_01J...',
  status: 'FINALIZED',
});

const result = await wg.invoices.finalize('inv_01J...');
// result.slug, result.checkoutUrl

await wg.invoices.charge({
  walletId: 'wal_01J...',
  customerId: 'cus_01J...',
  amount: '99.00',
  description: 'Monthly subscription',
  recurring: { interval: 'monthly' },
});

await wg.invoices.void('inv_01J...');
await wg.invoices.refund('inv_01J...');

const key = await wg.apiKeys.create({
  name: 'CI Deploy Key',
  permissions: ['wallets:read', 'payments:write'],
  environment: 'PRODUCTION',
});
// key.secret: "wg_live_..."  (save this — shown once)
// key.id: "key_01J..."

const result = await wg.apiKeys.list({ limit: 25 });
for (const key of result.data) {
  console.log(`${key.name} — ${key.status} — ${key.environment}`);
}

await wg.apiKeys.revoke('key_01J_key_id');

const result = await wg.approvals.list({ status: 'PENDING' });
for (const approval of result.data) {
  console.log(`${approval.id}: ${approval.transactionDetails.amount} to ${approval.transactionDetails.recipient}`);
}

const approval = await wg.approvals.retrieve('del_01J_approval_id');
// approval.status: "PENDING" | "APPROVED" | "REJECTED" | "EXPIRED"

// Approve — payment executes immediately
await wg.approvals.approve('del_01J_approval_id');

// Reject with a reason
await wg.approvals.reject('del_01J_approval_id', 'Amount exceeds monthly budget review threshold');

const result = await wg.delegations.list({ walletId: 'wal_01J...' });

const delegation = await wg.delegations.create({
  walletId: 'wal_01J_ops',
  delegateApiKeyId: 'key_01J_partner_key',
  permissions: ['wallets:read', 'payments:write'],
  walletScope: ['wal_01J_ops'],
  expiresAt: '2026-06-01T00:00:00Z',
});

await wg.delegations.delete('del_01J_delegation_id');

const result = await wg.auditLogs.list({
  action: 'wallet.created',
  resource: 'wallet',
  from: '2026-01-01T00:00:00Z',
  to: '2026-02-01T00:00:00Z',
  limit: 100,
});

for (const entry of result.data) {
  console.log(`[${entry.createdAt}] ${entry.actorType} — ${entry.action} on ${entry.resource}`);
}

const overview = await wg.merchants.getSettlementOverview();
// overview.balance: { amount: "1250.00", currency: "USD", status: "AVAILABLE" }
// overview.today: { count: 12, total: "340.00" }
// overview.month: { count: 187, total: "5820.00" }

const payments = await wg.merchants.listPayments({
  limit: 50,
  offset: 0,
  startDate: '2026-01-01',
  endDate: '2026-01-31',
});
// { data: MerchantPayment[], total: number, limit: number, offset: number }

const analytics = await wg.merchants.getAnalytics();
for (const point of analytics.volumeTrend) {
  console.log(`${point.date}: ${point.count} payments, $${point.volume}`);
}

import { autoPaginate } from '@wallgent/sdk';

for await (const wallet of autoPaginate((cursor) =>
  wg.wallets.list({ cursor, limit: 100 })
)) {
  console.log(wallet.id, wallet.name);
}

import { collectAll } from '@wallgent/sdk';

const allWallets = await collectAll((cursor) =>
  wg.wallets.list({ cursor, limit: 100 })
);

console.log(`Total wallets: ${allWallets.length}`);

import { verifyWebhookSignature } from '@wallgent/sdk';

// Express example
app.post('/webhooks/wallgent', (req, res) => {
  const rawBody = req.body; // must be the raw Buffer/string, not parsed JSON
  const signature = req.headers['wallgent-signature'] as string;
  const secret = process.env.WALLGENT_WEBHOOK_SECRET!;

  const isValid = verifyWebhookSignature(rawBody, signature, secret);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(rawBody.toString());
  console.log('Event:', event.type, event.data);

  res.status(200).send('OK');
});

import { WallgentRealtime } from '@wallgent/sdk';

const realtime = new WallgentRealtime(
  'wg_test_your_key_here',
  'https://api.wallgent.com', // http(s) is automatically converted to ws(s)
);

await realtime.connect();

const unsubscribePayment = realtime.on('payment.completed', (data) => {
  console.log('Payment completed:', data.transactionId);
});

realtime.on('wallet.funded', (data) => {
  console.log('Funded:', data.amount);
});

realtime.on('policy.denied', (data) => {
  console.log('Policy blocked:', data.reason);
});

// Unsubscribe later
unsubscribePayment();

realtime.on('*', (data) => {
  console.log(`Event: ${data._event}`, data);
});

realtime.disconnect();

import {
  WallgentError,
  InsufficientFundsError,
  PolicyDeniedError,
  WalletFrozenError,
  ApprovalRequiredError,
} from '@wallgent/sdk';

try {
  await wg.payments.send({
    fromWalletId: 'wal_source',
    toWalletId: 'wal_dest',
    amount: '10000.00',
    description: 'Large purchase',
  });
} catch (error) {
  if (error instanceof ApprovalRequiredError) {
    console.log('Awaiting approval:', error.message);
    // error.code: "APPROVAL_REQUIRED" (HTTP 202)
  } else if (error instanceof PolicyDeniedError) {
    console.log('Policy blocked:', error.message);
    // error.code: "POLICY_DENIED"
  } else if (error instanceof InsufficientFundsError) {
    console.log('Not enough funds:', error.message);
    // error.code: "INSUFFICIENT_FUNDS"
  } else if (error instanceof WalletFrozenError) {
    console.log('Wallet is frozen:', error.message);
  } else if (error instanceof WallgentError) {
    console.log('API error:', error.code, error.message, error.statusCode);
  }
}