# Banking Audit Log

Tenant-scoped, append-only audit trail for all banking domain events.

URL: https://docs.shiwake.app/docs/banking/audit



The **banking audit log** records every significant action in the banking
layer: wallet lifecycle events, transaction state changes, fee/limit
configuration changes, and suspense resolutions. It is separate from the
platform-level audit log (which tracks admin HTTP requests).

<Callout type="info">
  The audit log is append-only. Events are recorded automatically by the
  banking services. There are no write endpoints. You can only query it.
</Callout>

Tracked actions [#tracked-actions]

| Action                  | Resource       | When                            | Details                                            |
| ----------------------- | -------------- | ------------------------------- | -------------------------------------------------- |
| `wallet.created`        | `wallet`       | New wallet opened               | productCode, ownerId, currency, tier               |
| `wallet.frozen`         | `wallet`       | Wallet frozen                   | oldStatus, newStatus, reason                       |
| `wallet.unfrozen`       | `wallet`       | Wallet unfrozen                 | oldStatus, newStatus, reason                       |
| `wallet.closed`         | `wallet`       | Wallet closed                   | oldStatus, newStatus, reason                       |
| `wallet.tier_upgraded`  | `wallet`       | KYC tier changed                | oldTier, newTier                                   |
| `transaction.initiated` | `transaction`  | Withdrawal started              | type, walletId, amount, currency, channel          |
| `transaction.completed` | `transaction`  | Deposit or withdrawal confirmed | type, walletId, amount, fee, currency              |
| `transaction.failed`    | `transaction`  | Withdrawal cancelled            | type, walletId, reason                             |
| `transfer.completed`    | `transfer`     | Transfer between wallets        | senderWalletId, receiverWalletId, amount, currency |
| `product.created`       | `product`      | New wallet product              | code, name, currency                               |
| `product.updated`       | `product`      | Product config changed          | code, name                                         |
| `fee_schedule.created`  | `fee_schedule` | Fee schedule created            | name, transactionType, calculationType, currency   |
| `fee_schedule.updated`  | `fee_schedule` | Fee schedule modified           | name                                               |
| `fee_schedule.deleted`  | `fee_schedule` | Fee schedule removed            | name                                               |
| `limit.created`         | `limit`        | Limit rule created              | transactionType, period, maxAmount, currency       |
| `limit.updated`         | `limit`        | Limit rule modified             | maxAmount, isActive                                |
| `suspense.matched`      | `suspense`     | Suspense matched to wallet      | walletId, amount, currency, channel                |
| `suspense.refunded`     | `suspense`     | Suspense refunded to source     | amount, currency, channel                          |

The BankingAuditEvent object [#the-bankingauditevent-object]

```json
{
  "id": "bae_01HZ...",
  "actorId": "deposit-webhook",
  "actorType": "api_key",
  "action": "transaction.completed",
  "resourceType": "transaction",
  "resourceId": "btx_01HZ...",
  "details": {
    "type": "Deposit",
    "walletId": "wal_01HZ...",
    "amount": 50000,
    "fee": 500,
    "currency": "GHS"
  },
  "ipAddress": "10.0.1.42",
  "createdAt": "2026-04-07T12:00:00Z"
}
```

<TypeTable
  type="{
  id: { type: &#x22;string&#x22;, required: true, description: &#x22;Event identifier&#x22; },
  actorId: { type: &#x22;string&#x22;, required: true, description: <>Who triggered the action (user id, <code>&#x22;system&#x22;</code>, or API key context)</> },
  actorType: { type: &#x22;string&#x22;, required: true, description: <><code>&#x22;system&#x22;</code>, <code>&#x22;api_key&#x22;</code>, or <code>&#x22;platform_admin&#x22;</code></> },
  action: { type: &#x22;string&#x22;, required: true, description: &#x22;Dotted action name&#x22; },
  resourceType: { type: &#x22;string&#x22;, required: true, description: &#x22;Type of entity affected&#x22; },
  resourceId: { type: &#x22;string&#x22;, required: true, description: &#x22;Id of the entity affected&#x22; },
  details: { type: &#x22;object | null&#x22;, required: true, description: &#x22;Action-specific context (JSON)&#x22; },
  ipAddress: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Caller IP if available&#x22; },
  createdAt: { type: &#x22;datetime&#x22;, required: true, description: &#x22;When the event was recorded&#x22; },
}"
/>

***

List audit events [#list-audit-events]

<Endpoint method="GET" path="/api/v1/banking/audit" />

Cursor-based pagination, newest first.

Query parameters [#query-parameters]

<TypeTable
  type="{
  resourceType: { type: &#x22;string&#x22;, description: <>Filter by resource type (e.g. <code>wallet</code>, <code>transaction</code>)</> },
  resourceId: { type: &#x22;string&#x22;, description: &#x22;Filter by specific resource&#x22; },
  action: { type: &#x22;string&#x22;, description: <>Filter by action name (e.g. <code>wallet.created</code>)</> },
  from: { type: &#x22;datetime&#x22;, description: &#x22;Start of date range&#x22; },
  to: { type: &#x22;datetime&#x22;, description: &#x22;End of date range&#x22; },
  cursor: { type: &#x22;string&#x22;, description: <>Pagination cursor (<code>createdAt|id</code> format)</> },
  size: { type: &#x22;int&#x22;, description: &#x22;Page size (default 50, max 200)&#x22; },
}"
/>

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl "https://api.shiwake.example.com/api/v1/banking/audit?resourceType=wallet&action=wallet.created&size=20" \
      -H "X-Api-Key: sk_live_..."
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 200,
      "data": {
        "events": [
          {
            "id": "bae_01HZ...",
            "actorId": "system",
            "actorType": "api_key",
            "action": "wallet.created",
            "resourceType": "wallet",
            "resourceId": "wal_01HZ...",
            "details": {
              "productCode": "SAVINGS",
              "ownerId": "user_42",
              "currency": "GHS",
              "tier": "Unverified"
            },
            "ipAddress": null,
            "createdAt": "2026-04-07T12:00:00Z"
          }
        ],
        "next_cursor": null
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Useful query patterns [#useful-query-patterns]

**All events for a specific wallet:**

```
GET /api/v1/banking/audit?resourceType=wallet&resourceId=wal_01HZ...
```

**All completed transactions today:**

```
GET /api/v1/banking/audit?action=transaction.completed&from=2026-04-07
```

**All configuration changes (fees + limits):**

```
GET /api/v1/banking/audit?resourceType=fee_schedule
GET /api/v1/banking/audit?resourceType=limit
```

***

Get a single event [#get-a-single-event]

<Endpoint method="GET" path="/api/v1/banking/audit/{id}" />

```bash
curl "https://api.shiwake.example.com/api/v1/banking/audit/bae_01HZ..." \
  -H "X-Api-Key: sk_live_..."
```

***

Banking audit vs platform audit [#banking-audit-vs-platform-audit]

|                    | Banking audit                    | Platform audit           |
| ------------------ | -------------------------------- | ------------------------ |
| **Scope**          | Tenant-scoped                    | Cross-tenant             |
| **Trigger**        | Domain services                  | HTTP middleware          |
| **Endpoint**       | `/api/v1/banking/audit`          | `/api/v1/platform/audit` |
| **Auth**           | Tenant API key                   | Platform admin JWT       |
| **What it tracks** | Wallet/transaction/config events | Admin HTTP mutations     |
