---
title: "List wallet agents"
method: GET
path: "/wallets/{walletId}/agents"
tags: ["Wallets"]
---

# List wallet agents

`GET /wallets/{walletId}/agents`

List owned and customer-connected agents granted access to a wallet. Connected agents include customer connection limits and omit private metadata from the agent owner.

## Path parameters

- `walletId` string, required — Wallet ID (wal_*).

## Headers

- `X-Instance-ID` string, nullable

## Response `200`

Successful Response

- object
  - `data` object[], required
    - `type` 'agent', required — Resource type. Always `agent`.
    - `id` string, required — Agent ID (agt_*).
    - `attributes` object, required
      - `name` string, required — Agent display name.
      - `description` string, nullable, required — Agent description. Null for connected agents.
      - `tags` object, required — Agent tags. Empty for connected agents.
      - `handle` string, nullable, required — Agent handle, such as @acme-support, or null when none is set.
      - `status` 'ACTIVE' | 'REVOKED', required — Agent status: ACTIVE, or REVOKED after deletion.
      - `limits` object, nullable, required — Agent limits for an owned agent, or this customer's connection limits for a connected agent.
        - `perTransaction` integer, nullable — Per-transaction spending limit in cents, or null for no limit.
        - `perDay` integer, nullable — Daily spending limit in cents, or null for no limit.
        - `perMonth` integer, nullable — Monthly spending limit in cents, or null for no limit.
      - `createdAt` string, date-time, nullable, required — When the agent was created. Null for connected agents.
      - `createdBy` string, nullable, required — User who created the agent. Null for connected agents.
      - `lastActiveAt` string, date-time, nullable, required — When the agent last authenticated. Null for connected agents.
    - `relationships` object, required
      - `party` object, required — Party that owns the agent.
        - `data` object, required — Related resource identifier.
          - `type` 'party', required — Resource type. Always `party`.
          - `id` string, required
    - `meta` object, required
      - `walletAccess` object, required — The agent's access to this wallet.
        - `accessType` 'owned' | 'connected' — Whether the wallet owner owns the agent or has an active customer connection to it.
        - `isDefault` boolean, required — Whether this is the agent's default wallet.
        - `attachedAt` string, date-time, required — RFC 3339 timestamp when the agent was attached to this wallet.
  - `meta` object, required
    - `pagination` object, required
      - `hasMore` boolean, required — Whether more results are available.
      - `nextCursor` string, nullable, required — Cursor for the next page, or null when there are no more results.

## Other responses

- `400` — Validation Error
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
- `409` — Conflict
- `422` — Validation Error. The response contains one error object for each invalid request value.
- `428` — Precondition Required
- `429` — Too Many Requests
- `500` — Internal Server Error
- `501` — Not Implemented
- `502` — Bad Gateway
- `503` — Service Unavailable

## Changes

- **2026-09-26** `ca3882d75a00` — 1 info
  - added the optional property `data/items/meta/walletAccess/accessType` to the response with the `200` status
- **2026-09-02** `c7c12da5915f` — 12 info
  - added the optional property `errors/items/meta/limitScope` to the response with the `400` status
  - added the optional property `errors/items/meta/limitScope` to the response with the `401` status
  - added the optional property `errors/items/meta/limitScope` to the response with the `403` status
  - added the optional property `errors/items/meta/limitScope` to the response with the `404` status
  - …8 more
- **2026-08-27** `359d267dca88` — 1 info
  - deleted the `header` request parameter `X-Agent-ID` with deprecation
- **2026-08-23** `b1ad79e918ac` — 1 info
  - `header` request parameter `X-Agent-ID` was deprecated
- **2026-08-13** `ba1fb54c5939` — 1 info
  - added the required property `data/items/attributes/tags` to the response with the `200` status

[Full history](https://skmtc.dev/natural/apis/natural-api/changes/wallets/:walletId/agents/get.md)

---

[API](https://skmtc.dev/natural/apis/natural-api.md) · [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) · [OpenAPI document](https://skmtc.dev/natural/apis/natural-api/revisions/ca3882d75a00?raw)