Skip to main content

​
Overview

The audit sub-client provides a tamper-evident, append-only audit trail for all agent actions. Each entry is hash-chained to the previous entry, providing cryptographic integrity guarantees. 
await grantex.audit.log({
  agentId: agent.id,
  grantId: token.grantId,
  action: 'email.sent',
  status: 'success',
  metadata: { to: 'user@example.com', subject: 'Flight confirmation' },
});

​
audit.log()

Log an agent action to the audit trail. 
const entry = await grantex.audit.log({
  agentId: 'ag_01HXYZ...',
  grantId: 'grnt_01HXYZ...',
  action: 'payment.initiated',
  status: 'success',
  metadata: { amount: 420, currency: 'USD', merchant: 'Air India' },
});

console.log(entry.entryId);   // 'aud_01HXYZ...'
console.log(entry.hash);      // SHA-256 hash of this entry
console.log(entry.prevHash);  // Hash of the previous entry (null for the first)
console.log(entry.timestamp); // '2026-02-28T12:00:00Z'

​
Parameters

​
agentId
string
required
The agent that performed the action.
​
grantId
string
required
The grant under which the action was performed.
​
action
string
required
A descriptive action identifier (e.g. 'email.sent', 'payment.initiated', 'file.uploaded').
​
metadata
Record<string, unknown>
Arbitrary metadata to attach to the audit entry.
​
status
string
Action outcome: 'success', 'failure', or 'blocked'.

​
Response: AuditEntry

​
entryId
string
Unique audit entry identifier.
​
agentId
string
The agent that performed the action.
​
agentDid
string
The agent’s decentralized identifier.
​
grantId
string
The associated grant ID.
​
principalId
string
The user who authorized the grant.
​
action
string
The action identifier.
​
metadata
Record<string, unknown>
Arbitrary metadata attached to the entry.
​
hash
string
SHA-256 hash of this entry, used for chain integrity verification.
​
prevHash
string | null
Hash of the previous entry in the chain. null for the first entry.
​
timestamp
string
ISO 8601 timestamp when the action was logged.
​
status
string
Action outcome: 'success', 'failure', or 'blocked'.

​
audit.list()

Query audit entries with optional filters. 
const result = await grantex.audit.list({
  agentId: 'ag_01HXYZ...',
  action: 'payment.initiated',
  since: '2026-02-01T00:00:00Z',
  until: '2026-02-28T23:59:59Z',
  page: 1,
  pageSize: 50,
});

console.log(result.total);  // 128
for (const entry of result.entries) {
  console.log(`[${entry.timestamp}] ${entry.action} - ${entry.status}`);
}

​
Parameters

​
agentId
string
Filter by agent ID.
​
grantId
string
Filter by grant ID.
​
principalId
string
Filter by principal (user) ID.
​
action
string
Filter by action identifier.
​
since
string
ISO 8601 start date for the query range.
​
until
string
ISO 8601 end date for the query range.
​
page
number
Page number (1-indexed).
​
pageSize
number
Number of entries per page.

​
Response: ListAuditResponse

​
entries
AuditEntry[]
Array of audit entry objects.
​
total
number
Total number of entries matching the filters.
​
page
number
Current page number.
​
pageSize
number
Number of entries per page.

​
audit.get()

Retrieve a single audit entry by its ID. 
const entry = await grantex.audit.get('aud_01HXYZ...');

console.log(entry.action);   // 'payment.initiated'
console.log(entry.hash);     // 'a1b2c3d4e5f6...'
console.log(entry.prevHash); // '9z8y7x6w5v4u...'
console.log(entry.metadata); // { amount: 420, currency: 'USD' }

​
Parameters

​
entryId
string
required
The audit entry ID to retrieve.

​
Response

Returns an AuditEntry object.

​
Chain integrity

Each audit entry contains a hash of its contents and a prevHash linking it to the previous entry. This creates a tamper-evident chain similar to a blockchain. If any entry is modified after the fact, the hash chain breaks. Use the Compliance evidence pack to verify chain integrity programmatically: 
const pack = await grantex.compliance.evidencePack({ framework: 'soc2' });
console.log(pack.chainIntegrity.valid);          // true
console.log(pack.chainIntegrity.checkedEntries);  // 1024