@wallgent/sdk

Official TypeScript SDK for the Wallgent API — financial infrastructure for AI agents.

Install

npm install @wallgent/sdk
# or
pnpm add @wallgent/sdk

Quick Start

import { Wallgent } from '@wallgent/sdk'

const wallgent = new Wallgent('wg_test_...')

// Create a wallet for your AI agent
const wallet = await wallgent.wallets.create({ name: 'Shopping Agent' })

// Fund it (sandbox only)
await wallgent.wallets.fund(wallet.id, { amount: 100 })

// Check the balance
const balance = await wallgent.wallets.getBalance(wallet.id)
console.log(`Balance: $${balance.available}`)

// Send a payment
const payment = await wallgent.payments.send({
  from: wallet.id,
  to: 'wal_recipient',
  amount: '25.00',
  description: 'Service fee',
})

Configuration

const wallgent = new Wallgent('wg_test_...', {
  baseUrl: 'https://api.wallgent.com', // default: https://api.wallgent.com
  timeout: 30000,                       // request timeout in ms
})

Resources

Wallets

wallgent.wallets.create({ name, agentName?, currency? })
wallgent.wallets.retrieve(walletId)
wallgent.wallets.getBalance(walletId)
wallgent.wallets.fund(walletId, { amount })
wallgent.wallets.listTransactions(walletId, { limit?, cursor? })

Payments

wallgent.payments.send({ from, to, amount, description?, idempotencyKey? })
wallgent.payments.retrieve(paymentId)

Policies

wallgent.policies.create(walletId, { name, maxTransactionAmount?, dailySpendingLimit?, ... })
wallgent.policies.list(walletId)
wallgent.policies.update(walletId, policyId, { ... })
wallgent.policies.delete(walletId, policyId)

Cards

wallgent.cards.createCardholder({ firstName, lastName, email?, phone?, billingAddress, dob? })
wallgent.cards.create({ walletId, cardholderId, type?, spendingControls? })
wallgent.cards.list(walletId?)
wallgent.cards.get(cardId)
wallgent.cards.getDetails(cardId)   // requires cards:sensitive_read permission
wallgent.cards.update(cardId, { status?, spendingControls? })
wallgent.cards.cancel(cardId)
wallgent.cards.listAuthorizations(cardId)

Transfers

wallgent.transfers.deposit({ walletId, amount, rail, bankAccountId? })
wallgent.transfers.withdraw({ walletId, amount, rail, bankAccountId? })
wallgent.transfers.list({ walletId?, status?, limit?, cursor? })
wallgent.transfers.get(transferId)
wallgent.transfers.cancel(transferId)

Payment Links

wallgent.paymentLinks.create({ walletId, amount, description?, methods? })
wallgent.paymentLinks.list({ walletId?, status? })
wallgent.paymentLinks.getBySlug(slug)
wallgent.paymentLinks.claim(id, { method, ... })
wallgent.paymentLinks.cancel(id)

Customers

wallgent.customers.create({ name, email, metadata? })
wallgent.customers.list()
wallgent.customers.get(customerId)
wallgent.customers.update(customerId, { name?, email?, metadata? })
wallgent.customers.setupPaymentMethod(customerId)
wallgent.customers.listPaymentMethods(customerId)
wallgent.customers.removePaymentMethod(customerId, paymentMethodId)
wallgent.customers.getPaymentUpdateUrl(customerId)

Invoices

wallgent.invoices.create({ customerId, walletId, lineItems, dueDate? })
wallgent.invoices.list({ walletId?, status?, customerId? })
wallgent.invoices.get(invoiceId)
wallgent.invoices.finalize(invoiceId)
wallgent.invoices.void(invoiceId)
wallgent.invoices.refund(invoiceId)
wallgent.invoices.getCheckoutUrl(invoiceId)
wallgent.invoices.charge({ invoiceId, paymentMethodId })

Merchants (Settlement)

For merchant organizations with closed-loop settlement wallets:

wallgent.merchants.getSettlementOverview()
wallgent.merchants.listPayments({ limit?, offset?, startDate?, endDate? })
wallgent.merchants.getAnalytics()

Webhooks

wallgent.webhooks.create({ url, events })
wallgent.webhooks.list()
wallgent.webhooks.update(webhookId, { url?, events?, enabled? })
wallgent.webhooks.delete(webhookId)

Webhook Verification

Verify incoming webhook signatures to ensure they're from Wallgent:

import { verifyWebhookSignature } from '@wallgent/sdk'

const isValid = verifyWebhookSignature(
  rawBody,       // raw request body string
  signature,     // value of X-Wallgent-Signature header
  webhookSecret, // your webhook's signing secret
)

Closed-Loop Payments

Send payments directly to onboarded merchants via the closed-loop rail for instant settlement and lower fees:

// Pay a merchant by ID (routes via closed-loop if eligible)
const payment = await wallgent.payments.send({
  from: wallet.id,
  amount: '50.00',
  merchantId: 'mer_abc123',
  description: 'Order #1234',
})

// Or let the router discover the merchant by domain
const payment = await wallgent.payments.send({
  from: wallet.id,
  to: 'wal_merchant',
  amount: '50.00',
  merchantHint: { domain: 'shop.example.com' },
  preference: 'closed_loop_preferred',
})

The merchantHint.domain parameter helps the payment router match the destination wallet to an onboarded merchant. If a closed-loop route is available (merchant is KYB-approved, active, and currency matches), the payment settles instantly via internal ledger transfer.

The preference parameter controls rail selection: 'closed_loop_preferred' tries closed-loop first and falls back to other rails; 'cheapest' picks the lowest-fee option; 'fastest' picks the fastest settlement.

Merchant Settlement

Merchants use their API key (issued at onboarding) to check settlement balances and withdraw funds:

import { Wallgent } from '@wallgent/sdk'

const merchant = new Wallgent('wg_live_merchant_key...')

// Check settlement overview
const overview = await merchant.merchants.getSettlementOverview()
console.log(`Balance: $${overview.balance.amount} ${overview.balance.currency}`)
console.log(`Today: ${overview.today.count} payments, $${overview.today.total}`)

// List incoming payments
const payments = await merchant.merchants.listPayments({ limit: 20 })

// Withdraw to bank account
await merchant.transfers.withdraw({
  walletId: overview.settlementWalletId,
  amount: '1000.00',
  currency: 'USD',
  destination: { type: 'ACH', bankAccountId: 'ba_...' },
})

Error Handling

The SDK throws typed errors for common failure scenarios:

import {
  InsufficientFundsError,
  PolicyDeniedError,
  WalletNotFoundError,
  MerchantNotFoundError,
  MerchantSuspendedError,
  RateLimitExceededError,
} from '@wallgent/sdk'

try {
  await wallgent.payments.send({ from, to, amount: '1000.00' })
} catch (err) {
  if (err instanceof InsufficientFundsError) {
    console.log('Not enough funds:', err.message)
  } else if (err instanceof PolicyDeniedError) {
    console.log('Policy blocked this payment:', err.message)
  } else if (err instanceof MerchantSuspendedError) {
    console.log('Merchant is suspended:', err.message)
  }
}

Realtime (WebSocket)

Subscribe to live updates:

import { WallgentRealtime } from '@wallgent/sdk'

const realtime = new WallgentRealtime('wg_test_...')
// See docs for event subscription API

Environment Isolation

• Sandbox keys (wg_test_*) can only access sandbox wallets
• Production keys (wg_live_*) can only access production wallets
• Cross-environment access returns 404 (not 403) to avoid leaking wallet existence

License

MIT