Package Exports
- @wallgent/sdk
Readme
@wallgent/sdk
Official TypeScript SDK for the Wallgent API — financial infrastructure for AI agents.
Install
npm install @wallgent/sdk
# or
pnpm add @wallgent/sdkQuick 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.dev
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({ name, email, phone?, billingAddress? })
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 })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
)Error Handling
The SDK throws typed errors for common failure scenarios:
import {
InsufficientFundsError,
PolicyDeniedError,
WalletNotFoundError,
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)
}
}Realtime (WebSocket)
Subscribe to live updates:
import { WallgentRealtime } from '@wallgent/sdk'
const realtime = new WallgentRealtime('wg_test_...')
// See docs for event subscription APIEnvironment 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