Audit Logs

Query the immutable record of all actions in your organization for compliance and forensics.

Overview

Every action that touches your organization — payments, wallet changes, policy modifications, API key lifecycle events, delegation changes, user logins — is recorded in the audit log. Entries are immutable and cannot be edited or deleted.

What gets logged:

Payment creation, reversal, and failures
Wallet creation, freeze, unfreeze, and closure
Policy creation, updates, and deletion
API key creation, updates, and revocation
Delegation creation and revocation
Webhook creation and deletion
User authentication events
Invoice and billing actions
Any admin action on your organization

Querying Audit Logs

GET /v1/audit-logs

import Wallgent from '@wallgent/sdk'

const wg = new Wallgent({ apiKey: process.env.WALLGENT_API_KEY })

const { data, nextCursor } = await wg.auditLogs.list({
  action: 'api-key.create',
  from: '2026-02-01T00:00:00Z',
  to: '2026-03-01T00:00:00Z',
  limit: 50,
})

Filter Parameters

Parameter	Type	Description
`action`	`string`	Event name, e.g. `payment.created`, `api-key.revoke`, `policy.update`
`resource`	`string`	Resource ID, e.g. a wallet ID or policy ID
`actorId`	`string`	Filter by the API key or user ID that performed the action
`from`	`string`	ISO 8601 start of the date range
`to`	`string`	ISO 8601 end of the date range
`limit`	`number`	Max results per page (default: 20)
`cursor`	`string`	Cursor from previous response for pagination

Log Entry Shape

Each audit log entry contains:

{
  id: 'log_01J...',
  organizationId: 'org_01J...',
  actorType: 'API_KEY',         // 'API_KEY' | 'USER' | 'SYSTEM'
  actorId: 'wg_test_abc...del_01J...',
  action: 'payment.created',
  resource: 'wallet',
  resourceId: 'wal_01J...',
  metadata: {
    amount: '150.00',
    currency: 'USD',
    recipientWalletId: 'wal_01J...',
  },
  ipAddress: '203.0.113.42',
  createdAt: '2026-03-01T14:32:00.000Z',
}

Actor Types

Actor Type	Description
`API_KEY`	Automated action performed by an API key (your agents, services)
`USER`	Human action performed via the dashboard
`SYSTEM`	Internal Wallgent system action (scheduled jobs, automatic expiry)

Pagination

Audit logs are paginated using a cursor. Pass the nextCursor from each response as the cursor parameter in the next request.

let cursor: string | undefined
const allLogs = []

do {
  const page = await wg.auditLogs.list({
    from: '2026-01-01T00:00:00Z',
    to: '2026-02-01T00:00:00Z',
    limit: 100,
    cursor,
  })

  allLogs.push(...page.data)
  cursor = page.nextCursor
} while (cursor)

console.log(`Total log entries: ${allLogs.length}`)

Compliance Use Cases

Who approved a large payment?

const logs = await wg.auditLogs.list({
  action: 'approval.approved',
  resource: 'apr_01J...',
})
// actorId will be the API key or user that called /approve

What changed on a wallet this month?

const logs = await wg.auditLogs.list({
  resource: 'wal_01J...',
  from: '2026-03-01T00:00:00Z',
})

All API key creations in the last 30 days?

const logs = await wg.auditLogs.list({
  action: 'api-key.create',
  from: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
})

MCP Tool

Tool	Description
`wallgent_query_audit_logs`	Query audit logs with action, resource, actor, and date filters

API Endpoints

Method	Path	Description
`GET`	`/v1/audit-logs`	Query audit logs with filters

Permissions

Permission	Required For
`wallets:read`	Query audit logs

API Keys

Track key creation and revocation events

Approvals

See who approved or rejected held payments

Compliance

KYB and regulatory requirements

API Keys

Approvals

Compliance

On this page